API Reference

On larger screens you can follow along with examples in your language of choice.

cUrl

PHP

Python

Node.js

Java

.NET

Go

Introduction

By default, the Twikey API Docs demonstrate API interaction using cUrl. 
You can always select a specific language from the selection above.

# The easiest way to install the Twikey API client is with pip.

pip install twikey-api-python

// By far the easiest way to install the Twikey API client is to require it with Composer.

$ composer require twikey/twikey-api-php:^0.4.0

{
    "require": {
        "twikey/twikey-api-php": "^0.4.0"
    }
}

// Using npm

$ npm install twikey-api-client

// or using yarn

$ yarn add twikey-api-client

// The easiest way to install the Twikey API client is with maven.

<dependency>
  <groupId>com.twikey</groupId>
  <artifactId>twikey-api-java</artifactId>
  <version>{twikey.version}</version>
</dependency>

// Using the .NET Core command-line interface (CLI) tools:
dotnet add package TwikeySDK

// Using the NuGet Command Line Interface (CLI):
nuget install TwikeySDK

// Using the Package Manager Console:
Install-Package TwikeySDK

// The easiest way to install the Twikey API client is with go get
go get -u github.com/twikey/twikey-api-go 

Twikey offers a simple and safe multichannel solution to negotiate and collect recurring (or even occasional) payments using your own bank account and one or multiple payment service providers. We help you simplify your financial flows with Credit Card, SEPA Direct Debit or any other payment method by leveraging your own payment service provider or bank account.

Twikey has integrations with a lot of accounting and CRM packages. It is one of the first providers to operate on a European level for Direct Debit and can work directly with most European Banks. However, you can use the payment options of your favorite PSP to allow other customers to pay as well.

Twikey has set up an api enabling software partners, companies to integrate with their own systems. As there are numerous ways in which a business can make its customers pay, we have also provided a few high-level usage examples to get you started in no time.

Usage Guidelines

Sessions

All API requests must include a valid session token in the Authorization header. This token can be obtained using the login endpoint and remains valid for 24 hours. We recommend triggering the login call only when a request returns a 401 Unauthorized response. This approach simplifies token management by allowing your application to request a new token only when necessary.

Feeds

Status changes are much more common for agreements, invoices and transactions than for regular one-off payments. Since we don't want you to miss any event and multiple webhooks might not arrive in the correct order due to network latency, we provide "feeds" or queues which are actually a list of events you haven't received yet.

Each data feed (or queue of events so you will) includes the last sequence number (X-LAST) that allows clients to resume from a specific point in the event stream (via the request header X-RESUME-AFTER). This mechanism is particularly useful for error recovery or when reconnecting after an interruption (and also quite helpful when testing).

Continue reading the feed until there are no entries left.
It's crucial to keep processing the response until no further updates are available.
This ensures that every update is properly handled and nothing is missed.

Avoid having multiple clients in your network access the same feed simultaneously, as this can lead to race conditions and inconsistent data on your end. If concurrent access is necessary, consider one of the following approaches:

• Use separate API keys: Assign a unique API key to each client. You can generate additional keys from the Twikey settings menu.
• Implement a master-client pattern: Designate a single client as the master to fetch the feed. Other clients should read data from a shared datastore managed by the master.

