General use

Twikey has put in place several services enabling software partners, companies with own ERP or CRM systems, banks and other 3rd parties to exchange information. This page describes the different calls that are available to you. The calls allow integration in a number of ways.

Since there are numerous ways a company can allow its customers to pay, we also provided a couple of high level use-cases to get you up and running in no time.

All exchanges require a valid AuthorizationToken passed on as a header named "Authorization". The AuthorizationToken can be retrieved via the login call and is valid for 24h. We suggest that the call to the login is done when the actual call you wish to make is returning a 401. This way you don't need to handle the lifecycle of your token yourself.

Exchanges can be in both JSON & XML responses. By default they will be in JSON, but by giving the "Accept" header a value of 'application/xml', you can get an xml payload.

Errors can be divided into 2 categories. The first category are errors based on user input for which we return a 400 error with the code of the error mentioned in the response header "ApiError'. The translated error can be found in the body of the required exchange. The language is provided by the "Accept-Language" header or defaults to English. The second category of errors is one that you normally shouldn't run into a lot. In this case we return a 500 error which means that something went wrong on our end. We'll probably already know about it when you see the error.

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

When using the API the login call will provide you with an AuthorizationToken, 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 apiToken as a query parameter in the url as it exposes the apiKey. 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**

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,"apiToken=$apitoken");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$server_output = curl_exec ($ch);
$result = json_decode($server_output);
$authorization = $result->{'Authorization'} ;
curl_close ($ch);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    apitoken = "**API_KEY**",
    authorization = null,
    options = {
        host: host,
        port: '443',
        path: '/creditor',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        body:{
            'apiToken' : apitoken
        }
    };

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

public class TwikeyAPI {
    private String host = "https://api.twikey.com",
        apiToken = "**API_KEY**";
    public void logIn(){
        OkHttpClient client = new OkHttpClient();
        RequestBody body = new FormBody.Builder()
            .add("apiToken", apiToken)
            .build();

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

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

public class TwikeyAPI {
    private String host ="https://api.twikey.com",
        apiToken ="**API_KEY**";

    public void logIn(){
        RestClient client = new RestClient(host + "/creditor");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddParameter("application/x-www-form-urlencoded",
            "apiToken=" + apiToken,
            ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

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

Replace **API_KEY** with your personal API key which can be found in the Merchant Dashboard.

HTTP Request

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

Form Parameters

Name	Description	Required	Type
apiToken	API key	Yes	string
otp	Value calculated based on salt and private key (if enhanced security)	No	long

HTTP Response

Code	Description
200	For security reasons, the http status is always 200, however for returning error codes specific to the call 2 additional response headers were added "ApiError" and "ApiErrorCode" which are added on every response that contains errors. Notible exceptions are authentication errors and authorisation errors that don't have these 2 headers.

Error codes

Code	Description
err_no_login	Not logged in

Logout

Invalidates the AuthorizationToken by making a GET request to /creditor

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

$host = "https://api.twikey.com";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setOpt($ch, CURLOPT_HTTPHEADER, array(
    "authorization: $authorization"
);
$server_output = curl_exec ($ch);
curl_close ($ch);

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

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

public class TwikeyAPI {
    private String host = "https://api.twikey.com";

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

    Request request = new Request.Builder()
      .url(host + "creditor")
      .get()
      .addHeader("cache-control", "no-cache")
      .addHeader("Authorization", authorization)
      .build();

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

public class TwikeyApi {
    private String host = "https://api.twikey.com";
    public void logOut(){
        RestClient client = new RestClient(host + "/creditor");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

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

HTTP Response

Code	Description
204	Logged out successfully

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 an exit url defined on the template. This url can contain variables that are filled in depending on the outcome. See exit urls

curl -X POST https://api.twikey.com/creditor/invite \
  -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);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    ct = "**ct_id**",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/invite',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        data: {
            "ct": ct,
            "l": "nl",
            "email": "support@twikey.com",
            "lastname": "Support",
            "firstname": "Twikey",
            "address": "Stationstraat 43",
            "zip": "9051",
            "city": "Sint Denijs Westrem",
            "country": "BE"
        }
    };

var req = https.request(options, function (res) {
    res.on('data', function (chunk) {
        console.log("Redirect to : " + chunk)
    });
});

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

Name	Description	Required	Type	Max.
ct	Contract template to use	Yes	integer	4
l	Language (en/fr/nl/de/pt/es/it)	No	string	2
iban	International Bank Account Number of the debtor	No	string	35
bic	Bank Identifier Code of the IBAN	No	string	11
mandateNumber	Mandate Identification number (if not generated)	No	string	35
customerNumber	The customer number (strongly advised)	No	string	50
email	Email of the debtor	No	string	70
lastname	Lastname of the debtor	No	string	50
firstname	Firstname of the debtor	No	string	50
mobile	Mobile number required for sms (International format +32499123445)	No	string	50
	To update the address all address fields parameters are required	Yes	-	-
address	Address (street + number)	No	string	70
city	City of debtor	No	string	50
zip	Zipcode of debtor	No	string	50
country	ISO format	No	string	2
companyName	The company name (if debtor is company)	No	string	140
vatno	The enterprise number (if debtor is company)	No	string	50
contractNumber	The contract number which can override the one defined in the template.	No	string	35
campaign	Campaign to include this url in	No	string
prefix	Optional prefix to use in the url (default companyname)	No	string	20
check	If a mandate already exists, don't prepare a new one (based on email, customerNumber or mandatenumber and + template type(=ct))	No	boolean
reminderDays	Send a reminder if contract was not signed after number of days	No	number
sendInvite	Send out invite directly [*1]	No	boolean/string
document	Add a contract in base64 format	No	string
amount	In euro for a transaction via a first payment or post signature via an SDD transaction	No	string
token	(optional) token to be returned in the exit-url (lenght<100)	No	string
requireValidation	Always start with the registration page, even with all known mandate details	No	boolean

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

true: Invite is sent by email.
letter: Invite is sent by letter (requires IPEX)
letterWithMandate: Invite is sent by letter incl. the mandate (requires IPEX)

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.

Add a plan on invite

To add a plan in the invite request, an attribute named 'plan' and of type 'plan' need to be configured on the template*. To customize the plan attributes (amount, communication, ..) you can use the plan attributes. The plan is assigned when the end customer signs.

*: If a mandate is generated when signing a contract, the attribute 'plan' must be configured on the contract template.

HTTP Response

Code	Description
200	If the check option is provided and an existing collectable mandate is available it will be returned. Otherwise an url and key will be returned.
400	User error if parameter is given but not valid or collectable (available in apierror header and response)

Error codes

Code	Description
err_no_such_ct	No template found (or not active)
err_mandatenumber_required	No mandatenumber was given, while setting does not allow generation
err_double_mandatenumber	Signed mandate with the same mandatenumber already exists
err_missing_params	Attributes are missing while configured as mandatory
err_contract_signed	Specified contract is already signed
err_invalid_mandatenumber	Reference or prefix is invalid
err_bic_not_sepa	BIC code does not belong to a SEPA bank
err_duplicate_ref	Duplicated reference
err_invalid_bic	BIC code invalid
err_invalid_coc	Invalid enterprise number
err_invalid_country	Country code invalid
err_invalid_email	Email invalid
err_invalid_iban	IBAN invalid
err_invalid_lang	Language code invalid

Sign a mandate

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 negiotiate mandates with their signature directly via API. Depending on the method the set of required parameters and/or handling may differ. Methods currently supported :

sms: require the mobile parameter
itsme
import: import the mandate with a specific signdate
digisign: wet signature encoded as a base64 png (max 150 k)
emachtiging, idin, ideal: requires the bic parameter You can retrieve the connected banks and bic codes using fetch connected banks

curl -X POST https://api.twikey.com/creditor/sign \
  -H 'authorization: **authorization**' \
  -d 'method=sms' \
  -d '&place=Gent' \
  -d '&ct=**ct_id**' \
  -d '&iban=BE68068897250734' \
  -d '&bic=GKCCBEBB' \
  -d '&email=sms%40twikey.com' \
  -d '&lastname=Twikey' \
  -d '&firstname=SMS' \
  -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=sms%40twikey.com"
    ."&lastname=Twikey"
    ."&firstname=SMS"
    ."&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);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    ct = "**ct_id**",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/sign',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        data: {
            "method": "sms",
            "place": "Gent",
            "ct": ct,
            "l": "nl",
            "email": "support@twikey.com",
            "lastname": "Support",
            "firstname": "Twikey",
            "mobile": "+32479123123",
            "address": "Stationstraat 43",
            "zip": "9051",
            "city": "Sint Denijs Westrem",
            "country": "BE"
        }
    };

var req = https.request(options, function (res) {
    res.on('data', function (chunk) {
        console.log("manatenumber: " + chunk)
    });
});

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=sms%40twikey.com" +
            "&lastname=Twikey" +
            "&firstname=SMS" +
            "&mobile=%2B32479123123" +
            "&address=Stationstraat%2043" +
            "&city=Gent" +
            "&zip=9051" +
            "&country=BE" +
            , ParameterType.RequestBody);
        IRestResponse response = client.Execute(request);
    }
}

{
  "MndtId": "MyMandateId"
}

// Sign method: Itsme

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

HTTP Request

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

Query Parameters

Name	Description	Required	Type	Max.
ct	Contract template to use	Yes	number	4
l	Language (en/fr/nl/de/pt/es/it)	No	string	2
method	Method to sign (sms/digisign/import/itsme/emachtiging...)	Yes	string
digsig	Wet signature (PDF encoded as base64) required if method is digisign	No	string
mandateNumber	Mandate Identification number (if not generated)	No	string	35
key	shortcode from the invite url. Use this parameter instead of 'mandateNumber' to directly sign a prepared mandate.	No	string	36
iban		Yes	string	35
bic	Required for methods emachtiging, iDeal and iDIN	No	string	11
email	Email of the debtor (maximum length 70 characters)	No	string	70
lastname		No	string	50
firstname		No	string	50
mobile	mobile number required for sms (International format +32499123445)	No	string	50
address	Address (street + number)	No	string	70
city		No	string	50
zip		No	string	50
country	ISO format	No	string	2
companyName	the company name (if debtor is company)	No	string	140
vatno	the enterprise number (if debtor is company)	No	string	50
contractNumber	the contract number which can override the one defined in the template.	No	string	35
customerNumber	The customer number (if applicable)	No	string	50
signDate	Date of signature (xsd:dateTime), sms uses date of reply	No	string
place	Place of signature	No	string

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_such_ct	No template found (or not active)
err_mandatenumber_required	No mandatenumber was given, while setting does not allow generation
err_double_mandatenumber	Signed mandate with the same mandatenumber already exists
err_missing_params	Attributes are missing while configured as mandatory
err_invalid_signature	No valid method was provided
err_bic_not_sepa	BIC code is not SEPA
err_contract_signed	Contract is already signed
err_invalid_bic	BIC code is invalid
err_invalid_email	Email is invalid
err_invalid_iban	IBAN is invalid
err_invalid_mobile	Mobile number format is invalid
smsErrorSending	Error sending SMS
smsFixed	Phone number is fixed instead of mobile
smsPendingContract	Mobile number currently in use and awaiting response from customer

Mandate Feed

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 to make a split or fetch a specific type of document you need to pass "X-TYPES" in the header with following parameters in upper case only. (CONTRACT - CORE - B2B). Recurring Credit Card is only fetched when passing the CREDITCARD x-types header.

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"

curl https://api.twikey.com/creditor/mandate \
  -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");
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',
        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")
          .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");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}

{
  "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": "Bisschop de Vetplein 7",
            "PstCd": "5126CA",
            "TwnNm": "Gilze",
            "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"
    }
  ]
}

HTTP Request

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

Query Parameters

Name	Description	Required	Type
chunkSize	Amount of mandates to return per call (max 100)	No	long

Headers

Name	Value	Description
x-types	CREDITCARD	To retrieve the feed of recurring credit cards

Response

Code	Description
200	The request has succeeded

Error Codes

Code	Description
err_call_in_progress	Request already in progress by another client

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)

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,..)

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

Cancel a mandate

A contract 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. In order to avoid extra costs & stale information, Twikey requires the update of its systems. 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

Name	Description	Required	Type	Max.
mndtId	Mandate Reference	Yes	string	35
rsn	Reason of cancellation (Can be R-Message)	Yes	string	200
notify	Notify the customer by email when true	No	boolean

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_contract	No contract was selected or invalid mndtId supplied
err_invalid_state	Contract had wrong status (eg. already cancelled) or not authorised
err_no_contract	No mandate was found
err_provide_reason	Please provide reason

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.

Note: Rate limits apply, though this is perfect for one-offs, for updates we recommend using the feed (see above).

Header name	Description
X-STATE	State of the mandate
X-COLLECTABLE	Whether this mandate can be used for collections (true/false)

Possible states	Description
PREPARED	User created the mandate, but the mandate is not signed yet
SIGNED	Client signed the mandate
EXPIRED	Mandate is beyond it's final date
CANCELLED	Mandate has been revoked
SIGNED_PENDING_DEBTOR_BANK	only in case of B2B - debtor bank needs to validate the mandate
REFUSED_BY_DEBTOR_BANK	only in case of B2B - signed but debtor bank refused the mandate
REQUIRES_MORE_SIGNATURES	mandate needs to be signed by a 2nd person - option needs to be activated on template level
PRINT	only in case of B2B - mandate has been printed by debtor
PENDING_MERCHANT_APPROVAL	mandate has been uploaded by debtor but needs to be validated by merchant

Possible events	Description
Cancel	depending on the state of a mandate
Accepted Bank	depending on the state of a mandate
Reject Bank	depending on the state of a mandate
Sign	depending on the state of a mandate
Print	depending on the state of a mandate
Uploaded	depending on the state of a mandate
Debtor Upload	depending on the state of a mandate
Expired	depending on the state of a mandate

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);

