Payments

Tikkie Payment Request

Get paid faster by creating and sharing payment requests.

Technical Details

Open API Specification

  • To download the OAS 3.0 Tikkie Payment Request API in, .YAML format, click here.

  • To view the reference content and understand the full semantics of this service, open the .YAML file in a tool such as Swagger Editor.

Access token parameters

The Tikkie Payment Request API uses client authentication and user-based consent OAuth as described here. To use the API, you must obtain an access token from the Authentication API with the following scope:

Key Value
scope tikkie

POST Platform

POST /v1/tikkie/platforms

This operation creates a new platform. A platform is a container of users that you can initiate payment requests from. Details of the new platform are provided in the payload. At a minimum, you must provide the name of the new platform and a contact phone number. An e-mail address and notification URL may also be provided.

Note: Platforms support Dutch phone numbers only.

When the enrollment of a new platform is successful, a platform token will be provided that can be used to access the platform in the future.

Request types

The following request type is currently available: - PAYMENT_REQUEST_FOR_MYSELF: request to pay for a purchase which is sent from a business to a client.

Example

A client books a hotel through a website. The hotel generates a payment request using a PAYMENT_REQUEST_FOR_MYSELF platform. The client pays the payment request.

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 that is obtained after application registration on developer portal.
name String Body true Name of the new platform. Length: 2-100 characters.
phoneNumber String Body true Phone number of a contact person for the platform. Length: 5-100 characters. Example: 0601234567.
Note: The platform supports Dutch phone numbers only.
email String Body false E-mail address of a contact person for 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 Type of usage for a platform. Possible value is: PAYMENT_REQUEST_FOR_MYSELF.
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 Name of the platform.
platformToken String Body true Token that identifies the platform.
phoneNumber String Body true Phone number of a contact person for the platform.
email String Body false E-mail address of a contact person for the platform.
notificationUrl String Body false Optional URL on which to receive notifications.
status String Body true Current status of the platform. Possible values are: 'ACTIVE' and 'INACTIVE'.
platformUsage String Body true Type of usage for a platform. Possible values is: PAYMENT_REQUEST_FOR_MYSELF
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 application registration on the 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 Name of the new platform.
platformToken String Body true Token that identifies the platform.
phoneNumber String Body true Phone number of a contact person for the platform.
email String Body false E-mail address of a contact person for the platform.
notificationUrl String Body false Optional URL on which to receive notifications.
status String Body true Current status of the platform. Possible values are: 'ACTIVE' and 'INACTIVE'.
platformUsage String Body true Type of usage for a platform. Possible value is: PAYMENT_REQUEST_FOR_MYSELF
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

In a platform, you can initiate payments from multiple users. This operation enrolls new users into an existing platform. The platform is identified by a platformToken which is submitted as a path parameter.

The details of the new user must be provided in the payload, which includes the name and phone number of the user, an IBAN account number, and a label specifying the type of account. This account will be coupled to this user and will used in future payment requests.

Note: The platform supports Dutch phone numbers only.