As security is essential for payments, Twikey has decided not to pass on details about payments in webhooks, but only to provide them in requests coming from your end. We allow specific "detail" calls about an object but since they are only a snapshot of the object at that time (and might already have changed by the time you've handled it) we've added rate-limits to avoid using them.

Webhooks vs Polling

We support 2 kinds of integrations.

With a push-fetch architecture Twikey notifies you about an event in Twikey via a webhook. You can use this webhook as trigger to retrieve all events from the feed (or queue) and update your internal systems.

Note: Webhooks serve as notifications only and must be handled accordingly. To prevent duplicate deliveries due to timeouts or retries, ensure any internal business logic is handled asynchronously.

The alternative is a pull architecture, clients periodically fetch updates from Twikey to get the latest state within Twikey. This architecture caters for situations when no incoming webhooks are allowed. However, the downside is that there is a delay between the moment an event occurs in Twikey and the moment you receive the event.

Hybrid solutions where hooks are combined with recurrent pulls are obviously also possible.

Idempotency Keys

A request can return different status codes such as 200 meaning all is well or a 400 when you know the call did not succeed. But what when it is crucial that a certain request doesn't hit our system twice, when due to some networking issue for example you'd ideally want to retry?

To provide a way to ensure each request you make is unique we support the standard idempotency header for our creation endpoints of transactions, refunds and subscriptions.

Idempotency-Key: "your unique reference"

Regardless if the request succeeded, failed or succeeded but wrong parameters were passed and we returned an error, you can only use the request once as the idempotency-key can only be used once and ensure that no duplicates are created.

We already supported idempotency implicitly for example trying to cancel the same mandate multiple times. This would have no adverse effect. From now, you will receive a response 409 (Conflict) when using the idempotency header with the same value more then once while a response is not yet available and you are trying to use the same key in your request(s).

Once we can return the response from your original request, that is returned upon using the same idempotency-key. The same body and HTTP code from your original request is returned.

Error Handling

API errors fall into two main categories:

1. Client Errors (HTTP 400):

   These occur due to issues in the request and are communicated via a 400 Bad Request response. An ApiError header will be included with further details about the issue. The error message is localized based on the Accept-Language header. If this header is not provided, the message defaults to English.

2. Server Errors (HTTP 500):

   These indicate an internal error on our side. While rare, they suggest an unexpected failure in the API. In most cases, our team is already aware of such incidents when they occur.

Sample use cases

The fitness scenario

Imagine you're going to the fitness where you exercise every once in a while. Since this doesn't come free you pay a monthly subscription fee. This subscription fee is a recurring payment (we'll come back to that later). But since all those exercises get you thirsty, you want to drink there too. But of course, there are hotter and colder days. So how much you drink can vary.

Regardless of what you consume, the fitness wants to get paid. But you'd like to avoid getting out your wallet when you're all sweaty. So your fitness made the great decision to use direct debits to allow you to pay. At the end of the month they add the recurring amount to the one-off's (the drinks). They send the payment request to the bank. Everyone's happy and relax.

What did the fitness do to achieve this relaxed way of working:

First of all, everything starts with a mandate. When a customer enrolls at the fitness he fills in the details for the internal bookkeeping of the fitness. The same information is sent to the prepare call. This returns a URL (representing an unsigned mandate) that opens up after entering all details in the enrollment screen. Since the fitness has an internal subscription number they want to use to track payments and have multiple subscriptions (eg. with and without personal trainer) they add both parameters in the prepare call. Making it visible in the mandate overview.

Once the customer filled in the account info and signed the mandate he's sent back to the fitness website with a "thank you" message. When a customer ask for a drink at the bar, the cash register calls the transaction endpoint with the details and amount. These are one-off transactions. Recurring transactions can either be handled the same way or if a subscription parameter was added in the prepare call, a recurring transaction is automatically added every month to get this subscription paid. At the end of each month, the file is created and sent to the bank manually via the collect call or automatically every night. Your bill is paid and the bank sends you the money. When the bank sends us back the account information, it is marked in your transaction overview that the transaction was paid. This information can be retrieved by the payment call. This call returns all new payment information since the last call. If a payment didn't succeed, you can configure what will happen next in the interface in the dunning section.

The parking app scenario

Because my customers don't like running in the rain looking for a parking meter while there's an app for that. How can I use Twikey to get my parking fees paid? First of all, you need a mandate . There are three possible options to have this mandate signed:

Use an in-app browser with the link retrieved via the prepare call Use the sign call to invite the user to sign via an sms confirmation Use the sign call adding the manual signature as a png-image in the payload Once the mandate is signed, in-app purchases can be sent from the backend of the app, collected the same way as mentioned in the fitness scenario.

The (off-line) webshop scenario

I have a shop where people come in physically but I also have a webshop. I want people who signed a mandate (either online via the above flow or physically) to be able to purchase something from the online shop without requiring them to use their credit card and if possible give them the sameconvenience in the physical shop. This way I can send them an invoice every month by only registering their purchases and collecting the payment via direct debit.

In the past, I had to send out all invoices and patiently waited for them to be paid. Since I'm not the most patient person on earth and even a bit chaotic at times, I'd rather collect the money directly from my customers. This way they can't forget to pay and I don't need to remind them to do so. How convenient this is for both my customers and I.

Authentication

Login

When using the API the login call will provide you with an session token, which is to be send upon every subsequent call (via the authorization header) in order to use the api. If enhanced security is setup, the private key allows the generation of a Time-based One-time password. View our sample code snippets on how to calculate this OTP in various languages. Please do not pass the apiKey as a query parameter in the url as it exposes it in some proxies. Instead pass it into the body of the request.

Normally this call is made on request of another call that returned a 401 (UNAUTHORIZED) indicating that there was no session token or that it expired.

curl -X POST https://api.twikey.com/creditor /
-d apiToken=**API KEY**

use GuzzleHttp\Client;
use GuzzleHttp\ClientInterface;
use Twikey\Api;

$httpClient = new Client();
$APIKEY = "**API_KEY**";
$twikeyclient = new Twikey($httpClient,$APIKEY);

let twikeyClient:TwikeyClient = new TwikeyClient({
    apiKey: "apiKey",
    apiUrl: "https://mycompany.twikey.com/api/creditor",
    userAgent: "myApp",
});

public class TwikeyAPI {
    private String apiKey = "**API_KEY**";
    
    public void logIn(){
        TwikeyClient twikeyClient = new TwikeyClient(apiKey)
            .withUserAgent("myApp");
    }
}

public class TwikeyAPI {
    private String apiKey ="**API_KEY**";

    public void logIn(){
        TwikeyClient twikeyClient = new TwikeyClient(apiKey)
            .WithUserAgent("myApp");
    }
}

import "github.com/twikey/twikey-api-go"

func main() {
   client := twikey.NewClient("**API_KEY**")
}

import twikey

APIKEY = '**API_KEY**'
twikeyClient = twikey.TwikeyClient(APIKEY, "https://apiurl_as_found_in_twikey")

{
  "Authorization": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
}

This session token has a validity of 24h.

HTTP Request

POST https://api.twikey.com/creditor

Form Parameters

HTTP Response

(1) For security reasons, the http status is always 200, the regular error response-headers (ApiError/ApiErrorCode) are available. Other (regular) endpoints return a 401 upon passing an invalid session token.

Error codes

Logout

Invalidates the AuthorizationToken by making a GET request to /creditor

curl https://api.twikey.com/creditor \
  -H 'authorization: authorization'

HTTP Request

GET https://api.twikey.com/creditor

HTTP Response

Mandate

Invite a customer

Necessary to start with an eMandate or to create a contract. The end-result is a signed or protected shortlink that will allow the end-customer to sign a mandate or contract. The (short)link can be embedded in your website or in an email or in a paper letter. We advise to use the shortlink as the data is not exposed in the URL's. The parameters are as described in detail on the page "Create contracts".

After signing the end-customer is either presented with a thank-you page or is redirected to a (Global) Thank you page defined on the profile. This url can contain variables that are filled in depending on the outcome. See Thank you page

Requires a ct_id which can be found in the Twikey Creditor Template overview

curl -X POST https://api.twikey.com/creditor/invite \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'authorization: **authorization**' \
  -d 'ct=**ct_id**' \
  -d 'l=nl' \
  -d 'email=support@twikey.com' \
  -d 'lastname=Support' \
  -d 'firstname=Twikey' \
  -d 'mobile=32479123123' \
  -d 'address=Stationstraat 43' \
  -d 'zip="9051"' \
  -d 'city=Sint Denijs Westrem' \
  -d 'country=BE'

$host = "https://api.twikey.com";
$ct = **ct_id**;
$authorisation = null; //collected through login

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/invite");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    "ct=$ct"
    ."&l=nl"
    ."&email=support%40twikey.com"
    ."&lastname=Support"
    ."&firstname=Twikey"
    ."&address=Stationstraat%2043"
    ."&zip=9051"
    ."&city=Sint%20Denijs%20Westrem"
    ."&country=BE"
);
curl_setOpt($ch, CURLOPT_HTTPHEADER,"authorization: $authorization");

$server_output = curl_exec ($ch);
$result = json_decode($server_output);
$url = $result->{'url'} ;
curl_close ($ch);

let invite = await twikeyClient.document.create({
    ct: Number(CT),
    email: "no-reply@example.com",
    firstname: "Twikey",
    lastname: "Support",
    address: "Stationstraat 43",
    city: "Gent",
    zip: "9000",
    country: "BE",
    l: 'nl',
})

console.log("Redirect to : " + invite.url)

public class TwikeyApi{
    private String host = "https://api.twikey.com";
    private String ct = "**ct_id**";
    private String authorisation = null; //collected through logIn

    public void invite(){
        OkHttpClient client = new OkHttpClient();

        MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
        RequestBody formBody = new FormBody.Builder()
                .add("ct", ct)
                .add("l", "nl")
                .add("email", "support@twikey.com")
                .add("firstname", "Twikey")
                .add("lastname", "Support")
                .add("address", "Stationstraat 43")
                .add("zip", "9051")
                .add("city", "Sint-Denijs-Westrem")
                .add("country", "BE")
                .build();

        Request request = new Request.Builder()
          .url(host + "/creditor/invite")
          .post(formBody)
          .addHeader("Content-Type", "application/x-www-form-urlencoded")
          .addHeader("Authorization", authorisation)
          .addHeader("Cache-Control", "no-cache")
          .build();

        Response response = client.newCall(request).execute();
    }
}

public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        ct ="**ct_id**",
        authorisation = null; // collected through logIn

    public void invite(){
        RestClient client = new RestClient(host + "/creditor/invite");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("authorization", authorisation);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddParameter("application/x-www-form-urlencoded",
            "ct=" + ct +
            "&l=nl" +
            "&email=support%40twikey.com" +
            "&lastname=Support" +
            "&firstname=Twikey" +
            "&address=Stationstraat%2043" +
            "&zip=9051" +
            "&city=Sint%20Denijs%20Westrem" +
            "&country=BE"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

{
  "mndtId": "COREREC01",
  "url": "http://twikey.to/myComp/ToYG",
  "key": "ToYG"
}

HTTP Request

POST https://api.twikey.com/creditor/invite

Query Parameters

[*1] The mandateNumber is mandatory if you enabled the 'Never generate a mandate reference' in the template settings under 'Options'. The mandateNumber cannot use the same prefix as your template to avoid conflicts.

[*2] sendInvite can have a boolean or a string value, both are accepted:

• true: Invite is sent by email (requires an active email integration).
• letter: Invite is sent by letter
• letterWithMandate: Invite is sent by letter incl. the mandate

[*3] The transaction reference is either:

• The payment link remittance when the first payment is via a payment link
• The transaction reference when the first payment is via a transaction

[*4] The transaction description is either:

• The payment link title (displayed on screen when the customer is on the payment page) when the first payment is via a payment link
• The transaction communication when the first payment is via a transaction

[*5]

• The reference is a unique identifier for each subscription. This allows the subscription to be referred to when using a request.

[*6]

• The BIC code can be derived in most cases and is not mandatory. In some cases (foreign IBAN's) we can not derive the BIC code and return the error err_invalid_bic. In this case pass the BIC code in your request.

Special cases:

• Recurring Credit Card

  For this you have to include an amount, the 'ct' should contain the number of a template of type credit card and optional a parameter 'method' (mastercard/visa) in the request.

The first payment to sign this type of document is always a payment link. Retrieve the mandate feed using a x-types header and/or the payment link feed to fetch details.

• Recurring Credit Card - Paypal via CCV

You need a Credit Card profil with the signing method 'Paypal' enabled (contact our support to enable this).
In your API request include the additional attribute methodwith value paypal

• Add a plan on invite

When adding a subscription to a mandate it might be interesting to use a parent plan (in order to slice and dice your subscriptions). It also allows to change the base parameters of the subscription without the need to change your code.

To add a subscription based on a plan multiple options can be used:

• Put a default plan on a profile. Go to the profile > Payments > Default plan and select a plan. Note: This will always add a subscription when an agreement is signed.
• Or, if you do not have a default plan configured, add an attribute named 'plan' and of type 'plan' in the profile.

To pass a custom subscription on invite you need to pass the plan parameter using the name of an existing plan as value. This serves only as a base the subscription will use the values (subscriptionRecurrence, _subscriptionStart, etc..._) you passed using the subscription parameters in the request.

The subscription is created once the end customer signs.

HTTP Response

Error codes

Sign a mandate

curl -X POST https://api.twikey.com/creditor/sign \
  -H 'authorization: **authorization**' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'method=sms' \
  -d '&place=Gent' \
  -d '&ct=**ct_id**' \
  -d '&iban=BE68068897250734' \
  -d '&bic=GKCCBEBB' \
  -d '&email=support%40twikey.com' \
  -d '&lastname=Twikey' \
  -d '&firstname=Support' \
  -d '&mobile=%2B32479123123' \
  -d '&address=Stationstraat%2043' \
  -d '&city=Gent' \
  -d '&zip=9051' \
  -d '&country=BE'

$host = "https://api.twikey.com";
$ct = **ct_id**;
$authorisation = null; //collected through login

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/sign");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    "method=sms"
    ."&place=Gent"
    ."&ct=1323"
    ."&iban=BE68068897250734"
    ."&bic=GKCCBEBB"
    ."&email=support%40twikey.com"
    ."&lastname=Twikey"
    ."&firstname=Support"
    ."&mobile=%2B32479123123"
    ."&address=Stationstraat%2043"
    ."&city=Gent"
    ."&zip=9051"
    ."&country=BE"
);
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");

$server_output = curl_exec ($ch);
$result = json_decode($server_output);
$mandateId = $result->{'MndtId'} ;
curl_close ($ch);

let invite = await twikeyClient.document.sign({
    method: 'itsme', // or emachtiging / idin / ....
    ct: Number(CT),
    email: "support@twikey.com",
    firstname: "Twikey",
    lastname: "Support",
    address: "Stationstraat 43",
    city: "Gent",
    zip: "9000",
    country: "BE",
    l: 'nl',
})

public class TwikeyApi{
    private string host = "https://api.twikey.com";
    private String ct = "**ct_id**";
    private String authorisation = null; //collected through logIn

    public void inviteAndSign(){
        OkHttpClient client = new OkHttpClient();

        RequestBody body = new FormBody.Builder()
            .add("ct",ct)
            .add("method", "sms")
            .add("place"="Gent")
            .add("mobile","+32479123123")
            .add("l","nl")
            .add("email","support%40twikey.com")
            .add("lastname","Support")
            .add("firstname","Twikey")
            .add("address","Stationstraat%2043")
            .add("zip","9051")
            .add("city","Sint Denijs Westrem")
            .add("country","BE")
            .build();
        Request request = new Request.Builder()
          .url(host + "/creditor/sign")
          .post(body)
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .addHeader("authorization", authorisation)
          .addHeader("cache-control", "no-cache")
          .build();

        Response response = client.newCall(request).execute();
    }
}

public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        ct ="**ct_id**",
        authorisation = null; // collected through logIn

    public void inviteAndSign(){
        RestClient client = new RestClient(host + "/creditor/sign");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("authorization", authorisation);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddParameter("application/x-www-form-urlencoded",
            "method=sms" +
            "&place=Gent"
            "&ct="+ ct +
            "&iban=BE68068897250734" +
            "&bic=GKCCBEBB" +
            "&email=support%40twikey.com" +
            "&lastname=Twikey" +
            "&firstname=Support" +
            "&mobile=%2B32479123123" +
            "&address=Stationstraat%2043" +
            "&city=Gent" +
            "&zip=9051" +
            "&country=BE" +
            , ParameterType.RequestBody);
        IRestResponse response = client.Execute(request);
    }
}

{
  "MndtId": "MyMandateId"
}

{
  "MndtId": "MNDT123",
  "url": "https://e2emerchant.itsme.be/oidc/authorization?response_type=code&client_id=M48..."
}

Create a contract with an invitation/signature directly via API. Note that this call can require different parameters depending on the method of signature. All parameters are described in Create contracts When enabled for your contract it is possible to negotiate mandates with their signature directly via API. Depending on the method the set of required parameters and/or handling may differ. Methods currently supported :

• bancontact (or bcmc)
• sms: require the mobile parameter
• itsme
• paper: preview the document or send a print invite via email
  • 'print the document and return the signed document via e-mail or upload.' must be enabled in the template under 'options'.
  • Include the parameter 'sendInvite: true' to directly send the invitation via email.
  • When 'sendInvite' is not passed or false, nothing is sent out.
  • The response includes a preview of the PDF in base64 format.
• import: import the mandate with a specific signdate
  • Either reference to an existing customer using email or customerNumber
  • For new customers you need to pass the address parameters( address, city, zip, country)
  • B2B: When using the method 'import' for a B2B profile, the mandate is directly signed. To require bank validation use bankSignature: false
• digisign: wet signature encoded as a base64 png (max 150 k)
• emachtiging, idin: requires the bic parameter You can retrieve the connected banks and bic codes using fetch connected banks

Credit cards:

Some psp's have limited support for some more exotic methods, please see the integration page in Twikey to verify if your method is supported.

HTTP Request

POST https://api.twikey.com/creditor/sign

Query Parameters

Same parameters as the invite call +

HTTP Response

Error codes

Mandate Feed

curl https://api.twikey.com/creditor/mandate \
  -H 'authorization: **authorization**' \

$twikey->document->feed(new class implements DocumentCallback {
   function handleNew($update)
   {
       print("New " . $update->Mndt->MndtId . ' @ '. $update->EvtTime . "\n");
   }

   function handleUpdate($update)
   {
       $rsn = $update->AmdmntRsn->Rsn;
       print("Update: " . $update->Mndt->MndtId . ' -> '. $rsn . ' @ '. $update->EvtTime . "\n");
   }

   function handleCancel($update)
   {
       $rsn = $update->CxlRsn->Rsn;
       print("Cancel: " . $update->OrgnlMndtId . ' -> '. $rsn . ' @ '. $update->EvtTime . "\n");
   }
}
);

import twikey

class MyDocumentFeed(twikey.DocumentFeed):
    def newDocument(self, doc, evt_time):
        print("new ", doc["MndtId"])

    def updatedDocument(self, original_mandate_number, doc, reason, evt_time):
        print("update ", doc["MndtId"], "b/c", reason["Rsn"])

    def cancelDocument(self, doc_number, reason, evt_time):
        print("cancelled ", doc_number, "b/c", reason["Rsn"])

twikey.TwikeyClient.document.feed(MyDocumentFeed())

foreach(var mandateUpdate in await twikeyClient.Document.FeedAsync())
{
    if(mandateUpdate.IsNew())
    {
        Console.WriteLine("New mandate: " + JsonConvert.SerializeObject(mandateUpdate, Formatting.Indented));
    }
    else if(mandateUpdate.IsUpdated())
    {
        Console.WriteLine("Updated mandate: " + JsonConvert.SerializeObject(mandateUpdate, Formatting.Indented));
    }
    else if(mandateUpdate.IsCancelled())
    {
        Console.WriteLine("Cancelled mandate: " + JsonConvert.SerializeObject(mandateUpdate, Formatting.Indented));
    }
}

err := c.DocumentFeed(context.Background(), 
    func(mandate *Mndt, eventTime string, eventId int64) {
        fmt.println("Document created   ", mandate.MndtId, " @ ", eventTime)
    }, func(originalMandateNumber string, mandate *Mndt, reason *AmdmntRsn, eventTime string, eventId int64) {
        fmt.println("Document updated   ", originalMandateNumber, reason.Rsn, " @ ", eventTime)
    }, func(mandateNumber string, reason *CxlRsn, eventTime string, eventId int64) {
        fmt.println("Document cancelled ", mandateNumber, reason.Rsn, " @ ", eventTime)
    })

twikeyClient.document().feed(new DocumentCallback() {
    @Override
    public void newDocument(JSONObject newMandate) {
        System.out.println("New mandate: "+newMandate);
    }

    @Override
    public void updatedDocument(JSONObject updatedMandate) {
        System.out.println("Updated mandate: "+updatedMandate);
    }

    @Override
    public void cancelledDocument(JSONObject cancelledMandate) {
        System.out.println("Cancelled mandate: "+cancelledMandate);
    }
})

const feed = client.document.feed();
for await (const document of feed) {
   if (document.IsNew) {
      console.log("New mandate: ",newMandate)
   }
   if (document.IsUpdated) {
      console.log("Updated mandate: ",newMandate)
   }
   if (document.IsCancelled) {
      console.log("Cancelled mandate: ",newMandate)
   }
}

{
  "GrpHdr": {
    "CreDtTm": "2021-04-09T12:49:46Z"
  },
  "Messages": [
    {
      "Mndt": {
        "MndtId": "B2B38434",
        "LclInstrm": "B2B",
        "Ocrncs": {
          "SeqTp": "RCUR",
          "Frqcy": "ADHO",
          "Drtn": {
            "FrDt": "2021-04-09"
          }
        },
        "CdtrSchmeId": "BE81ZZZ1234567891",
        "Cdtr": {
          "Nm": "Merchant Company",
          "PstlAdr": {
            "AdrLine": "Companystreet 100",
            "PstCd": "1000",
            "TwnNm": "Brussel",
            "Ctry": "BE"
          },
          "Id": "BE0123456789",
          "CtryOfRes": "BE",
          "CtctDtls": {
            "EmailAdr": "merchant.email@example.com"
          }
        },
        "Dbtr": {
          "Nm": "Twikey NV",
          "PstlAdr": {
            "AdrLine": "Stationstraat 43",
            "PstCd": "9051",
            "TwnNm": "Gent",
            "Ctry": "BE"
          },
          "Id": "BE0533800797",
          "CtryOfRes": "BE",
          "CtctDtls": {
            "EmailAdr": "support@twikey.com",
            "Othr": "custNumber001"
          }
        },
        "DbtrAcct": "BE31798258915655",
        "DbtrAgt": {
          "FinInstnId": {
            "BICFI": "GKCCBEBB",
            "Nm": "BELFIUS BANK"
          }
        },
        "RfrdDoc": "Terms and Conditions",
        "SplmtryData": [
          {
            "Key": "SignerMethod#0",
            "Value": "maestro"
          },
          {
            "Key": "Signer#0",
            "Value": "Mock Maestro"
          },
          {
            "Key": "SignerPlace#0",
            "Value": "Ghent"
          },
          {
            "Key": "SignerDate#0",
            "Value": "2021-04-09T13:18:19Z"
          }
        ]
      },
      "EvtTime": "2021-04-09T13:19:19Z"
    },
    {
      "Mndt": {
        "MndtId": "NL-B2B60",
        "LclInstrm": "B2B",
        "Ocrncs": {
          "SeqTp": "RCUR",
          "Frqcy": "ADHO",
          "Drtn": {
            "FrDt": "2021-04-09"
          }
        },
        "MaxAmt": "1000",
        "CdtrSchmeId": "BE81ZZZ1234567891",
        "Cdtr": {
          "Nm": "Merchant Company",
          "PstlAdr": {
            "AdrLine": "Companystreet 100",
            "PstCd": "1000",
            "TwnNm": "Brussel",
            "Ctry": "BE"
          },
          "Id": "BE123456789",
          "CtryOfRes": "BE",
          "CtctDtls": {
            "EmailAdr": "merchant.email@example.com"
          }
        },
        "Dbtr": {
          "Nm": "Twikey BV",
          "PstlAdr": {
            "AdrLine": "Bargelaan 200",
            "PstCd": "2333CW",
            "TwnNm": "Leiden",
            "Ctry": "NL"
          },
          "Id": "65772989",
          "CtryOfRes": "NL",
          "CtctDtls": {
            "EmailAdr": "support@twikey.com",
            "Othr": "custNumber002"
          }
        },
        "DbtrAcct": "BE31798258923546",
        "DbtrAgt": {
          "FinInstnId": {
            "BICFI": "GKCCBEBB",
            "Nm": "BELFIUS BANK"
          }
        },
        "RfrdDoc": "General terms and conditions",
        "SplmtryData": [
          {
            "Key": "SignerMethod#0",
            "Value": "mock"
          },
          {
            "Key": "Signer#0",
            "Value": "Twikey Mock Signer"
          },
          {
            "Key": "SignerPlace#0",
            "Value": "Ghent"
          },
          {
            "Key": "SignerDate#0",
            "Value": "2021-04-09T12:49:42Z"
          }
        ]
      },
      "EvtTime": "2021-04-09T13:19:34Z"
    },
    {
      "AmdmntRsn": {
        "Orgtr": {
          "Nm": "Twikey NV",
          "PstlAdr": {
            "AdrLine": "Stationstraat 43",
            "PstCd": "9000",
            "TwnNm": "Gent",
            "Ctry": "BE"
          },
          "Id": "BE0533800797",
          "CtryOfRes": "BE",
          "CtctDtls": {
            "EmailAdr": "support@twikey.com"
          }
        },
        "Rsn": "_T50"
      },
      "Mndt": {
        "MndtId": "CF2498",
        "LclInstrm": "CORE",
        "Ocrncs": {
          "SeqTp": "RCUR",
          "Frqcy": "ADHO",
          "Drtn": {
            "FrDt": "2021-04-09"
          }
        },
        "CdtrSchmeId": "BE81ZZZ1234567891",
        "Cdtr": {
          "Nm": "Merchant Company",
          "PstlAdr": {
            "AdrLine": "Companystreet 100",
            "PstCd": "1000",
            "TwnNm": "Brussel",
            "Ctry": "BE"
          },
          "Id": "BE123456789",
          "CtryOfRes": "BE",
          "CtctDtls": {
            "EmailAdr": "merchant.email@example.com"
          }
        },
        "Dbtr": {
          "Nm": "Company NV",
          "PstlAdr": {
            "AdrLine": "streetname 100",
            "PstCd": "1000",
            "TwnNm": "Brussel",
            "Ctry": "BE"
          },
          "Id": "BE0154521254",
          "CtryOfRes": "BE",
          "CtctDtls": {
            "EmailAdr": "customer.email@example.com",
            "Othr": "custNumber00125"
          }
        },
        "DbtrAcct": "BE12123356223353",
        "DbtrAgt": {
          "FinInstnId": {
            "BICFI": "GKCCBEBB",
            "Nm": "BELFIUS BANK"
          }
        },
        "RfrdDoc": "HvvGeWz627a",
        "SplmtryData": [
          {
            "Key": "SignerMethod#0",
            "Value": "print"
          },
          {
            "Key": "Signer#0",
            "Value": "customer.email@example.com"
          },
          {
            "Key": "SignerPlace#0",
            "Value": "(Imported)"
          },
          {
            "Key": "SignerDate#0",
            "Value": "2021-04-09T10:03:44Z"
          }
        ]
      },
      "OrgnlMndtId": "CF2498",
      "CdtrSchmeId": "BE81ZZZ1234567891",
      "EvtTime": "2021-04-09T13:26:53Z"
    },
    {
      "CxlRsn": {
        "Orgtr": {
          "Nm": "Twikey NV",
          "PstlAdr": {
            "AdrLine": "Stationstraat 43",
            "PstCd": "9000",
            "TwnNm": "Gent",
            "Ctry": "BE"
          },
          "Id": "BE0533800797",
          "CtryOfRes": "BE",
          "CtctDtls": {
            "EmailAdr": "support@twikey.com"
          }
        },
        "Rsn": "Custom cancel reason"
      },
      "OrgnlMndtId": "CF2506",
      "CdtrSchmeId": "BE81ZZZ1234567891",
      "EvtTime": "2021-04-09T13:30:51Z"
    }
  ]
}

Returns a List of all updated mandates (new, changed or cancelled) since the last call. From the moment there are changes (eg. a new contract/mandate or an update of an existing contract) this call provides all related information to the creditor. The service is initiated by the creditor and provides all MRI information (and extra metadata) to the creditor. This call can either be triggered by a callback once a change was made or periodically when no callback can be made. This information can serve multiple purposes:

• Updating a CRM system to take appropriate actions (eg. call the customer on cancel..)
• Integrate the info in an ERP system to create the correct SDD files (in case of mandates)

In order too avoid polling, a webhooks can be setup to notify the client when new information is available. This hook can be configured in the Settings > API.

There are 3 possible updates.

• The first one is when a new signed mandate is available.
• The second is an amendment on a mandate (like address change). Indicated by the existence of an "AmdmntRsn".
• Last one is a cancellation of a mandate. Indicated by the existence of a "CxlRsn"

Amendments and cancellation:

• Updates on unsigned (prepared) agreemenets are not included
• Retrieving the feed after a mandate was signed and cancelled will only return the event for the cancel.

Messages - SplmtryData

Each Message consists of a Mndt object containing all basic information such as merchant information (Cdtr), the customer information (Dbtr), mandate details, ..

The SplmtryData contains all non-structured data: custom attributes, plans, signer(s), ..
By default all attributes are returned, but this can be changed using the include parameter.

See Query Parameters for all possible values.

Messages - Seq

For each Message we also return the event date and time. This can be extended by the event id.
The event id is a sequence number - but is not sequential necessarily in your feed - used as identifier for the message.

To return the event identifier you can use the include parameter: include=seq
When you use include parameters, only those are returned.
See Query Parameters for all values.

Read the high level structure document for a more in depth explanation.

Signed, Updated, Cancelled

Signed

A signed mandate will be returned in the feed including all the mandate, creditor, debtor details and the supplementary data. Supplementary data returns several keys: Each person that signed the document will be returned for each key using consecutive numbers #0, #1, .. .

• The signer(s) name: Signer#0, Signer#1, ..
• The method used by each signer: SignerMethod#0
• The place: SignerPlace#0 (city name, imported, ..)
• The date: SignerDate#0

This is returned in the "SplmtryData[key|value]" array.

Updated

When a document is updated, it is returned in the feed as amendment with initiator and reason:

• AmdmntRsn
• Orgtr (contains the details about the initiator)
• Rsn

The "Rsn" value informs you about the change, this can be information on the mandate that was updated or information about the mandate state. Examples:

• Rsn: uncollectable|user (mandate was suspended by a user)
• Rsn: collectable (mandate was activated, collectable again)
• Rsn: _T50 (specific T5 codes - see Types: Specific codes)
• Rsn: key|value (a (custom) attribute value was changed or added)
  • This can be a 'plan' for example or a custom attribute 'amount'
  • E.g.: "change|amount=5000" (attribute "amount" was changed to a new value)
• Rsn: _DUN (mandate is cancelled due to a dunning step)

Cancelled

When a mandate was cancelled, this is returned as Cancelled reason with initiator and reason:

• CxlRsn
• Orgtr (contains the details about the initiator)
• Rsn

The "Rsn" value can be a custom reason the user, bank or debtor entered on cancellation. This can also contain the reason of cancellation in case of automated dunning steps. Examples:

• Rsn: Transaction disputed (automated dunning step to cancel the mandate in this case)
• Rsn: custom reason (by user, customer,..)

HTTP Request

GET https://api.twikey.com/creditor/mandate

Headers

Query Parameters

To reduce the feed and only return information you need, you can opt to use the include parameters.
Example: GET /creditor/mandate?include=mandate&include=signature

HTTP Response

Error Codes

Mandate query

Create a search query to return all contracts for a specific iban, customer or a combination of different query parameters.
The response is limited to a set of 500 contracts per page. The response returns the contracts found based on your search query.

This request is rate limited.

curl https://api.twikey.com/creditor/mandate/query?iban=BE21798857497403 \
  -H 'authorization: **authorization**' \

$host = "https://api.twikey.com";
$ct = **ct_id**;$authorisation = null; //collected through login

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/mandate/query?iban=BE21798857497403");
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");

$server_output = curl_exec ($ch);
$result = json_decode($server_output);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/mandate/query?iban=BE21798857497403',
        method: 'GET',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        }
    };