var https = require('https'),
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/mandate/detail?mndtId=mndtId123',
        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 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);
    }
}

HTTP Request

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

Query Parameters

Name	Description	Required	Type	Max.
mndtId	Mandate Reference	Yes	string	35
force	Also include non-signed states	No	boolean

Response

Code	Description
200	Details of the mandate (see /creditor/mandate)
400	User error if parameter is given but not valid (available in apierror header and response)
429	Too many requests

Error codes

Code	Description
err_no_contract	No contract was selected or invalid mndtId supplied
err_no_contract	No contract was found
err_invalid_state	Contract was not signed (ignored when force=true)

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'iban=BE32 1234 1234 1234' \
--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.

Name	Description	Required	Type	Max.
mndtId	Mandate Reference	Yes	string	35
state	active or passive (activated or suspend mandate)	No	String	7
mobile	Owner's mobile number	No	String	50
iban	Debtor's IBAN	No	String	35
bic	Debtor's BIC code	No	String	11
email	email address of debtor	No	String	70
firstname	Firstname of the debtor	No	String	50
lastname	Lastname of the debtor	No	String	50
companyName	Company name on the mandate	No	String	140
vatno	The enterprise number (can only be changed if companyName is changed)	No	String	50
customerNumber	The customer number (can be added, updated or used to move a mandate)	No	string	50
l	language on the mandate	No	String	2
	To update the address all fields below are required	Yes	-	-
address	Address (street + number)	No	String	70
city	City of debtor	No	String	50
zip	Zipcode of debtor	No	String	50
country	ISO format	No	String	2

HTTP Response

Code	Description
204	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta-information
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_contract	No contract was found
err_invalid_country	Invalid country code or not in ISO format (2 letters)
err_invalid_state	mandate state is invalid: some query parameters are invalid or not allowed in the current state.

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.

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

Name	Description	Required	Type	Max.
mndtId	Mandate Reference	Yes	string	35

HTTP Response

Code	Description
200	Request succeeded
400	Bad Request

Error Codes

Name	Description
err_no_contract	No contract was found

Update planned transactions

Sometimes a plan on an existing mandate needs to be updated. This endpoint allows to update a plan, just by passing the new plan data. Each parameter can be passed individually, only a plan name is required (or be passed empty to remove a plan).

curl -X POST https://api.twikey.com/creditor/mandate/plan \
  -H 'authorization: **authorization**' \
  -d 'mndtId=mdntId123'\
  -d 'plan=planName'\
  -d '_pls=2017-11-09'\
  -d '_pli=1m'\
  -d '_plo=4'\
  -d '_plt=5'\
  -d '_pla=50.00'\
  -d '_pld=description for the plan'

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/mandate/plan");
curl_setOpt($ch, CURLOPT_HTTPHEADER, array("authorization: $authorization"));
curl_setOpt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setOpt($ch, CURLOPT_POSTFIELDS, array(
    "mndtId" => "mdntId123",
    "plan" => "planName",
    "_pls" => "2017-11-09",
    "_pli" => "1m",
    "_plo" => "4",
    "_plt" => "5",
    "_pla" => "50.00",
    "_pld" => "description for the plan",
    "_pld" => "your refrence")
);
$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/plan',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body:{
            'mndtId': 'mndtId123',
            'plan': 'planName',
            '_pls': '2017-11-09',
            '_pli': '1m',
            '_plo': '14',
            '_plt': '5',
            '_pla': '50.00',
            '_pld': 'description for the plan'
        }
    };

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")
                        .add("plan", "planName")
                        .add("_pls", "2017-11-09")
                        .add("_pli", "1m")
                        .add("_plo", "4")
                        .add("_plt", "5")
                        .add("_pla", "50.00")
                        .add("_pld", "description for the plan")
                        .build();
        Request request = new Request.Builder()
          .post(body)
          .url(host + "/creditor/mandate/plan")
          .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/mandate/update");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("authorization", authorisation);
        request.AddParameter("application/x-www-form-urlencoded",
            "mndtId=mndtId123" +
            "&plan=planName" +
            "&_pls=2017-11-09" +
            "&_pli=1m" +
            "&_plo=14" +
            "&_plt=5" +
            "&_pla=50.00" +
            "&_pld=description for the plan" ,
            ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

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

Query Parameters

Name	Description	Required	Type
mndtId	Mandate Reference	Yes	string
plan	Name of the plan (can be empty in order to remove the plan)	Yes	string
_pls	Startdate for the plan	No	string
_pli	Periodicity of the plan, possible values are 1w, 2w, 1m, 2m, 3m, 4m, 6m, 12m	No	string
_plo	The day of the month on which the plan needs to be executed (1-31)	No	string
_plt	Number of times the plan should be executed	No	string
_pla	Amount associated with the plan	No	string
_pld	Communication to debtor you send when a plan is executed	No	string

HTTP Response

Code	Description
204	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta-information
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_plan_name	The plan parameter was not provided or an invalid planparameter supplied
err_invalid_state	Mandates are editable only when in Prepared/Print state or CORE or not authorised
err_no_contract	No contract was found
smsFixed	Phone number is fixed

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

Name	Description	Required	Type
mndtId	Mandate Reference	Yes	string

HTTP Response

Code	Description
200	PDF is available in the body of the response
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_contract	No contract was found

Upload pdf

Import existing mandate pdf (eg. scan of a printed document) After import the mandate is set on signed state.

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

Name	Description	Required	Type
mndtId	Mandate Reference	Yes	string

HTTP Response

Code	Description
200	Import of the pdf was done
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_contract	Contract not found
err_invalid_iban	no (valid) iban on the mandate

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

Name	Description	Required	Type
locale	the locale (fr, fr_FR, fr_BE, de, nl, nl_BE, nl_NL, es, pt, it)	no (defaults to en)	string

Responses

Code	Description
200	The request has succeeded

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);

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: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body :{
            'mndtId' : 'mndtId123',
            '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 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 Parameters

Name	Description	Required	Type	Max.
mndtId	Mandate Reference	Yes	string	35
date	Date of the transaction or now when empty	No	date
reqcolldt	Requested collection date of the transaction or null to collect as soon as possible	No	date
message	Message to the customer [*1]	Yes	string
ref	Your reference	No	string
amount	Amount to be billed	Yes	decimal
place	Optional place	No	string
refase2e	The reference is used as E2E identifier for the first payment Conform with the Rule Book of the EPC.	No	boolean

[*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

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_contract	No mandate found
err_invalid_state	The mandate is not active
err_invalid_date	Invalid Date
err_invalid_sepachars	Invalid characters in message to debtor
err_invalid_amount	Invalid Amount given
err_billing_overdrawn	Maximum amount reached according to risk rules

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);

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: '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 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,
                "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
        },
        "..."
    ]
}

<blockquote class="sample"><p>Including all parameters::</p></blockquote>

{
"Entries": [
{
    "id": 218914,
    "contractId": 1320345,
    "mndtId": "MNDT123",
    "contract": "CTR123",
    "amount": 5.63,
    "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

Query Parameters

Name	Description	Required	Type
chunkSize	Amount of transactions to return per call (max 100)	No	long

include parameter

The 'include' parameter can be added multiple times with different values

Value	Description
collection	returns the batch id
lastupdate	returns the last update in datetime format and 'bkdate' as date.
action	returns the dunning steps taken for a transaction
link	returns the url of the dunning payment link (when in dunning)

Dunning steps (actions)

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

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

Possible states

Possible states	Description
PAID	The transaction has been executed + final flag info
ERROR	The transaction has not been executed + final flag info

Final flag state

Possible states	Description
TRUE	No more actions are pending. Manual action is required if the state is in error
FALSE	More actions are pending to debit the debtor's account

HTTP Response

Code	Description
200	The request has succeeded

Error codes

Code	Description
err_missing_params	No parameter given
err_no_transaction	No link found based on the transaction
err_not_found	No link found
err_call_in_progress	Request already in progress by another client

Response parameters

Name	Description
date	Date when the transaction was created
bkdate	Date when the transaction was booked (received feedback from the bank)
reqcolldt	The requested collection date
bkerror	Error code when a transaction failed
bkamount	The amount booked
collection	The collection/batch ID in which the transaction was executed

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.

Note: Rate limits apply

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"
        }
    ]
}

HTTP Request

GET /creditor/transaction/detail

Request Parameters

Name	Description	Required	Type
id	id of a transaction	No	string
ref	ref of a transaction	No	string
mndtId	mandate reference	No	string
state	only return transaction in this state (OPEN/PAID/ERROR)	No	string

include parameter

This parameter can be added multiple times with different values

Name	Value	Description
include	collection	returns the batch id
include	lastupdate	returns the last update in datetime format and 'bkdate' as date.
include	link	returns the url of the dunning payment link (when in dunning)

Possible states

Possible states	Description
OPEN	The transaction is created but not processed by the bank
PAID	The transaction has been executed + final flag info
ERROR	The transaction has not been executed + final flag info

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)
429	Too many requests

Error codes

Code	Description
err_invalid_params	Either id or ref or mndtId is invalid or is empty

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

Name	Description	Required	Type	Options
id	Transaction id	Yes	string
action	Action to execute for the given transaction	Yes	string	paid, reoffer, backup*, archive

*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

Code	Description
200	The request has succeeded
201	Deletion of the transaction has succeeded
400	User error if parameter is given but not valid (available in api error header and response)

Error codes

Code	Description
err_no_transaction	No transaction found
err_no_contract	No mandate found (or not active)
err_invalid_params	one of the parameters provided contains invalid data

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

Name	Description	Required	Type
id	Transaction id	Yes	string
reqcolldt	Requested date of the billable event	No	string
message	Message to the customer	No	string
ref	Your reference	No	string
amount	Amount to be billed	No	string
place	Optional place	No	string

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in api error header and response)

Error codes

Code	Description
err_no_transaction	No transaction found
err_no_contract	No mandate found (or not active)
err_invalid_params	one of the parameters provided contains invalid data
err_invalid_date	Invalid Date
err_invalid_amount	Invalid Amount given

Refund a transaction

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.

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 Parameters

Name	Description	Required	Type
id	The transaction id	Yes	String
message	Message for the refund	Yes	String
amount	Amount to be refunded	Yes	Number
ref	Add a reference for the refund	No	String
place	Place of refund	No	String
iban	Iban of the Beneficiary account (optional otherwise iban from the mandate)	No	String
bic	Bic of the Beneficiary account	No	String

{
    "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

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_invalid_params	Missing request parameters or invalid values
err_msg_missing	message parameter missing

Remove a transaction

Remove a transaction that wasn't collected yet

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

Name	Description	Required	Type
id	a transactionId as returned in the post	No	string
ref	transactionReference as provided in the post to be removed	No	string

HTTP Response

Code	Description
204	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_contract	Contract not found
err_not_found	Transaction not found
err_transaction_invalid_action	Action invalid for the current state of the transaction

Collections

Execute Collection

Prepare a collection file and sent to collecting agent if available with the account data specified in the contract template.

HTTP Request

POST /creditor/collect

curl -X POST https://api.twikey.com/creditor/collect \
  -d ct=123 \
  -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/collect");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    "ct=$ct"
    ."clltndt=2017-09-15"
);
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",
    ct = "**ct_id**",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/collect',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        data: {
            "ct":"$ct",
            "clltndt":"2017-09-15"
        }
    };

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
    private String ct = "**ct_id**";

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

        MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
        RequestBody formBody = new FormBody.Builder()
            .add("ct", ct)
            .add("clltndt","2017-09-15")
            .build();

        Request request = new Request.Builder()
          .url(host + "/creditor/collect")
          .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 executeCollect(){
        RestClient client = new RestClient(host + "/creditor/collect");
        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 +
            "clltndt="2017-09-15"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

Query parameters

Name	Description	Required	Type
ct	Contract template for which to do the collection	Yes	number
colltndt	Collection date (default=earliest possible)	No	string
mndtId	Optional array of mandateId's (default = all with billable entries)	No	array
prenotify	Optional parameter, it's existence will trigger the prenotification towards the debtor (true/false)	No	boolean

HTTP Response

Code	Description
200	Returns the id referencing both first and recurring sdd send to bank
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_such_ct	No template specified
err_invalid_ct	Invalid template specified
err_provide_account	No account specified in template
err_no_access_subscription	No connection to the bank in your subscription
err_invalid_date	Invalid date

Status Collection

This endpoint allows to retrieve an SDD batch. In case we receive an error from the bank, we mark the transaction with status "error" or "paid", but on top of it we add a final flag which will either be true or false.

HTTP Request

GET /creditor/collect

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

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/collect");
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");
curl_setOpt($ch, 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/collect',
        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 authorization = null; //collected through logIn

    public void statusCollection(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
          .url(host + "/creditor/collect")
          .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",
        authorisation = null; // collected through logIn

    public void statusCollection(){
        RestClient client = new RestClient(host + "/creditor/collect");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}

{
    "Sdds":[
        {
            "id":1437939405111,
            "pmtinfid": "mypmtid",
            "tx":4,    // Number of transactions
            "amount":120.0,   // Total amount of the transactions
            "Entries": [
                {
                    "e2eid": "mye2e",
                    "amount": 30.0,
                    "contractId": 7488, // internal reference to the contract
                    "mandateRef": "TWIKEYCORE22",  // mandate reference
                    "msg": "testing",
                    "final": false,  // Does Twikey have any outstanding actions ?
                    "state": "open"  // No payment information received as of yet
                },
                {
                    "e2eid": "mye2e",
                    "amount": 30.0,
                    "contractId": 7488,
                    "mandateRef": "TWIKEYCORE22",
                    "msg": "testing",
                    "final": true,
                    "state": "paid",  // Transaction was paid
                    "bkamount": 30.0,  // Booked amount as stated in account information
                    "bkdate": "2015-07-27",  // Booking date as stated in account information
                    "bkerror": null   // No errors
                },
                {
                    "e2eid": "mye2e",
                    "amount": 30.0,
                    "contractId": 6358,
                    "mandateRef": "TWIKEYCORE21",
                    "msg": "test",
                    "final": false, // This is FYI, since we haven't exhausted yet all possibilities (will continue dunning)
                    "state": "error", // Transaction was paid but customer requested a refund
                    "bkamount": 30.0,
                    "bkdate": "2015-07-27",
                    "bkerror": "MD06" // Actual error code (refund request)
                },
                {
                    "e2eid": "mye2e",
                    "amount": 30.0,
                    "contractId": 6358,
                    "mandateRef": "TWIKEYCORE21",
                    "msg": "test",
                    "final": true,  // Could not collect, please contact your customer
                    "state": "error",
                    "bkamount": 30.0,
                    "bkdate": "2015-07-27",
                    "bkerror": "AG01"
                }
            ]
        }
    ]
}

Query parameters

Name	Description	Required	Type
id	Specific SDD reference	No	number
pmtinfid	Specific Payment identifier	No	string

HTTP Response

Code	Description
200	The request has succeeded

Error Codes

Error	Description
err_call_in_progress	Request already in progress by another client

Import Collection

Import a direct debit batch for collection. When the batch is imported and valid, it is directly sent to the bank for processing. Accepted format: Pain 008.001.02 (ISO 20022)

HTTP Request

POST /creditor/collect/import The Direct Debit message can be imported as file or as XML in the body of the request.

curl --location --request POST 'https://api.twikey.com/creditor/collect/import' \
-h 'authorization: **authorization**' \
-h 'Content-Type: application/xml' \
-d '@path/to/batch.xml'

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.twikey.com/creditor/collect/import',
  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 => "<file contents here>",
  CURLOPT_HTTPHEADER => array(
    'Authorization: $authorization',
    'Content-Type: application/xml'
  ),
));

$response = curl_exec($curl);
$result = json_decode($response);

curl_close($curl);

var data = "<file contents here>",
    authorization = null; //collected through login

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.twikey.com/creditor/collect/import");
xhr.setRequestHeader("Authorization", authorization);
xhr.setRequestHeader("Content-Type", "application/xml");

xhr.send(data);

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

    public void importCollection(){
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/xml");
RequestBody body = RequestBody.create(mediaType, "<file contents here>");
Request request = new Request.Builder()
  .url(host + "/creditor/collect/import")
  .method("POST", body)
  .addHeader("Authorization", authorization)
  .addHeader("Content-Type", "application/xml")
  .build();
Response response = client.newCall(request).execute();
    }
}

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

    public void importCollection(){
var client = new RestClient(host + "/creditor/collect/import");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", authorization);
request.AddHeader("Content-Type", "application/xml");
request.AddParameter("application/xml", "<file contents here>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
  }
}

