Skip to main content
Version
API docs by Redocly

Payments Gateway API (1.27.21)

Download OpenAPI specification:Download

License: Apache 2.0

Common payments API

Authorization

OAuth2.0 Authorization Framework

https://tools.ietf.org/html/rfc6749#section-4.4.2

Obtain access token using OAuth 2.0.

RFC 6749 - The OAuth2.0 Authorization Framework
Request Body schema: application/x-www-form-urlencoded
required
client_id
required
string

Client id that was provided for authentication

client_secret
required
string

Client secret that was provided for authentication

grant_type
required
string
Value: "client_credentials"

Authorization grant type. The only supported value is client_credentials.

Responses

Response samples

Content type
application/json
{
  • "access_token": "2YotnFZFEjr1zCsicMWpAA",
  • "token_type": "Bearer",
  • "expires_in": 3600
}

Checkout

Checkout endpoints for using the CM hosted checkout.

https://developers.cm.com/payments-platform

Create checkout

Create a new checkout. After receiving a HTTP status 201 you have to redirect the consumer to the url given in action.redirect.url. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create checkout

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string <= 35 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

merchantOrderReference
required
string (MerchantOrderReference) <= 35 characters

Unique identifier, as known by the merchant. This value will end up in the payments portal.

object (CheckoutConsumer)
maxRetries
integer (MaxRetries) [ 0 .. 255 ]

Maximum number of payment attempts allowed for this checkout order. Values:

  • null or omitted: Defaults to 0 (no retry limit, skip UI with single payment method)
  • 0: No retry limit enforcement. When combined with a single payment method, the hosted checkout will skip the payment method selection screen and redirect the customer directly to the payment method (e.g., iDEAL, PayPal). Useful for external integrations that have their own checkout UI.
  • 1-255: Enforces retry limit. After exceeding this number of failed payment attempts, the checkout will be locked out with status LOCKED_OUT. The payment method selection screen will be shown normally, even with a single payment method.

Use Cases:

  • External integrations: Set to 0 to enable seamless redirect from external checkout to payment provider
  • Fraud prevention: Set to 3-5 to limit retry attempts and prevent abuse
  • Standard checkout: Set to 10-255 for generous retry limits with fraud protection

Important: maxRetries=0 does NOT mean "lock out immediately". It means "allow unlimited retries without lockout enforcement".

paymentMethods
Array of strings (PaymentMethods)
Items Enum: "apple_pay" "bancontact" "bank_transfer" "creditcard" "google_pay" "ideal" "klarna" "paypal" "in3"

List of payment methods used in the checkout. If not provided all available payment methods will be shown.

Array of objects (OrderItems) [ 1 .. 512 ] items

Items included in the order. Required field for the following payment methods: Klarna, Riverty. We request both values 'vatAmount' and 'vatRate' to prevent errors.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
Example
{}

Fetch payment

Retrieve details for an existing Checkout transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Refund payment

Create a refund for a previous made Credit Card transaction. A payment must be fully processed, captured and there shouldn't exist a chargeback to be able to refund them.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "36a798e5-c2f5-48f2-bf68-2f58870d7c82",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "merchantOrderReference": "bandwidth",
  • "description": "Order at yourdomain.tld",
  • "paymentMethods": [
    ],
  • "expiresAt": "2026-01-02T15:04:05Z",
  • "status": "SUCCESS",
  • "action": null,
  • "createdAt": "2025-09-23T11:52:33Z",
  • "returnUrl": "https://yourdomain.tld/order/payment-result.html",
  • "maxRetries": 255,
  • "payments": [
    ],
  • "refunds": {
    }
}

Fetch checkout refund

Retrieve refunds for a Checkout transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Bancontact

Bancontact is a popular payment method in Belgium, allowing customers to pay online using their Bancontact card.

https://www.bancontact.com/en

Create transaction

Create a new Bancontact transaction (order), that can be paid later with card details or via QR code / Intent URL. The id field in the response can be used in future calls as transactionId to reference this transaction.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create Bancontact Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooksBancontact)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

required
object (ConsumerBase)

Responses

Request samples

Content type
application/json
{
  • "returnUrl": "https://yourdomain.tld/order/return?orderID=order123",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "language": "nl",
  • "webhooks": [],
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2006-01-02T15:04:05Z",
  • "consumer": {
    }
}

Response samples

Content type
application/json
{}

Start payment with encrypted card details

Start a Bancontact Card payment transaction. Use the id field from the former made create transaction response.

This endpoint is used to start a Bancontact payment with card details that are encrypted using the CSE library.

The encryptedCardDetails object must be created using the CSE library, which is available at /paymentmethods/library/cse. The browserInformation object is required to provide information about the consumer's browser.

If the user is not able to use the intent URL or QR code, they can continue by entering their card data manually.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required

Start Bancontact Card transaction with encrypted card details

required
object (BrowserInformation)
required
object (EncryptedCardDetails)

Responses

Request samples

Content type
application/json
{
  • "browserInformation": {
    },
  • "encryptedCardDetails": {
    }
}

Response samples

Content type
application/json
{}

Fetch transaction

Retrieve details for an existing Bancontact transaction, either created in the API directly or through a Bancontact QR-code. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Create refund for payment

Create a refund for an existing Bancontact payment.

The paymentId parameter can be obtained from:

  • The id field in the response of the "Start payment with encrypted card details" endpoint.
  • The payment field in the webhook payload sent when the payment was made via QR code or intent URL.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

paymentId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds as paymentId.

Request Body schema: application/json
required

Create Bancontact Payment Refund

amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "620fd54b-1dd9-46a2-a926-2f0a11aca741",
  • "orderId": "b3789760-865c-438e-bb5b-498e2cd84334",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2025-06-02T15:04:05Z",
  • "language": "nl",
  • "country": "BE",
  • "webhooks": [],
  • "status": "SUCCESS",
  • "action": null,
  • "createdAt": "2025-05-28T11:53:32Z",
  • "returnUrl": "https://yourdomain.tld/order/return?orderID=order123",
  • "refunds": {
    }
}

Fetch payment refunds

Retrieve refunds for an existing Bancontact payment.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

paymentId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds as paymentId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Create refund Deprecated

This endpoint is deprecated and will be removed in a future release. Please use the payment refunds endpoint instead, indicating the specific payment to be refunded.

Create a refund for an existing Bancontact transaction. The transactionId parameter must be the ID of the transaction to be refunded.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required

Create Bancontact Refund

amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "620fd54b-1dd9-46a2-a926-2f0a11aca741",
  • "orderId": "b3789760-865c-438e-bb5b-498e2cd84334",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2025-06-02T15:04:05Z",
  • "language": "nl",
  • "country": "BE",
  • "webhooks": [],
  • "status": "SUCCESS",
  • "action": null,
  • "createdAt": "2025-05-28T11:53:32Z",
  • "returnUrl": "https://yourdomain.tld/order/return?orderID=order123",
  • "refunds": {
    }
}

Fetch refunds Deprecated

This endpoint is deprecated and will be removed in a future release. Please use the get payment refunds endpoint instead, indicating the specific payment for which you wish to list the refunds.

