API Workflow & Setup

This document describes the standard (happy-path) flow for the Payment Request API. It explains how to:

Create a payment request
Retrieve the payment request status
Manage or delete existing payment requests

It also lists the available status codes and their definitions. To test error scenarios, see Try it Out (Sandbox).

Before you begin

Before you create a payment request, make sure you meet the requirements below.

Sandbox Requirements

Set up a sandbox account
Set up sandbox application and subscription to:
- Payment Request Sandbox
Set up your Mutual TLS connection, you can find our example certificates for sandbox here.
Set up your signing flow, you can find our example certificates for sandbox here.
Set up your Oauth flow

Production Requirements

Set up a production account. To get a production account, see Go to Production
Set up production application and subscription to:
- Payment Request
Set up your Mutual TLS connection with your EV SSL certificate
Set up your signing flow with your EV SSL certificate
Set up your OAuth flow

Required headers

You are required to sign the payload for the POST (creation of a payment request) request.

📘
Read our Validate Signing Requests for a detailed explanation of the signing process.

Required headers to include in your requests are:

Name	Description	Format
Date	The date in a RFC-compliant date/time format.	String
Digest	The digest is a base64 encoded hash of the body.	String
X-Request-ID	The X-Request-ID is a UUID generated by you.	UUID
Signature	The signature is the signing string signed with your private key.	String
Signature-Certificate	The signature certificate is the public part of your EV SSL signing certificate.	String
X-IBM-Client-ID	The X-IBM-Client-ID is a UUID generated by your application.	UUID
Authorization	The Authorization header should include your access token.	String
PSU-IP-Address	The PSU-IP-Address consist of the IP address of the initiating party.	String
Content-Type	Defines the type of the request. Only required for POST requests.	String

Step 1 - Read account list

Endpoint:

Read Accounts List
GET /payments/payment-requests/accounts

Purpose: Retrieve the list of accounts that can be used to create payment requests.
Use this endpoint to obtain the required iban and currency.

Step 2 - Create a new payment request

Endpoint:

Create Payment Request
POST /payments/payment-request

Purpose: Create a new payment request. A successful response returns the assignedId and a paymentPageUrl.

Optional request body parameters

Name	Description	Format
redirectUrl	URL to redirect the user after completion, cancellation, or expiration.	URL (RFC 3986), HTTPS only
hasVariableAmount	Indicates whether the payer can enter the amount manually.	True or False

RedirectUrl

Use redirectUrl to send the user back to your website after the payment flow ends. Requirements:

The URL must be valid and use HTTPS.
You must implement the destination page.

"redirectUrl": https://www.abc.nl/payment-request/redirect

After completion, cancellation, or expiration, we redirect the user automatically. You use the id and trxid in the query parameters of the URL to fetch the transaction status and display it to the customer on their page.

https://www.abc.nl/payment-request/redirect?id=fe129503-4141-4f6e-967d-5bdb5b1fd630&trxid=b6248d63-0aad-4d68-9a4c-c925efeeb4a1

🚧

Do not pass a redirectUrl unless the page exists.

We generate and populate the id and trxid values automatically.

hasVariableAmount

Use hasVariableAmount to allow the payer to enter the payment amount.

false(default):
- amountCents is required.
true:
- amountCents is optional and may be null.

Step 3 - Get Transaction Status

Endpoint:

Transaction Status Payment Request
GET payments/payment-requests/{id}/transactions/{transactionId}.

Purpose: Retrieve the transaction status for a specific payment request.

Optional next steps

After creating a payment request, you can manage it using the endpoints below.

Generate QR Code

Endpoint:

Generate QR Code
GET /payments/payment-requests/{id}/qr-codes

Purpose: Generate a QR code for the specified payment request.

List Payment Requests

Endpoint:

List of Payment Requests
GET payments/payment-requests

Purpose: Retrieve all payment requests created by the current user.

Get Payment Request Details

Endpoint:

Payment Request Details
GET payments/payment-requests/{id}

Purpose: Retrieve details of a specific payment request.

Delete A Payment Request

Endpoint:

Delete Payment Request:
DELETE /payments/payment-requests/{Id}

Purpose: Delete a payment request. This action invalidates the associated paymentPageUrl.