HTTP Response

Code	Description
204	The request has succeeded
400	Bad request

Error codes

Code	Description
invalid_file	Invalid format or file already uploaded*

*Collection with the same value of 'PmtInfId' and 'EndToEndId' was already uploaded.

Invoices

Create invoice

Create a new invoice for a customer. The invoice can be sent to your customer automatically or manually. Depending on the selected template, different payment options are provided to the customer.

It is possible to create invoices with a zero amount. Those will directly be set on 'paid' after import.

UBL format: To create a new invoice use the endpoint: POST /creditor/invoice/ubl and Content-Type: application/xml.

HTTP Request

POST /creditor/invoice

curl -X POST https://api.twikey.com/creditor/invoice \
  -H 'authorization: **authorization**' \
  -H "Content-Type: application/json" \
  -d '{
             "number": "Inv20200001",
             "title": "Invoice July",
             "remittance": "596843697521",
             "ct": 1988,
             "amount": 100,
             "date": "2020-01-31",
             "duedate": "2020-02-28",
             "locale": "nl",
             "customer": {
               "customerNumber": "customer123",
               "email": "no-reply@twikey.com",
               "firstname": "Twikey",
               "lastname": "Support",
               "address": "Stationstraat 43",
               "city": "Gent",
               "zip": "9000",
               "country": "BE",
               "l": "fr",
               "mobile": "32498665995"
             },
             "pdf": "JVBERi0xLj....RU9GCg=="
     }'

Response:
      '{
          "id": "fec44175-b4fe-414c-92aa-9d0a7dd0dbf2",
          "number": "Inv20200001",
          "title": "Invoice July",
          "ct": 1988,
          "amount": 100.00,
          "date": "2020-01-31",
          "duedate": "2020-02-28",
          "status": "BOOKED",
          "url": "https://app.twikey.com/<company_id>/fec44175-b4fe-414c-92aa-9d0a7dd0dbf2"
      }'

** Or by referencing an existing document or customerNumber **

curl -X POST https://api.twikey.com/creditor/invoice \
  -H 'authorization: **authorization**' \
  -H "Content-Type: application/json" \
  -d '{
             "number": "Inv20200001",
             "title": "Invoice July",
             "remittance": "596843697521",
             "ct": 1988,
             "amount": 100,
             "date": "2020-01-31",
             "duedate": "2020-02-28",
             "customerByRef": "customer123"  // or "customerByDocument": "MandateReference123"
             "pdf": "JVBERi0xLj....RU9GCg=="
     }'

$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('http://api.twikey/creditor/invoice');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
             "number": "Invss123",
             "id": "fec44175-b4fe-414c-92aa-9d0a7dd0dbf2",
             "title": "Invoice April",
             "remittance": "123456789123",
             "ct": 60,
             "amount": 100,
             "date": "2020-03-20",
             "duedate": "2020-04-28",
             "locale": "nl",
             "customer": {
               "customerNumber": "customer123",
               "email": "no-reply@twikey.com",
               "firstname": "Twikey",
               "lastname": "Support",
               "address": "Stationstraat 43",
               "city": "Gent",
               "zip": "9000",
               "country": "BE",
               "lang": "fr",
               "mobile": "32498665995"
                }
 }');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Authorization' => '...',
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Response:
  '{
      "id": "fec44175-b4fe-414c-92aa-9d0a7dd0dbf2",
      "number": "Inv20200001",
      "title": "Invoice July",
      "ct": 1988,
      "amount": 100.00,
      "date": "2020-01-31",
      "duedate": "2020-02-28",
      "status": "BOOKED",
      "url": "https://app.twikey.com/<company_id>/fec44175-b4fe-414c-92aa-9d0a7dd0dbf2"
  }'

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'http://api.twikey/creditor/invoice',
  'headers': {
    'Authorization': '.....',
    'Content-Type': ['application/json']
  },
  body: {
             "number": "Invss123",
             "id": "fec44175-b4fe-414c-92aa-9d0a7dd0dbf2",
             "title": "Invoice April",
             "remittance": "123456789123",
             "ct": 60,
             "amount": 100,
             "date": "2020-03-20",
             "duedate": "2020-04-28",
             "locale": "nl",
             "customer": {
               "customerNumber": "customer123",
               "email": "no-reply@twikey.com",
               "firstname": "Twikey",
               "lastname": "Support",
               "address": "Stationstraat 43",
               "city": "Gent",
               "zip": "9000",
               "country": "BE",
               "lang": "fr",
               "mobile": "32498665995"
             }
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

Response:

      {
          "id": "fec44175-b4fe-414c-92aa-9d0a7dd0dbf2",
          "number": "Inv20200001",
          "title": "Invoice July",
          "ct": 1988,
          "amount": 100.00,
          "date": "2020-01-31",
          "duedate": "2020-02-28",
          "status": "BOOKED",
          "url": "https://app.twikey.com/<company_id>/fec44175-b4fe-414c-92aa-9d0a7dd0dbf2"
      }

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n" +
        "  \"number\": \"Invss123\",\n" +
        "  \"id\" : \"fec44175-b4fe-414c-92aa-9d0a7dd0dbf2\",\n" +
        "  \"title\": \"Invoice April\",\n" +
        "  \"remittance\": \"123456789123\",\n" +
        "  \"ct\": 60,\n" +
        "  \"amount\": 100,\n" +
        "  \"date\": \"2020-03-20\",\n" +
        "  \"duedate\": \"2020-04-28\",\n" +
        "  \"customer\": {\n" +
        "    \"customerNumber\": \"customer123\",\n" +
        "    \"email\": \"no-reply@twikey.com\",\n" +
        "    \"firstname\": \"Twikey\",\n" +
        "    \"lastname\": \"Support\",\n" +
        "    \"address\": \"Stationstraat 43\",\n" +
        "    \"city\": \"Gent\",\n" +
        "    \"zip\": \"9000\",\n" +
        "    \"country\": \"BE\",\n" +
        "    \"lang\": \"nl\",\n" +
        "    \"mobile\": \"32498665995\"\n" +
        "  }\n" +
        "}");
Request request = new Request.Builder()
        .url("https://api.twikey.com/creditor/invoice")
        .method("POST", body)
        .addHeader("Authorization", "701fbbfd-2681-47c3-8077-59345df335f2")
        .addHeader("Content-Type", "application/json")
        .build();
Response response = client.newCall(request).execute();


// Response:
      '{
          "id": "fec44175-b4fe-414c-92aa-9d0a7dd0dbf2",
          "number": "Inv20200001",
          "title": "Invoice July",
          "ct": 1988,
          "amount": 100.00,
          "date": "2020-01-31",
          "duedate": "2020-02-28",
          "status": "BOOKED",
          "url": "https://app.twikey.com/<company_id>/fec44175-b4fe-414c-92aa-9d0a7dd0dbf2"
      }'

var client = new RestClient("http://api.twikey/creditor/invoice");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "701fbbfd-2681-47c3-8077-59345df335f2");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n" +
        "  \"number\": \"Invss123\",\n" +
        "  \"id\" : \"fec44175-b4fe-414c-92aa-9d0a7dd0dbf2\",\n" +
        "  \"title\": \"Invoice April\",\n" +
        "  \"remittance\": \"123456789123\",\n" +
        "  \"ct\": 60,\n" +
        "  \"amount\": 100,\n" +
        "  \"date\": \"2020-03-20\",\n" +
        "  \"duedate\": \"2020-04-28\",\n" +
        "  \"locale\": \"nl\",\n" +
        "  \"customer\": {\n" +
        "    \"customerNumber\": \"customer123\",\n" +
        "    \"email\": \"no-reply@twikey.com\",\n" +
        "    \"firstname\": \"Twikey\",\n" +
        "    \"lastname\": \"Support\",\n" +
        "    \"address\": \"Stationstraat 43\",\n" +
        "    \"city\": \"Gent\",\n" +
        "    \"zip\": \"9000\",\n" +
        "    \"country\": \"BE\",\n" +
        "    \"lang\": \"fr\",\n" +
        "    \"mobile\": \"32498665995\"\n" +
        "  }\n" +
        "}",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

// Response
Response:
      '{
          "id": "fec44175-b4fe-414c-92aa-9d0a7dd0dbf2",
          "number": "Inv20200001",
          "title": "Invoice July",
          "ct": 1988,
          "amount": 100.00,
          "date": "2020-01-31",
          "duedate": "2020-02-28",
          "status": "BOOKED",
          "url": "https://app.twikey.com/<company_id>/fec44175-b4fe-414c-92aa-9d0a7dd0dbf2"
      }'

Header X-Purpose:

Use X-Purpose to alter the url for specific use cases

Value	Description
qr (default)	Returns a url that can be used in different bank apps.
redirect	Returns a branded-url for generic use cases (faster)
merchant	Returns a url that can be used over the counter

Request Parameters

Invoice Object

language:

The language in the invoice object can be passed using the parameter 'l' or 'locale'. When language is not passed the default language of the invoice is as defined in your Company information configuration.

The language passed in the customer object has no impact on the language of the invoice.

Name	Description	Required	Type	Max.
id	UUID of the invoice (optional)	No	string	36
number	Invoice number [1]	Yes	string	50
title	Message to the debtor [2], if empty one is generated.[2a]	No	string	140
remittance	Payment message, if empty then title will be used [3]	No	string	140
ct	Template to be used[4]	No	string	4
amount	Amount to be billed	Yes	number
date	Invoice date	Yes	date
duedate	Due date	Yes	date
locale	Language of the invoice	No	string	2
customer	Customer	Yes	object
customerByDocument	Customer by document reference	No	string
manual	Never auto collect the invoice via a recurring mechanism	No	boolean
pdf	Base64 encoded document	No	string

Customer Object

Name	Description	Required	Type	Max.
customerNumber	The customer number to link this invoice too (strongly advised)	Yes*	string	50
email	Debtor's email	Yes*	string	70
firstname	Debtor's first name - if not known we will put unknown	No	string	50
lastname	Debtor's last name - if not known we will put unknown	No	string	50
companyName	Name of the company	No	string	140
coc	Enterprise number of the company	No	string	50
lang / l	Debtor's language	No	string	2
address	Debtor's address (street + number)e	No	string	70
city	Debtor's city	No	string	50
zip	Debtor's zipcode	No	string	50
country	Debtor's country	No	string	2
mobile	Debtor's mobile number place	No	string	50

[1]: If an invoice with this number already exist, it will return the invoice details instead.
[2]: This is the message that your customer will see on their bank statement. More info...
[2a]: The generated title depends on the language of the invoice. E.g.: "Invoice 123", "Factuur 123", ..
[3]: This will be the code used in the bank statements Twikey provides that you'll be able to import in your accounting package.
Belgium*: When 12 characters long and the checksum is correct, this is treated as a structured message (OGM)
[4]: Contract Template: When passed: we use that template When not passed: we use the default template of either the customer if they already exist or the default template from your merchant environment in case of a new customer.

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Possible states

Possible states	Description
BOOKED	The invoice created but not processed by the bank
PENDING	The payment is in progress
EXPIRED	The invoice has expired