Retrieve refunds for an existing Bancontact transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Fetch payments

Retrieve a paginated list of payments for an existing BanContact transaction (order).

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

query Parameters
pageSize
integer (PaymentPageSize) [ 10 .. 100 ]
Example: pageSize=20

The number of elements to be returned in the response

after
string <date-time> (After) >= 20 characters
Example: after=2022-10-13T14:21:30.478935Z

ISO 8601 date and time.

Responses

Response samples

Content type
application/json
{
  • "total": 3,
  • "pageSize": 10,
  • "payments": [
    ]
}

Cards

Creditcard payments allow customers to pay online using their credit or debit cards.

https://www.visa.com/ and https://www.mastercard.com/

Create payment

Create a new Credit Card payment transaction. After receiving a HTTP status 201 you have to redirect the consumer to the url given in action.redirect.url. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create Card Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

required
object (ConsumerBase)
required
object (CardDetails)

Card details like the cardholders name, PAN, CVC and expiry date.

Responses

Request samples

Content type
application/json
{
  • "reference": "5e6baea7-607c-438a-aaba-b06ce0ae7776",
  • "amount": 89999,
  • "description": "Your order at My Web Shop.",
  • "expiresAt": "2025-05-21T14:17:44.491Z",
  • "language": "nl",
  • "consumer": {},
  • "cardDetails": {
    },
  • "returnUrl": "https://tradename.tld/shop/return/?purchase=PO1234567"
}

Response samples

Content type
application/json
{}

Fetch payment

Retrieve details for an existing Credit Card transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Refund payment

Create a refund for a previous made Credit Card transaction. A payment must be fully processed, captured and there shouldn't exist a chargeback to be able to refund them.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "0264f864-c815-47cb-9e1f-fe7ba4326565",
  • "orderId": "6c166afa-ae48-467d-8eed-fdbbf2f30198",
  • "reference": "b63fcd00-6643-4387-a47a-1d0044bb989e",
  • "amount": 89999,
  • "currency": "EUR",
  • "cardProvider": "visa",
  • "description": "Your order at My Web Shop.",
  • "expiresAt": "2025-05-21T13:53:31Z",
  • "language": "nl",
  • "country": "NL",
  • "status": "SUCCESS",
  • "action": null,
  • "createdAt": "2025-05-20T13:53:36Z",
  • "returnUrl": "https://cm.com",
  • "refunds": {
    }
}

Fetch refunds

Retrieve refunds for an existing Credit Card transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Create payment (v2)

Create a new Credit Card payment transaction using the v2 API. This version supports enhanced consumer data including billing and shipping addresses for improved fraud prevention.

The clientSideEncryptedCard must be encrypted using the provided CSE javascript library. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create Card Transaction V2

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> (Datetime) >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

clientSideEncryptedCard
required
string

Encrypted cardholder credit card details using the provided CSE javascript library.

required
CreditCardConsumerV2 (object) or CreditCardConsumerV2 (object) (CreditCardConsumerV2)

Cardholder personal information

  • Either email and/or MobilePhone must be provided
  • billingAddress conditional on the market

Responses

Request samples

Content type
application/json
{
  • "returnUrl": "https://yourdomain.tld/order/return?orderID=order123",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "language": "nl",
  • "webhooks": [],
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2006-01-02T15:04:05Z",
  • "clientSideEncryptedCard": "7cJG1p/j5Dl8FrvMN5rSGVq9IqXVZE3herLkQfpoNbZL1r6sUHXkJLPYH+IbG0tYwvNO2hZZeDdNhOWMHV0tT3sSYVeN5uelgV2RLRkPC3b5XRolW3URk80i8kHoOO2tQoBbIkXc47le0xbTDFl4UNAsIa/SnBWwZbJAFpMYyMHIP1faey9OD5qQ2L+KTQ07ipFHtlDyRvJWG8xDn2Mnz9We7tE0wn6oUilTcGs3fwMX+/14VBhQPRoZCM15OHuTrdK6lwqMJN0xxpfPFBMk9kHcq8VZ2hvLkbRkbvMYBfxkt9f6lxwCF8PdrVvDwHAOsfgIWXZVefCnIFdSHoX8ToMVD/GKWqJzF0nJgl6hLNo7OFBGmbMgXQZbQQKMl9eFx2m1QXYNHN7wpsAJhy+O1pF1aqQa0bnM6C2NTE6Glcik0GmgG4epFIvQnZXrJrRAtKKqYGh8Bs8MNvramaFfRiY+h9ZCHtA+alxKWVyGgES6YeqQZ2iiJCU0aOrdJBSyjpox6DRlnZsnWO/lyKD3OkKh+5XtXqOWhubQQiWL2+hGWy35dzYYhTXSdPot48emzSBtqtgNRREKZ9dtNd6O4d0/y+ruO1dsIpCMLByOr7yO7pMVcGBo1WRbohCEn52QYmo/Zbz8GF919G8uzD1wGaBRAx7vOb6otnhxKyRLLtjw6sV+wmI+eIplpaeaIIitZzIjy6II+TaY1uosBTWZqusdH21VQKo5A7OpHbTzqUJYuX5cXK978WCuA0lGlBJMnXZDJcBFlJLJZ6zNuKpbDZjSoaX7EkJhJznCX8OC6iYKR0Jyf/opDPAc+YlB13DFd5kCcSsEC3g4l/VcqrdQypbMWyTGkGVXKuwuF6Dk1+2VYCBvx9WqcPK3OuhVyCOXm+Y5DDYqsjh4hrszSxkOkjB7C+rMScKaqRxEdigNdKkqnHB/JNkfVKm1zc5HGXaEToVXEGg9sD1Ng/PIz3cn4zG9qQ6gmd0Nyn7w/0Ok8OfEi4pm0ohP1jxQ0c3VMT1Lblfzz+aW18R/+bgERr+Jeo17sxA6LK7u+LmGa4ZjwknaJ1lXKNkpawVlW9/mlm5dRZZqaI5LW4Opqa3gtguyZ8qM5ufQPPN5XkTQZ7m4WPFWhnySzhCZfRKlcjGtu8bi7EHVcdlpo5x/qX6BRrRyvA99S35v8HPISEBvZotsa0y+DVRJyL4HPna08EMdqUc0fXvz2zm57WDfquHzSTcBGEbNx/3K+E86T0esFNcFsU4dQgYg/YWKFfIoiUhvsaC9sA8kNnC5DvDTCbmVWFY/U33QINd7qgpCwfUDISVaqSjXkiF2N9ne/t59gW3EKEkncuzIJn1s3ncsUxHb7iVZHySnvb7fJblMfhp0CQei5WIZPTQaUYMgP8FK4VGSiE4FP27nTH6Ltyk0aiGLvObCDoc9jRi5rqsPSRf2sGlYclz5k3nLBL4e4H9VrpJAfZo/dqbepcShRjAuEECPuhlFKCLmHydRNNWQ4EwT7nqMZHlU2lQjibM3t6Mipn8Fono6z7HlhsUbIad5sX/QKWxbk8PoPmM80qWLjuSTxit0GPuTZZk9MEwVNNmbkomfZyc4YtebWvAPoOM7PkD89gFB/tISG1hgbr0M6Hc6Sax3gPPJA7WTgJhLJdcuAkC7kYReTutomzZ07ZIgt+0f3oJCTvQ9PCYvdKD3E3S280jl1AdtAaylnLQBP0O0ZAfBJKPfqEf5j4e+/8Dm7ALdwB9cFnAy9nfm6lFDk3wSmjdXisuY6s33k1PSYg528LzidEk9UGIJV378DhX2NftktsXjC3y6x7YtLno8m0vmdvCT+5Nb1xv9GiUtUUCjNNB8fdjT0nz299STedUVMYKkH84fpDbYpSJieOr1KxA9T6HoH2a4v6i4Gx3tHVvJtjSKV7OzyvaL7buMa2nNppMAPaZ2gLADLBMGF6YQghES5qBSTt5dBzPttPe1PwJ96yZIO8137b2Ry4iJcqc3fBdSIs4D8k6Ju0xwu+4IA4IH4I2ne715bfs8yEpudE22A1w3iOr+rcYtEzzV+qb53uik/GgQRp1Dx260wXyebbS+YpM5jBxmp9MnXu5rRvkmZGi0/1s7J2hx3d0Rdq1GyAP109dV8SQlTrLMOn3zjxb4lLo7PqZOpn+efPkn2oOMwHHz9VTJ0bII5wh9YwdPNNfp0w9Pfe70VIkEh7mMhVjXYJyaD+3hM3M+5iEi7GYywECvEw==",
  • "consumer": {
    }
}

