Nav
bash php javascript java C#

General use

Twikey has put in place a number of 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.

All exchanges require a valid AuthorizationToken passed as a header named "Authorization". The AuthorizationToken can be retrieved via the login call and is valid for 24h. Exchanges can respond with both JSON & XML responses (based on the "Accept" header).

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

Sample use cases

The fitness scenario

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

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

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

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

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

The parking app scenario

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

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

The (off-line) webshop scenario

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

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

Authentication

Login

When using the API the login call will provide you with an AuthorizationToken, which is to be send upon every subsequent call (via the authorization header) in order to use the api. If the creditor opted for enhanced security, the private key allows the generation of a Time-based One-time password. See Appendix C of the Creditor API documentation for a more detailed explanation or sample code on how to calculate this OTP (samples in various languages are available).

Requires an API Token which can be found in the Twikey Creditor Dashboard

curl -X POST https://api.twikey.com/creditor /
-d apiToken=**API Token**
$host = "https://api.twikey.com";
$apitoken = "**API_TOKEN**";

$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_TOKEN**",
    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_TOKEN**";
    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_TOKEN**";

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

This AuthorizationToken acts as a session token and has a validity of 24h.

HTTP Request

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

Query Parameters

Name Description Required Type
apiToken API Token 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.

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 succesfully

Mandate

Invite a customer

Necessary to start with an eMandate. The end-result is a signed or protected shortlink that will allow the end-customer to sign a mandate. 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 Create contracts

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

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=Derbystraat 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=Derbystraat%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": "Derbystraat 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", "Derbystraat 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=Derbystraat%2043" +
            "&zip=9051" + 
            "&city=Sint%20Denijs%20Westrem" +
            "&country=BE"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

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

Query Parameters

Name Description Required Type
ct Contract template to use Yes integer
l Language (en/fr/nl/de/pt/es/it) No string
iban No string
bic No string
mandateNumber Mandate Identification number (if not generated) No string
email Yes string
lastname No string
firstname No string
mobile mobile number required for sms (International format +32499123445) 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
companyName the company name (if debtor is company) No string
vatno the enterprise number (if debtor is company) No string
form the legal form of the company (if debtor is company) No string
contractNumber the contract number which can override the one defined in the template. No string
campaign Campaign to include this url in No string
prefix Optional prefix to use in the url (default companyname) No string
check If an existing mandate exists, don't prepare a new (based on email + template(=ct)) No boolean

HTTP Response

Code Description
200 If the check option is provided and an existing mandate is available it will be returned. Otherwise an url and key will be returned.

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 :

curl -X POST https://api.twikey.com/creditor/mandate/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=Derbystraat%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=Derbystraat%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": "Derbystraat 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","Derbystraat%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=Derbystraat%2043" +
            "&city=Gent" +
            "&zip=9051" +
            "&country=BE" +
            , ParameterType.RequestBody);
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

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

Query Parameters

Name Description Required Type
signDate Date of signature (xsd:dateTime), sms uses date of reply No string
method Method to sign (sms or digisign) No string
place Place of signature No string
key If a contract was already prepared, its key can be provided instead of the other mandate related info. In case this parameter is not provided the other info is required. No string
ct Contract template to use No number
iban Yes string
bic Yes string
mandateNumber Mandate Identification number (if not generated) No string
email No string
lastname No string
firstname No string
mobile mobile number required for sms (International format +32499123445) No string
address Address (street + number) No string
city No string
zip No string
country ISO format (2 letters) No string
companyName the company name (if debtor is company) No string
vatno the enterprise number (if debtor is company) No string
form the legal form of the company (if debtor is company) No string
contractNumber the contract number which can override the one defined in the template. No string

HTTP Response

Code Description
200 The request has succeeded

Update 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:

If your system is out of sync or the full mandate database needs to be refreshed an optional "X-RESET" header can be passed. The format can be a timestamp like "2015-08-20T13:02:03Z" or a specific MandateNumber. After that you will receive (all) mandate updates since that time again. In order too avoid polling, a hook can be setup to notify the client when new information is available. This hook can be configured in the settings > erp section.

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("x-reset", "2017-08-29T00:00:00.000Z")
          .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("x-reset", "2017-08-29T00:00:00.000Z");
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}
{
    "GrpHdr": {
        "CreDtTm": "2015-08-20T13:02:03Z"
    },
    "Messages": [
        {
            "EvtTime": "2015-06-23T11:31:51Z",
            "Mndt": {
                "Cdtr": {
                    "CtctDtls": {
                        "EmailAdr": "info@creditor.com"
                    },
                    "CtryOfRes": "BE",
                    "Id": "BE0533800797",
                    "Nm": "Twikey N.V.",
                    "PstlAdr": {
                        "AdrLine": "Veldstraat 11",
                        "Ctry": "BE",
                        "PstCd": "9000",
                        "TwnNm": "Gent"
                    }
                },
                "CdtrSchmeId": "BE54ZZZ0533800797",
                "Dbtr": {
                    "CtctDtls": {
                        "EmailAdr": "admin@debtorcpy.be"
                    },
                    "CtryOfRes": "BE",
                    "Id": "BE123456789",
                    "Nm": "debtorCompany Inc.",
                    "PstlAdr": {
                        "AdrLine": "Street 52",
                        "Ctry": "BE",
                        "PstCd": "1000",
                        "TwnNm": "Brussels"
                    }
                },
                "DbtrAcct": "BE493104522",
                "DbtrAgt": {
                    "FinInstnId": {
                        "BICFI": "BBRUBEBB",
                        "Nm": "ING BELGIUM NV/SA"
                    }
                },
                "LclInstrm": "CORE",
                "MaxAmt": "0",
                "MndtId": "1600650622",
                "Ocrncs": {
                    "Drtn": {
                        "FrDt": "2015-06-13"
                    },
                    "Frqcy": "ADHO",
                    "SeqTp": "RCUR"
                },
                "RfrdDoc": "1000",
                "SplmtryData": [
                    {
                        "Key": "SignerPlace#0",
                        "Value": "Brussels"
                    },
                    {
                        "Key": "SignerDate#0",
                        "Value": "2015-06-22T21:00:00Z"
                    }
                ]
            }
        }
    ]
}

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

Response

Code Description
200 The request has succeeded

Import existing mandates

Import existing mandates (or updates)

curl -X POST https://api.twikey.com/creditor/mandate \
  -H 'authorization: **authorization**' \
  -d @import.json
$host = "https://api.twikey.com";
$authorisation = null; //collected through login

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

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "$host/creditor/mandate");
curl_setOpt($ch, CURLOPT_HTTPHEADER, array(
    "authorization: $authorization",
    "Content-Type: application/json',
    "Content-Length: ' . strlen($post))
);
curl_setOpt($ch, CURLOPT_POST, true);
curl_setOpt($ch, CURLOPT_POSTFIELDS, $post);

$server_output = curl_exec ($ch);
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',
        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);
    });
};


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 importMandates(){
        String json;
         try{
            FileReader fr = new FileReader("/path/to/import.json"); 
            BufferedReader br = new BufferedReader(fr); 
            String s; 
            while((s = br.readLine()) != null) { 
                json+=s;
            } 
            fr.close(); 

            OkHttpClient client = new OkHttpClient();
            RequestBody body = RequestBody.create(mediaType, "import.json");
            Request request = new Request.Builder()
              .url(host + "/creditor/mandate")
              .post(json)
              .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 json = file.ReadAllText("\path\to\import.json");

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

HTTP Request

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

Query Parameters

Name Description Required Type
Mandates All mandate updates like in fetch (json) Yes

HTTP Response

Code Description
204 Batch import of mandates was fully done or not at all

Cancel existing 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("x-reset", "2017-08-29T00:00:00.000Z");
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

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

Query Parameters

Name Description Required Type
mndtId Mandate Reference Yes string
rsn Reason of cancellation Yes string

HTTP Response

Code Description
200 The request has succeeded
400 No contract was selected or invalid mndtId supplied
403 Contract had wrong status (eg. already cancelled) or not authorised
404 No contract was selected or mandate not found
405 Please provide reason

Detail of an existing mandate

Retrieve details of a specific 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
mndtId Mandate Reference Yes string
force Also include non-signed states No boolean

Response

Code Description
200 Details of the mandate (see /creditor/mandate)

Update an existing mandate

Sometimes sending in the complete mandate is overkill and sending just the updated information is a lot easier by just passing the updated information. This endpoint allows to update account, address, email and phone information.

curl -X POST https://api.twikey.com/creditor/mandate/update \
  -H 'authorization: **authorization**' \
  -d 'mndtId=mndtId123' \
  -d 'mobile=+32479123123'
$host = "https://api.twikey.com";

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/mandate/update");
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");
curl_setOpt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setOpt($ch, CURLOPT_POSTFIELDS, array(
    "mndtId" =>  "mdntId123",
    "mobile" => "+32479123123")
);
$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/update',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body:{
            'mndtId': 'mndtId123',
            'mobile':'+32479123123'
        }
    };

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("mobile", "+32479123123")
                        .build();
        Request request = new Request.Builder()
          .post(body)
          .url(host + "/creditor/mandate/detail")
          .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" +
            "&mobile=+32479123123", 
            ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

HTTP Request

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

Query Parameters

