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

Payments

Tikkie

Get paid faster by creating easy payment requests. Share them via any channel you want.

Technical Details

Open API Specification

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

Access token parameters

Tikkie API uses client assertion based OAuth as described here for authentication. To use the Tikkie API, you need to obtain an access token from OAuth API with the following scope:

Key Value
scope tikkie

POST Platform

POST /v1/tikkie/platforms

This operation will enroll a new platform. The details of the platform are specified in the payload.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
name String Body true Name of the new platform. Length: 2-100 characters
phoneNumber String Body true The phone number of a contact person of the platform. Length: 5-100 characters. Example: 0601234567. Currently only Dutch mobile numbers are supported
email String Body false The email address of a contact person of the platform. Length: 5-100 characters
notificationUrl String Body false Optional url on which to receive notifications. Length: up to 200 characters
platformUsage String Body true The type of usage for this platform. Possible values are PAYMENT_REQUEST_FOR_MYSELF and PAYMENT_REQUEST_FOR_OTHERS (see Functional details)
Sample Request
curl -X POST \
https://api-sandbox.abnamro.com/v1/tikkie/platforms \
-H 'Authorization: Bearer {your_access_token}' \
-H "Content-Type: application/json" \
-H "API-Key: {your_api_key}"-d '{"name": "NewPlatform", "phoneNumber": "0601234567", "email": "x@yz.com", "platformUsage":"PAYMENT_REQUEST_FOR_MYSELF"}'
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
name String Body true The name of the new platform
platformToken String Body true The token that identifies the new platform
phoneNumber String Body true The phone number of a contact person of the platform
email String Body false The email address of a contact person of the platform
notificationUrl String Body false Optional url on which to receive notifications
status String Body true The current status of the new platform, one of [ACTIVE, INACTIVE]
platformUsage String Body true The type of usage for this platform. Possible values are PAYMENT_REQUEST_FOR_MYSELF and PAYMENT_REQUEST_FOR_OTHERS
Sample Response
{
  "name" : "NewPlatform",
  "platformToken" : "platformtoken1",
  "phoneNumber" : "0601234567",
  "email" : "x@yz.com",
  "notificationUrl" : null,
  "status" : "ACTIVE",
  "platformUsage":"PAYMENT_REQUEST_FOR_MYSELF"
}

GET Platform

GET /v1/tikkie/platforms

This operation will fetch all platforms created for a certain API consumer.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
Sample Request
curl https://api-sandbox.abnamro.com/v1/tikkie/platforms \
-H "Authorization: Bearer {your_access_token}" \
-H "API-Key: {your_api_key}"
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
name String Body true The name of the new platform
platformToken String Body true The token that identifies the new platform
phoneNumber String Body true The phone number of a contact person of the platform
email String Body false The email address of a contact person of the platform
notificationUrl String Body false Optional url on which to receive notifications
status String Body true The current status of the new platform, one of [ACTIVE, INACTIVE]
platformUsage String Body true The type of usage for this platform. Possible values are PAYMENT_REQUEST_FOR_MYSELF and PAYMENT_REQUEST_FOR_OTHERS
Sample Response
[
  {
    "name" : "NewPlatform",
    "platformToken" : "platformtoken1",
    "phoneNumber" : "0601234567",
    "email" : "x@yz.com",
    "notificationUrl" : null,
    "status" : "ACTIVE",
    "platformUsage":"PAYMENT_REQUEST_FOR_MYSELF"
  }
]

POST User

POST /v1/tikkie/platforms/{platformToken}/users