Response samples

Content type
application/json
{}

Initialize payment for 3DS (v2)

Initialize a Credit Card transaction for 3D Secure authentication preparation. This endpoint is used before the actual payment to set up the authentication flow.

After initialization, you can proceed with the payment by calling the create transaction endpoint with the encrypted card details.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Initialize Card Transaction V2

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> (Datetime) >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

required
CreditCardConsumerV2 (object) or CreditCardConsumerV2 (object) (CreditCardConsumerV2)

Cardholder personal information

  • Either email and/or MobilePhone must be provided
  • billingAddress conditional on the market

Responses

Request samples

Content type
application/json
{
  • "returnUrl": "https://yourdomain.tld/order/return?orderID=order123",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "language": "nl",
  • "webhooks": [],
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2006-01-02T15:04:05Z",
  • "consumer": {
    }
}

Response samples

Content type
application/json
{}

Fetch payment (v2)

Retrieve details for an existing Credit Card v2 transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Create refund (v2)

Create a refund for a previous made Credit Card v2 transaction. A payment must be fully processed, captured and there shouldn't exist a chargeback to be able to refund them.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required

Create Credit Card Refund V2

amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{}

Fetch refunds (v2)

Retrieve refunds for an existing Credit Card v2 transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

iDEAL

iDEAL is a widely used online payment method in the Netherlands, allowing customers to pay directly from their bank accounts.

https://www.ideal.nl/en/

Create payment

Create a new iDEAL payment transaction. After receiving a HTTP status 201 you have to redirect the consumer to the url given in action.redirect.url. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create iDEAL Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string <= 35 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

purchaseId
required
string (PurchaseID) [ 1 .. 35 ] characters ^[A-Za-z0-9]{1,35}$

Unique identification of the order within the Merchant's system. This value appears on the bank statement of the Consumer.

The purchaseID can only contain letters and numbers.

object (IdealCheckout)

An iDEAL payment with iDEAL Checkout allow users to centrally manage their shipping, invoice and contact details in an iDEAL profile and provide these to a Merchant as part of the iDEAL payment.

Use this object to enable the iDEAL Checkout flow and specify the shipping costs and the consumer details to be returned after a successful payment.

requestUserToken
boolean (IdealPayFastRequestUserToken)

Requests a User Token for future Pay Fast transactions with the same Consumer.

When enabled and the Consumer consents, a User Token will be generated that enables push notifications in future transactions.

Only request User Tokens for Consumers who have established accounts with your service and can be reliably identified on return visits.

object (IdealPayFastExpectedDebtor)

If the Merchant is in possession of a User Token, obtained through a previous transaction, and the Consumer has indicated that he wants to reuse the bank account that was displayed after retrieving it from the getDebtorPreferences-endpoint, the User Token and browsers user-agent can be provided to enable the enhanced flow.

The Consumer for which a User Token is used MUST hold an account with the merchant. The Merchant MUST only use the iDEAL User Token that was received in the last transaction for the Consumer.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
Example
{}

Fetch payment

Retrieve details for an existing iDEAL transaction, either created in de API directly or through an iDEAL QR-code. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Refund iDEAL payment

Create a refund for a previous made iDEAL transaction. A payment must be fully processed to be able to refund them. This may take up to 30 minutes.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "72149cbf-d4a1-4309-9872-6ec19fa782cc",
  • "orderId": "68dcf257-b15d-4a86-9baa-4cf60c6c8a5c",
  • "reference": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e081",
  • "amount": 5999,
  • "currency": "EUR",
  • "purchaseId": "PO1234567",
  • "description": "Your order at My Web Shop.",
  • "expiresAt": "2025-05-08T17:36:50Z",
  • "language": "nl",
  • "idealTransactionId": "8153248198760451",
  • "status": "SUCCESS",
  • "action": null,
  • "createdAt": "2025-05-08T17:06:49Z",
  • "returnUrl": "https://tradename.tld/shop/return/?purchase=PO1234567",
  • "consumer": {
    },
  • "refunds": {
    }
}

Fetch refunds

Retrieve refunds for an iDEAL transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Fetch Pay Fast User Token

Retrieve the Pay Fast User Token that was generated by iDEAL for this transaction.

If no User Token was requested, the payment is not successful, the Consumer did not give consent, or the User Token is not yet available, a 404 status is returned.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "transactionId": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "userToken": "Z7xmaEJlB3rDLpmln9xbUlaQ"
}

Get consumers preferred bank account

Get the preferred bank account of the consumer by userToken before creating a Pay Fast transaction. The response must be rendered in the checkout so that the consumer can review it. If a 404 is returned a new token can be requested.

Authorizations:
oAuth2ClientCredentials
path Parameters
userToken
required
string (IdealPayFastUserToken) [ 1 .. 128 ] characters
Example: Z7xmaEJlB3rDLpmln9xbUlaQ

iDEAL Pay Fast User Token as generated by iDEAL, which is received in the response of a Create iDEAL Transaction when the field "requestUserToken" is set to true.

Responses

Response samples

Content type
application/json
{}

iDEAL-QR

iDEAL-QR codes can be used to initiate a predefined iDEAL transaction by scanning the QR-code by a Consumer mobile device.

https://www.ideal.nl/en/

Create iDEAL QR payment

Reusable idealQR transactions only have open and expired statuses. When a payment for an idealQR transaction is successful, the transaction status successful is updated only for non-reusable idealQR transactions, reusable ones will remain open until they expire.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required
One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooksQR)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string <= 35 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> (Datetime) >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