Name Description Required Type
mndtId Mandate Reference Yes string
iban No string
bic No string
address Street (street + number) No string
zip No string
city No string
country Country (ISO 2 letters) No string
mobile International format +32499123445 No string
email 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 No contract was selected or invalid mndtId supplied
403 Mandates are editable only when in Prepared/Print state or CORE or not authorised
404 No contract was selected or mandate not found

Retrieve pdf

Retrieve pdf of a mandate

curl https://api.twikey.com/creditor/mandate/pdf?mndtId123 \
  -H 'authorization: **authorization**'
$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

Upload pdf

Import existing mandate pdf (eg. scan of a printed document)

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

Parameters

Name Description Required Type
mndtId Mandate Reference Yes string

Responses

Code Description
200 Import of the pdf was done

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
mndtId Mandate Reference Yes string
date Date of the billable event or now when empty No string
reqcolldt Requested date of the billable event No string
message Message to the customer (if only 1 entry) Yes string
ref Your reference No string
amount Amount to be billed Yes string
place Optional place No string

HTTP Response

Code Description
200 The request has succeeded

Get transaction feed

Retrieve list of transactions that had changes since the last call.

curl https://api.twikey.com/creditor/transaction \
  -H 'authorization: **authorization**' \
  -H 'x-reset: 2017-08-29T00:00:00.000Z'
$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);
    }
}

HTTP Request

GET /creditor/transaction

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

HTTP Response

Code Description
200 The request has succeeded

Get transaction status

Retrieve status of transactions (Note that this is a snapshot and is not final)

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": [
        {
            "amount": 10.0,
            "contract": "Algemene voorwaarden",
            "contractId": 325638,
            "date": "2017-09-16T14:32:05Z",
            "id": 381563,
            "mndtId": "MNDT123",
            "msg": "Monthly payment",
            "place": null,
            "ref": null,
            "state": "OPEN"
        }
    ]
}

HTTP Request

GET /creditor/transaction/detail

Request Parameters

Name Description Required Type
id 1 or more ids of a transaction (empty means all open) No string
ref 1 or more refs of a transaction No string

HTTP Response

Code Description
200 The request has succeeded

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
mndtId all open transactions linked to the mandateReference No string
ref transactionReference as provided in the post to be removed No string

HTTP Response

Code Description
204 The request has succeeded

Collections

Prenotify a customer

Send a prenotification notice to the customer

HTTP Request

POST /creditor/prenotification

curl -X POST https://api.twikey.com/creditor/prenotification \
  -d mndtId=MNDT123 \
  -d message="Monthly payment" \
  -d collectionDate=2017-09-15 \
  -d amount="10" \
  -H 'authorization: **authorization**'
$host = "https://api.twikey.com";
$authorisation = null; //collected through login

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/prenotification");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "mndtId=MNDT123" 
    ."message=Monthly payment"
    ."collectionDate="2017-09-15"
    ."amount=10"
);
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/prenotification',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        data: {
            "message":"Monthly payment",
            "collectionDate":"2017-09-15",
            'amount': 10
        }
    };

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

        MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
        RequestBody formBody = new FormBody.Builder()
                .add("message","Monthly payment")
                .add("collectionDate","2017-09-15")
                .add("amount","10")
                .build();

        Request request = new Request.Builder()
          .url(host + "/creditor/prenotify")
          .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",
        authorisation = null; // collected through logIn

    public void prenotify(){    
        RestClient client = new RestClient(host + "/creditor/prenotify");
        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", 
            "message=Monthly payment" +
            "collectionDate="2017-09-15" +
            "amount=10"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

Query parameters

Name Description Required Type
mndtId Mandate Reference Yes string
message Message to debtor Yes string
collectionDate Date of collection Yes string
amount Amount (Format 12.33) Yes double
invoiceUrl Url to the actual invoice No string

HTTP Response

Code Description
200 success
404 No contract was found for the mndtId supplied
405 Invalid amount was given
406 Invalid date was given

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

Download collection file(s)

Prepare the collection file(s) and download the zipped sdd file(s)

HTTP Request

POST /creditor/collect/sdd

curl -X POST https://api.twikey.com/creditor/collect/sdd \
  -d 'ct=**ct_id**' \
  -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/sdd");
curl_setOpt($ch, CURLOPT_HTTPHEADER, "authorization: $authorization");
curl_setOpt($ch, CURLOPT_POST, true);
curl_setOpt($ch, CURLOPT_POSTFIELDS, "ct=**ct_id**");
$server_output = curl_exec ($ch);
$result = json_decode($server_output);
curl_close ($ch);
var https = require('https'),
    querystring = require('querystring'),
    ct = "**ct_id**",
    host = "api.twikey.com",
    authorization = null, //collected through login
    options = {
        host: host,
        port: '443',
        path: '/creditor/collect/sdd',
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Authorization': authorization
        },
        body :{
            'ct': ct
        }
    };

