Create checkout

post

https://example.com/api/v1/paymentmethods/checkout/v1/transactions

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).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Create checkout

returnUrls

object

required

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

string

required

length between 1 and 255

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

integer

required

1 to 99999999

Denomination in the smallest currency subunit, as for example eurocents.
Ignored (although required) for requests that include items (e.g. Klarna). In this cases the total amount is calculated internally using item prices.

currency

string

length between 3 and 3

Defaults to EUR

ISO 4217 currency code.

language

string

required

length between 2 and 2

Defaults to nl

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).

webhooks

array of objects

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.

webhooks

description

string

required

length ≤ 35

Description of the underlying value or reason of the payment.

expiresAt

date-time

length ≥ 20

ISO 8601 date and time. If a transaction is not finalized before this time the status becomes EXPIRED. If left empty, the value defaults to 30 mins.

merchantOrderReference

string

required

length ≤ 35

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

consumer

object

maxRetries

integer

0 to 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

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

paymentMethods

orderItems

array of objects

length between 1 and 512

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

orderItems

Item object that can be used to provide details of the items in the order.
This is only used by payment methods that support it, like Klarna and Riverty.

code

string

required

length between 1 and 50

Merchant Product identification. Each item code must be unique per transaction.

description

string

length ≤ 100

A human readable description of the item.

unitPrice

integer

required

1 to 99999999

Unit price (including VAT) of the item, specified in the smallest currency subunit, as for example euro cents.

quantity

integer

required

1 to 1000000000

The number of items of this type.

vatAmount

integer

required

1 to 99999999

Total VAT amount of the orderline, specified in the smallest currency subunit as for example euro cents.

vatRate

number

required

0 to 99.9

Percentage of VAT applied.
Only the first decimal value will be taken into account, the rest will be ignored.

name

string

length ≤ 50

A human readable name of the item.

type

string

enum

The type of order line item. Used by Klarna to classify the order line.

201The iDEAL transaction was created successfully. The response contains the transaction details and a redirect URL to complete the payment.

4XXThe user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized)

5XXInternal server error. This can be caused by an unresponsive backend