object (AmountChangeable)

Contains the minimum and maximum values for the amount of a QR code that a consumer can set themselves after scanning the code.

purchaseId
string (PurchaseID) [ 1 .. 35 ] characters ^[A-Za-z0-9]{1,35}$

Unique identification of the order within the Merchant's system. This value appears on the bank statement of the Consumer.

The purchaseID can only contain letters and numbers.

reusable
boolean (IDEALQRReusable)

Indicates the QR code's ability to accept multiple successful payments.

size
required
integer (DefaultPageSize) [ 100 .. 2000 ]

The number of elements to be returned in the response

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
Example
{}

Fetch payment

Retrieve details for an existing iDEAL-QR transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Fetch payments details

Retrieve a paginated list of payment details for an existing iDEAL-QR transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

query Parameters
pageSize
integer (PaymentPageSize) [ 10 .. 100 ]
Example: pageSize=20

The number of elements to be returned in the response

after
string <date-time> (After) >= 20 characters
Example: after=2022-10-13T14:21:30.478935Z

ISO 8601 date and time.

Responses

Response samples

Content type
application/json
{
  • "total": 6,
  • "pageSize": 10,
  • "payments": [
    ]
}

Fetch payment details

Retrieve details from a payment for an existing iDEAL-QR transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

paymentId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds as paymentId.

Responses

Response samples

Content type
application/json
{
  • "total": 6,
  • "pageSize": 10,
  • "payments": [
    ]
}

Fetch payments summary

Retrieve a summary that contains one or more payments for an iDEAL-QR transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

query Parameters
status
string
Enum: "OPEN" "SUCCESS" "FAILURE" "CANCELLED" "EXPIRED"

The status for a transaction.

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Refund a payment for an iDEAL-QR transaction

Creates a refund for payment that belongs to an iDEAL-QR transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

paymentId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds as paymentId.

Request Body schema: application/json
amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "payment": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "transaction": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "idealTransactionId": "1234567890123456",
  • "status": "FAILURE",
  • "createdAt": "2006-01-02T15:04:05Z",
  • "amount": 0,
  • "consumerName": "John",
  • "consumerBic": "string",
  • "consumerIban": "NL24RABO8487376045",
  • "refunds": {
    }
}

Fetch refunds for payment

Retrieve details of one or more refunds for an iDEAL transaction were returned successfully.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

paymentId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds as paymentId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Create iDEAL-QR in bulk

Allows the creation of iDEAL-QR transactions in bulk. Since this is a bulk operation the following rules apply:

  • if at least 1 qr code was created, the response status of the request wil be 200 (status 200 does not guarantee that all the Qr codes have been created, see the response body to get more details over which qr codes have been successfully created)
  • In case none of the qr codes was created, if there is any scenario where the reason might be a request with a client error, then a status 400 wil be given as response code, otherwise a status 500 will be retrieved.
  • The client always has to check the response body to see which Qr codes have been created successfully.
Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required
BulkDefaults (object) or BulkDefaults (object) (BulkDefaults)

Contains default values to create an iDEAL-QR transaction in a bulk operation.

required
Array of BulkQrCodeItemInRequest (object) or BulkQrCodeItemInRequest (object) (BulkQrCodesRequest) [ 1 .. 100 ]

Array of qr code objects with values to overwrite defaults

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

in3

in3 is a Dutch BNPL method where customers pay in 3 installments, at no extra cost and without having to register with the Bureau Krediet Registratie (BKR). in3 guarantees settlement after receiving the first installment.

https://payin3.eu/

Create payment

Create a new in3 payment transaction. After receiving a HTTP status 201 you have to redirect the consumer to the url given in action.redirect.url. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create in3 Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

required
object
expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time.

required
object (Consumer-2)

The person initiating the checkout, typically the buyer who places the order.

required
Array of objects (IN3Items) [ 1 .. 512 ] items

Items included in the order. We request both values 'vatAmount' and 'vatRate' to prevent errors.

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

Responses

Request samples

Content type
application/json
Example
{
  • "invoice": {
    },
  • "expiresAt": "2025-09-25T17:03:48.456Z",
  • "consumer": {
    },
  • "items": [
    ],
  • "returnUrl": "https://yourdomain.tld/order/payment-completed.html"
}

Response samples

Content type
application/json
Example
{}

Fetch payment

Retrieve details for an existing in3 transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Create refund

Create a refund for an existing in3 transaction. The transactionId parameter must be the ID of the transaction to be refunded.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "transactionId": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "amount": 1200,
  • "reason": "Refund required by consumer.",
  • "status": "SUCCESS",
  • "created": "2006-01-02T15:04:05Z",
  • "updated": "2006-01-02T15:04:05Z"
}

Fetch refunds

Retrieve refunds for an existing in3 transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Klarna

Klarna is a payment method that allows customers to pay for their purchases later, either in installments or at a later date.

https://www.klarna.com/

Create payment

Create a new Klarna payment transaction. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund). This endpoint is used to create a Klarna payment transaction. The webhooks object is optional and can be used to specify webhooks for the transaction.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create Klarna Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

required
Array of objects (Items) [ 1 .. 512 ] items

Items included in the order. We request both values 'vatAmount' and 'vatRate' to prevent errors.

required
object (ConsumerBase)

Responses

Request samples

Content type
application/json
{
  • "reference": "20210623130413",
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2025-06-02T15:04:05Z",
  • "language": "nl",
  • "consumer": {
    },
  • "items": [
    ],
  • "webhooks": [],
  • "returnUrl": "https://yourdomain.tld/order/payment-success.html"
}

Response samples

Content type
application/json
{}

Fetch payment

Retrieve details for an existing Klarna transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "id": "a95e9fab-e779-49fd-9dae-0c962a4321c8",
  • "orderId": "18a62430-566a-419a-9f8b-09bc9a95d312",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2025-06-02T15:04:05Z",
  • "language": "nl",
  • "country": "NL",
  • "items": [
    ],
  • "webhooks": [],
  • "status": "SUCCESS",
  • "action": null,
  • "createdAt": "2025-05-28T13:00:50Z",
  • "returnUrl": "https://yourdomain.tld/order/payment-success.html"
}

Create refund

Create a refund for an existing Klarna transaction. The transactionId parameter must be the ID of the transaction to be refunded.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "a95e9fab-e779-49fd-9dae-0c962a4321c8",
  • "orderId": "18a62430-566a-419a-9f8b-09bc9a95d312",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2025-06-02T15:04:05Z",
  • "language": "nl",
  • "country": "NL",
  • "items": [
    ],
  • "webhooks": [],
  • "refunds": {
    },
  • "status": "SUCCESS",
  • "action": null,
  • "createdAt": "2025-05-28T13:00:50Z",
  • "returnUrl": "https://yourdomain.tld/order/payment-success.html"
}

Fetch refunds

Retrieve refunds for an existing Klarna transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Paymentmethods

Payment methods available in the API.

Get an array of all available payment methods.

Receive a list of all available payments which can be rendered in your checkout.