var req = https.request(options, function (res) {
    console.log(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 downloadCollection(){
        OkHttpClient client = new OkHttpClient();
        Requestbody body = Formbody.Builder()
            .add("ct", ct)
            .build();
        Request request = new Request.Builder()
          .url(host + "/creditor/collect/sdd")
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .post(body)
          .addHeader("x-reset", "2017-08-29T00:00:00.000Z")
          .addHeader("authorization", authorisation)
          .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 downloadCollection(){    
        RestClient client = new RestClient(host + "/creditor/collect/sdd");
        RestRequest request = new RestRequest(Method.POST);
        request.AddHeader("x-reset", "2017-08-29T00:00:00.000Z");
        request.AddHeader("authorization", authorisation);
         request.AddParameter("application/x-www-form-urlencoded", 
            "ct=" + ct 
            , 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 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 zip containing all files to be uploaded to the bank

Status collection

Retrieve all payments obtained so far from collecting agent per collection batch

HTTP Request

GET /creditor/payment

curl https://api.twikey.com/creditor/payment \
  -H 'authorization: **authorization**'
$host = "https://api.twikey.com";
$authorisation = null; //collected through login

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "$host/creditor/payment");
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/payment',
        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 statusCollection(){
        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder()
          .url(host + "/creditor/collect/sdd")
          .addHeader("content-type", "application/x-www-form-urlencoded")
          .addHeader("x-reset", "2017-08-29T00:00:00.000Z")
          .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 statusCollection(){    
        RestClient client = new RestClient(host + "/creditor/payment");
        RestRequest request = new RestRequest(Method.GET);
        request.AddHeader("x-reset", "2017-08-29T00:00:00.000Z");
        request.AddHeader("authorization", authorisation);
        IRestResponse response = client.Execute(request);
    }
}

Query parameters

Name Description Required Type
id Specific SDD reference No number
detail Include details (true = default/false) No boolean

HTTP Response

Code Description
200 The request has succeeded

Payments

The payment information can be retrieved in 2 ways. This can either be done by polling the transaction feed or by the status of the collection. Both can be polled periodically or triggered by a callback.

Per transaction

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

This endpoint allows to retrieve a list of all the transactions for which new payment information has been received since the last call. This endpoint doesn't require any parameters. If we receive an error from the bank, we mark the transaction with status "error" or "paid". We also add a final flag which can either be true or false. 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 like debtor deceased. An action will be required on your part. False means that we still have actions pending to debit the debtor's account.

Per Collection

{
    "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 re-offer)
                    "state": "error", // Transaction was paid
                    "bkamount": 30.0,
                    "bkdate": "2015-07-27",
                    "bkerror": "MSO3"  // Actual error code
                },
                {
                    "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"
                }
            ]
        }
    ]
}

This endpoint allows to retrieve a list of SDD's for which new payment information is given. If the parameter 'id' is passed, it will also return the details of the mandates contained in the referenced SDD. If the 'detail' parameter is passed (regardless of its value) then the call with the 'id' parameter is obsolete as the details are included in the general call. 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. 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 like debtor deceased. An action would be required from your part. False means that we still have actions pending to debit the debtor's account.

Credit Transfer

New Credit Transfer

Add Credit Transfer to batch

HTTP Request

POST /creditor/transfer

curl https://api..twikey.com/creditor/transfer \
  -H 'authorization: authorization' \
  -d 'iban=BE68068897250734' \
  -d 'message=test%20credit%20transfer' \
  -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" 
    ."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'),
    querystring = require('querystring'),
    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":"BE68068897250734", 
            "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", "BE68068897250734")
            .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" +
            "message=test credit transfer" +
            "amount=50.00"
            , ParameterType.RequestBody
        );
        IRestResponse response = client.Execute(request);
    }
}

Query parameters

Name Description Required Type
iban Iban of the beneficiary (requires the registration in settings > credit transfer) Yes string
message Message to the creditor Yes 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

Submit Credit Transfer

Create Credit Transfer (and optionally send)

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

Callbacks

In order to reduce the number of polling requests, one can opt to implement a callback endpoint and use this as a way to trigger polling requests. The endpoint is set in the ERP 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...

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

Update types

contract

Extra parameters:

transaction

Extra parameters:

plan

Extra parameters:

payment

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

dunning

Extra parameters:

Security

In order to be sure that the callback is coming from us we add 2 headers:

API key : Your api token as defined in the API section otp : The otp calculated (provided the enhanced security was enabled) The calculation is done the same way as the login.