Tutorial

Overview

The Tikkie API enables Tikkie business customers to create payment requests.

This API provides the following functionality:

• Create payment requests and retrieve transaction details.
• List payments that have been made on a payment request.
• Refund payments and retrieve refund details.
• Subscribe to notifications on payments, refunds, and bundled payouts.
• Retrieve transaction bundles.
• Note: Bundled payout must be enabled in your Tikkie Business Account.

⚠️ This API cannot delete payment requests.

API Key & App Token

An API Key is a unique token per organization. It is used to identify your company. The API Key can be retrieved in the ABN AMRO Developer Portal after registering your application. Follow the How to use this API instruction to learn how to obtain an API Key.

An App Token is connected to your Tikkie Business account (and you can have multiple). It is possible to assign different permissions to each token.

Important: In a production environment, App Tokens are created and configured in the Tikkie Business Portal under API settings. In a Sandbox environment, an App Token is created using the API, see How to use this API.

An App Token can have multiple permissions:

Permission	Functionality Description
Payment request	Create payment requests, retrieve payment request details, retrieve payment information and execute refunds, and create subscriptions to payment request notifications.
Refund	Create refunds. Refund is an additional permission on top of payment request.
Transaction bundle	Retrieve transaction bundles and subscribe to transaction notifications.

Make sure to enable each permission you need for your application in the Tikkie Business Portal. If you do not enable a permission, the API will return a 403 Forbidden error when you try to use that functionality. More information on App Tokens and permissions can be found in the Tikkie Business Portal under API settings.

Important: The API Key and App Token must be included in the header of each request. The API Key is included in the API-Key header, and the App Token is included in the X-App-Token header.

Thresholds

Different thresholds apply to aspects of payment requests, such as: the number of payments per payment request, the maximum amount of a payment request, and the maximum yield. These thresholds are discussed on a per customer basis when access to production is requested. These thresholds are not applicable in the sandbox environment.

Payout of transactions

When a payment request is paid, the transaction is bundled and paid out to your bank account once a day. This is called a 'bundled payout'. How to configure your method of payout, can be found in the settings of your Tikkie Business Portal account. By default, your Tikkie transactions are bundled. To get transaction details and notifications on a bundled payout, the application must have the transaction bundle permission. For more information on permissions, see App token.

For Tikkie transactions that are paid out individually and directly, the application does not have the functionality of the transaction bundle module.

Bundle information is retrieved using the GET Transaction Bundles and GET Transaction Bundle endpoints.

Downloading transaction bundle files

It is possible to download a file that contains all transactions for a specific bundle. This can be used in your bookkeeping system. We support the CAMT.053 format only.

• Files are available for download when the bundle is paid out to your account. To receive notifications when this occurs, set up a transactions subscription using: POST Transactions Subscription.
• The full file URL is located in the files property of the bundle. Locate this by executing GET Bundle.
• Using the obtained URL, the file can be downloaded. The following headers must be added in the request to download the file:
• X-App-Token
• User-Agent
• API-Key

Note: If you receive a 'Forbidden' response, ensure all headers are present.

Requirements

To use this API in a production environment, you must have the following:

• Visit the Tikkie website to sign up for a contract.
• An app token created in Tikkie business portal.

Note: This is not required if you want to use this API in the Sandbox environment.

Important: Consumer to Consumer (C2C) use of the API is prohibited.

Important: Generation of payment requests on behalf of third parties is prohibited.

Sandbox access

Use the ABN AMRO Developer Sandbox to access dummy data, and safely test all functionality of an API. For most products, the sandbox environment is identical to production.

To access the Tikkie API in a sandbox environment, complete the steps within How to use this API instruction.

Production access

When you are ready to go live with your application, complete the following steps:

Important: To go live with your application, you must create a new application in the developer portal. A different API key is required for your production environment. This is described below:

1. Log in to your account .
2. In the left-side navigation, click Apps.
3. Click Request Production Access.
4. Select the API category (Tikkie) that you want to request production access on.

   Note: It is not possible to request production access for multiple API categories in one request.