Note: this list is not context aware and is only a list of your activated payment methods.

Authorizations:
oAuth2ClientCredentials

Responses

Response samples

Content type
application/json
[
  • "bancontact",
  • "creditcard",
  • "ideal"
]

PayPal

PayPal is a widely used online payment system that allows customers to pay for goods and services using their PayPal account.

https://www.paypal.com/

Create PayPal payment

Create a PayPal transaction. After receiving a HTTP status 201 you have to redirect the consumer to the url given in action.redirect.url. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create PayPal Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

required
object (ConsumerBase)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Fetch PayPal payment

Retrieve details for an existing PayPal transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{}

Create PayPal refund

Create a refund for an existing PayPal transaction. The transactionId parameter must be the ID of the transaction to be refunded.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{}

Fetch refunds

Retrieve refunds for an existing PayPal transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Create PayPal payment

Create a PayPal transaction. After receiving a HTTP status 201 you have to redirect the consumer to the url given in action.redirect.url. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create PayPal Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
required
string (Currency) = 3 characters

ISO 4217 currency code.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

Array of objects (PayPalV2Item)
object (PayPalV2Consumer)
Array of objects (PayPalV2Webhooks)

Responses

Request samples

Content type
application/json
{
  • "reference": "b5910552-7344-4c9c-a0e8-3657d8bc1897",
  • "amount": 123,
  • "currency": "EUR",
  • "description": "Your order at My Web Shop.",
  • "consumer": {},
  • "items": [
    ],
  • "returnUrl": "https://tradename.tld/shop/return/?purchase=PO1234567"
}

Response samples

Content type
application/json
{}

Fetch PayPal payment

Retrieve details for an existing PayPal transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{}

Create refund

Create a refund for an existing PayPal transaction. The transactionId parameter must be the ID of the transaction to be refunded.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "transactionId": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "amount": 1200,
  • "reason": "Refund required by consumer.",
  • "status": "SUCCESS",
  • "created": "2006-01-02T15:04:05Z",
  • "updated": "2006-01-02T15:04:05Z"
}

Fetch refunds

Retrieve refunds for an existing PayPal transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Riverty

Riverty is a payment method that allows customers to pay for their purchases in installments or at a later date.

https://docs.riverty.com/bnpl

Create Riverty payment

Create a Riverty transaction. After receiving a HTTP status 201 you have to redirect the consumer to the url given in action.redirect.url. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a capture, cancellation or refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create Riverty Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount-2) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string <enum> (Currency-2) = 3 characters
Default: "EUR"
Value: "EUR"

ISO 4217 currency code.

language
string <enum> = 2 characters
Default: "nl"
Enum: "no" "sv" "fi" "da" "en" "de" "nl" "fr"

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

orderNumber
required
string <= 50 characters

Order number. Unique order number provided by the merchant. A valid order number can include alphanumeric characters, dashes and underscores.

type
required
string <enum>
Value: "Invoice"

The type of the Riverty payment method.

netAmount
required
integer (NetAmount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

merchantImageURL
string <url>

Image URL for the merchants brand. This image is shown at the top of the order page in Riverty. Supported image formats are: gif, jpeg (jpg), png, webp.

additionalMerchantData
string <= 4096 characters

Additional information about the merchant Format: Base64 encoded JSON

required
object (Consumer-3)

The person initiating the checkout, typically the buyer who places the order.

required
Array of objects (RivertyItems) [ 1 .. 500 ] items

Array of order items. Maximum allowed 500 items.

object (RivertyWebhooks)

A single webhook object consists out of an URL to which we need to send the occurred event together with the event that needs to trigger the webhook call.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
Example
{}

Fetch Riverty payment

Retrieve details for an existing Riverty transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{}

Create a Riverty capture

Important: This endpoint isn't available for customers who enabled auto capture in their Riverty account.

Create a capture for an existing Riverty transaction. The transactionId parameter must be the ID of the transaction to be captured.

For an amount equal to the full amount of the transaction, items is optional, otherwise it has to be provided. The amount cannot exceed the remaining uncaptured amount of the transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required
amount
required
integer (Amount-2) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

netAmount
required
integer (NetAmount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

Array of objects (RivertyItems) [ 1 .. 500 ] items

List of items to be captured. Mandatory for partial captures. If not provided, the full amount will be captured. If provided, the total amount of all items must match the amount in the capture request.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 2400,
  • "netAmount": 2000
}

Response samples

Content type
application/json
Example
{
  • "id": "5b84c8e5-3c8d-45c4-8fe1-7f549c1972b3",
  • "transactionId": "5b84c8e5-3c8d-45c4-8fe1-7f549c1972b3",
  • "amount": 2400,
  • "netAmount": 2000,
  • "created": "2025-10-25T20:38:49Z",
  • "updated": "2025-10-25T20:38:49Z"
}

Fetch Riverty transaction captures

Retrieve captures for an existing Riverty transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "captures": [
    ]
}

Cancel an authorization

Cancel an existing Riverty transaction. The transactionId parameter must be the ID of the transaction to be cancelled.

Important: A transaction cannot be cancelled if it has already been partially or fully captured. Cancellation is only possible for authorized transactions that have not yet been captured.

Leaving the amount field empty will cancel the full amount of the transaction. If an amount is specified, it must be a positive value and not exceed the remaining uncancelled amount of the transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required
amount
required
integer (Amount-2) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

netAmount
required
integer (NetAmount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

Array of objects (RivertyItems) [ 1 .. 500 ] items

List of items to be cancelled. Mandatory for partial cancellations. If not provided, the full order will be cancelled. If provided, the total amount of all items must match the amount in the cancel request.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 2400,
  • "netAmount": 2000
}

Response samples

Content type
application/json
Example
{
  • "id": "fbd7e1c9-3039-4f79-a57b-bd1257e03c5f",
  • "transactionId": "3fec0a41-6073-452f-b59c-8e7c7faf7b85",
  • "amount": 42400,
  • "netAmount": 38000,
  • "created": "2025-10-25T20:38:49Z",
  • "updated": "2025-10-25T20:38:49Z"
}

Create Riverty refund

Create a refund for a specific capture within an existing Riverty transaction.

The captureId field is required for transactions with multiple captures, and optional for transactions with a single capture.

The items field is optional. If omitted, all items of the capture will be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

header Parameters
X-Idempotency-Key
string <= 50 characters ^[A-Za-z0-9_-]+$
Example: refund-2024-06-01-a1b2c3

A unique client-supplied key to safely retry a request without creating a duplicate operation.

Can include letters, numbers, hyphens and underscores, up to 50 characters long.

Request Body schema: application/json
captureId
string <uuid> (Uuid) = 36 characters

Unique identifier of the capture to be refunded, received in the capture response.

Required for transactions with multiple captures.

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Array of objects (RivertyItems) [ 1 .. 500 ] items

Array of order items. Maximum allowed 500 items.

Responses

Request samples

Content type
application/json
Example
{ }

Response samples