When an enrollment is successful, a userToken and a bankAccounToken will be provided. These tokens can be used to access a specific user.

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 the platform that the user is enrolled on.
name String Body true Name of the user. Length: 2-70 characters.
phoneNumber String Body true Phone number of the user. Length: 10 characters. Example: 0601234567.
Note: The platform supports Dutch phone numbers only.
iban String Body true The users IBAN number.
Note: The platform supports Dutch IBANs only.
Note: The Tikkie Payment Request API limits the number of users with the same IBAN account number, if you assign a user an IBAN that is associated with another user, user creation will fail.
bankAccountLabel String Body true Label that describes the bank account of the new user, for example, 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 Token that identifies the user.
name String Body true Name of the new user.
status String Body true Current status of the new user. Possible values are 'ACTIVE' and 'INACTIVE'.
bankAccounts Array Body true Array of bank account objects that represent the bank accounts of the user. The fields below are properties of bank account objects, and not of the bankAccounts array itself.
bankAccounts.
bankAccountToken
String Body true Bank account token for this bank account.
bankAccounts.
iban
String Body true IBAN account number of this bank account.
bankAccounts.
bankAccountLabel
String Body true Label that describes the bank account of the user, for example, personal 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 fetches all users on an existing platform 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 application registration on the developer portal.
platformToken String Path true Identifies the platform that the user is enrolled on.
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 Token that identifies the user.
name String Body true Name of the user.
status String Body true Current status of the user. Possible values are: 'ACTIVE' and INACTIVE.
bankAccounts Array Body true Array of bank account objects that represent the bank accounts of the user. The fields below are properties of bank account objects, and not of the bankAccounts array itself.
bankAccounts.bankAccountToken String Body true Bank account token for this bank account.
bankAccounts.iban String Body true IBAN account number of this bank account.
bankAccounts.bankAccountLabel String Body true Label that describes the bank account of the user, for example, personal 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 creates a new payment request for an existing user. Payment requests are initiated by a specific user of your platform. The Tikkie Payment request API produces a link that is sent to the entity which must fulfil the payment request.

The user and bank account relating to a request is specified by the userToken and bankAccountToken, which must be submitted as path parameters. The details of the request are provided in the payload, which includes: currency, amount, and a description.

When a payment request is created, a paymentToken and a payment URL is returned. The payment URL, which must be sent to a user, will direct to the Tikkie website where a payment can be initiated. The paymentToken can be used for future access.

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 the platform that the user is enrolled on.
userToken String Path true Identifies the user that a request is being made to.
bankAccountToken String Path true Identifies the account the request is made on.
amountInCents String Body false The amount to be payed, in cents. If left empty, the payment request will automatically become a payment request with an 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 must be payed. Length: 3 characters.
description String Body true Description of the request. Length: 1-35 characters.
externalId String Body true* An external identifier for this payment request, for example, 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 URL that directs the counter party to a payment page.
paymentRequestToken String Body true Token that identifies the payment request, for future access.
externalId String Body false 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

This operation fetches all payment requests for a certain user. The identity of a user is determined based on the associated userToken. Results are paginated based on the request, and which record is first in the batch. Filtering is optional and is available based on date.

The result of this operation is one page of payment requests. For each payment request, a list of details is provided, such as: the amount, currency, creation date, and status. It also includes a list of payments that were completed to fulfill the payment request.