var req = https.request(options, function (res) {
    console.log(res);
});

public class TwikeyApi{
    private String host = "https://api.twikey.com";
    private String authorisation = null; //collected through logIn

    public void updateFeed(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
          .url(host + "/creditor/mandate/query?iban=BE21798857497403")
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .addHeader("authorization", authorisation)
          .build();

        Response response = client.newCall(request).execute();
    }
}

public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        authorisation = null; // collected through logIn

    public void updateFeed(){
        RestClient client = new RestClient(host + "/creditor/mandate/query?iban=BE21798857497403");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}

{
  "Contracts": [
    {
      "id": 3291639,
      "type": "CORE",
      "state": "SIGNED",
      "suspended": false,
      "pdfAvailable": true,
      "mandateNumber": "MNDT123",
      "contractNumber": "General Terms",
      "ct": 2223,
      "signDate": "2024-03-01T15:02:45Z",
      "iban": "BE21798857497403",
      "bic": "GKCCBEBB",
      "attributes": {
        "vehicle": null,
        "km": null
      }
    },
    {
      "id": 3291538,
      "type": "CORE",
      "state": "SIGNED",
      "suspended": true,
      "pdfAvailable": true,
      "mandateNumber": "MNDT456",
      "contractNumber": "General Terms",
      "ct": 2223,
      "signDate": "2024-03-01T13:44:39Z",
      "iban": "BE21798857497403",
      "bic": "GKCCBEBB",
      "attributes": {
        "vehicle": "Sedan",
        "km": "12000"
      }
    }
  ],
  "_links": {
    "self": "/creditor/mandate/query?page=0"
  }
}