Content type
application/json
Example
{
  • "id": "76840859-3388-4573-beb6-ed02e10a2679",
  • "transactionId": "cb3ae4bb-1085-4c34-9e48-ecb1a31aaef3",
  • "captureId": "385720a9-4118-481b-b431-a4797496c8a9",
  • "status": "SUCCESS",
  • "created": "2025-10-19T20:38:49Z",
  • "updated": "2025-10-19T20:38:49Z"
}

Fetch Riverty transaction refunds

Retrieve refunds for an existing Riverty transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

ApplePay

Apple Pay is a mobile payment and digital wallet service that allows customers to make secure, contactless payments in stores (using NFC), within iOS apps, and on the web.

https://www.apple.com/apple-pay/

Create/initialize Apple Pay session

Create/initialize an Apple Pay session. Returns a details object containing configuration needed to render the Apple Pay button on the checkout UI. The id field in the response can be used in future calls as sessionId to reference this session.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json

Create Apple Pay Session

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

description
required
string <= 255 characters

Description of the underlying value or reason of the session. Ultimately appears on the confirmation (statement and confirmation screen).

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

object (Consumer)
object (SessionTransactionWebhooks)

A single webhook object consists out of an URL to which we need to send the occurred event together with the event that needs to trigger the webhook call.

returnUrl
string <url> (ReturnUrl) <= 2000 characters

URL where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this implementation you are responsible to fetch the payment status and incorporated into your site.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e082",
  • "reference": "5e6baea7-607c-438a-aaba-b06ce0ae7776",
  • "amount": 2000,
  • "currency": "EUR",
  • "description": "Some Apple Pay session",
  • "expiresAt": "2025-05-21T14:17:44.491Z",
  • "language": "nl",
  • "status": "OPEN",
  • "action": {
    },
  • "createdAt": "2025-05-11T14:17:44.491Z",
  • "returnUrl": "https://tradename.tld/shop/return/?purchase=PO1234666"
}

Start Apple Pay session

Generates a valid Apple Pay payment session by interacting with Apple Pay servers. Use the id field from the initialize response as sessionId.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

Request Body schema: application/json
required
validationUrl
string

The validation URL that is generated by the Apple device.

displayName
string

The name to display on the payment sheet. You get this information from the initialize endpoint.

domainName
string

The domain of the website on which the session will occur. The value must match the domain from which the request is started. If there is a mismatch between this field and the domain that the Apple device determined, then the Apple Pay session will be terminated by the Apple device (with a generic error message or nothing happens).

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "displayName": "My merchant commercial name",
  • "domainName": "https://app-domain.tld",
  • "epochTimestamp": 1689601984961,
  • "expiresAt": 1689601984961,
  • "merchantIdentifier": "A25210A72D2148E13005A300DFF6435FB401C317CF84C881D9D4018F67BA7D1E",
  • "merchantSessionIdentifier": "SSHB12847F0ACB6478B9C1140CED6216A91_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24",
  • "nonce": "83ds18s",
  • "operationalAnalyticsIdentifier": "A25210A72D2148E13005A300DFF6435FB401C317CF84C881D9D4018F67BA7D1E",
  • "pspId": "A25210A72D2148E13005A300DFF6435FB401C317CF84C881D9D4018F67BA7D1E",
  • "retries": 0,
  • "signature": "308006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e330820388a00302010202084c304149519d5436300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3139303531383031333235375a170d3234303531363031333235375a305f3125302306035504030c1c6563632d736d702d62726f6b65722d7369676e5f5543342d50524f4431143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004c21577edebd6c7b2218f68dd7090a1218dc7b0bd6f2c283d846095d94af4a5411b83420ed811f3407e83331f1c54c3f7eb3220d6bad5d4eff49289893e7c0f13a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d65732061636365707461..."
}

Fetch Apple Pay session

Retrieve details for an existing Apple Pay session. This endpoint must be used to obtain the status for a session.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

Responses

Response samples

Content type
application/json
{
  • "id": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e082",
  • "reference": "5e6baea7-607c-438a-aaba-b06ce0ae7776",
  • "amount": 2000,
  • "currency": "EUR",
  • "description": "Some Apple Pay session",
  • "expiresAt": "2025-05-21T14:17:44.491Z",
  • "language": "nl",
  • "status": "OPEN",
  • "action": {
    },
  • "createdAt": "2025-05-11T14:17:44.491Z",
  • "returnUrl": "https://tradename.tld/shop/return/?purchase=PO1234666"
}

Authorize Apple Pay transaction

Authorize a transaction for an existing Apple Pay session. When the shopper selected a card, the details are returned as payment data by the Apple Pay client. The request data is passed on as-is received from the Apple device in the on authorize payment event. Modifications are not allowed.

This endpoint creates the actual transaction for the session. A TRANSACTION_CREATED webhook will be triggered if subscribed.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

Request Body schema: application/json
required
object
object
object
transactionIdentifier
string

Responses

Request samples

Content type
application/json
{
  • "token": {
    }
}

Response samples

Content type
application/json
Example
{}

Fetch Apple Pay session transactions

Retrieve all transactions for an existing Apple Pay session.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

Responses

Response samples

Content type
application/json
{
  • "transactions": [
    ]
}

Fetch Apple Pay session transaction

Retrieve a specific transaction for an existing Apple Pay session.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Create refund for transaction

Create a refund for an existing Apple Pay transaction.

The transactionId parameter can be obtained from the payment field in the webhook payload sent when the transaction was created.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required

Create Apple Pay Transaction Refund

amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "transactionId": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "amount": 1200,
  • "reason": "Refund required by consumer.",
  • "status": "SUCCESS",
  • "created": "2006-01-02T15:04:05Z",
  • "updated": "2006-01-02T15:04:05Z",
  • "sessionId": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e082"
}

Fetch transaction refunds

Retrieve refunds for an existing Apple Pay transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

GooglePay

Google Pay is a fast and secure payment method that allows customers to pay online using their Google account.

https://developers.google.com/pay/api/web/overview

Create/initialize Google Pay session

Create/initialize a Google Pay session. Returns a details object containing configuration needed to render the Google Pay button on the checkout UI. The id field in the response can be used in future calls as sessionId to reference this session.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json

Create Google Pay Session

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

description
required
string <= 255 characters

Description of the underlying value or reason of the session. Ultimately appears on the confirmation (statement and confirmation screen).

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

object (Consumer)
object (SessionTransactionWebhooks)

A single webhook object consists out of an URL to which we need to send the occurred event together with the event that needs to trigger the webhook call.

returnUrl
string <url> (ReturnUrl) <= 2000 characters

URL where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this implementation you are responsible to fetch the payment status and incorporated into your site.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "11111111-1111-1111-1111-111111111111",
  • "reference": "20240612104501",
  • "amount": 1200,
  • "currency": "EUR",
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2025-06-24T12:48:21Z",
  • "language": "nl",
  • "status": "OPEN",
  • "action": {
    },
  • "createdAt": "2025-06-23T12:48:24Z",
  • "returnUrl": "https://tradename.tld/shop/return/?purchase=PO1234567"
}

Fetch Google Pay session

Retrieve details for an existing Google Pay session. This endpoint must be used to obtain the status for a session.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