This operation will enroll a new user into an existing platform payment. The details of the user are specified in the payload, the platform is identified by the platformToken submitted as a path parameter.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
platformToken String Path true Identifies to which platform the new user is enrolled
name String Body true Name of the new user. Length: 2-70 characters
phoneNumber String Body true The phone number of the new user. Length: 10 characters. Example: 0601234567. Currently only Dutch phone numbers are supported
iban String Body true The IBAN number of the bank account of the new user. Only Dutch IBANs are supported. The Tikkie API limits the number of users with the same IBAN account number, so if you use an IBAN that has been used too often, the user creation will fail
bankAccountLabel String Body true A label to describe the bank account of the new user, e.g. personal account. Length: 2-70 characters
Sample Request
curl -X POST \
https://api-sandbox.abnamro.com/v1/tikkie/platforms/{your_platform_token}/users \
-H "authorization: Bearer {your_access_token}" \
-H "API-Key: {your_api_key}" \
-H "Content-Type: application/json" -d '{"name": "NewUser", "phoneNumber": "0601234567", "iban": "NL02ABNA0123456789", "bankAccountLabel": "Personal account"}'
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
userToken String Body true The token that identifies the new user
name String Body true The name of the new user
status String Body true The current status of the new user, one of [ACTIVE, INACTIVE]
bankAccounts Array Body true An array holding bank account objects, that represent the bank accounts of the user. The fields below are properties of the bank account objects, not of the bankAccounts array itself
bankAccounts.
bankAccountToken
String Body true The bank account token for this bank account
bankAccounts.
iban
String Body true The IBAN account number of this bank account
bankAccounts.
bankAccountLabel
String Body true The label of this bank account
Sample Response
{
  "userToken" : "usertoken1",
  "name" : "NewUser",
  "status" : "ACTIVE",
  "bankAccounts": [
    "bankAccountToken": "bankaccounttoken1",
    "iban": "NL02ABNA0123456789",
    "bankAccountLabel": "Personal account"
  ]
}

GET User

GET /v1/tikkie/platforms/{platformToken}/users

This operation will fetch all users for an existing platform of a certain API consumer.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
platformToken String Path true Identifies to which platform the new user is enrolled
Sample Request
curl https://api-sandbox.abnamro.com/v1/tikkie/platforms/{your_platform_token}/users \
-H 'Authorization: Bearer {your_access_token}'
-H 'API-Key: {your_api_key}'
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
userToken String Body true The token that identifies the new user
name String Body true The name of the new user
status String Body true The current status of the new user, one of [ACTIVE, INACTIVE]
bankAccounts Array Body true An array holding bank account objects, that represent the bank accounts of the user. The fields below are properties of the bank account objects, not of the bankAccounts array itself
bankAccounts.
bankAccountToken
String Body true The bank account token for this bank account
bankAccounts.
iban
String Body true The IBAN account number of this bank account
bankAccounts.
bankAccountLabel
String Body true The label of this bank account
Sample Response
[
  {
    "userToken" : "usertoken1",
    "name" : "NewUser",
    "status" : "ACTIVE",
    "bankAccounts": [
      "bankAccountToken": "bankaccounttoken1",
      "iban": "NL02ABNA0123456789",
      "bankAccountLabel": "Personal account"
    ]
  }
]

POST Payment request

POST /v1/tikkie/platforms/{platformToken}/users/{userToken}/bankaccounts/{bankAccountToken}/paymentrequests

This operation will create a new payment request for an existing user. The details of the request are specified in the payload, the user is identified by the userToken and bankAccountToken submitted as a path parameters.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
platformToken String Path true Identifies to which platform the user is enrolled
userToken String Path true Identifies to which user the request is made
bankAccountToken String Path true Identifies to which account of the user the request is made
amountInCents String Body false The amount to be payed, in cents. When left empty, the payment request will automatically becomes a payment request with open amount, where the payer can decide on the amount when paying. Length: 1-6 characters
currency String Body true The currency in which the amount has to be payed. Length: 3 characters
description String Body true Description of the (reason for) the request. Length: 1-35 characters
externalId String Body true* An external identifier for this payment request, e.g. an invoice number. Mandatory when platformUsage is set to PAYMENT_REQUEST_FOR_MYSELF. Length: 1-35 characters
Sample Request
curl -X POST \
https://api-sandbox.abnamro.com/v1/tikkie/platforms/{your_platform_token}/users/{your_user_token}/bankaccounts/{your_account_token}/paymentrequests \
-H 'authorization: Bearer {your_access_token}' \
-H 'API-Key: {your_api_key}' \
-H "Content-Type: application/json" -d '{"amountInCents": "123", "currency": "EUR", "description": "Last night's dinner", "externalId": "Invoice: 4567"}'
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
paymentRequestUrl String Body true The URL that directs the counter party to a payment page
paymentRequestToken String Body true The token that identifies the payment request, for future access
externalId String Body false An external identifier for this payment request, if provided
Sample Response
{
  "paymentRequestURL" : "https://pay.here.com/123",
  "paymentRequestToken" : "paymentrequesttoken1",
  "externalId": "Invoice: 4567"
}

GET User payment requests

GET /v1/tikkie/platforms/{platformToken}/users/{userToken}/paymentrequests