HTTP Request

GET https://api.twikey.com/creditor/mandate/query?parameter=value

Query Parameters

At least one of iban, customerNumber or emailis required. state is optional. A combination of these parameters is possible.

• customerNumber is prioritized over email when you combine both.
• state: possible values are SIGNED, PREPARED or CANCELLED.

HTTP Response

Error codes

Cancel agreements

Agreements can be cancelled by either debtor or creditor, this can be done via the website or the api. However, there may be circumstances in which the creditor receives the cancel not through Twikey. Our advise is to communicate cancellations to Twikey. That way all databases are up to date and in some cases the cancellation is also forwarded to the debtor bank. The creditor, the creditor bank or the debtor bank, can initiate this request. Afterwards the update is distributed to all parties.

curl -X DELETE https://api.twikey.com/creditor/mandate?mndtId123&rsn=test \
  -H 'authorization: **authorization**'

$host = "https://api.twikey.com";
$ct = **ct_id**;$authorisation = null; //collected through login

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/mandate".
    "?mndtId=mndtId123&rsn=some%20reason"
);
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");
curl_setOpt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
$server_output = curl_exec ($ch);
$result = json_decode($server_output);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/mandate?mndtId=**mdntId**&rsn=some%20reason',
        method: 'DELETE',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        }
    };

var req = https.request(options, function (res) {
    console.log(res);
});

public class TwikeyApi{
    private String host = "https://api.twikey.com";
    private String authorisation = null; //collected through logIn

    public void cancelMandate(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
          .url(host + "/creditor/mandate?mndtId=**mndtId&rsn=some%20reason")
          .delete(null)
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .addHeader("authorization", authorisation)
          .build();

        Response response = client.newCall(request).execute();
    }
}

public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        authorisation = null; // collected through logIn

    public void cancelMandate(){
        RestClient client = new RestClient(host + "/creditor/mandate" +
            "?mndtId=mndtId123" +"
            &rsn=some%20reason"
        );
        RestRequest request = new RestRequest(Method.DELETE);
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

DELETE https://api.twikey.com/creditor/mandate

Query Parameters

HTTP Response

Error codes

Fetch mandate details

Retrieve details of a specific mandate. Since the structure of the mandate is the same as in the update feed but doesn't include details about state, 2 extra headers are added. Though this is perfect for one-offs, for updates we recommend using the feed.

This request is rate limited.

curl https://api.twikey.com/creditor/mandate/detail?mndtId=mndtId123 \
  -H 'authorization: **authorization**'

$host = "https://api.twikey.com";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/mandate/detail" . "
    ?mndtId=mndtId123"
);
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");
curl_setOpt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$server_output = curl_exec ($ch);
$result = json_decode($server_output);
curl_close ($ch);