Responses

Response samples

Content type
application/json
{
  • "id": "11111111-1111-1111-1111-111111111111",
  • "reference": "20240612104501",
  • "amount": 1200,
  • "currency": "EUR",
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2025-06-24T12:48:21Z",
  • "language": "nl",
  • "status": "OPEN",
  • "action": {
    },
  • "createdAt": "2025-06-23T12:48:24Z",
  • "returnUrl": "https://tradename.tld/shop/return/?purchase=PO1234567"
}

Authorize Google Pay transaction

Authorize a transaction for an existing Google Pay session. When the shopper selected a card, the details are returned as payment data by the Google Pay client. The paymentData.paymentMethodData must be sent here as-is.

This endpoint creates the actual transaction for the session. A TRANSACTION_CREATED webhook will be triggered if subscribed.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

Request Body schema: application/json
required

Authorize Google Pay Transaction

description
string

Google Pay payment description

object
object
type
string

Responses

Request samples

Content type
application/json
{
  • "description": "Visa •••• 1111",
  • "info": {
    },
  • "tokenizationData": {
    },
  • "type": "CARD"
}

Response samples

Content type
application/json
Example
{}

Fetch Google Pay session transactions

Retrieve all transactions for an existing Google Pay session.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

Responses

Response samples

Content type
application/json
{
  • "transactions": [
    ]
}

Fetch Google Pay session transaction

Retrieve a specific transaction for an existing Google Pay session.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Create refund for transaction

Create a refund for an existing Google Pay transaction.

The transactionId parameter can be obtained from the payment field in the webhook payload sent when the transaction was created.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required

Create Google Pay Transaction Refund

amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{
  • "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "transactionId": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "amount": 1200,
  • "reason": "Refund required by consumer.",
  • "status": "SUCCESS",
  • "created": "2006-01-02T15:04:05Z",
  • "updated": "2006-01-02T15:04:05Z",
  • "sessionId": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e082"
}

Fetch transaction refunds

Retrieve refunds for an existing Google Pay transaction of a session.

Authorizations:
oAuth2ClientCredentials
path Parameters
sessionId
required
string <uuid> (Uuid) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the initialize session response, used to reference the session in subsequent calls.

transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

BelfiusPayButton

Belfius Pay Button is a Belgian online payment method that allows customers to pay securely using their Belfius bank account.

https://www.belfius.be/

Create payment

Create a new Belfius Pay Button payment transaction. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create Belfius Pay Button Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

object (Consumer)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Fetch payment

Retrieve details for an existing Belfius Pay Button transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Create refund

Create a refund for an existing Belfius Pay Button transaction. The transactionId parameter must be the ID of the transaction to be refunded.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required

Create Belfius Pay Button Refund

amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{}

Fetch refunds

Retrieve refunds for an existing Belfius Pay Button transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

SepaDirectDebit

SEPA Direct Debit allows merchants to collect payments directly from customer bank accounts within the SEPA zone.

https://www.europeanpaymentscouncil.eu/

Create payment

Create a new SEPA Direct Debit payment transaction. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create SEPA Direct Debit Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

required
object (SepaDirectDebitConsumer)

The consumer initiating the SEPA Direct Debit payment. A shopper is registered with the payment processor using these details, so the consumer's name, email and a complete billing address are required.

required
object (SepaDirectDebitDetails)

Details needed for SEPA direct debit

Responses

Request samples

Content type
application/json
{
  • "returnUrl": "https://yourdomain.tld/order/return?orderID=order123",
  • "reference": "20210623130413",
  • "amount": 1200,
  • "currency": "EUR",
  • "language": "nl",
  • "webhooks": [],
  • "description": "Order at yourdomain.tld",
  • "expiresAt": "2006-01-02T15:04:05Z",
  • "consumer": {
    },
  • "sepaDirectDebitDetails": {
    }
}

Response samples

Content type
application/json
{}

Fetch payment

Retrieve details for an existing SEPA Direct Debit transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Create refund

Create a refund for an existing SEPA Direct Debit transaction. The transactionId parameter must be the ID of the transaction to be refunded.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required

Create SEPA Direct Debit Refund

amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{}

Fetch refunds

Retrieve refunds for an existing SEPA Direct Debit transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

BankTransfer

Bank Transfer payment method allows customers to pay by transferring funds directly from their bank account.

Create payment

Create a new Bank Transfer payment transaction. The id field in the response can be used in future calls as transactionId to reference this transaction (for instance in a refund).

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Create Bank Transfer Transaction

One of
required
object (ReturnUrls)

URLs where the Consumer is redirected to after completing the transaction at its issuing bank or at the chosen payment method.

With this object we can redirect consumer to a dedicated page per payment result status. Either this object or the returnUrl field is mandatory.

reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

amount
required
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents.

currency
string (Currency) = 3 characters

ISO 4217 currency code.

language
required
string (Language) = 2 characters

Preferred language for the user interface as ISO 639-1 code. If the provided language is not supported the default will be used. Commonly supported languages are Dutch (nl) and English (en).

Array of objects (TransactionWebhooks)

Array of webhooks that enables receiving a web request once a given event occurs. We won't do preventive rate-limiting in order to have the highest throughput possible. However, we will honor 429 (Too-many-requests) responses per callback. We use the Retry-After header to retry after a certain period. If the header was not set we use our default exponential delay implementation.

description
required
string (Description) <= 255 characters

Description of the underlying value or reason of the payment.

expiresAt
string <date-time> >= 20 characters

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED.

required
object (Consumer)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Fetch payment

Retrieve details for an existing Bank Transfer transaction. This endpoint must be used to obtain the status for a transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
Example
{}

Create refund

Create a refund for an existing Bank Transfer transaction. The transactionId parameter must be the ID of the transaction to be refunded.

The amount field is required and must be a positive value, which is the amount to be refunded.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Request Body schema: application/json
required

Create Bank Transfer Refund

amount
integer (Amount) [ 1 .. 99999999 ]

Denomination in the smallest currency subunit, as for example euro cents. If empty, the refund amount will be the remaining available amount of the transaction (i.e., total payment amount minus already refunded amounts minus the amounts of the pending refund requests).

reason
string (RefundReason) <= 255 characters

The description for the refund for administrative purpose only. This reason will be visible in the portal.

Responses

Request samples

Content type
application/json
{
  • "amount": 1200,
  • "reason": "Refund required by consumer."
}

Response samples

Content type
application/json
{}

Fetch refunds

Retrieve refunds for an existing Bank Transfer transaction.

Authorizations:
oAuth2ClientCredentials
path Parameters
transactionId
required
string <uuid> (TransactionId) = 36 characters
Example: 8db1e7fa-ba8a-4189-92fd-67a20217443d

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

Responses

Response samples

Content type
application/json
{
  • "refunds": [
    ]
}

Utils

Utility endpoints for health checks and other functionalities.

Webhook event for a transaction. Webhook

Webhook that will be called if requested in the initial create transaction request.

Implement this webhook when you want to receive a notification when a given event occurs. This will give you the advantage of not having to poll the payment method specific GET endpoint for status updates.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Transaction event