The Tikkie Payment request API can be used to access all the payment requests for an existing user.
The user is identified by its userToken. The results are paginated and the desired offset and limit must be specified as query parameters. Filtering is possible based on the date. When the platform has been created with the platformUsage field set to PAYMENT_REQUEST_FOR_OTHERS then the payments will be empty.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
platformToken String Path true Identifies to which platform the user is enrolled
userToken String Path true Identifies from which user the payment requests are accessed
offset Number Query true Pagination: zero based index of the records range to return
limit Number Query true Pagination: the number of records to return
fromDate String Query false Filtering: only include payment requests created after this date/time (in ISO-8601 format). Example: 2017-05-31T23:59:59Z
toDate String Query false Filtering: only include payment requests created before this date/time (in ISO-8601 format). Example: 2017-05-31T23:59:59Z
Sample Request
curl -X GET \
https://api-sandbox.abnamro.com/v1/tikkie/platforms/{your_platform_token}/users/{your_user_token}/paymentrequests?offset=0&limit=20&fromDate=2017-05-31T23:59:59Z \
-H 'authorization: Bearer {your_access_token}' \
-H 'API-Key: {your_api_key}' \
-H "Content-Type: application/json"
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
paymentRequests Array Body true Array containing all the payment requests in the requested range
paymentRequests.
paymentRequestToken
String Body true The token that identifies the payment request
paymentRequests.
amountInCents
String Body true The requested amount, in cents
paymentRequests.
currency
String Body true The currency of the requested amount
paymentRequests.
description
String Body true Description of the (reason for) the request
paymentRequests.
created
String Body true The date and time on which this payment request was created (in ISO-8601 format)
paymentRequests.
expired
String Body true The date and time on which this payment request was expired (in ISO-8601 format)
paymentRequests.
status
String Body true The current status of the payment request, one of [ OPEN, CLOSED, EXPIRED, MAX_YIELD_REACHED, MAX_SUCCESSFUL_PAYMENTS_REACHED ]
paymentRequests.
bankAccountYieldedTooFast
Boolean Body true If true, the bank account linked to this payment request is temporarily blocked due to exceeding the configured maximum yield per day
paymentRequests.
externalId
String Body true An external identifier for this payment request, if provided
paymentRequests.
payments
Array Body true List of all the payments that have been done to fulfill this request
paymentRequests.payments
paymentToken
String Body false The token for this payment
paymentRequests.payments
counterPartyName
String Body false The name of the counter party (the person paying this payment)
paymentRequests.payments
amountInCents
String Body false The amount that was paid in cents
paymentRequests.payments
amountCurrency
String Body false The currency of the amount that was paid
paymentRequests.payments
description
String Body false Description for this payment
paymentRequests.payments
created
String Body false The date and time on which this payment was created (in ISO-8601 format)
paymentRequests.payments
onlinePaymentStatus
String Body true The online payment state of this payment. This indicates if the counter party paid or not. One of [ NEW, PENDING, PAID, NOT_PAID ]
totalElements Integer Body true Total number of payment requests
Sample Response
{
  "paymentRequests": [
    {
      "paymentRequestToken": "paymentrequesttoken1",
      "amountInCents": "123",
      "currency": "EUR",
      "description": "Last night's dinner",
      "created": "2016-06-09T18:00:00.000Z",
      "expired": null,
      "status": "OPEN",
      "bankAccountYieldedTooFast": false,
      "externalId": "Invoice: 4567",
      "payments": [
        {
          "paymentToken": "paymenttoken1",
          "counterPartyName": "E. Xample",
          "amountInCents": "123",
          "amountCurrency": "EUR",
          "description": "Payment for tikkie",
          "created": "2016-06-09T18:00:00.000Z",
          "onlinePaymentStatus": "NEW"
        }
      ],
    }
  ],
  "totalElements": 1
}

GET Payment request

GET /v1/tikkie/platforms/{platformToken}/users/{userToken}/paymentrequests/{paymentRequestToken}

The Tikkie Payment request API can also be used to access a single payment request. The payment request is identified by its paymentRequestToken and the userToken of the corresponding user. When the platform has been created with the platformUsage field set to PAYMENT_REQUEST_FOR_OTHERS then the payments will be empty.