const details = await client.document.detail(importedMandate);
console.log(details);

public class TwikeyApi{
    private String host = "https://api.twikey.com";
    private String authorisation = null; //collected through logIn

    public void getMandateDetail(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
          .get()
          .url(host +
            "/creditor/mandate/detail" +
            "?mndtId=mndtId123"
          )
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .addHeader("authorization", authorisation)
          .build();

        Response response = client.newCall(request).execute();
    }
}

public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        authorisation = null; // collected through logIn

    public void getMandateDetail(){
        RestClient client = new RestClient(host +
            "/creditor/mandate/detail" +
            "?mndtId=mndtId123"
        );
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}

{
  "Mndt": {
    "MndtId": "MNDT8380",
    "LclInstrm": "CORE",
    "Ocrncs": {
      "SeqTp": "RCUR",
      "Frqcy": "ADHO",
      "Drtn": {
        "FrDt": "2022-09-28"
      }
    },
    "CdtrSchmeId": "BE81ZZZ1234567891",
    "Cdtr": {
      "Nm": "Merchant Company",
      "PstlAdr": {
        "AdrLine": "Companystreet  51N",
        "PstCd": "9000",
        "TwnNm": "Gent",
        "Ctry": "BE"
          },
      "Id": "BE0123456789",
      "CtryOfRes": "BE",
      "CtctDtls": {
        "EmailAdr": "merchant.email@example.com"
      }
    },
    "Dbtr": {
      "Nm": "Luke Devon",
      "PstlAdr": {
        "AdrLine": "Stationstraat 43",
        "PstCd": "9051",
        "TwnNm": "Gent",
        "Ctry": "BE"
      },
      "CtryOfRes": "BE",
      "CtctDtls": {
        "EmailAdr": "debtor@example.com",
        "Othr": "custNumber001"
      }
    },
    "DbtrAcct": "BE31798258915655",
    "DbtrAgt": {
      "FinInstnId": {
        "BICFI": "GKCCBEBB",
        "Nm": "BELFIUS BANK"
      }
    },
    "RfrdDoc": "Terms and Conditions",
    "SplmtryData": [
      {
        "Key": "TRACKER",
        "Value": "rWFq"
      },
      {
        "Key": "MandateName",
        "Value": "Core Mandate"
      },
      {
        "Key": "TemplateId",
        "Value": 2223
      },
      {
        "Key": "amount",
        "Value": "10"
      },
      {
        "Key": "licenseplate",
        "Value": "1-AAA-001"
      },
      {
        "Key": "plan",
        "Value": null
      },
      {
        "Key": "FirstName",
        "Value": "Luke"
      },
      {
        "Key": "LastName",
        "Value": "Devon"
      },
      {
        "Key": "Language",
        "Value": "nl"
      },
      {
        "Key": "SignerMethod#0",
        "Value": "print"
      },
      {
        "Key": "Signer#0",
        "Value": "Luke Devon"
      },
      {
        "Key": "SignerPlace#0",
        "Value": "(Imported)"
      },
      {
        "Key": "SignerDate#0",
        "Value": "2022-09-28T13:42:14Z"
      }
    ]
  }
}

HTTP Request

GET https://api.twikey.com/creditor/mandate/detail

Query Parameters

Response

Header Response

Possible states

Possible events

Error codes

Update mandate details

You can change details of a mandate. Note: Include email only when changing it's value. bic code is generated automatically based on iban if not included. Custom attributes that are defined in the template can also be updated.

Note: Company name and language are always updated on the mandate itself, not the owner. Note: Mobile number and email are always updated on both the mandate and customer.

curl POST 'https://api.twikey.com/creditor/mandate/update' \
--h 'Authorization: ....' \
--d 'mndtId=MDT123' \
--d 'address=Stationstraat 43' \
--d 'zip=9000' \
--d 'city=Gent' \
--d 'country=BE' \
--d 'mobile=+32 483 115862' \
--d 'iban=BE75 0509 9307 0051' \
--d 'bic=BRUBBEB'

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.twikey.com/creditor/mandate/update',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => 'mndtId=MDT123&address=Stationstraat%2043&zip=9000&city=Gent&country=BE&iban=BE32%201234%201234%201234&bic=BRUBBEB',
  CURLOPT_HTTPHEADER => array(
    'Authorization: ....'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var myHeaders = new Headers();
myHeaders.append("Authorization", "....");

var urlencoded = new URLSearchParams();
urlencoded.append("mndtId", "MDT123");
urlencoded.append("address", "Stationstraat 43");
urlencoded.append("zip", "9000");
urlencoded.append("city", "Gent");
urlencoded.append("country", "BE");
urlencoded.append("iban", "BE32 1234 1234 1234");
urlencoded.append("bic", "BRUBBEB");

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("https://api.twikey.com/creditor/mandate/update", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "mndtId=MDT123&address=Stationstraat 43&zip=9000&city=Gent&country=BE&iban=BE32 1234 1234 1234&bic=BRUBBEB");
Request request = new Request.Builder()
  .url("https://api.twikey.com/creditor/mandate/update")
  .method("POST", body)
  .addHeader("Authorization", "....")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.twikey.com/creditor/mandate/update");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "....");
request.AddParameter("mndtId", "MDT123");
request.AddParameter("address", "Stationstraat 43");
request.AddParameter("zip", "9000");
request.AddParameter("city", "Gent");
request.AddParameter("country", "BE");
request.AddParameter("iban", "BE32 1234 1234 1234");
request.AddParameter("bic", "BRUBBEB");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

HTTP Request

POST https://api.twikey.com/creditor/mandate/update

Query Parameters

B2B type mandate: iban cannot be updated once the document is signed.

HTTP Response

Error codes

Move a mandate

It is possible to move the mandate to another customer (owner). Include the customer number of the target in the request.

• The email address is updated on the mandate using the new owner's one.
• The mobile number is updated on the mandate using the new owner's one.
• Address and name are preserved on the mandate.
• payment links and invoices remain stored on the original owner. This can be done for both pending and signed mandates.

Mandate actions

curl -X POST "https://api.twikey.com/creditor/mandate/MANDATE_ID_HERE/action" \
  -H "Authorization: Bearer YOUR_API_TOKEN_HERE" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "type=invite"

This endpoint allows you to trigger specific actions on a mandate. The following action types are supported:

HTTP Request

POST https://api.twikey.com/creditor/mandate/{mndtId}/action

Query Parameters

HTTP Response

Error Codes

Customer access

You may want to give your customer access to the mandate details without actually requiring him to get a Twikey account. You can do this by using this call. This call returns a url that you can redirect the user to for a particular mandate.

curl -X POST https://api.twikey.com/creditor/customeraccess \
  -H 'authorization: **authorization**' \
  -d 'mndtId=mndtId123'

$host = "https://api.twikey.com";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/customeraccess");
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");
curl_setOpt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setOpt($ch, CURLOPT_POSTFIELDS, array(
    "mndtId" =>  "mdntId123"
);
$server_output = curl_exec ($ch);
$result = json_decode($server_output);
curl_close ($ch);
?>

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/customeraccess',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body:{
            'mndtId': 'mndtId123'
        }
    };

var req = https.request(options, function (res) {
    console.log(res);
});

public class TwikeyApi{
    private String host = "https://api.twikey.com";
    private String authorisation = null; //collected through logIn

    public void updateMandate(){
        OkHttpClient client = new OkHttpClient();
        RequestBody body = new FormBody.Builder()
                        .add("mndtId", "mndtId123")
                        .build();
        Request request = new Request.Builder()
          .post(body)
          .url(host + "/creditor/customeraccess")
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .addHeader("authorization", authorisation)
          .build();

        Response response = client.newCall(request).execute();
    }
}