Error codes

Code	Description
err_no_contract	No mandate found
err_debtor_not_found	Debtor was not found
err_invalid_state	The mandate is not active
err_invalid_date	Invalid Date
err_invalid_sepachars	Invalid characters in message to debtor
err_invalid_amount	Invalid Amount given
err_billing_overdrawn	Maximum amount reached according to risk rules
err_debtor_id_missing	A customer number or email address is missing in the customer object
err_invalid_email	Email invalid
err_invalid_name_length	first and/or last name is too long
register_lastname_missing	'lastname' is empty
register_firstname_missing	'firstname' is empty

Update invoice

Update invoice details. Use the unique invoice id in the request url.

HTTP Request

PUT /creditor/invoice/{{id}}

curl -X PUT https://api.twikey.com/creditor/invoice/{{id}}

  -H 'authorization: **authorization**' \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Invoice Updated",
  "date": "{{invoiceDate}}",
  "duedate": "{{dueDate}}",
  "ref": "reference",
  "pdf": "JVBERi...RU9GCg==",
  "status": "paid"
}'

Request parameters

Name	Description	Required	Type
title	Title of the invoice	No	String
date	Invoice date	Yes	String
duedate	Invoice due date	Yes	String
ref	Invoice reference	No	String
pdf	Base64 encoded document	No	String
status	Mark invoice as "booked", "archived", "paid"	No	String

HTTP Response

Code	Description
200	The request has succeeded

Error codes

Code	Description
err_invalid_params	No invoice id passed in the request
err_not_found	Invoice id not found
err_invalid_date	date or due date is invalid
err_invalid_state	Invoice state does not allow updates

Invoice feed

Retrieve the list of updates on invoices that had changes since the last call.

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

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/invoice");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, array("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/invoice',
        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 getTransactions(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
            .url(host + "/creditor/invoice")
            .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/invoice");
        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);
    }
}

HTTP Request

GET /creditor/invoice

Request Parameters

The parameter 'include' can be reused in the url several times with a different value. 'include=lastpayment' replaces the prior parameter 'include=paymentdetail' offering more details.

Value	Description	Required	Type
meta	Include meta data in the response (more information below)	No	string
customer	Include customer details	No	string
lastpayment	List details about the method and state of executed payments	No	string

{
    "Invoices": [
      {
        "id": "b3340469-2bc6-4d20-b717-5d3015979038",
        "number": "INVOICE_8317363890",
        "title": "B8 Sales, Inc.",
        "remittance": "B7-64-3C-22-37-4C",
        "ref": "my reference",
        "state": "PAID",
        "amount": 1.8,
        "date": "2020-10-12",
        "duedate": "2020-10-13",
        "ct": 2223,
        "url": "https://app.twikey.com/<company_id>/b3340469-2bc6-4d20-b717-5d3015979038",
        "customer": {
          "email": "support@twikey.com",
          "firstname": "Twikey",
          "lastname": "Support",
          "address": "Stationstraat 100",
          "city": "Gent",
          "zip": "9000",
          "country": "NL",
          "ref": "customernumber",
          "l": "nl",
          "mobile": "+321231231"
        },
        "meta": {
          "reminderLevel": "1",
          "partial": "70553"
        }
      }
    ]
}

Possible states

Possible states	Description
BOOKED	The invoice created but not processed by the bank
PENDING	The payment is in progress
PAID	The invoice has been paid
EXPIRED	The invoice has expired
ARCHIVED	The invoice has been archived

HTTP Response

Code	Description
200	The request has succeeded

Meta data

parameter	Description
reminderLevel	the number of reminders sent out
partial	payment link id used to pay a partial amount of the invoice
lastError	last error received from the bank in case of an SDD transaction
name	Company name of the debtor

Error Codes

Code	Description
err_call_in_progress	Request already in progress by another client

Invoice details

Retrieve the details of an invoice. This can be done on either the invoice unique identifier or invoice number.

curl https://api.twikey.com/creditor/invoice/{{invoice}} \
  -H 'authorization: **authorization**'

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/invoice/$invoice");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, array("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/invoice/invoice123',
        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
        invoice = "invoice123";
    public void getTransactions(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
            .url(host + "/creditor/invoice/" + invoice)
            .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
        invoice = "invoice123";
    public void getTransactions(){
        RestClient client = new RestClient(host + "/creditor/invoice/" + invoice);
        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);
    }
}

HTTP Request

GET /creditor/invoice/{{invoice}}

Request Parameters

The parameter 'include' can be reused in the url several times, please refer to the feed parameters for more details.

{
    "Invoices": [
      {
        "id": "b3340469-2bc6-4d20-b717-5d3015979038",
        "number": "INVOICE_8317363890",
        "title": "B8 Sales, Inc.",
        "remittance": "B7-64-3C-22-37-4C",
        "ref": "my reference",
        "state": "PAID",
        "amount": 1.8,
        "date": "2020-10-12",
        "duedate": "2020-10-13",
        "ct": 2223,
        "url": "https://app.twikey.com/<company_id>/b3340469-2bc6-4d20-b717-5d3015979038",
        "customer": {
          "email": "support@twikey.com",
          "firstname": "Twikey",
          "lastname": "Support",
          "address": "Stationstraat 100",
          "city": "Gent",
          "zip": "9000",
          "country": "NL",
          "ref": "customernumber",
          "l": "nl",
          "mobile": "+321231231"
        },
        "meta": {
          "reminderLevel": "1",
          "partial": "70553"
        }
      }
    ]
}

Possible states

Possible states	Description
BOOKED	The invoice created but not processed by the bank
PENDING	The payment is in progress
PAID	The invoice has been paid
EXPIRED	The invoice has expired
ARCHIVED	The invoice has been archived

HTTP Response

Code	Description
200	The request has succeeded

Meta data

parameter	Description
reminderLevel	the number of reminders sent out
partial	payment link id used to pay a partial amount of the invoice
lastError	last error received from the bank in case of an SDD transaction
name	Company name of the debtor

Error Codes

Code	Description
err_call_in_progress	Request already in progress by another client

Action on Invoice

Action request enables to send the invitation or reminder to a customer. This can be done by sms or email. The reminder level (1 - 4) is based accordingly on prior reminders already send to the customer. Type smsreminder has only one reminder level.

HTTP Request

POST /creditor/invoice/{{id}}/action

curl -X POST https://api.twikey.com/creditor/invoice/${invoiceId}/action \
  -H 'authorization: **authorization**' \
  -d 'type=sms'

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.twikey.com/creditor/invoice/$invoiceId/action",
  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 => "type=sms",
  CURLOPT_HTTPHEADER => array(
    "Authorization: $authorization",
    "Content-Type: application/x-www-form-urlencoded"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "type=sms");
Request request = new Request.Builder()
  .url("https://api.twikey.com/creditor/invoice/" + invoiceId)
  .method("POST", body)
  .addHeader("Authorization", authorization)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.twikey.com/creditor/invoice/{invoiceId}/action");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "{authorization}");
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("type", "sms");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Request Parameters

Name	Description	Required	Type
type	The type of invite or reminder to send	yes	string

Type values

Name	Description
email	Send invitation by email
sms	Send invitation by sms
reminder	Send a reminder by email
smsreminder	Send a reminder by sms

HTTP Response

Code	Description
200	The request has succeeded

Error codes

Code	Description
err_invalid_email	Debtor has no email configured
err_invalid_mobile	Debtor has no mobile number configured
err_invalid_type	Type was not defined or invalid

Reconciliation

Generate Files

Reconciliation files can be generated in CAMT053 or CODA. Direct debit files are available 3 days after sending the transactions to the bank. Payment link files are available every day for payments done the prior day(s).

When using Mollie for your settlements the frequency can vary. Please contact Mollie for more information about settlements.

HTTP Request

POST /creditor/files

curl POST 'https://api.twikey.com/creditor/files' \
--h 'Authorization: .....' \
--d 'sdd=false' \
--d 'format=coda' \
--d 'paylink=true'


$ch = curl_init();
$authorization = null; // collected through logIn

curl_setopt_array($ch, array(
  CURLOPT_URL => "https://api.twikey.com/creditor/files",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "sdd=true&paylink=true&format=coda",
  CURLOPT_HTTPHEADER => array(
    '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/files',
        method: 'POST',
        headers: {
            'Authorization': authorization
        },
        body :{
            'sdd:' 'true',
            'paylink:' 'true',
            'format:' : 'coda'
        }
    };

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

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "sdd=false&format=coda&paylink=true");
Request request = new Request.Builder()
  .url("https://api.twikey.com/creditor/files")
  .method("POST", body)
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .addHeader("Authorization", "....")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.twikey.com/creditor/files");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "....");
request.AddParameter("sdd", "false");
request.AddParameter("format", "coda");
request.AddParameter("paylink", "true");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Query parameters

Name	Description	Required	Type
sdd	Set true to generate sdd files	Yes	boolean
paylink	Set true to generate paylink files	Yes	boolean
format	the format of the file (see Formats below). Default is camt	No	String

Formats:

coda: Default coda format
coda6: Detailed coda version
camt: CAMT053
mt940: MT940 Exact Online compatible
mt940f: MT940 TwinField compatible

HTTP Response

Code	Description
204	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)
X-FILES-CREATED	Only included in the header when files are generated, returns the number of files generated

Error codes

Code	Description
err_invalid_params	Parameters are invalid

List Files

Return a list of reconciliation files. The list returned include the files generated since this request was lasted performed. To retrieve files older then this you can add a X-RESET header to reset the feed to an earlier time. The value of the header is in UTC (standard ISO) format.

HTTP Request

GET /creditor/files

curl GET 'https://api.twikey.com/creditor/files' \
--h 'Authorization: ...'

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.twikey.com/creditor/files',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: ...'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

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

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

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

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.twikey.com/creditor/files")
  .method("GET", null)
  .addHeader("Authorization", "...")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.twikey.com/creditor/files");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "...");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

{
    "Files": [
        {
            "name": "sdd_twikey_BE81ZZZ0000000000--201222090211-2223.cod",
            "created": "2021-03-16T17:28:38Z"
        },
        {
            "name": "sdd_twikey_BE81ZZZ0000000000--201222090212-2223.cod",
            "created": "2021-03-16T17:28:38Z"
        }
      ]
  }

HTTP Response

Code	Description
200	The request has succeeded

Download File

Download reconciliation files.

HTTP Request

GET /creditor/files/filename

curl GET 'https://api.twikey.com/creditor/files/sdd_twikey_BE81ZZZ0000000000--201222090211-2223.cod' \
--h 'Authorization: .....'

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.twikey.com/creditor/files/sdd_twikey_BE81ZZZ0000000000-201222090211-2223.cod',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: ....'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

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

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("https://api.twikey.com/creditor/files/sdd_twikey_BE81ZZZ0000000000--201222090211-2223.cod", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.twikey.com/creditor/files/sdd_twikey_BE81ZZZ0000000000--201222090211-2223.cod")
  .method("GET", null)
  .addHeader("Authorization", "....")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.twikey.com/creditor/files/sdd_twikey_BE81ZZZ0000000000--201222090211-2223.cod");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "....");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Query parameters

Name	Description	Required	Type
filename	the filename	Yes	String

HTTP Response

Code	Description
200	The request has succeeded

Paymentlinks

Paymentlinks can facilitate a one-off payment that needs to happen or can be used in the dunning process. For the latter you don't need to use these endpoints. However if you want to use the former, these endpoints will be of service to you. We don't provide a list endpoint as updates should be retrieved upon receiving a webhook.

Create paymentlink

Create a payment link for an affiliated customer (via email) or via a name (in which case no customer is linked). It is possible to create a -consolidated- paymentlink by using the parameter txref. Unique transaction references are required! In this case you create a paymentlink linked over several transactions based on their transaction reference. Once paid, every transaction will be marked as paid as well. When specifying a redirectUrl, use http:// or https:// to refer to the website. If an email address is added, the debtor is also added as a customer in Twikey.

HTTP Request

POST /creditor/payment/link

curl -X POST https://api.twikey.com/creditor/payment/link \
  -H 'authorization: **authorization**'\
  -d 'email=no-repy@twikey.com'\
  -d 'message=Faulty payments last month'\
  -d 'amount=100'

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/payment/link");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
      "email=no-repy@twikey.com"
    ."&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/payment/link',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body :{
            'email': 'no-repy@twikey.com',
            '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 addTransaction(){
        OkHttpClient client = new OkHttpClient();
        RequestBody body = new FormBody.Builder()
            .add("email=no-repy@twikey.com")
            .add("message", "Monthly payment")
            .add("amount", "10")
            .build();

        Request request = new Request.Builder()
            .url(host + "/creditor/payment/link")
            .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/payment/link");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);
        request.AddParameter("application/x-www-form-urlencoded",
            "email=no-repy@twikey.com" +
            "message=Monthly payment" +
            'amount=10"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

{
  "id": 1,
  "amount": 55.66,
  "msg": "Test",
  "url": "https://mycompany.twikey.com/payment/tr_l2iKz0LT8HvRrmf0"
}

Header X-Purpose:

Use X-Purpose to alter the url for specific use cases

Value	Description
qr	Returns a url that can be used in different bank apps.
redirect(default)	Returns a branded-url for generic use cases (faster)

Request Parameters

Name	Description	Required	Type
customerNumber	The customer number (strongly advised)	No	string
email	Email of the debtor	No (Required to send invite)	string
lastname		Yes	string
firstname		Yes	string
l	Language (en/fr/nl/de/pt/es/it)	No	string
mobile	mobile number	No	String
ct	contract template	No	String
title	Message to the debtor [*1]	Yes	string (200)
remittance	Payment message, if empty then title will be used [*2]	No	string
amount	Amount to be billed	Yes	string
redirectUrl	Optional redirect after pay url (must use http(s)://)	No	url
place	Optional place	No	string
expiry	Optional expiration date	No	date
sendInvite	Send out invite email or sms directly (email, sms) [*3]	No	string
address	Address (street + number)	No	string
city	City of debtor	No	string
zip	Zipcode of debtor	No	string
country	ISO format (2 letters)	No	string
txref	References from existing transactions	No	string
method	Circumvents the payment selection with PSP (bancontact/ideal/maestro/mastercard/visa/inghomepay/kbc/belfius)	No	string
invoice	Create payment link for specific invoice number	No	string
isTemplate	Use a (custom) payment form [*4].	No	boolean

note: A timestamp can also be included in the expiry date, but this is only supported by certain PSP's. For more information contact our support. Our standard UTC is -1 hour.

[1]: This is the message that your customer will see on their bank statement. (More info..)
[2]: This will be the code used in the bank statements Twikey provides that you'll be able to import in your accounting package.
[3]: A registered email can be sent using the value 'registeredEmail' (requires Registered-email integration). [4]: When set on 'true' the customer is redirected to a (custom) payment form. For more information about template links, please contact support.

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_invalid_amount	Invalid Amount given
err_invalid_date	Invalid Expiry Date
err_duplicate_tx	Duplicate transaction
err_not_found	Invoice not found or invoice amount is exceeded
err_invalid_state	Invoice state is not booked or expired
err_invalid_email	Email is invalid
err_invalid_name	Name is invalid
err_msg_missing	Title is missing

Special cases:

Send payment links using sms.

For this you have to include a mobile number and email address in the request. The parameter 'sendInvite' has to be set on 'sms'.
Create payment link for invoices

It is possible to create payment links for booked or expired invoices. This can be done for the total amount of the invoice, or a partial amount.

In case of a partial payment, the payment link id is displayd in the invoice feed meta data ('partial': 'link-id'). Add the parameter 'invoice' and use the invoice number to create a payment link for invoices.

Important: When the customer use that link and pays, the invoice is marked as paid even in case of a partial amount.
Payment link for a SDD transaction

In order to create a payment link for SDD transactions use either 'tx' (for the id of the transaction) or 'txref' for the reference. Note however that the transaction can only be linked when it is in 'failed' state.

Paymentlink Feed

Get payment link feed since the last retrieval

HTTP Request

GET /creditor/payment/link/feed

curl -X GET https://api.twikey.com/creditor/payment/link/feed \
  -H 'authorization: **authorization**'

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/payment/link/feed?all="");
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/payment/link/feed',
        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 getTransactions(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
            .url(host + "/creditor/payment/link/feed")
            .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/payment/link/feed");
        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);
    }
}