Request Attributes
Name Type In Required Description
Authorization String Header true Access token to be passed as a Bearer token
API-Key String Header true Consumer key obtained after app registration on developer portal
platformToken String Path true Identifies to which platform the user is enrolled
userToken String Path true Identifies from which user this payment request is accessed
paymentRequestToken String Path true Identifies the accessed payment request
Sample Request
curl -X GET \
https://api-sandbox.abnamro.com/v1/tikkie/platforms/{your_platform_token}/users/{your_user_token}/paymentrequests/{your_payment_request_token} \
-H 'authorization: Bearer {your_access_token}' \
-H 'API-Key: {your_api_key}' \
-H "Content-Type: application/json"
Response Attributes
Name Type In Required Description
Trace-Id String Header true Unique id generated for every request
paymentRequestToken String Body true The token that identifies the payment request
amountInCents String Body true The requested amount, in cents
currency String Body true The currency of the requested amount
description String Body true Description of the (reason for) the request
created String Body true The date and time on which this payment request was created (in ISO-8601 format)
expired String Body true The date and time on which this payment request was expired (in ISO-8601 format)
status String Body true The current status of the payment request, one of [ OPEN, CLOSED, EXPIRED, MAX_YIELD_REACHED, MAX_SUCCESSFUL_PAYMENTS_REACHED ]
bankAccountYieldedTooFast Boolean Body true If true, the bank account linked to this payment request is temporarily blocked due to exceeding the configured maximum yield per day
externalId String Body true An external identifier for this payment request, if provided
payments Array Body true List of all the payments that have been done to fulfill this request
payments
paymentToken
String Body false The token for this payment
payments
counterPartyName
String Body false The name of the counter party (the person paying this payment)
payments
amountInCents
String Body false The amount that was paid in cents
payments
amountCurrency
String Body false The currency of the amount that was paid
payments
description
String Body false Description for this payment
payments
created
String Body false The date and time on which this payment was created (in ISO-8601 format)
payments
onlinePaymentStatus
String Body true The online payment state of this payment. This indicates if the counter party paid or not. One of [ NEW, PENDING, PAID, NOT_PAID ]
Sample Response
{
  "paymentRequestToken": "paymentrequesttoken1",
  "amountInCents": "123",
  "currency": "EUR",
  "description": "Last night's dinner",
  "created": "2016-06-09T18:00:00.000Z",
  "expired": null,
  "status": "OPEN",
  "bankAccountYieldedTooFast": false,
  "externalId": "Invoice: 4567",
  "payments": [
    {
      "paymentToken": "paymenttoken1",
      "counterPartyName": "E. Xample",
      "amountInCents": "123",
      "amountCurrency": "EUR",
      "description": "Payment for tikkie",
      "created": "2016-06-09T18:00:00.000Z",
      "onlinePaymentStatus": "NEW"
    }
  ]
}

Error Response & Codes

This section describes the error response & the codes being sent by Tikkie API.

Sample Error Response
{
    "errors": [{
        "code": "ERR_4100_002",
        "category": "NOT_FOUND",
        "message": "Platform not found",
        "reference": "https://developer.abnamro.com/api/tikkie/technical-details",
        "traceId": "6fda2ce8-225d-4ca2-920a-b687c7aeb2f3",
        "status": 404
    }]
}
Error Attributes

This section lists the errors that are particular for this API. If your error is not listed here, or you want to know which general errors can occur, please check the general error section.

Code Status Category Description
ERR_1100_001 400 BAD_REQUEST The user could not be created
ERR_1100_002 400 BAD_REQUEST The payment request could not be found/does not exist
ERR_1100_003 400 BAD_REQUEST Could not search for payment requests
ERR_1100_004 400 BAD_REQUEST One of the input paramater is invalid
ERR_1100_005 400 BAD_REQUEST A parameter is missing, see the message field of the response to find out which one
ERR_1100_006 400 BAD_REQUEST See the message field of the response for more information
ERR_1100_007 400 BAD_REQUEST This operation was not found
ERR_3100_001 403 FORBIDDEN Maximum number of platforms per client reached
ERR_3100_002 403 FORBIDDEN Maximum number of users has been reached for this platform
ERR_4100_001 404 NOT_FOUND The client could not be found/does not exist
ERR_4100_002 404 NOT_FOUND The platform could not be found/does not exist
ERR_4100_003 404 NOT_FOUND The user could not be found/does not exist
ERR_8100_001 500 INTERNAL_SERVER_ERROR An unknown error occurred in the backend. Please contact us if this problem persists
ERR_9100_011 503 SERVICE_UNAVAILABLE Tikkie service unavailable