Payment status values
  • OPEN: a payment request is open and ready to be paid.
  • CLOSED: a payment request is closed.
  • EXPIRED: a payment request has expired.
    The default expiry period is 14 days. You can customize this when you start using the Payment Request API in production.
  • MAX_YIELD_REACHED: The payment request has reached its maximum amount in euro. This limit is dependent on the agreed maximum amount.
  • MAX_SUCCESSFUL_PAYMENTS_REACHED: The payment request has reached its maximum amount of payments. The maximum amount of payments per request can be set to one or unlimited.
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 application registration on the developer portal.
platformToken String Path true Identifies the platform that the user is enrolled on.
userToken String Path true Identifies the user who accessed a payment request.
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: include payment requests that are created after this date/time (in ISO-8601 format) only. Example: 2017-05-31T23:59:59Z
toDate String Query false Filtering: include payment requests that are created before this date/time (in ISO-8601 format) only. 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 payment requests in the requested range.
paymentRequests.paymentRequestToken String Body true Token that identifies the payment request.
paymentRequests.amountInCents String Body true Requested amount, in cents.
paymentRequests.currency String Body true Currency of the requested amount.
paymentRequests.description String Body true Description of the request.
paymentRequests.created String Body true Date and time a payment request was created (in ISO-8601 format).
paymentRequests.expired String Body true The date and time a payment request expired (in ISO-8601 format).
paymentRequests.status String Body true Current status of the payment request. Possible values are: 'OPEN', 'CLOSED', 'EXPIRED', 'MAX_YIELD_REACHED', and 'MAX_SUCCESSFUL_PAYMENTS_REACHED'
paymentRequests.bankAccountYieldedTooFast Boolean Body true If true, the bank account linked to this payment request is temporarily blocked for 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 completed to fulfill this request.
paymentRequests.payments.tikkieId String Body true Unique ID for the payment. This will be shown on the receipt of the payer.
paymentRequests.payments.paymentToken String Body false Token for this payment.
paymentRequests.payments.counterPartyName String Body false Name of the counter party (the person paying this payment).
paymentRequests.payments.amountInCents String Body false Amount that was paid in cents.
paymentRequests.payments.amountCurrency String Body false 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 this payment was created (in ISO-8601 format).
paymentRequests.payments.onlinePaymentStatus String Body true Online payment state of this payment. This indicates if the counter party paid or not. Possible values are: 'NEW', 'PENDING', 'PAID', and '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": [
        {
          "tikkieId": "000100392833",
          "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}

This operation will fetch a single payment request. The request is specified based on the provided paymentRequestToken and the userToken of the corresponding user. As a result, the details of that payment request are shown. This includes: amount, currency, creation date, and status. It also includes a list of payments that are completed to fulfill the payment request.

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 application registration on developer portal.
platformToken String Path true Identifies the platform that the user is enrolled on.
userToken String Path true Identifies the user who accessed this payment request.
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 Token that identifies the payment request.
amountInCents String Body true The requested amount, in cents.
currency String Body true Currency of the requested amount.
description String Body true Description of the request.
created String Body true Date and time this payment request was created (in ISO-8601 format).
expired String Body true Date and time this payment request expired (in ISO-8601 format).
status String Body true Current status of the payment request. Possible values are: 'OPEN', 'CLOSED', 'EXPIRED', 'MAX_YIELD_REACHED', and 'MAX_SUCCESSFUL_PAYMENTS_REACHED'
bankAccountYieldedTooFast Boolean Body true If true, the bank account linked to this payment request is temporarily blocked for exceeding the configured maximum yield per day.
externalId String Body true External identifier for this payment request, if provided.
payments Array Body true List of all the payments that have been completed to fulfill this request.
payments.tikkieId String Body true Unique ID for the payment. This will be shown on the receipt of the payer.
payments.paymentToken String Body false Token for this payment.
payments.counterPartyName String Body false Name of the counter party (the person paying this payment).
payments.amountInCents String Body false Amount that was paid in cents.
payments.amountCurrency String Body false Currency of the amount that was paid.
payments.description String Body false Description of this payment.
payments.created String Body false Date and time 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. Possible values are: 'NEW', 'PENDING', 'PAID', and '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": [
    {
      "tikkieId": "000100392833",
      "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 and codes that are sent by Tikkie Payment Request 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, see Error codes.

Code Status Category Description
ERR_1100_001 400 BAD_REQUEST User could not be created.
ERR_1100_002 400 BAD_REQUEST Payment request was not be found or does not exist.
ERR_1100_003 400 BAD_REQUEST Could not search for the payment request.
ERR_1100_004 400 BAD_REQUEST Invalid input parameter.
ERR_1100_005 400 BAD_REQUEST A parameter is missing. To determine which parameter is missing, view the message field of the response.
ERR_1100_006 400 BAD_REQUEST For more information, see the message field of the response.
ERR_1100_007 400 BAD_REQUEST Operation was not found.
ERR_3100_001 403 FORBIDDEN Maximum number of platforms per client has been reached.
ERR_3100_002 403 FORBIDDEN Maximum number of users has been reached for this platform.
ERR_4100_001 404 NOT_FOUND Client could not be found or does not exist.
ERR_4100_002 404 NOT_FOUND Platform could not be found OR does not exist.
ERR_4100_003 404 NOT_FOUND User could not be found or does not exist.
ERR_8100_001 500 INTERNAL_SERVER_ERROR Unknown error occurred in the backend. If this problem persists, contact support.
ERR_9100_011 503 SERVICE_UNAVAILABLE Tikkie service is unavailable.