[
    {
        "amount": 17.95,
        "id": 3354,
        "msg": "Betaling Factuur 123",
        "ref": "J7F079OG00000",
        "state": "paid"
    },
    {
        "amount": 19.95,
        "id": 3821,
        "msg": "Rappel Factuur 101",
        "ref": "KJEVMD5",
        "state": "paid"
    }
]

{
    "links": [
        {
            "id": 228192,
            "ct": 2223,
            "amount": 12.19,
            "msg": "Order-id 10058",
            "ref": "R10058",
            "state": "paid",
            "customer": {
                "id": 1010238,
                "email": "email@example.com",
                "firstname": "Smith,",
                "lastname": " Douglas",
                "address": "Stationstraat  43",
                "city": "Gent",
                "zip": "9000",
                "country": "BE",
                "customerNumber": "de8f0be99b1b2521c7a74a5067b5d85f",
                "l": "nl",
                "mobile": null
            },
            "meta": {
                "active": false,
                "sdd": "130542",
                "tx": "255733"
            },
            "time": {
                "creation": "2021-05-03T07:42:40Z",
                "expiration": "2021-05-17T07:42:40Z",
                "lastupdate": "2021-05-03T07:44:00Z"
            }
        },
        {
            "id": 244041,
            "ct": 2223,
            "amount": 449.87,
            "msg": "Invoice February",
            "ref": "invoice-2021-02",
            "state": "paid",
            "customer": {
                "id": 1200553,
                "email": "email@example.com",
                "firstname": "John",
                "lastname": "Smith",
                "address": "Stationstraat 43",
                "city": "Gent",
                "zip": "9000",
                "country": "BE",
                "customerNumber": "5921071",
                "l": "nl",
                "mobile": "+3283838383"
            },
            "meta": {
                "active": false,
                "method": "bancontact",
                "invoice": "d133b08b-fe06-445b-81ff-6846a568d71f"
            },
            "time": {
                "creation": "2021-05-06T15:16:52Z",
                "lastupdate": "2021-05-06T15:16:55Z"
            }
        }
    }

Request Parameters

Name	Description	Required	Type
all	Include all non-paid updates too (by default only paid updates are returned)	No	boolean

include parameter

The 'include' parameter can be added multiple times with different values

Value	Description	Required	Type
customer	customer detail	No	string
meta	meta data	No	string
time	time data	No	string

Possible states

States	Description
Created	The payment link has been created but the customer did not do anything with it yet.
Started	The customer has clicked on the payment link you transmitted him but did not complete the payment. In the Twikey dashboard the state will be shown as clicked.
Pending	The customer started to pay, but did not complete the payment process. (only for iDeal, Paypal & Tikkie)
Declined	The customer completed the payment process but the payment wasn't successful
Paid	The customer paid the amount asked.
Expired	The customer did not complete the payment before the expiration date you defined when creating the payment link.

Response Parameters

meta

Payment links used to pay invoices or direct debit transactions (in case of dunning for example) will include additional meta data. Dependant the case, different response parameters are returned.

Parameter	Description
active	the payment link url is still valid (true, false)
sdd	internal sdd identifier (Twikey)
tx	transaction id returned when linked to a transaction
method	the method of payment. Not returned when linked to a direct debit
invoice	invoice unique identifier returned when linked to an invoice

time

Parameter	Description
creation	creation of the payment link
expiration	expiry of the payment link. Not returned when there is none
lastupdate	last time the payment link was updated

A payment link can have a state 'active': false when the expiration date is not set or not yet reached. The link is then already invalidated in a different way (paid, archived,..).

HTTP Response

Code	Description
200	The request has succeeded

Error Codes

Code	Description
err_call_in_progress	Request already in progress by another client

Status paymentlink

Get status of a payment link

HTTP Request

GET /creditor/payment/link

curl  https://api.twikey.com/creditor/payment/link?id=123 \
  -H 'authorization: **authorization**'

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/payment/link?id=123");
$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/payment/link?id=123',
        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 addTransaction(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
            .url(host + "/creditor/payment/link/id=123")
            .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/payment/link?id=123");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        request.AddHeader("Authorization", authorization);
        IRestResponse response = client.Execute(request);
    }
}

[{
   "id": 1,
   "amount": 55.66,
   "msg": "Test",     // title of the paymentlink
   "ref": "My Ref",   // remittance of the paymentlink
   "state": "paid"    // one of created, started, declined, paid, pending, expired
 }]

Query Parameters

Either id or ref is mandatory.

Name	Description	Required	Type
id	Id of the link	No	string
ref	Your reference	No	string

Sideloading is also possible please see the feed parameters.

Possible states

States	Description
created	The payment link has been created but the customer did not do anything with it yet.
started	The customer has clicked on the payment link you transmitted him but did not complete the payment. In the Twikey dashboard the state will be shown as clicked.
pending	The customer started to pay, but did not complete the payment process. (only for iDeal, Paypal & Tikkie)
declined	The customer completed the payment process but the payment wasn't successful
paid	The customer paid the amount asked.
expired	The customer did not complete the payment before the expiration date you defined when creating the payment link.

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_missing_params	No parameter given
err_no_transaction	No link found based on the transaction
err_not_found	No link found

Refund paymentlink

Refund the full or partial amount of a payment link.

curl -x POST 'https://api.beta.twikey.com/creditor/payment/link/refund' \
  -H 'authorization: **authorization**'\
  -D 'id=123' \
  -D 'message=refund' \
  -D 'amount=25'

HTTP Request

POST /creditor/payment/link/refund

Supported PSP

Name	Supported
Mollie	Yes
MultiSafePay	Yes

Request Parameters

Name	Description	Required	Type
id	Paymentlink ID	Yes	string
message	Refund message	Yes	String
amount	Full or partial amount (if not passed, full amount is used)	No	number

{
    "id": 10.23,
    "amount": 25.0,
    "msg": "refund"
}

HTTP Response

Code	Description
200	The request has succeeded

Error codes

Code	Description
err_contact_support	Error details in response "extra"
err_fail_refund	Error details in response "extra"

Remove paymentlink

Remove a payment link. Only paymentlinks with status 'created' can be removed, all other ones will be archived.

curl -X DELETE https://api.twikey.com/creditor/payment/link?id=123 \
  -H 'authorization: **authorization**'

HTTP Request

DELETE /creditor/payment/link

Request Parameters

Name	Description	Required	Type
id	paymentlink ID	Yes)	string

Meta data

Including meta data when you retrieve the status of one (or more) payment link(s) provides you with the following information:

If the link was generated in a dunning step.
If the link was generated in order to get an invoice paid

{
    "Links": [
        {
            "id": 77920,
            "ct": 2223,
            "amount": 6.0,
            "msg": "123456789123",
            "ref": "CF933-20200807073818839144-0",
            "state": "created",
            "meta": {
                "sdd": "63884",
                "tx": "1234567"
            }
        },
        {
            "id": 77955,
            "ct": 2223,
            "amount": 10.0,
            "msg": "124512454",
            "ref": "CF933-202008070738447439143-0",
            "state": "created",
            "meta": {
                "tx": "1234567"
            },
        {
            "id": 76667,
            "ct": 2223,
            "amount": 100.0,
            "msg": "123456789123",
            "ref": null,
            "state": "paid",
            "meta": {
                "invoice": "a48c77a7-349e-424b-bdfc-baa748ee9e55"
            }
        }
    ]
}

Meta parameters

Name	Description
tx	The transaction for which this link was generated
sdd	The sdd transaction (state = failed) send to the bank for wich this link was generated
invoice	The invoice uuid linked to the payment link

While the tx can be returned if the link was generated on a transaction, the sdd will only be returned in the context of dunning. To retrieve related transaction, use the returned 'tx' id in the transaction status request.

Refunds (Credit Transfer)

Refunds can be used to completely or partially refund a transaction to a debtor. In exceptional cases, you may have to transfer funds from one account to another. This could be the case when you collected money that should be transferred to another person/company.

If the customer was not known, you may need to create a beneficiary account prior to making this call. In order to avoid extra costs on bank side an additional call to create the batch may be necessary or can be done automatically upon request.

Create/add a new credit transfer

Create or add a new credit transfer. This can only be done after the creation of the beneficary in case no signed SDD mandate exists. The customerNumber is strongly recommended since an account may be linked to multiple customers.

When no iban is specified in the call, if the customer has a signed sdd we use that iban for refunds.

HTTP Request

POST /creditor/transfer

curl https://api.twikey.com/creditor/transfer \
  -H 'authorization: authorization' \
  -d 'iban=BE68068897250734' \
  -d 'customerNumber=123' \
  -d 'message=test%20credit%20transfer' \
  -d 'ref'='123' \
  -d 'amount='0.00'

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfer");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    "iban=BE68068897250734"
    ."&customerNumber=123"
    ."&message=test credit transfer"
    ."&amount="50.00"
);
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/transfer',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        data: {
            "iban":"BE680688972.....",
            "customerNumber":"123",
            "message":"test credit transfer",
            "amount":"50.00"
        }
    };

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/x-www-form-urlencoded");
        RequestBody formBody = new FormBody.Builder()
            .add("iban", "BE680688972.....")
            .add("customerNumber","123")
            .add("message","test credit transfer")
            .add("amount", "50.00")
            .build();

        Request request = new Request.Builder()
          .url(host + "/creditor/transfer")
          .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 createCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/transfer");
        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",
            "iban=BE68068897250734" +
            "&customerNumber=123" +
            "&message=test credit transfer" +
            "&amount=50.00"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

{
    "Entries": [
        {
            "id": "11DD32CA20180412220109485",
            "iban": "BE12356798",
            "bic": "BBRUBEBB",
            "amount": 12,
            "msg": "test",
            "place": null,
            "ref": "123",
            "date": "2018-04-12"
        }
    ]
}

Query parameters

Name	Description	Required	Type
customerNumber	The customer number	Yes	string
iban	Iban of the beneficiary	Yes	string
message	Message to the creditor	Yes	string (140)
ref	Reference of the transaction	No	String
amount	Amount to be send	Yes	number
date	Required execution date of the transaction (ReqdExctnDt)	No	string
place	Optional place	No	string

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_invalid_iban	Invalid Iban
403	Account unregistered
err_invalid_state	Mandate existed, but was not active
err_invalid_date	Invalid date
err_invalid_sepachars	Invalid message
err_invalid_amount	Invalid amount
err_invalid_params	Invalid parameters

Get credit transfer feed

Retrieve list of credit transfers that have changes since the last call.

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

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfer");
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/transfer',
        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 getTransactions(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
            .url(host + "/creditor/transfer")
            .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; // collected through login

    public void getTransactions(){
        RestClient client = new RestClient(host + "/creditor/transfer");
        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);
    }
}

HTTP Request

GET /creditor/transfer

{
    "Entries": [
        {
            "id": "IBWICD6E44Y1N3YRMCVB2U7BA",
            "iban": "BE70361272935897",
            "bic": "GDOENFY",
            "amount": 1000,
            "msg": "credit transfer message",
            "place": null,
            "ref": "123",
            "date": "2017-01-20"
        },
        {
            "id": "X52D04L9DNNPWKCRGBV7YPV2R",
            "iban": "BE93261223700539",
            "bic": "BRODBZL",
            "amount": 12345,
            "msg": "credit transfer message",
            "place": "Brugge",
            "ref": "456",
            "date": "2018-01-23"
        },
        {
            "id": "ZE31QPMT6GRMHEY7IPOOD219R",
            "iban": "BE4447226747140",
            "bic": "ORNSRAM",
            "amount": 250099,
            "msg": "",
            "place": "Ghent",
            "ref": "789",
            "date": "2017-03-23",
            "state": "PAID", // when paid
            "bkdate": "2017-03-24"
        },
        "..."
    ]
}