public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        authorisation = null; // collected through logIn

    public void updateMandate(){
        RestClient client = new RestClient(host + "/creditor/customeraccess);
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("authorization", authorisation);
        request.AddParameter("application/x-www-form-urlencoded",
            "mndtId=mndtId123" ,
            ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

{
    "token": "A4DE98FD091....",
    "url": "https://merchant.twikey.com/p/customeraccess?token=A4DE98FD0915F"
}

HTTP Request

POST https://api.twikey.com/creditor/customeraccess

Query Parameters

HTTP Response

Error Codes

Retrieve pdf

Retrieve pdf of a mandate

curl https://api.twikey.com/creditor/mandate/pdf?mndtId123 \
  -H 'authorization: **authorization**'

# Example for downloading the content straight to a file
curl -v -X GET https://api.twikey.com/creditor/mandate/pdf?mndtId=mndtId123 -H 'authorization: **authorization**' --output test.pdf

$host = "https://api.twikey.com";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/mandate/pdf?mndtId=mndtId123");
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");
curl_setOpt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$server_output = curl_exec ($ch);
$result = json_decode($server_output);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/mandate/pdf?mndtId=mdntId123',
        method: 'GET',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        }
    };

var req = https.request(options, function (res) {
    console.log(res);
});

public class TwikeyApi{
    private String host = "https://api.twikey.com";
    private String authorisation = null; //collected through logIn

    public void retrievePdf(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
          .get()
          .url(host + "/creditor/mandate/pdf?mndtId=mndtId123")
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .addHeader("authorization", authorisation)
          .build();

        Response response = client.newCall(request).execute();
    }
}

public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        authorisation = null; // collected through logIn

    public void retrievePdf(){
        RestClient client = new RestClient(
            host +
            "/creditor/mandate/pdf" +
            "?mndtId=mndtId123"
        );
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        request.AddParameter("application/x-www-form-urlencoded",
            "mandate.pdf",
            ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

GET https://api.twikey.com/creditor/mandate/pdf

Query Parameters

HTTP Response

Error codes

Upload pdf

Import existing mandate pdf (eg. scan of a printed document) After import the mandate is set on signed state. For B2B mandates the parameter bankSignature determines if it will be offered to the bank (Twikey affiliated banks only)

curl -X POST https://api.twikey.com/creditor/mandate/pdf \
  -H 'authorization: **authorization**' \
  -d 'mndtId=mndtId123' \
  -d @mndtId123.pdf

$host = "https://api.twikey.com";

$post = array(
    "file_box"=>"@/path/to/mndtId123.pdf",
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/mandate/pdf?mndtId=mndtId123");
curl_setOpt($ch, CURLOPT_HTTPHEADER, array(
    "authorization: $authorization",
    "Content-Type: application/pdf',
    "Content-Length: ' . strlen($post))
);
curl_setOpt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setOpt($ch, CURLOPT_POSTFIELDS, $post);
$server_output = curl_exec ($ch);
$result = json_decode($server_output);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null; //collected through login

var requestUrl = 'path/to/import.json';
var request = new XMLHttpRequest();
request.open('GET', requestUrl);
request.responseType = 'json';

request.send();
request.onload = function (){
    var options = {
        host: host,
        port: '443',
        path: '/creditor/mandate/pdf?mndtId=mndtId123',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        data: request.response
    };
    var req = https.request(options, function (res) {
        console.log(res);
    });
};

import java.io.FileReader;
import java.io.BufferedReader;
public class TwikeyApi{
    private String host = "https://api.twikey.com";
    private String authorisation = null; //collected through logIn

    public void uploadPdf(){
        String pdf;
        try{
           FileReader fr = new FileReader("/path/to/mndtId123.pdf");
           BufferedReader br = new BufferedReader(fr);
           String s;
           while((s = br.readLine()) != null) {
               pdf+=s;
           }
           fr.close();
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
          .post(pdf)
          .url(host + "/creditor/mandate/pdf?mndtId=mndtId123")
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .addHeader("authorization", authorisation)
          .build();

        Response response = client.newCall(request).execute();
        } catch (FileNotFoundException e){
            System.out.printLn(e);
        }
    }
}

using System.IO;
public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        authorisation = null; // collected through logIn

    String pdf = file.ReadAllText("\path\to\mndtid123.pdf");

    public void uploadPdf(){
        RestClient client = new RestClient(
            host +
            "/creditor/mandate/pdf" +
            "?mndtId=mndtId123"
        );
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("authorization", authorisation);
        request.AddParameter("application/x-www-form-urlencoded",
            pdf,
            ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

POST https://api.twikey.com/creditor/mandate/pdf

Query Parameters

HTTP Response

Error codes

Retrieve legal terms

Retrieve legal terms

curl https://api.twikey.com/creditor/legal?locale=nl_BE \
  -H 'authorization: authorization'

$host = "https://api.twikey.com";
$authorisation = null; // collected through login

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/legal?locale=nl_BE");
curl_setOpt($ch, CURLOPT_HTTPHEADER,"authorization: $authorization");

$server_output = curl_exec ($ch);
curl_close ($ch);

var https = require('https'),
    host = "api.twikey.com",
    authorization = null, // collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/legal?locale=nl_BE',
        headers: {
            'Content-Type': 'application/json'
        }
    };

var req = https.request(options, function (res) {
        console.log("response: " + res)
});

public class TwikeyApi{
    private String host = "https://api.twikey.com";
    private String authorisation = null; // collected through logIn

    public void createCreditTransfer(){
        OkHttpClient client = new OkHttpClient();

        MediaType mediaType = MediaType.parse("application/json");

        Request request = new Request.Builder()
          .url(host + "/creditor/legal?locale=nl_BE")
          .addHeader("content-type", "application/json")
          .addHeader("authorization", authorisation)
          .addHeader("cache-control", "no-cache")
          .build();

        Response response = client.newCall(request).execute();
    }
}

public class TwikeyAPI {
    private  String host ="https://api.twikey.com",
        authorisation = null; // collected through logIn

    public void createCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/legal?locale=nl_BE");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        request.AddHeader("content-type", "application/json");
        IRestResponse response = client.Execute(request);
    }
}

{
    "tcUrl": "https://www.beta.twikey.com/nl/tc.html",
    "bySigning": "Door ondertekening van dit mandaatformulier ...",
    "rightsCore": "U kunt een Europese domiciliëring laten terugbetalen. Vraag ...",
    "rightsB2b": "Dit mandaat is uitsluitend bedoeld voor betalingen tussen bedrijven. U hebt ...",
    "infoCorrect": ""
}

Parameters

Responses

Subscriptions

Add a subscription

A subscription (previously called plan) can be added on an agreement. This means than when the subscription is run a new transaction will be created using the defined schedule. If you opted for the automatic sending this will be collected as soon as the bank permits it.

request without and with a plan:

curl -X POST https://api.twikey.com/creditor/subscription \
  -H 'authorization: **authorization**' \
  -d 'mndtId=TEST03'\
  -d 'msg=Monthly subscription'\
  -d 'ref=MyRef'\
  -d 'amount=12.00'\
  -d 'recurrence=1m'\
  -d 'start=2022-11-29'
  
curl -X POST https://api.twikey.com/creditor/subscription \
  -H 'authorization: **authorization**' \
  -d 'mndtId=TEST03'\
  -d 'ref=MyRef'\
  -d 'plan=myplan'\
  -d 'start=2022-11-29'

HTTP Request

POST https://api.twikey.com/creditor/subscription

{
    "id": 10,
    "state": "active",
    "amount": 12.0,
    "message": "Monthly subscription",
    "ref": "MyRef",
    "plan": 0,
    "runs": 0,
    "stopAfter": 5,
    "start": "2022-11-29",
    "next": "2022-12-01",
    "recurrence": "1m",
    "mndtId": "TEST03"
}

Request Headers

Query Parameters

[*1]: The reference is converted to uppercase and can't contain any spaces.

HTTP Response

Error codes

Update a Subscription

This endpoint allows you to create a new subscription based on an existing one. The current subscription is cancelled and a new one is created using the same reference.

curl -X POST https://api.twikey.com/creditor/subscription/:agreement/:ref \
  -H 'authorization: **authorization**' \
  -d 'mndtId=MNDT123' \
  -d 'start=2025-05-05' |
  -d 'message=mymessage'\
  -d 'plan=planName'\
  -d 'amount=10.22'

HTTP Request

POST https://api.twikey.com/creditor/subscription/:agreement/:ref

:agreement: the mandate reference (e.g.: MNDT123)
:ref : the reference of the subscription

{
    "id": 10,
    "state": "active",
    "amount": 10.22,
    "message": "mymessage",
    "ref": "reference123",
    "plan": 0,
    "runs": 0,
    "stopAfter": 5,
    "start": "2022-11-29",
    "next": "2022-12-01",
    "recurrence": "1m",
    "mndtId": "TEST03"
}

Query Parameters

Notes

• If you intend not to cancel the current subscription, consider using our PATCH Subscription request instead.

HTTP Response

Error codes

Patch a subscription

To update a subscription but not cancel it, you can use this endpoint. It allows you to update specific fields or move the subscription to a different mandate.

curl -X PATCH https://api.twikey.com/creditor/subscription/MNDT100/myreference
?mndtId=MNDT200&message=mymessage&amount=25
  -H 'authorization: **authorization**' 

HTTP Request

PATCH https://api.twikey.com/creditor/subscription/:agreement/:ref{queryparameters}

:agreement: the mandate reference (e.g.: MNDT123)
:ref : the reference of the subscription

{
    "id": 10,
    "state": "active",
    "amount": 25.0,
    "message": "mymessage",
    "ref": "myreference",
    "plan": 0,
    "runs": 0,
    "stopAfter": 5,
    "start": "2024-11-29",
    "next": "2024-12-01",
    "recurrence": "1m",
    "mndtId": "MNDT200"
}

URL Query Parameters

HTTP Response

Error codes

Cancel a subscription

A subscription can be cancelled by using it's ref for a specific agreement.

curl -X DELETE https://api.twikey.com/creditor/subscription/:agreement/:ref \
  -H 'authorization: **authorization**' 

HTTP Request

DELETE https://api.twikey.com/creditor/subscription/:agreement/:ref

HTTP Response

Error codes

Retrieve a single subscription

A single subscription can be fetched for a specific agreement, but note that this call is rate limited.

curl https://api.twikey.com/creditor/subscription/:agreement/:ref \
  -H 'authorization: **authorization**' 

HTTP Request

GET https://api.twikey.com/creditor/subscription/:agreement/:ref

{
    "id": 10,
    "state": "active",
    "amount": 12.0,
    "message": "Monthly subscription",
    "ref": "MyRef",
    "plan": 0,
    "runs": 0,
    "stopAfter": 5,
    "start": "2022-11-29",
    "last": null,
    "next": "2022-12-01",
    "recurrence": "1m",
    "mndtId": "MNDT123"
}

Path Parameters

HTTP Response

Error codes

Query all subscription

All subscription can be retrieved based on some criteria.

This request is rate limited.

curl -X POST https://api.twikey.com/creditor/subscription/query?mndtId=mdntId123&customerNumber=123&state=active \
  -H 'authorization: **authorization**'

{
  "Subscriptions": [
    {
      "id": 10,
      "state": "active",
      "amount": 12.0,
      "message": "Message for customer",
      "ref": "MyRef",
      "plan": 0,
      "runs": 0,
      "stopAfter": 5,
      "start": "2022-10-29",
      "last": "2022-11-29",
      "next": "2022-12-01",
      "recurrence": "1m",
      "mndtId": "PLOPSAABO3"
    },
    ...
  ]
}

HTTP Request

GET https://api.twikey.com/creditor/subscription/query

Query Parameters

HTTP Response

Error codes

No specific error codes. When passing incorrect values the response will return an empty subscriptions array.

Action a subscription

A subscription can be suspended/resumed by using it's ref for a specific agreement.

curl -X POST https://api.twikey.com/creditor/subscription/:agreement/:ref/:action \
  -H 'authorization: **authorization**' 

HTTP Request

POST https://api.twikey.com/creditor/subscription/:agreement/:ref/:action

Where action is either 'suspend' or 'resume'

HTTP Response

Error codes

Transactions

New transaction

Add transaction to an existing mandate. This transaction will be sent to the bank when the collection is sent to the bank either automatically or manually.

HTTP Request

POST /creditor/transaction

curl -X POST https://api.twikey.com/creditor/transaction \
  -H 'authorization: **authorization**'\
  -d 'mndtId=mndtId123' \
  -d 'message=Monthly payment' \
  -d 'amount=10'

$host = "https://api.twikey.com";
$authorization = null; /collected through logIn

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transaction");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,"mndtId=mndtId123"
    ."&message=Monthly payment"
    ."&amount=10");
$server_output = curl_exec ($ch);
curl_close ($ch);

const transaction = await client.transaction.create({
    mndtId: "CORERECURRENTNL16318",
    message: "Test message",
    amount: 500,
});

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; //collected through logIn
    public void addTransaction(){
        OkHttpClient client = new OkHttpClient();
        RequestBody body = new FormBody.Builder()
            .add("mndtId", "mndtId123")
            .add("message", "Monthly payment")
            .add("amount", "10")
            .build();

        Request request = new Request.Builder()
            .url(host + "/creditor/transaction")
            .post(body)
            .addHeader("content-type", "application/x-www-form-urlencoded")
            .addHeader("authorization", authorization)
            .build();

        Response response = client.newCall(request).execute();
    };
}

public class TwikeyAPI {
    private String host ="https://api.twikey.com",
        authorization =null; //collected through logIn

    public void addTransaction(){
        RestClient client = new RestClient(host + "/creditor/transaction");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);
        request.AddParameter("application/x-www-form-urlencoded",
            "mndtId=mndtId123" +
            "message=Monthly payment" +
            "amount=10"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

{
  "Entries": [
    {
      "id": 381563,
      "contractId": 325638,
      "mndtId": "MNDT123",
      "contract": "Algemene voorwaarden",
      "amount": 10.0,
      "msg": "Monthly payment",
      "place": null,
      "ref": null,
      "date": "2017-09-16T14:32:05Z"
    }
  ]
}

Request Headers

Request Parameters

[*1]:

• This is the message that both you and your customer will see on their bank statement. More info..
• Belgium: The message is treated as structured message (OGM) when it is 12-characters long and the check-sum is correct.

HTTP Response

Error codes

Transaction feed

Retrieve list of transactions that had changes since the last call. This endpoint allows to retrieve a list of transactions for which new payment information has been received since the last call. This endpoint doesn't require any parameters. If we receive feedback from the bank, we mark the transaction with status "error" or "paid".

The final flag is important as it indicates whether or not there are still automatic actions going on. True (being final) means that we can't do anything with it anymore. This could be the case for paid transactions as well as for errors where no more automatic actions can be performed. Here an action will be required on your part. False means that we still have actions pending to debit the debtor's account. Note that a paid state paid with final flag on true can be reverted by the bank (refund request by the debtor).

curl https://api.twikey.com/creditor/transaction \
  -H 'authorization: **authorization**'

$host = "https://api.twikey.com";
$authorization = null; /collected through logIn

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transaction");
curl_setopt($ch, CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, 'Authorization : $authorization');
$server_output = curl_exec ($ch);
curl_close ($ch);

const feed = await client.transaction.feed();
for await (const tx of feed) {
    console.log("Updated transaction: ",tx)
}

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; //collected through logIn
    public void getTransactions(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
            .url(host + "/creditor/transaction")
            .get()
            .addHeader("content-type", "application/x-www-form-urlencoded")
            .addHeader("authorization", authorization)
            .build();

        Response response = client.newCall(request).execute();
    };
}

public class TwikeyAPI {
    private String host ="https://api.twikey.com",
        authorization =null; // gathered through logIn

    public void getTransactions(){
        RestClient client = new RestClient(host + "/creditor/transaction");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);

        IRestResponse response = client.Execute(request);
    }
}

{
    "Entries": [
            {
                "id": 123456789,
                "contractId": 10001,
                "mndtId": "mandateReference",
                "contract": "contractNumber",
                "amount": 99.99,
                "msg": "transaction message",
                "place": "web",
                "ref": null,
                "final": true,
                "state": "PAID",
                "bkdate": "2017-03-21T08:13:21Z",
                "reqcolldt": "2017-03-23T08:13:21Z"
        },
        {
                "id": 987654321,
                "contractId": 2002,
                "mndtId": "mandateReference",
                "contract": "contractNumber",
                "amount": 100,
                "admincharge": 10.0,
                "msg": "transaction message",
                "place": "web",
                "ref": "INVOICE001",
                "final": false,
                "state": "ERROR",
                "bkerror": "MS03",
                "bkmsg": "Geen reden opgegeven",
                "bkdate": "2016-09-21T08:13:21Z",
                "reqcolldt": null
        },
        {
                "id": 56789123,
                "contractId": 3003,
                "mndtId": "mandateReference",
                "contract": "contractNumber",
                "amount": 49.99,
                "msg": "buy item X",
                "place": "web",
                "ref": null,
                "final": true,
                "state": "ERROR",
                "bkerror": "AC04",
                "bkmsg": "Rekening afgesloten",
                "bkdate": "2016-08-29T13:14:40Z",
                "reqcolldt": null
        },
        "..."
    ]
}

Including all parameters:

{
  "Entries": [
    {
      "id": 218914,
      "contractId": 1320345,
      "mndtId": "MNDT123",
      "contract": "CTR123",
      "amount": 5.63,
      "admincharge": 10.0,
      "msg": "Delivery fee",
      "place": null,
      "ref": "DLVRY EXPRESS 001",
      "date": "2020-12-09T16:07:19Z",
      "final": true,
      "state": "ERROR",
      "bkerror": "AM04",
      "bkmsg": "Insufficient funds",
      "bkdate": "2020-12-09",
      "lastupdate": "2020-12-09T16:07:24Z",
      "bkamount": 0,
      "collection": 9314,
      "reqcolldt": "2020-12-11",
      "link": "https://mycompany.twikey.com/payment/tr_...",
      "actions": [
        {
          "type": "FAIL_SOFT",
          "reason": "AM04",
          "action": "again",
          "at": "2020-12-09T16:07:24Z"
        },
        {
          "type": "FAIL_SOFT",
          "reason": "AM04",
          "action": "backup",
          "at": "2020-12-10T03:30:09Z"
        }
      ]
    }
  ]
}

HTTP Request

GET /creditor/transaction

Headers

include parameter

The include parameter (optional) can be used several times with a different value to include additional information about the transaction in the response.
Example: GET /creditor/transaction?include=collection&include=lastupdate&include=action&include=link

Dunning types

• FAIL_SOFT: Action(s) when insufficient funds
• FAIL_HARD: Action(s) when customer refuses
• TECHNICAL: Action(s) on failure at bank

Dunning actions

• notify: notification sent to the customer
• backup: alternative payment proposed to the customer
• again: re-offer the transaction.
• state: changed state of the mandate
• wik: official WIK letter sent
• paid: partial payment registered with amount as decimal value

Transaction stage values

• NONE: failed and still in dunning.
• UNSETTLED: failed and requires manual action
• WIKLETTER: official WIK letter sent
• AGENCY: sent to the collection agency
• ARCHIVED: planned dunning steps are stopped (those in progress are not)

admincharge

This is returned when a transaction failed and administrative charges were applied.

bkamount

The bkamount is the amount of the transaction was (partially) paid. This value is increased with each partial payment up to a maximum of the total amount.

Possible states

Final flag state

The final flag is only relevant in case of dunning. If a transaction is paid the final state is always true.
Should the transaction change to failed (eg. chargeback) and dunning is configured the final flag changes to false as long as the dunning is running.

Transaction in a state ERROR + final:true require manual action.

HTTP Response

Error codes

Response parameters

Transaction status

Retrieve the status of transactions at a certain point in time, this may change at any time. We strongly recommend using the transaction feed to keep your system up to date as you'll never miss an update while this is merely a snapshot in time.

This request is rate limited.

curl https://api.twikey.com/creditor/transaction/detail?id=1234 \
  -H 'authorization: **authorization**'

$host = "https://api.twikey.com";
$authorization = null; /collected through logIn

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transaction/detail?id=1234");
curl_setopt($ch, CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, 'Authorization : $authorization");
$server_output = curl_exec ($ch);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through logIn
    options = {
        host: host,
        port: '443',
        path: '/creditor/transaction/detail?id=1234',
        method: 'GET',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        }
    };

var req = https.request(options, function (res) {
    console.log("result : ",result);
});

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; //collected through logIn
    public void getTransactionDetail(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
            .url(host + "/creditor/transaction/detail?id=1234")
            .get()
            .addHeader("content-type", "application/x-www-form-urlencoded")
            .addHeader("authorization", authorization)
            .build();

        Response response = client.newCall(request).execute();
    };
}

public class TwikeyAPI {
    private String host ="https://api.twikey.com",
        authorization =null; // gathered through logIn

    public void getTransactionDetail(){
        RestClient client = new RestClient(host + "/creditor/transaction/detail?id=1234");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);

        IRestResponse response = client.Execute(request);
    }
}

{
    "Entries": [
        {
            "id": 1234,
            "amount": 10.0,
            "contract": "Algemene voorwaarden",
            "contractId": 325638,
            "date": "2017-09-16T14:32:05Z",
            "mndtId": "MNDT123",
            "msg": "Monthly payment",
            "place": null,
            "ref": null,
            "state": "OPEN",
            "reqcolldt": "2021-01-11"
        }
    ]
}

Sample response when using multiple parameters:

{
  "Entries": [
    {
      "id": 558295,
      "contractId": 1826643,
      "mndtId": "MNDT123",
      "contract": "TC",
      "amount": 22.0,
      "admincharge": 5.0,
      "msg": "Monthly payment",
      "place": null,
      "ref": null,
      "date": "2022-03-09T12:56:29Z",
      "final": true,
      "state": "ERROR",
      "bkerror": "AC04",
      "bkmsg": "Account closed",
      "bkdate": "2022-03-09",
      "lastupdate": "2022-03-09T13:30:01Z",
      "bkamount": 0,
      "collection": 16336,
      "link": "https://company.twikey.com/payment/tr_zwBA7H9N5cxbOIw4g5drv2b",
      "reqcolldt": "2022-03-11"
    }
  ]
}

HTTP Request

GET /creditor/transaction/detail

Request Parameters

General parameters

state parameter

The state parameter (optional) can be used to return only transactions in a specific state. Most common usage of this is in combination with a mandate id, to retrieve all the transactions in a specific state for that mandate.

Example: GET /creditor/transaction/detail?mndtId=MNDT123&state=error

• [*1]: The state is 'OPEN' when:
  • When the transaction is not yet sent to the bank. The transaction can still be deleted
  • When the transaction is already sent to the bank, but no feedback was received. The transactions can't be deleted

include parameter

The include parameter (optional) can be used several times with a different value to include additional information about the transaction in the response.
Example: GET /creditor/transaction/detail?id=12345&include=collection&include=lastupdate&include=link

Final flag

When a transaction is in a PAID or ERROR state, the final flag is returned in the response.
This can be true or false.

• true: There are no more pending actions. If the transaction is in the state ERROR then a manual action is required.
• false: At least one action is still pending for the transaction.

HTTP Response

Error codes

Action on transaction

Execute an action on a transaction, this will allow you to change the status or start a specific flow for the given transaction.

HTTP Request

POST /creditor/transaction/action

curl -X POST https://api.twikey.com/creditor/transaction/action \
  -H 'authorization: **authorization**'\
  -d 'id=345' \
  -d 'action=reoffer'

$host = "https://api.twikey.com";
$authorization = null; // collected through login

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transaction/action");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,"id=345"
    ."&action=reoffer");
