1. Create an order
To initiate a transaction, you need to use the Order:Create API.
Be sure to check out the API recipe for a simple, step-by-step code example that walks you through the process and helps you get started with this API quickly.
1.1 API Reference
The Order.Create API reference, including the option to execute real-time requests, can be found at:: https://developer.pay.nl/reference/api_create_order-1
1.2 Authentication
Authentication occurs via Basic Authentication using:
- Token code (AT-…) as the username and API token (hash of 40 characters) as the password or
- Service ID (SL-…) as the username and the secret as the password.
You can find the Token code and the API token under the "Merchant" -> "Company information" tab in the PAY. Admin Panel.
You can find the Service ID and the secret under the tab "Settings" -> "Sales locations" in the PAY. Admin Panel. The Service ID is the unique reference of the sales location and starts with SL-… You can find the corresponding secret by clicking on the data icon of the relevant sales location. The secret, a 40- character hash, is displayed at the top of the popup.
1.3 Request
A request via the Order:Create API looks something like this:
curl --request POST \
--url https://connect.pay.nl/v1/orders \
--header 'accept: application/json' \
--header 'authorization: Basic dG9rZW46ZWQ2Nzg3OTQyOWM0ODkwYT*******A==' \
--header 'content-type: application/json' \
--data '
{
"amount": {
"value": 150,
"currency": "EUR"
},
"paymentMethod": {
"id": 10
},
"serviceId": "SL-4882-5753",
"description": "iDEAL order",
"reference": "REF1234",
"expire": "2025-02-20T20:30:00",
"exchangeUrl": "https://demo.pay.nl/start/exchange.php"
}In this example, a 1,50 EUR iDeal transaction is initiated via sales location SL-1234-5678. You should use 10 as the paymentMethod.id. A complete list of our PaymethodsID can be found here.
Using the expire variable (must be in ATOM/ISO-8601 format), you can specify the date the order remains valid. After this date, a message will appear indicating that the paylink has expired. If no expire value is provided, a default validity period of one week will be applied.
1.4 Response
A response via the Order:Create API looks something like this:
{
"id": "6a0f241d-5223-8ebf-1c47-4882575323cd",
"type": "sale",
"serviceId": "SL-4882-5753",
"description": null,
"reference": null,
"manualTransferCode": "9000 0525 2704 7046",
"orderId": "52527047046X23cd",
"uuid": "a7d74882-5753-23cd-5252-7047046a23cd",
"customerKey": null,
"status": {
"code": 20,
"action": "PENDING"
},
"receipt": null,
"integration": {
"pointOfInteraction": null,
"test": false
},
"splitPayments": [],
"stats": {
"extra1": null,
"extra2": null,
"extra3": null,
"tool": null,
"info": null,
"object": null,
"promotorId": null,
"domainId": null
},
"transferData": {},
"amount": {
"value": 1,
"currency": "EUR"
},
"authorizedAmount": {
"value": 0,
"currency": "EUR"
},
"capturedAmount": {
"value": 0,
"currency": "EUR"
},
"checkoutData": null,
"payments": [
{
"id": "6a0f241d-5223-8c64-28c1-052527047046",
"paymentMethod": {
"id": 10,
"input": []
},
"billingLineId": null,
"customerType": null,
"customerKey": null,
"customerId": null,
"customerName": null,
"customerMethod": null,
"ipAddress": null,
"secureStatus": false,
"paymentVerificationMethod": 0,
"status": {
"code": 20,
"action": "PENDING"
},
"currencyAmount": {
"value": 1,
"currency": "EUR"
},
"amount": {
"value": 1,
"currency": "EUR"
},
"authorizedAmount": {
"value": 0,
"currency": "EUR"
},
"capturedAmount": {
"value": 0,
"currency": "EUR"
},
"supplierData": null,
"recurring": false
}
],
"createdAt": "2026-05-21T17:26:21+02:00",
"createdBy": "AT-0111-7701",
"modifiedAt": "2026-05-21T17:26:21+02:00",
"modifiedBy": null,
"expiresAt": "2026-06-18T17:26:21+02:00",
"completedAt": null,
"links": {
"status": "https://connect.payments.nl/v1/orders/6a0f241d-5223-8ebf-1c47-4882575323cd/status",
"abort": "https://connect.payments.nl/v1/orders/6a0f241d-5223-8ebf-1c47-4882575323cd/abort",
"approve": "https://connect.payments.nl/v1/orders/6a0f241d-5223-8ebf-1c47-4882575323cd/approve",
"decline": "https://connect.payments.nl/v1/orders/6a0f241d-5223-8ebf-1c47-4882575323cd/decline",
"void": "https://connect.payments.nl/v1/orders/6a0f241d-5223-8ebf-1c47-4882575323cd/void",
"capture": "https://connect.payments.nl/v1/orders/6a0f241d-5223-8ebf-1c47-4882575323cd/capture",
"captureAmount": "https://connect.payments.nl/v1/orders/6a0f241d-5223-8ebf-1c47-4882575323cd/capture/amount",
"captureProducts": "https://connect.payments.nl/v1/orders/6a0f241d-5223-8ebf-1c47-4882575323cd/capture/products",
"debug": "https://checkout.pay.nl/to/checkout/6a0f241d-5223-8ebf-1c47-4882575323cd/with/debugging/6a0f241d52238ebf1c474882575323cd",
"checkout": "https://checkout.pay.nl/to/payment/6a0f241d-5223-8c64-28c1-052527047046",
"redirect": "https://checkout.pay.nl/to/payment/6a0f241d-5223-8c64-28c1-052527047046"
}
}The response from the Order.Create API contains a large number of variables. The most important ones are listed below:
| Variable | Description |
|---|---|
id | The unique reference of the entire order |
description | The text that is displayed on the payment screen and on the customer’s bank statement. Maximum of 32 characters |
reference | A unique reference to the merchant's internal order ID. |
status | The status of the paylink |
amount.value | The amount for which the paylink was initiated. |
payments | Contains an object for each payment attempt. Each object includes details such as the selected payment method, the amount, and the payment status. If the paylink has just been created and no payment attempt has been made yet, this variable will be empty. |
expiresAt | The validity period of the paylink. After this date the paylink will expire. |
links.status | Endpoint to verify the status of a paylink transaction. |
links.redirect | URL where the customer should be redirected to complete the payment |
A comprehensive list of available payment options and their corresponding identifiers is available here: Payment Option ID's / SubID's