HTTP Response

Code	Description
200	The request has succeeded

Details of a credit transfer

Retrieve the details of a credit transfer by id. The id is the e2e id of the credit transfer upon creating the credit transfer. By hovering over the credit transfer in Twikey GUI, the E2E id appears.

HTTP Request

GET /creditor/transfer/detail

curl https://api.twikey.com/creditor/transfer/detail?id=609C16C920180919083905923 \
  -H 'authorization: authorization'

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfer/detail?id=609C16C920180919083905923");
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/transfer/detail?id=609C16C920180919083905923',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        }
    };

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/x-www-form-urlencoded");

        Request request = new Request.Builder()
          .url(host + "/creditor/transfer/detail?id=609C16C920180919083905923")
          .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 createCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/transfer/detail?id=609C16C920180919083905923");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        IRestResponse response = client.Execute(request);
    }
}

{
    "Entries": [
        {
            "id": "609C16C920180919083905923",
            "iban": "BE08001166979213",
            "bic": "GEBABEBB",
            "amount": 5,
            "msg": "test",
            "place": null,
            "ref": "123",
            "date": "2018-09-19",
            "state": "PAID", // when paid
            "bkdate": "2017-03-24" // when paid
        }
    ]
}

Query parameters

Name	Description	Required	Type
id	id (e2e identifier) of the created refund	Yes	string

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_transaction	No such transaction

Remove a credit transfer

Remove a single credit transfer.

HTTP Request

DELETE /creditor/transfer

curl -X DELETE https://api.twikey.com/creditor/transfer?id=123 \
  -H 'authorization: **authorization**'

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfer?id=123");
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/transfer?id=123',
        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/transfer?id=123")
            .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/transfer?id=123");
        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);
    }
}

Query parameters

Name	Description	Required	Type
id	id of the created refund	Yes	string

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_transaction	No such transaction

Batch creation

Once the credit transfers are created, you need to create the batch with refunds to send to the bank. A batch can be created based upon the account from an existing contract template or new account. After the creation of the batch, the file needs to be processed in your bank environment. For some banks we can do the upload of the batch in your bank environment, for other banks you will need to download the batch from the Twikey dashboard via the menu Refunds. A refund must always be signed extra in your bank environment.

HTTP Request

POST /creditor/transfer/complete

curl https://api..twikey.com/creditor/transfer/complete \
  -H 'authorization: authorization' \
  -d 'ct=**ct_id**'

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfer"/complete);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "ct=$ct");
curl_setOpt($ch, CURLOPT_HTTPHEADER,"authorization: $authorization");

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

var https = require('https'),
    ct= "**ct_id**",
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/transfer/complete',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        data: {
            "ct": ct
        }
    };

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

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

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

        MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
        RequestBody formBody = new FormBody.Builder()
            .add("ct", ct)
            .build();

        Request request = new Request.Builder()
          .url(host + "/creditor/transfer/complete")
          .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 completeCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/transfer/complete");
        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,
            ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

Query parameters

Name	Description	Required	Type
ct	Template containing the originating account	Yes	string
iban	Originating account, if different from ct account	No	string

HTTP Response

Code	Description
200	The request has succeeded
400	Invalid request

Batch details

Get all details from a specific batch

HTTP Request

GET /creditor/transfer/complete

curl https://api..twikey.com/creditor/transfer/complete \
  -H 'authorization: authorization' \
  -d 'id=**id**'

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfer/complete?id=123");
curl_setOpt($ch, CURLOPT_HTTPHEADER,"authorization: $authorization");

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

var https = require('https'),
    ct= "**ct_id**",
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/transfer/complete?id=123',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        }
    };

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 completeCreditTransfer(){
        OkHttpClient client = new OkHttpClient();

        MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
        Request request = new Request.Builder()
          .url(host + "/creditor/transfer/complete?id=123")
          .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 completeCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/transfer/complete?id=123");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("authorization", authorisation);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        IRestResponse response = client.Execute(request);
    }
}

Query parameters

Name	Description	Required	Type
id	Id of the batch previously submitted	No	string
pmtinfid	PmtInfId of the batch previously submitted	No	string

HTTP Response

Code	Description
200	The request has succeeded
400	Invalid request

Error codes

Code	Description
err_invalid_params	No such batch available

Get beneficiary accounts

Fetch a list of all customers' beneficiary accounts.

HTTP Request

GET /creditor/transfers/beneficiaries

curl https://api.twikey.com/creditor/transfers/beneficiaries?withAddress=true \
  -H 'authorization: authorization'

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfers/beneficiaries?withAddress=true");
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/transfers/beneficiaries?withAddress=true',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        }
    };

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/x-www-form-urlencoded");

        Request request = new Request.Builder()
          .url(host + "/creditor/transfers/beneficiaries?withAddress=true")
          .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 createCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/transfers/beneficiaries?withAddress=true");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("authorization", authorisation);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        IRestResponse response = client.Execute(request);
    }
}

{
    "beneficiaries": [
        {
            "name": "sdfsf",
            "iban": "BE92221216720939",
            "bic": "GEBABEBB",
            "available": true,
            "address": null
        },
        {
            "name": "beneficiary2",
            "iban": "BE16645348971174",
            "bic": "JVBABE22",
            "available": true,
            "address": {
                "street": "Veldstraat 11",
                "city": "Gent",
                "zip": "9000",
                "country": "BE"
            }
        }
    ]
}

Query parameters

Name	Description	Required	Type
withAddress	include addresses in reponse	Yes	boolean

HTTP Response

Code	Description
200	The request has succeeded
500	System error

Add a beneficiary account

In order to be able to do a refund, one needs to have a beneficiary account. The account can be either created explicitly via this call or implicitly via a signed SDD mandate. In the latter case, the account from the mandate is taken so you can immediately call the refund without this call.

Creating a beneficiary account can be done for an existing customer or a new one. This is done based on the customerNumber or in its absence the email address. If a customer is found, the address will also be updated if address, zip, city and country are passed on in the call.

For new customers and therefor new accounts, it is strongly advised to add the customerNumber as it allows you to reference them later for updates or creation of other objects such as contracts/mandate and/or paymentlinks. An address and name are mandatory, mobile and language are optional though recommended as it makes the customers journey better.

HTTP Request

POST /creditor/transfers/beneficiaries

curl -X POST https://api.twikey.com/creditor/transfers/beneficiaries \
  -H 'authorization: authorization' \
  -d 'customerNumber=123' \
  -d 'email=support@twikey.com' \
  -d 'name=Support Twikey' \
  -d 'l=NL' \
  -d 'mobile=32479123123' \
  -d 'address=Stationstraat 43' \
  -d 'zip="9051"' \
  -d 'city=Sint Denijs Westrem' \
  -d 'country=BE' \
  -d 'iban=BE68068897250734' \
  -d 'bic=JVBABE22'

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfers/beneficiaries");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    "&email=support%40twikey.com"
    ."&customerNumber=123"
    ."&name=Support Twikey"
    ."&l=NL"
    ."&address=Stationstraat%2043"
    ."&zip=9051"
    ."&city=Sint%20Denijs%20Westrem"
    ."&country=BE"
    ."iban=BE68068897250734"
    ."bic=JVBABE22"
);
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/transfers/beneficiaries',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        data: {
            "customerNumber": "134",
            "email": "support@twikey.com",
            "name": "Support Twikey",
            "l": "NL",
            "address": "Stationstraat 43",
            "zip": "9051",
            "city": "Sint Denijs Westrem",
            "country": "BE",
            "iban": "BE68068897250734",
            "bic": "JVBABE22"
        }
    };

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/x-www-form-urlencoded");
        RequestBody formBody = new FormBody.Builder()
            .add("customerNumber", "134")
            .add("email", "support@twikey.com")
            .add("name", "Support Twikey")
            .add("l", "NL")
            .add("address", "Stationstraat 43")
            .add("zip", "9051")
            .add("city", "Sint Denijs Westrem")
            .add("country", "BE")
            .add("iban","BE68068897250734")
            .add("bic", "JVBABE22")
            .build();

        Request request = new Request.Builder()
          .url(host + "/creditor/transfers/beneficiaries")
          .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 createCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/transfers/beneficiaries");
        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",
            "&customerNumber=123" +
            "&email=support%40twikey.com" +
            "&name=Support Twikey" +
            "&l=NL" +
            "&address=Stationstraat%2043" +
            "&zip=9051" +
            "&city=Sint%20Denijs%20Westrem" +
            "&country=BE" +
            "iban=BE68068897250734" +
            "bic=JVBABE22"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

{
    "name": "Beneficiary Name",
    "iban": "BE68068897250734",
    "bic": "JVBABE22",
    "available": true,
    "address": {
        "street": "Veldstraat 11",
        "city": "Gent",
        "zip": "9000",
        "country": "BE"
    }
}

Query parameters

Name	Description	Required	Type
customerNumber	The customer number	Yes	string
name	Firstname & lastname of the debtor (required if debtor is not a company)	Yes	string
email	Email of the debtor	No	string
l	language of the customer ISO format (2 letters)	No	string
mobile	Mobile number required for sms (International format +32499123445)	No	string
address	The street name and number/box	Yes	string
city	City of debtor	Yes	string
zip	Zipcode of debtor	Yes	string
country	ISO format (2 letters)	Yes	string
companyName	The company name (required if debtor is company)	Yes	string
vatno	The enterprise number (if debtor is company)	No	string
iban	IBAN of the beneficiary	Yes	string
bic	BIC of the beneficiary	Yes	string

HTTP Response

Code	Description
200	The request has succeeded
400	Validation error due to wrong user input
500	System error

Error codes

Code	Description
err_name_required	Invalid or missing name
err_invalid_iban	Invalid IBAN number
err_invalid_bic	Invalid BIC number
register_address_missing	Address missing

Disable a beneficiary account

Removal of a beneficiary can be done via an IBAN number, but it's strongly advisable to add the customerNumber in the call. This is optional for backwards compatible reasons, but strongly recommended as an account may be used on multiple customers. Note that the the beneficiary will be disabled and not deleted. Reactivating a beneficiary account can only be done using the interface.

HTTP Request

DELETE /creditor/transfers/beneficiaries/{IBAN}?customerNumber={customerNumber}

curl -X DELETE https://api.twikey.com/creditor/transfers/beneficiaries/BE16645348971174?customerNumber=123 \
  -H 'authorization: **authorization**'

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/transfers/beneficiaries/BE16645348971174?customerNumber=123");
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/transfers/beneficiaries/BE16645348971174?customerNumber=123',
        method: 'DELETE',
        headers: {
            '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/transfers/beneficiaries/BE16645348971174?customerNumber=123")
            .delete(null)
            .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/transfers/beneficiaries/BE16645348971174?customerNumber=123");
        RestRequest request = new RestRequest(Method.DELETE);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("Authorization", authorization);

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

HTTP Response

Code	Description
200	the request has succeeded, no content
400	bad request, the IBAN provided is not valid
404	the entity was not found
500	system error

Error codes

Code	Description
err_not_found	No such beneficary
err_invalid_iban	No beneficary found for that IBAN
err_fail_refund	Beneficiary account is disabled
error_system	An error occured on the system

Issuers

Some requests require to pass a BIC code to identify the bank. With this request you can fetch the banks connected to Emachtiging, iDIN, iDeal.

Fetch connected banks

Return the banks that are currently connected to iDIN, Emachtiging and iDeal. For Emachtiging CORE banks are returned by default. A 'type' parameter can be passed to return B2B supported banks.

HTTP Request

GET /creditor/issuers/<method>

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

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/issuers/ideal");
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/issuers/ideal',
        method: 'GET',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        }
    };

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/x-www-form-urlencoded");
        Request request = new Request.Builder()
          .url(host + "/creditor/issuers/ideal")
          .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"
        authorisation = null; // collected through logIn

    public void createCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/issuers/ideal");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("authorization", authorisation);
        request.AddHeader("content-type", "application/x-www-form-urlencoded");
        IRestResponse response = client.Execute(request);
    }
}

[
    {
        "Bic": "ABNANL2A",
        "Name": "ABN AMRO"
    },
    {
        "Bic": "ASNBNL21",
        "Name": "ASN"
    }
]

Method

Replace by one of the currently supported methods:

emachtiging
idin
ideal

Query parameters

Name	Description	Required	Type
type	only for method emachtiging. 'core' (default) or 'b2b'	No	string

HTTP Response

Code	Description
200	The request has succeeded
400	bad request

Customer

Update a customer