$server_output = curl_exec ($ch);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through logIn
    options = {
        host: host,
        port: '443',
        path: '/creditor/transaction/action',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body :{
            'id' : '345',
            'action': 'reoffer'
        }
    };

var req = https.request(options, function (res) {
    console.log("result : ",result);
});

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; // collected through login
    public void addTransaction() {
        OkHttpClient client = new OkHttpClient();
        RequestBody body = new FormBody.Builder()
            .add("id", "345")
            .add("action", "reoffer")
            .build();

        Request request = new Request.Builder()
            .url(host + "/creditor/transaction/action")
            .post(body)
            .addHeader("content-type", "application/x-www-form-urlencoded")
            .addHeader("authorization", authorization)
            .build();

        Response response = client.newCall(request).execute();
    };
}

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; // collected through login

    public void addTransaction() {
        RestClient client = new RestClient(host + "/creditor/transaction/action");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);
        request.AddParameter("application/x-www-form-urlencoded",
            "id=345" +
            'action=reoffer"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

Request Parameters

*backup: alternative payment method is sent to the customer by email. This can include a payment link or bank transfer details depending on your configuration.

HTTP Response

Error codes

Update a transaction

Update parameters for an existing transaction.

HTTP Request

PUT /creditor/transaction

curl -X PUT https://api.twikey.com/creditor/transaction \
  -H 'authorization: **authorization**'\
  -d 'id=345' \
  -d 'message=Monthly payment' \
  -d 'amount=10'

$host = "https://api.twikey.com";
$authorization = null; /collected through logIn

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transaction");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS,"id=345"
    ."&message=Monthly payment"
    ."&amount=10");
