Svg Vector Icons : http://www.onlinewebfonts.com/icon

Payments

Tikkie

Create payment requests that you can share via SMS, Whatsapp, Facebook Messenger or any other channel you want.

Overview

Introduction

The Tikkie API can be used to create payment requests on behalf of users. The users of Tikkie are organized into platforms. The possibilities of the API include adding new platforms and users, creating payment requests, or retrieving information about existing payment requests. More information about the Tikkie service can be found here.

Gaining Access

To gain access to the Tikkie API, you have to:

  • Register and create an account
  • Login
  • Create an app, subscribe to the Tikkie API Product and get API credentials
  • Authenicate yourself by following the instruction below

Authentication

The authentication for this API is done on the basis of access tokens. To obtain an access token, you need to call our OAuth API. The authentication mechanism can vary per API depending on the required level of authentication. Currently we support only client assertion based OAuth which is described below.

OAuth API (Client assertion based)

The OAuth API has one endpoint. By making a post request to this endpoint, you can obtain an access token for the other APIs.

To make the request to this endpoint, you need the following settings:

Request attributes Value
Method POST
Path https://api-sandbox.abnamro.com/v1/oauth/token
Headers Content-Type: application/x-www-form-urlencoded
API-Key: (your API key)
Form-data client_assertion: (JSON Web token required to authenticate client)
client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
grant_type: client_credentials
scope: (the desired scope)(Optional)

Client Assertion (JSON Web Token)

The request body will contain a json payload with an attribute named "client_assertion". This attribute will contain the JSON Web token. The token will be used to authenticate the consumer and send back an access token in response.

A JSON web token is a string which consists of three parts where is part is separated by a dot: header.payload.signature. The API consumer needs to generate the JSON web token. Please refer the following steps to create the JSON web token.

1. Create public/private key pair

The above OAuth API to be used for authentication requires a JSON web token, which requires signing by a private key from at least a 2048 bit size public/private key pair. The public key of the key pair needs to be shared with ABN AMRO. Following are sample commands to generate a 2048 bit size key pair:

#generates RSA private key of 2048 bit size
openssl genrsa -out private_rsa.pem 2048

#generates public key from the private key
openssl rsa -in private_rsa.pem -outform PEM -pubout -out public_rsa.pem

The keys need to be in PEM format.

Note: Please share your public key along with your app name and developer email id at api.support@nl.abnamro.com. Token generation will not work unless public key is associated with your app.

2. Create the header

The header describes how the signature should be generated. It is a JSON object of the following format:

{
  "typ": "JWT",
  "alg": "RS256"
}

In the above json the value of "typ" specifies that this is a JSON web token (JWT), and the value of "alg" specifies the hashing algorithm used to generate the signature component of the JSON web token. Following is the list of alogrithms supported by our OAuth API.

  • RS256
  • RS384
  • RS512
3. Create the payload

The payload component of the JSON web token stores the data to be passed in the web token. This data is referred to as "claims" of the JSON web token. The required claims are "exp", "nbf", "sub", "iss" and "aud". It can have an optional claim as "nbf". Following are the definitions of each claim:

Claim Description Mandatory
exp This claim will contain the expiry time in seconds since 1st January, 1970. It cannot be before the current time. This is an integer value, don't put quotes around the value. Yes
nbf This claim will contain the time in seconds since 1st January, 1970 before which the JSON web token cannot be processed. Current date date/time must be equal to or after this value. This is an integer value, don't put quotes around the value. Yes
iss This claim contains the name of the issuer Yes
sub This claim will contain the api key of the consumer. Refer this link Yes
aud This claim will contain the token URL which are fixed strings.
For sandbox: https://auth-sandbox.abnamro.com/oauth/token
For production: https://auth.abnamro.com/oauth/token
Yes

Note: The difference between "exp" and "nbf" cannot be greater than 20 minutes. A sample payload is as following:

{
  "nbf": 1499947668,
  "exp": 1499948668,
  "iss": "me",
  "sub": "anApiKey",
  "aud": "https://auth-sandbox.abnamro.com/oauth/token"
}
4. Create the signature

The signature is created using the following pseudocode.

data = base64urlEncode( header ) + “.” + base64urlEncode( payload )
signature = Hash( data, secret );

What this pseudocode does is base64url encodes the header and the payload created in steps 1 and 2. The algorithm then joins the resulting encoded strings together with a period (.) in between them. This joined string is assigned to data. To get the JSON web token signature, the data string is hashed with the private key(generated in first step) using the hashing algorithm specified in the JWT header. The Base64 url encoded values and the signature are as following:

header = eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
payload = eyJzdWIiOiJ4eHh4eHgiLCJleHAiOiIxNDk5OTQ3NjY4IiwiaXNzIjoibWUiLCJhdWQiOiJodHRwczovL2F1dGgtc2FuZGJveC5hYm5hbXJvLmNvbS9vYXV0aC90b2tlbiJ9
signature = jGwHKG_YjgKpR8NPpaLu6nJ97obeP2vcxg6fOWBKdJ0
The JSON web token will be like the following:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ4eHh4eHgiLCJleHAiOiIxNDk5OTQ3NjY4IiwiaXNzIjoibWUiLCJhdWQiOiJodHRwczovL2F1dGgtc2FuZGJveC5hYm5hbXJvLmNvbS9vYXV0aC90b2tlbiJ9.jGwHKG_YjgKpR8NPpaLu6nJ97obeP2vcxg6fOWBKdJ0

Sample JSON web tokens can be generated at jwt.io You can also use the following node.js code snippet to generate a JSON web token. The code snippet reads the private key from a file named "private_rsa.pem".

var jwt = require('jsonwebtoken');
var fs = require('fs');
var algo='RS256';
var payload={
    nbf:Math.floor(Date.now() / 1000),
        exp:Math.floor(Date.now() / 1000) + 300,
        sub:'DLjpQoVpzPshdnwIJEMXnTUhGzGrCG2m',
        iss:'me',
        aud:'https://auth-sandbox.abnamro.com/oauth/token'
};

// sign with RSA SHA256
var cert = fs.readFileSync('private_rsa.pem');  // get private key
jwt.sign(payload, cert, { algorithm: algo},function(error,token){
console.log(token);
});

A complete example call made with curl:

curl -X POST https://api-sandbox.abnamro.com/v1/oauth/token -H "Content-Type: application/x-www-form-urlencoded" -H "API-Key: xxxxxx" -d 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=client_credentials&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ4eHh4eHgiLCJleHAiOiIxNDk5OTQ3NjY4IiwiaXNzIjoibWUiLCJhdWQiOiJodHRwczovL2F1dGgtc2FuZGJveC5hYm5hbXJvLmNvbS9vYXV0aC90b2tlbiJ9.jGwHKG_YjgKpR8NPpaLu6nJ97obeP2vcxg6fOWBKdJ0&scope=tikkie'

If the request is successful, you can expect the following response:

{
"access_token": "{your access token}",
"expires_in": "{duration of validity in seconds}",
"scope": "{scope(s) for which the access token is valid}",
"token_type": "{it is always Bearer}"
}

You can now start using the APIs using your access token!

Click here to download the Open API Specification of OAuth API in yaml format.

Try it out!

After obtaining an access token using above process you can use it to test the Tikkie API operations on the Operations & Sandbox page.