transaction
required
string <uuid> (TransactionId) = 36 characters

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

event
required
string (TransactionWebhookEvent)
Enum: "STATUS_CHANGE" "PAYMENT_CREATED" "TRANSACTION_CREATED" "REFUND_STATUS" "FINALSTATUS"
  • STATUS_CHANGE - When the status of the transaction changes to any other value.
  • PAYMENT_CREATED - When a new payment is created for the transaction.
  • TRANSACTION_CREATED - When a new transaction is created for a session (used by Google Pay and Apple Pay).
  • REFUND_STATUS - Invoke webhook when a transaction receives an update on one of its requested refunds.
  • FINALSTATUS - This value is deprecated and shouldn't be used anymore. Use STATUS_CHANGE instead.
reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

createdAt
required
string <date-time> (Datetime) >= 20 characters

Time when the event occurred.

Responses

Request samples

Content type
application/json
{
  • "transaction": "72149cbf-d4a1-4309-9872-6ec19fa782cc",
  • "event": "STATUS_CHANGE",
  • "reference": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e081",
  • "createdAt": "2006-01-02T15:04:05Z"
}

Webhook event for a transaction for an iDEAL-QR payment. Webhook

Webhook that will be called if requested in the initial create transaction request.

Implement this webhook when you want to receive a notification when a given event occurs. This will give you the advantage of not having to poll the payment method specific GET endpoint for status updates.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Transaction event

transaction
required
string <uuid> (TransactionId) = 36 characters

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

event
required
string
Enum: "STATUS_CHANGE" "QR_PAYMENT_CREATED" "REFUND_STATUS" "PAYMENT_CREATED" "TRANSACTION_CREATED" "FINALSTATUS"
  • STATUS_CHANGE - When the status of the transaction changes to any other value.
  • PAYMENT_CREATED - When a new payment is created for the transaction.
  • TRANSACTION_CREATED - When a new transaction is created for a session (used by Google Pay and Apple Pay).
  • REFUND_STATUS - Invoke webhook when a transaction receives an update on one of its requested refunds.
  • FINALSTATUS - This value is deprecated and shouldn't be used anymore. Use STATUS_CHANGE instead.
reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

createdAt
required
string <date-time> (Datetime) >= 20 characters

Time when the event occurred.

payment
string <uuid> (Uuid) = 36 characters

Unique identifier for an iDEAL-QR payment.

Responses

Request samples

Content type
application/json
{
  • "transaction": "72149cbf-d4a1-4309-9872-6ec19fa782cc",
  • "event": "QR_PAYMENT_CREATED",
  • "reference": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e081",
  • "createdAt": "2006-01-02T15:04:05Z",
  • "payment": "193cb243-283a-4760-9c56-8a6444d588b2"
}

Webhook event for a BanContact payment. Webhook

Webhook that will be called if requested in the initial create transaction request.

Implement this webhook when you want to receive a notification when a new payment is created for a BanContact order. This will give you the advantage of not having to poll the payment method specific GET endpoint for status updates.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Transaction event

transaction
required
string <uuid> (TransactionId) = 36 characters

ID received in the POST transaction response root object, which can be used in up following calls like refunds or cancellations as transactionId.

event
required
string
Enum: "STATUS_CHANGE" "PAYMENT_CREATED" "REFUND_STATUS" "FINALSTATUS" "TRANSACTION_CREATED"
  • STATUS_CHANGE - When the status of the transaction changes to any other value.
  • PAYMENT_CREATED - When a new payment is created for the transaction.
  • TRANSACTION_CREATED - When a new transaction is created for a session (used by Google Pay and Apple Pay).
  • REFUND_STATUS - Invoke webhook when a transaction receives an update on one of its requested refunds.
  • FINALSTATUS - This value is deprecated and shouldn't be used anymore. Use STATUS_CHANGE instead.
reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

createdAt
required
string <date-time> (Datetime) >= 20 characters

Time when the event occurred.

payment
string <uuid> (Uuid) = 36 characters

Unique identifier for a BanContact payment.

Responses

Request samples

Content type
application/json
{
  • "transaction": "72149cbf-d4a1-4309-9872-6ec19fa782cc",
  • "event": "PAYMENT_CREATED",
  • "reference": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e081",
  • "createdAt": "2006-01-02T15:04:05Z",
  • "payment": "193cb243-283a-4760-9c56-8a6444d588b2"
}

Webhook event for a session-based payment (Google Pay, Apple Pay). Webhook

Webhook that will be called if requested in the initial create session request.

Implement this webhook when you want to receive a notification when a given event occurs on a session-based payment flow. Unlike the standard transaction event, this payload uses a sessionID to identify the session and a transactionID to identify the individual transaction within it.

Authorizations:
oAuth2ClientCredentials
Request Body schema: application/json
required

Session event

sessionID
required
string <uuid> = 36 characters

Unique identifier for the session. Present for TRANSACTION_CREATED, STATUS_CHANGE, and PAYMENT_CREATED events.

event
required
string (TransactionWebhookEvent)
Enum: "STATUS_CHANGE" "PAYMENT_CREATED" "TRANSACTION_CREATED" "REFUND_STATUS" "FINALSTATUS"
  • STATUS_CHANGE - When the status of the transaction changes to any other value.
  • PAYMENT_CREATED - When a new payment is created for the transaction.
  • TRANSACTION_CREATED - When a new transaction is created for a session (used by Google Pay and Apple Pay).
  • REFUND_STATUS - Invoke webhook when a transaction receives an update on one of its requested refunds.
  • FINALSTATUS - This value is deprecated and shouldn't be used anymore. Use STATUS_CHANGE instead.
reference
required
string (Reference) [ 1 .. 255 ] characters

The clients identifier. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.

createdAt
required
string <date-time> (Datetime) >= 20 characters

Time when the event occurred.

transactionID
string <uuid> = 36 characters

Unique identifier for the payment transaction within the session. Present for TRANSACTION_CREATED, STATUS_CHANGE, and PAYMENT_CREATED events.

Responses

Request samples

Content type
application/json
Example
{
  • "sessionID": "72149cbf-d4a1-4309-9872-6ec19fa782cc",
  • "transactionID": "193cb243-283a-4760-9c56-8a6444d588b2",
  • "event": "TRANSACTION_CREATED",
  • "reference": "bcbb3733-4d3e-4a4d-9254-1ddb90e6e081",
  • "createdAt": "2006-01-02T15:04:05Z"
}

Check API health status

Health check status endpoint to check the API's operational status.

Responses

Response samples

Content type
application/json
{
  • "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d",
  • "message": "no authorization methods provided"
}

Get Client-Side Encryption library

This endpoint is for documentation purposes. When you call this endpoint the response contains an URL specific to your account. This url can be used to access the Client-Side Encryption library. This is a JavaScript library made to be used in the front-end. The library must be used to encrypt the Card Details of your consumer in their browser.The library MUST NOT be cached since the encryption keys are rotated automatically.

Authorizations:
oAuth2ClientCredentials

Responses

Response samples

Content type
application/json
{}