5. Fill in the form, click Preview and, after reviewing your details, click Submit.
6. You receive a confirmation email and ticket-ID.
7. ABN AMRO developer support validates the form, and if necessary contacts you.
8. When the setup is complete, ABN AMRO developer support contacts you, and a new app is added in Apps. This new app contains your API key for your production environment.

How to use this API

This instruction describes how to connect the Tikkie API to the sandbox environment, along with the API's functionality.

Postman collection

Use the following Postman collection to try out the functionality of this API:

• This collection highlights all available operations of the API: open API in Postman.

For additional information on how to configure Postman and import a collection, see Postman.

Step 1 - Get an API key

1. Register and create an account:
   • Go to ABN AMRO Developer Portal and click Sign up.
   • Enter your details, and click Create new account.
   • Developer support will send you an activation link by email.
   • Click the activation link.
2. Create and register an application:
   • Log in to your account.
   • In the left-side navigation click Apps.
   • Click on Add app button.
   • In the App name field, enter a name for your application.
   • In the APIs field, select Tikkie, and click Add app.
3. Obtain your API key:
   • In the left-side navigation, click Apps.
   • Click on the app you created.
   • Copy the API Key STRING.

Step 2 - Create a sandbox appToken

Important: In a production environment, App Token is created in the Tikkie Business Portal. The functionality described in this step is available in the sandbox only.

The functionality described in this step is only available in the sandbox environment.

To create a new App Token, which already has all permissions enabled (see App token) on Sandbox, using the API key you obtained in the previous step, execute the following curl command:

    curl -X POST "https://api-sandbox.abnamro.com/v2/tikkie/sandboxapps" \
    -H "API-Key: <YOUR_API_KEY>"

Or see: POST Sandbox App.

The response contains an App Token (appToken) which should be used in subsequent requests.

Step 3 - Create a payment request

To create a payment request, using the App Token you created in Step 2, execute: POST Payment Request.

This operation creates a new payment request as specified by the body of the request, and returns a paymentRequestToken which is used as unique identifier of a payment request.

The operation also returns a url that is used to direct the user to where the request can be paid. On sandbox environment, this URL goes to the iDEAL simulator where you can simulate a payment. Make sure you have done this before going to the next step.

Step 4 - Retrieve payment request details

To retrieve details of payment requests, use one of the following operations:

• GET Payment Request: Returns the details of one payment request, specified by a paymentRequestToken.
• GET Payment Requests: Returns a list of payment requests based on the query parameters passed in the request. This list is paginated.

Step 5 - Retrieve payment details

When a user pays a payment request, the transaction is marked as a 'payment'. This indicates that the payment is completed.

To retrieve payment details, use one of the following operations:

• GET Payment: Returns the details of one payment, specified by a paymentToken which is used as unique identifier of one paid payment request.
• GET Payments: Returns a list of payments based on the query parameters passed in the request. This list is paginated.

Step 6 - Create a refund

To create a refund, execute: POST Refund.

This operation initiates a refund on a specific payment, and returns a refundToken which can be used to retrieve details.

Step 7 - Retrieve refund details

To retrieve refund details, execute: GET Refund.

This operation returns the details of one refund, specified by a refundToken.

Step 8 - Set up a payment subscription

To receive notifications when a payment is paid, or when a refund has been paid executed, set up a subscription using: POST Notification Subscription.

HTTP post requests will be made to the specified url, containing information about the payment or refund in the body of the request.

Step 9 - Cancel a payment subscription

To cancel a subscription and stop receiving notifications, execute: DELETE Notification Subscription.

Step 10 - Retrieve transaction bundle details

To retrieve details of transactions, use one of the following operations:

• GET Transaction Bundle: Returns the details of one transaction bundle specified by a bundleId.
• GET Transaction Bundles: Returns a list of transaction bundles based on the query parameters passed in the request. This list is paginated.
• Download bundle file: Describes how to download a CAMT.053 file of a specific bundle.

Step 11 - Set up a transactions subscription

To receive notifications when a transactions bundle is paid, set up a subscription using: POST Transactions Subscription.

HTTP post requests will be made to the specified url, containing information about the transactions bundle in the body of the request.

Step 12 - Cancel a transactions subscription

To cancel a subscription and stop receiving notifications, execute: DELETE Transactions Subscription.