Update a customer via this request. It is not possible create a new customer or to merge customers using this request.

  curl PATCH 'https://api.twikey.com/creditor/customer/{customerNumber}?
  firstname=John
  &lastname=Doe
  &address=Highstreet 66
  &city=Gent
  &zip=9000
  &country=BE
  &l=nl
  &email=mycustomer@example.com
  &mobile=+32488995577
  &ct=2223
  &customerNumber=newCustomerNumber123' \
--h 'Authorization: .....'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.twikey.com/creditor/customer/{customerNumber}?firstname=John&lastname=Doe&address=Highstreet%2066&city=Gent&zip=9000&l=NL&email=mycustomer@example.com&mobile=+32488995577&ct=2223&customerNumber=newCustomerNumber123',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_HTTPHEADER => array(
    'Authorization: ....'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

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

var urlencoded = new URLSearchParams();

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

fetch("https://api.twikey.com/creditor/customer/{customerNumber}?firstname=John&lastname=Doe&address=Highstreet 66&city=Gent&zip=9000&lang=NL&email=mycustomer@example.com&mobile=+32488995577&ct=2223&ref=newCustomerNumber123", 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, "");
        Request request = new Request.Builder()
        .url("https://api.twikey.com/creditor/customer/{customerNumber}?firstName=John&lastname=Doe&address=Highstreet 66&city=Gent&zip=9000&l=NL&email=mycustomer@example.com&mobile=+32488995577&ct=2223&customerNumber=newCustomerNumber123")
        .method("PATCH", body)
        .addHeader("Authorization", ".....")
        .build();
        Response response = client.newCall(request).execute();

var client = new RestClient("https://api.twikey.com/creditor/customer/11233?firstname=John&lastname=Doe&address=Highstreet 66&city=Gent&zip=9000&l=NL&email=mycustomer@example.com&mobile=+32488995577&ct=2223&customerNumber=newCustomerNumber123");
client.Timeout = -1;
var request = new RestRequest(Method.PATCH);
request.AddHeader("Authorization", ".....");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

HTTP Request

PATCH https://api.twikey.com/creditor/customer/{customerNumber}

Query Parameters

Name	Description	Required	Type	Max.
ct	Default template	No	integer	4
l	Language (en/fr/nl/de/pt/es/it)	No	string	2
customerNumber	Update the customer number	No	string	50
email	Email of the customer	No	string	70
lastname	Lastname of the customer	No	string	50
firstname	Firstname of the customer	No	string	50
mobile	Mobile number required for sms (International format 0032499123445)	No	string	50
address	Address (street + number)	No	string	70
city	City of customer	No	string	50
zip	Zipcode of customer	No	string	50
country	ISO format	No	string	2
companyName	The company name (if customer is company)	No	string	140

HTTP Response

Code	Description
204	Request has succeeded
400	Request failed

Error codes

Code	Description
err_invalid_params	Invalid parameters
err_invalid_country	Country code invalid
err_invalid_email	Email invalid
err_invalid_lang	Language code invalid
err_debtor_not_found	customer not found
err_duplicate_ref	the customer number already exist

Other

Blacklist account

When there is (suspected) abuse or another valid reason, you can add bank accounts to a blacklist. Bank accounts listed can't be used to register new mandates, existing mandates registered with this iban can be suspended or cancelled. The option to notify the customer will trigger the standard email informing the customer that their mandate was suspended, reactivated or cancelled.

Blacklisting is available in the Enterprise subscription.

When adding a bank account to the blacklist a parameter can be passed to change the state of all the mandates registered with this iban. "passive": The mandate is suspended. "cancel": The mandate is cancelled.

curl -X POST 'https://api.twikey.com/creditor/ibanblacklist' \
--h 'Authorization: {{authorization}}' \
--d' rsn=IBAN blacklisted' \
--d 'iban=BE123456789123456' \
--d 'notify=false' \
--d 'state=passive' \

response

 "iban": "BE123456789123456",
    "rsn": "IBAN blacklisted",
    "state": "passive",
    "updatedMandates": [
        {
            "mndtId": "MNDT123"
        }
                        ]

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.twikey.com/creditor/ibanblacklist',
  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 => 'rsn=IBAN%20blacklisted&iban=BE123456789123456&notify=false&state=passive',
  CURLOPT_HTTPHEADER => array(
    'Authorization: $authorization'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

HTTP Request

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

Query Parameters

Name	Description	Required	Type
iban	bank account to add to the blacklist	Yes	string
rsn	reason	Yes	string
state	update all mandates state registered with this iban (passive, cancel)	No	string
notify	notify the customer by email	No	boolean

HTTP Response

Code	Description
200	Request succeeded
400	Invalid or missing parameter(s)

Error codes

Code	Description
err_provide_reason	Reason is missing
err_invalid_params	invalid or missing parameter

List blacklisted accounts

Retrieve a list of all the bank accounts currently blacklisted.

curl GET 'https://api.twikey.com/creditor/ibanblacklist' \
--h 'Authorization: {{authorization}}'

[
    {
        "iban": "BE123456789123456",
        "rsn": "IBAN blacklisted"
        },
    {
        "iban": "BE33445566889988",
        "rsn": "Suspected abuse"
    }
]

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.twikey.com/creditor/ibanblacklist',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: $authorization'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var myHeaders = new Headers();
var authorization = '.......';

myHeaders.append("Authorization", authorization);

var urlencoded = new URLSearchParams();

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

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

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://api.twikey.com/creditor/ibanblacklist")
  .method("GET", null)
  .addHeader("Authorization", ".......")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.twikey.com/creditor/ibanblacklist");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "........");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

HTTP Request

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

HTTP Response

Code	Description
200	Request succeeded

Remove blacklisted account

Remove prior added accounts from the blacklist. Suspended mandates can be reactivated using this request.

curl -X DELETE 'https://api.twikey.com/creditor/ibanblacklist' \
--h 'Authorization: {{authorization}}' \
--d 'iban=BE123456789123456' \
--d 'state=active' \
--d 'notify=false'

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.twikey.com/creditor/ibanblacklist?iban=BE123456789123456&state=active&notify=false',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => array(
    'Authorization: $authorization'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

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

var urlencoded = new URLSearchParams();

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

fetch("https://api.twikey.com/creditor/ibanblacklist?iban=BE123456789123456&state=active&notify=false", 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, "");
Request request = new Request.Builder()
  .url("https://api.twikey.com/creditor/ibanblacklist?iban=BE123456789123456&state=active&notify=false")
  .method("DELETE", body)
  .addHeader("Authorization", "......")
  .build();
Response response = client.newCall(request).execute();

var client = new RestClient("https://api.twikey.com/creditor/ibanblacklist?iban=BE123456789123456&state=active&notify=false");
client.Timeout = -1;
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "......");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

{
  "iban": "BE123456789123456",
  "state": "active",
  "updatedMandates": [
    {
      "mndtId": "MNDT123"
    }
  ]
}

HTTP Request

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

Query Parameters

Name	Description	Required	Type
iban	bank account to remove from the blacklist	Yes	string
state	reactivate all suspended mandates using this iban (active)	No	string
notify	notify the customer by email	No	boolean

HTTP Response

Code	Description
200	Request succeeded
400	Invalid or missing parameter(s)

Error codes

Code	Description
err_invalid_params	invalid or missing parameter

Account reporting

Get account reporting, this endpoint allows you to retrieve a stream of items listed on your account as soon as they're made available from the bank.

Returns all reporting since the last call.

HTTP Request

GET /creditor/reporting

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

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/reporting");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$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/reporting',
        method: 'GET',
        headers: {
            '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 updateTransaction(){
        OkHttpClient client = new OkHttpClient();

        Request request = new Request.Builder()
            .url(host + "/creditor/reporting")
            .get()
            .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/reporting");
        RestRequest request = new RestRequest(Method.PUT);
        request.AddHeader("cache-control", "no-cache");
        request.AddHeader("Authorization", authorization);
        IRestResponse response = client.Execute(request);
    }
}

{
    "Statements": [
        {
            "id": 146406841,
            "type": "PMNT/RCDT/ESCT",
            "date": "2018-11-20",
            "amount": 12.58,
            "iban": "BE01234567890123",
            "bic": "GEBABEBB",
            "msg": "Testing",
            "mndtId": "TST123",
            "party": "Koen BVBA"
        }
    ]
}

HTTP Response

Code	Description
200	The request has succeeded

Retrieve Identification url

Identification can be used to identify a customer using a third party (bank, government, ..). When using this request, a url to their services is generated that can be used by the customer. A template of type 'IDENT' is requested and a specific signing method. Currently supported signing methods are iDIN (Netherlands) and itsme (Belgium).

Retrieve direct link from the bank

HTTP Request

POST /creditor/ident

curl https://api..twikey.com/creditor/ident \
  -H 'authorization: authorization' \
  -d 'ct=**ct_id**'

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

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/ident");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "ct=$ct&bic=ABNANL2A");
curl_setOpt($ch, CURLOPT_HTTPHEADER,"authorization: $authorization");

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

var https = require('https'),
    ct= "**ct_id**",
    querystring = require('querystring'),
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/ident',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        data: {
            "ct": ct,
            "bic": 'ABNANL2A'
        }
    };

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

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

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

        MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
        RequestBody formBody = new FormBody.Builder()
            .add("ct", ct)
            .add("bic","ABNANL2A")
            .build();

        Request request = new Request.Builder()
          .url(host + "/creditor/ident")
          .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 completeCreditTransfer(){
        RestClient client = new RestClient(host + "/creditor/ident");
        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,
            "bic=ABNANL2A",
            ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

Query parameters

Name	Description	Required	Type
ct	Template containing the originating account	Yes	string
bic	BIC Code of the bank to retrieve a url for (Idin only)	Yes	string
method	itsme or idin	Yes	string
l	Language	No	string

HTTP Response

Code	Description
200	The request has succeeded

Error Codes

Code	Description
err_bank_t_o	Time out at the bank
err_idin_fail	Failure at the bank

Transaction reservations

Validates if a transaction is eligible for creation and returns a reservation code that can be used to create the actual transaction. The transaction is evaluated against your configured risk rules.

To create a reservation:

You can use the same parameters as in the actual transaction but an extra 'reservation=true' parameter is required.

Name	Description	Required	Type	Max.
reservation	Indicates this is a reservation (should contain true)	Yes	boolean	4
reservationMinimum	Optional value, which if passed allows Twikey to reserve the highest amount lower than the amount but higher than this value	No	decimal
reservationExpiration	Optional date after which this reservation automatically is voided	No	date

The default reservation code is valid for 24h

To create a transaction for the reservation:

Add the header X-RESERVATION with the reservation code as value
the amount can be equal or less as the reserved amount
A response 200 is received: the request succeeded

HTTP Request

POST /creditor/reservation

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

{
    "id":"2e708d7a-a4bf-4535-aea2-3ab24c179519",
    "mndtId":"MYMANDATE123",
    "reservedAmount":50.00,
    "expires":"2021-12-07T22:42:47Z"
}

{
    "code": "err_billing_overdrawn",
    "message": "Maximum amount reached",
    "over_amount": "50.00",
    "rule_amount": "400.00",
    "rule": "Limit400euro",
    "tx_amount": "125.00"
}

When a new transaction can't be created due to configured risk rules, the details are returned in the response.

Code	Description
err_billing_overdrawn	Maximum amount/number of transactions reached according to risk rules
rule_amount	Maximum amount/number of transactions defined in the risk rule
over_amount	Amount/number of transactions exceeding the risk rule

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_contract	No mandate found
err_invalid_state	The mandate is not active
err_invalid_date	Invalid Date
err_invalid_sepachars	Invalid characters in message to debtor
err_invalid_amount	Invalid Amount given

IBAN-Name Check

The IBAN-Name Check allows you to verify account details registered at the bank of origin. When a response is returned, it is wat is registered at the bank-side, not in your Twikey environment.

HTTP Request

POST /creditor/ibancheck

curl -X POST https://api.twikey.com/creditor/ibancheck \
  -H 'authorization: **authorization**'\
  -d 'name=Doortje Doorzon' \
  -d 'iban=NL51ABNA0577013939'

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/ibancheck");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,"name=Doortje Doorzon"
    ."&iban=NL51ABNA0577013939");
$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/ibancheck',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body :{
            'name' : 'Doortje Doorzon',
            'iban': 'NL51ABNA0577013939'
        }
    };

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("name", "Doortje Doorzon")
            .add("iban", "NL51ABNA0577013939")
            .build();

        Request request = new Request.Builder()
            .url(host + "/creditor/ibancheck")
            .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/ibancheck");
        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",
            "name=Doortje Doorzon" +
            "iban=NL51ABNA0577013939"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

{
    "iban": {
        "found": true,
        "valid": true,
        "blackListed": false,
        "nameMatching": true
    },
    "name": {
        "valid": true,
        "suggestion": "some suggestion"
    },
    "account": {
        "foreign": false,
        "countryCode": "NL",
        "active": true,
        "holderType": "NP",
        "holderResidenceMunicipality": "Amsterdam",
        "holderOfficialName": "",
        "holdersNumber": 1,
        "holderJointAccount": false
    }
}

Request Parameters

Name	Description	Required	Type	Max.
name	Name of the account holder	Yes	string	70
iban	Account number	Yes	string	34

Response Parameters

Name	Description	Type
iban.found	True if the IBAN is found in the registry	boolean
iban.valid	True if the specified IBAN has a valid format	boolean
iban.blackListed	True if the iban is blacklisted	boolean
iban.nameMatching	True if the name matches the name of the account holder	boolean
name.valid	The name registered in the system (not the one provided) is valid [*1].	boolean
name.suggestion	When the provided name doesn't match the account holders name or type [*2].	string
account.foreign	True if the account is Dutch	boolean
account.countryCode	Country code of the account (ISO 2 characters)	string
account.active	True if the account is active	boolean
account.holderType	Type of account holder. [*3]	string
account.holderResidenceMunicipality	City of the account holder	string
account.holderOfficialName	Official name of the account holder	string
account.holdersNumber	Number of account holders for this account	number
account.holderJointAccount	True if it is a joint account	boolean

[1] The name *registered in the system** (not the one provided) is valid

True (valid): The name is between 3 and 70 characters long.
False (invalid): if the name is shorter than 3/longer than 70 characters or if only first name is entered.

[*2] When the provided name doesn't match the account holders name or type

When the provided name does not completely match the account holders name, a suggestion is returned. E.g.: in case of a mistype.
When the account belongs to an organization, the legal name of the organization is provided.

[*3] Type of account holder.

NP: person
ORG: Organization
Unknown: account type is unknown

HTTP Response

Code	Description
200	The request has succeeded
400	User error if parameter is given but not valid (available in apierror header and response)

Error codes