$server_output = curl_exec ($ch);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through logIn
    options = {
        host: host,
        port: '443',
        path: '/creditor/transaction',
        method: 'PUT',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body :{
            'id' : '345',
            'message': 'Monthly payment',
            'amount': '10'
        }
    };

var req = https.request(options, function (res) {
    console.log("result : ",result);
});

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; //collected through logIn
    public void updateTransaction(){
        OkHttpClient client = new OkHttpClient();
        RequestBody body = new FormBody.Builder()
            .add("id", "345")
            .add("message", "Monthly payment")
            .add("amount", "10")
            .build();

        Request request = new Request.Builder()
            .url(host + "/creditor/transaction")
            .put(body)
            .addHeader("content-type", "application/x-www-form-urlencoded")
            .addHeader("authorization", authorization)
            .build();

        Response response = client.newCall(request).execute();
    };
}

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; // collected through login

    public void updateTransaction(){
        RestClient client = new RestClient(host + "/creditor/transaction");
        RestRequest request = new RestRequest(Method.PUT);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);
        request.AddParameter("application/x-www-form-urlencoded",
            "id=345" +
            "message=Monthly payment" +
            'amount=10"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

Request Parameters

HTTP Response

Error codes

Refund a transaction

General transactions

If the beneficiary account does not already exist, the account is added to the customer. The IBAN of the refund account is the one registered on the mandate linked to the transaction. After a refund request, the refund batch need to be prepared to be proccessed.

Credit Card transactions

Currently, supported payment providers for refunds are: CCV, Multisafepay, Mollie In the response the id is 1-on-1 with the refund id from your provider.

curl -X POST https://api.twikey.com/creditor/transaction/refund \
  -H 'authorization: **authorization**'\
  -d 'id=345' \
  -d 'iban=BE12356798' \
  -d 'bic=BBRUBEBB' \
  -d 'message=refund payment' \
  -d 'amount=10'

$host = "https://api.twikey.com";
$authorization = null; /collected through logIn

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transaction/refund");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS,"id=345"
    ."&message=Refund payment"
    ."&iban=BE12356798"
    ."&bic=BBRUBEBB"
    ."&amount=10");
$server_output = curl_exec ($ch);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through logIn
    options = {
        host: host,
        port: '443',
        path: '/creditor/transaction/refund',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body: {
            'id': '345',
            'message': 'Refund payment',
            'amount': '10',
            'iban': 'BE12356798',
            'bic': 'BBRUBEBB'
        }
    };

var req = https.request(options, function (res) {
    console.log("result : ", result);
});

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; //collected through logIn

    public void refundTransaction() {
        OkHttpClient client = new OkHttpClient();
        RequestBody body = new FormBody.Builder()
            .add("id", "345")
            .add("message", "Refund payment")
            .add("amount", "10")
            .add("iban", "BE12356798")
            .add("bic", "BBRUBEBB")
            .build();

        Request request = new Request.Builder()
            .url(host + "/creditor/transaction/refund")
            .post(body)
            .addHeader("content-type", "application/x-www-form-urlencoded")
            .addHeader("authorization", authorization)
            .build();

        Response response = client.newCall(request).execute();
    }

    ;
}

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; // collected through login

    public void refundTransaction(){
        RestClient client = new RestClient(host + "/creditor/transaction/refund");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);
        request.AddParameter("application/x-www-form-urlencoded",
            "id=345" +
            "&message=Refund payment" +
            "&amount=10"
            "&iban=BE12356798"
            "&bic=BBRUBEBB"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

POST /creditor/transaction/refund

Request Headers

Request Parameters

{
    "Entries": [
        {
            "id": "9FD3492820210119162251192138",
            "iban": "BE123456789",
            "bic": "GKCCBEBB",
            "amount": 10.0,
            "msg": "Refund payment",
            "place": "Ghent",
            "ref": "refund reference 123",
            "date": "2021-01-19"
        }
    ]
}

HTTP Response

Error codes

Remove a transaction

Remove a transaction that wasn't sent to the bank yet based on the id and/or reference.

curl -X DELETE https://api.twikey.com/creditor/transaction \
  -H 'authorization: **authorization**'

$host = "https://api.twikey.com";
$authorization = null; /collected through logIn

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transaction");
curl_setopt($ch, CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_HTTPHEADER, 'Authorization : $authorization");
$server_output = curl_exec ($ch);
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through logIn
    options = {
        host: host,
        port: '443',
        path: '/creditor/transaction',
        method: 'DELETE',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        }
    };

var req = https.request(options, function (res) {
    console.log("result : ", result);
});

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        authorization = null; //collected through logIn

    public void removeTransaction() {
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
            .url(host + "/creditor/transaction")
            .delete(null)
            .addHeader("content-type", "application/x-www-form-urlencoded")
            .addHeader("authorization", authorization)
            .build();

        Response response = client.newCall(request).execute();
    }

    ;
}

public class TwikeyAPI {
    private String host ="https://api.twikey.com",
        authorization =null; // gathered through logIn

    public void removeTransaction(){
        RestClient client = new RestClient(host + "/creditor/transaction");
        RestRequest request = new RestRequest(Method.DELETE);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);

        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

DELETE /creditor/transaction

Request Parameters

At least one parameter must be passed in the request.

HTTP Response

Error codes

Query transactions

Sequentially retrieve all created transactions starting from any given transaction ID. This endpoint is meant only for exporting transactions in bulk and registering transactions created by subscriptions.
We strongly recommend using the transaction feed to keep your system up to date as you'll never miss an update while this is merely a snapshot in time.

This request is rate limited.

curl https://api.twikey.com/creditor/transaction/query?fromId=1000000 \
  -H 'authorization: **authorization**' 

{
    "Entries": [
        {
            "id": 4692115,
            "contractId": 3408156,
            "ct": 3764,
            "subscriptionId": 230863,
            "mndtId": "EXAMPLE-AI3I",
            "amount": 623.0,
            "msg": "Bike",
            "place": null,
            "ref": "F7B2F7F3910D4B139AE2A3D7C20677E4",
            "date": "2024-08-27T08:26:19Z",
            "final": true,
            "state": "PAID",
            "bkdate": "2024-08-23",
            "lastupdate": "2024-08-23T08:40:01Z",
            "collection": 51014
        },
        {
            "id": 4692116,
            "contractId": 3408152,
            "ct": 3764,
            "subscriptionId": 230858,
            "mndtId": "EXAMPLE-AGPWU",
            "amount": 849.0,
            "msg": "Gloves",
            "place": null,
            "ref": "079D43896FA44CEC809222C54402B66C",
            "date": "2024-08-27T08:26:19Z",
            "final": true,
            "state": "PAID",
            "bkdate": "2024-08-23",
            "lastupdate": "2024-08-23T08:40:01Z",
            "collection": 51014
        },
        {
            "id": 4692118,
            "contractId": 3408186,
            "ct": 3764,
            "subscriptionId": 230866,
            "mndtId": "EXAMPLE-AGPVZ",
            "amount": 872.0,
            "msg": "Gloves",
            "place": null,
            "ref": "ACBDD129FBE745838303188F9505DB8E",
            "date": "2024-08-27T08:26:19Z",
            "final": true,
            "state": "PAID",
            "bkdate": "2024-08-23",
            "lastupdate": "2024-08-23T08:40:02Z",
            "collection": 51014
        }
    ],
    "_links": {
        "self": "/creditor/transaction/query?fromId=4692115",
        "next": "/creditor/transaction/query?fromId=4692119"
    }
}