Code	Description
err_no_integration	No intergation was configured
err_invalid_name	The provided name is invalid
err_err_invalid_iban	The provided account is invalid
err_fail_integration	An error occured on the system

Webhooks

In order to reduce the number of polling requests, one can opt to implement a webhook endpoint and use this as a way to trigger polling requests. The endpoint is set in the API section of the settings screen and will convey information about various events in Twikey. The call is done via a simple GET with basic (non-sensitive) parameters eg. http://my.company.com/callback?type=contract&mandateNumber=MNDT123&state=signed...

In order to verify that the request is indeed coming from Twikey you can verify the 'X-Signature' header. This is a one-way encryption (HMAC256) of the url-decoded posted fields with your secret key (apiToken) converted into a hex encoded string.

Setup the different webhooks in your Twikey Dashboard under 'Settings: Api'. Activate up to four differen categories (documents, payments, customer updates and other events).

You can test your implementation by using the 'Test' button in your environment (Api settings) which will send the sample payload 'msg=dummytest&type=event' as text.

$apiKey = "**API_KEY**";
$message= urldecode($_SERVER['QUERY_STRING']);
$xsignature= hash_hmac('sha256', $message, $apiKey);

$provided_signature= $_SERVER['HTTP_X_SIGNATURE']; // To verify that both signatures match

echo $xsignature;

Retry mechanism

When a HTTP request is made, but we receive an error code (e.g. 3xx, 4xx, 5xx) the request is marked to be retried. All requests following this one will be suspended for a certain duration (currently 30min.)

We try up to 3 times after which the request will be archived and eventually removed. This allow us to resend the webhooks in case you have some issues on your end.

Note that the url to be given in the interface is without parameters since these are filled up depending on the type.

Types

type=contract

curl -H "apiToken=MyToken" https://example.com/callback \
    -d type=contract \
    -d reason=resumed \
    -d mandateNumber=CORE01 \
    -d name=<empty> \
    -d contractNumber=General terms and conditions \
    -d state=SIGNED \
    -d event=Update

Triggered when something happens to the mandate. Activation events will be included in the event=Update with the reason being either 'resumed' or 'suspended'. Update events can also contain a specific _Txx code.

mandateNumber: Mandatenumber
contractNumber: Contract reference defined on the template under 'General', or a custom reference if assigned one during the creation of the document.
state: Previous state of the document
name: This parameter is not used anymore and the value is always empty when returned (kept in place for some older configurations).
event: Name of the event
reason: Optional reason

Specific codes:

_T50 Account changed
_T51 Address changed
_T52 MandateNumber changed
_T53 Name changed
_T54 Email changed
_T57 Owner Mandate changed

type=plan

Triggered when a plan was executed

Extra parameters:

name : Name of the plan that was executed

type=customer

Triggered on customer updates.

Eg. When two customers are merged, you receive a webhook for both customers. If a customer has documents, you'll recieve a webhook with type=contract for every document.

type=payment (batch)

type=payment (batch)

type    payment

Triggered when a batch of payments were received. Note that this is triggered for the batch and not per transaction as it could cause a flood of requests.

No parameters to avoid hammering your site when new transaction feedback is received

type=payment (payment links)

type=payment (payment links)
amount 45.42
ct      2223
id      186229
ref     123456
status  paid
type    payment

Triggered when a paymentlink was updated to either paid, rejected or expired. In that case you will receive the initial id, ref and status back.

type=payment (invoices)

type=payment (invoices)
amount  168.05
ct      2223
id      186402
ref     813124990774
status  paid
type    payment

Currently we do not provide a dedicated webhook for invoices. The type=payment can be used instead when the invoice is paid by direct payment. You will receive the linked paymentlink id and ref (remittance of the invoice).

type=dunning

type=dunning
mandateNumber    MNDT123
txIds            [258802]
type             dunning

Triggered when a dunning action was executed for a failed transaction. Option to notify 'webhook' must be activated in the dunning actions.

Extra parameters:

mandateNumber : Mandatenumber
txIds : Transaction ID
type=ipex

type             ipex
mailId           JJBEA120090000185103100
docType          contract
createdOn        2021-11-17 10:58:01.962
sentOn           2021-11-17
delivered        true
docNumber        WIKLETTER420

Triggered when a letter was delivered or bounced.

Extra parameters:

mailId : Id returned by the actual post service
docType : Type of document
createdOn : When the document was generated
delivered : When the document was delivered to the post service
docNumber : Reference to the document (invoice number or mandate number)

Exit Url

An alternative to a webhook can be the exit url or the page where the end-user is being redirected to after signing. This is a thank-you page or a redirect to an exit url defined on the template. This url can contain variables that are filled in depending on the outcome. The variables can either be positional or named.

{0} / {{mandateNumber}} : mandate number
{1} / {{status}} : status (ok = returned without error)
{2} / {{account}} : iban/bic encrypted wih key privateKey+contract.getMandateNumber()
{3} / {{s}} : signature over mandate and status separated by a slash (hex encoded)
{4} / {{token}} : token (optional: if passed in the incoming url)

Some of the exceptional statusses can be (but not limited to):

ok: document is signed
cancel: cancel in the signing flow
fail: signature / authentication failed
pending: signature still pending (customer printed the document, extra signatures required)

Exit url's can be defined for mandates and invoices as described in How to define an exit URL.

In order to be sure that the return call is coming from Twikey, it's strongly recommended to verify the signature to the exit url. View our sample code snippets to find examples in various languages on how to calculate the signature.

eg. an exit url with the following value

http:///website.com/{0}/{1}/{3}

http:///website.com/{{mandateNumber}}/{{status}}/{{s}}

would be expanded to if the end-customer returned without error

http:///website.com/MND123/ok/C9FB0D93...

Changes

January 2022
- 07/01 Payment links: Send registered email A new value added for the parameter 'sendInvite'. The value 'registeredEmail' can be passed to send a registered email (requires integration).
- 07/01 Create invoice: new parameter 'manual' When creating a new invoice you can pass the parameter 'manual' (boolean). When set on true creates no transaction for the invoice.
- 07/01 Invoice details: fetch details by invoice number The invoice number can now also be used to fetch invoice details. Before it was only possible via the unique identifier.
December 2021
- 05/12 Allow custom attributes for invoices and payment links You can now use custom attributes defined on your template when creating a new invoice or payment link. The attribute is returned in the detail and feed and can also be used in invitations to pay.
November 2021
- 12/11 Create transaction: additional response added for risk rules When a new transaction cannot be created due to a risk rule, additional information is now included in the response (amount exceeding the risk rule, allowed amount, rule name, ...).
October 2021
- 29/10 Transaction feed and status: include link The transaction feed and status request can return the payment link url used in dunning. To retrieve this use the 'include=link' parameter. Note: it is only available when the dunning is ongoing.
- 28/10 Added Update customer request Updating a customer can now be done via the PATCH request 'update customer'.
- 28/10 Create transaction: 'dryrun' renamed to 'reservation' and improved usage The parameter 'dryrun' was renamed to 'reservation'. The reservation parameter can now be used to not only validate if a transaction can be created, but also create a reservation code for it that is returned in the response header.
- 18/10 Paymentlinks: Added X-Purpose header Create a new payment link: 'X-Purpose' header was added. You can use this to alter the url for specific use cases.

September 2021
- 14/09 Fetch connected banks for Dutch issuers: new endpoint New endpoint to fetch connected banks for Dutch issuers. GET host/creditor/issuers/method allows to retrieve the connected banks for Emachtiging, iDIN and iDeal.
- 14/09 Create transaction: New parameter 'dryrun' The parameter 'dryrun' (boolean) allows you to do a validation check before creating the transaction. During the dryrun the transaction is evaluated through your risk rules.

August 2021
- 05/08 Company ID is returned in the authorization header Your company ID is now included in the authorization response header X-MERCHANT-ID.

July 2021
- 28/07 Create invoice: 'title' is generated when empty The value of the 'title' parameter is generated automatically if left empty.
- 27/07 Mandate invite: added two new parameters '_txd' and '_txr' The parameters enable you to use your own transaction message and reference when the customer signs the mandate using a payment. Those are also used in the verification reconciliation files.
- 12/07 Mandate invite: can now be sent by letter (IPEX) Invitations can now be send by letter. Two new values are available for the 'sendInvite' parameter. 'letter' or 'letterWithMandate' can be used.
- 12/07 New Invoice: language handling revised The language of the invoice is now only defined by the language passed in the invoice object. The parameter to use is 'l' or 'locale'
June 2021
- 21/06 New endpoint for invoices: UBL Import invoices in UBL format.
- 14/06 New Transaction: 'date' parameter The 'date' parameter is now limited to 10 days in the past and future.
- 02/06 Reconciliation files: new formats available New formats available: MT940 (Exact Online/Twinfield) and Coda 6 (detail).

May 2021
- 19/05 Transaction feed: include dunning steps A new parameter 'include=action' returns the dunning steps taken for a transaction.
- 10/05 Create invoice: updated required parameters for the customer object The customer object parameters for address are not mandatory anymore. The 'customerNumber' and/or 'email' is the minimal requirement now.
- 07/05 Payment link status and feed: Added more response The meta data now includes the parameter 'active' returning a boolean value about the validity of the link. The parameter 'include=time' was added and returns creation, expiry and last updated.
April 2021
- 23/04 New Transaction: reference as End To End Identifier The new parameter 'refase2e' can be set on true to use the 'ref' parameter as end to end identifier for the first payment.
- 19/04 Transaction Feed/Status: include collection Includes the batch identifier in the transaction feed or status.
March 2021
- 19/03 Transaction feed improvements The feed is now restricted to 100 returned transactions each call. Enhancements were also made for a faster performance.
- 11/03 Action on transaction: replaced parameter Replaced the deprecated parameter 'transfer' with 'backup'. The parameter is used to send an email with a backup payment method in case of a failed payment.
- 01/03 Blacklist bank accounts New request added to blacklist bank accounts. Requires Enterprise subscription.
- 01/03 Invoice details & feed: replaced additional parameter The parameter 'include=paymentdetail' was replaced by 'include=lastpayment'. A more detailed and clear overview of past payments.
February 2021
- 15/02 Webhooks are now sorted in four catgories Webhooks are now sorted in four categories that can be triggered. Activate or deactivate the webhooks in your Twikey Dashboard under 'Settings: Api'.
- 05/02 Removed parameter 'mndtId' from the transaction delete request To avoid the risk of deleting transactions in bulk, the parameter was removed.
- 04/02 New request for collection: import a collection This request can be used to upload a batch for collection.
- 03/02 Create invoices: return invoice details When the same invoice number already exist, we return the invoice details instead of a duplicate message.
January 2021
- 19/01 New request for transactions: refund a transaction
- 10/01 Allow paymentlinks to be retrieved via transaction (also in feed)
December 2020
- 17/12 Allow archiving of transaction
- 7/12 Ident response should also show mandate number
November 2020
- 23/11 Removed parameter 'form' in the invite request.
  This parameter is not supported anymore. The form can be added in the companyName parameter instead.
- 19/11 New invite or reminder request for invoices: action
  Use the action request to send out the initial invitation or a reminder to the customer. Can be done by email or sms.
- 18/11 New parameter for credit transfers: ref
  Add a reference to a credit transfer. Enables to create a reference of the transaction between our platform and your (booking) system.
- 10/11 Move a mandate to another customer
  Move a mandate to another customer using the mandate update request.
- 09/11 Update or add a customer number
  Update or add the customer number when updating mandate details.
July 2020
- 28/07 New request for invoices: Update invoice
  Update title, date, due date and PDF on invoices.
- 28/07 New parameter for payment links: invoice
  Create a payment link to pay the total or partial amount of invoices.
- 24/07 New parameter for beneficiary accounts: customerNumber
  Ensure the beneficiary account is created on the correct customer.
- 23/07 New parameter for payment links: sms
  Send invites for payment links by sms.
- 10/07 New identification method: Itsme
  Itsme identification is now possible.
April 2020
- 29/04 New parameter for payment link feed 'include'
  Added possibility of sideloading customers for paymentlinks
- 29/4 Added ct parameter to payment link information
March 2020
- 23/03 Added parameters and return codes for invoices.
  Improved documentation about states of invoices
- 20/03 Renamed error from err_mandate_invalid_state to err_invalid_state
- 14/03 Improved webhook verification method added (X-Signature)
  A newer verification method X-Signature was added to the header. The previous verification method can still be used, but will be dropped end of april
February 2020
- 17/02 Added HTTP request to add comments to a mandate
  A new request was added to post a public or private comment on the audit trail of a mandate.

General use

Sample use cases

The fitness scenario

The parking app scenario

The (off-line) webshop scenario

Authentication

Login

HTTP Request

Form Parameters

HTTP Response

Error codes

Logout

HTTP Request

HTTP Response

Mandate

Invite a customer

HTTP Request

Query Parameters

Special cases:

HTTP Response

Error codes

Sign a mandate

HTTP Request

Query Parameters

HTTP Response

Error codes

Mandate Feed

HTTP Request

Query Parameters

Headers

Response

Error Codes

Signed, Updated, Cancelled

Signed

Updated

Cancelled

Cancel a mandate

HTTP Request

Query Parameters

HTTP Response

Error codes

Fetch mandate details

HTTP Request

Query Parameters

Response

Error codes

Update mandate details

HTTP Request

Query Parameters

HTTP Response

Error codes

Move a mandate

Customer access

HTTP Request

Query Parameters

HTTP Response

Error Codes

Update planned transactions

HTTP Request

Query Parameters

HTTP Response

Error codes

Retrieve pdf

HTTP Request

Query Parameters

HTTP Response

Error codes

Upload pdf

HTTP Request

Query Parameters

HTTP Response

Error codes

Retrieve legal terms

Transactions

New transaction

HTTP Request

Request Parameters

HTTP Response

Error codes

Transaction feed