2. Verify the status

2.1 API reference

The Order.Status API reference, including the option to execute real-time requests, can be found at: https://developer.pay.nl/reference/api_get_status-1

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

📘

Authentication or no authentication?

You can call this API without authentication. In that case, you will receive only the basic payment details, such as the status and the payment methods used. If you also wish to receive customer data (e.g IBAN or hashed creditcard number), you need to use authentication.

2.3 Request

A request via the Order:Status API looks something like this:

curl --request GET \
     --url https://connect.pay.nl/v1/orders/68e678e2-4744-8f8d-1d4d-2265038344e6/status \
     --header 'accept: application/json' \
     --header 'authorization: Basic dG9rZW46ZWQ2Nzg3OTQyOWM0ODkwYTM5ZGUxYjY4YTNlYmViOGUxY2JkOGEzZA=='

In this example, the status of paylink order 68e678e2-4744-8f8d-1d4d-2265038344e6 is being requested. The Order ID is sent as a PATH parameter. The API URL being called is the same as the one you receive through the links.status variable when initiating a paylink:

2.4 Response

A response via the Order:Status API looks something like this:

{
  "id": "68e678e2-4744-8f8d-1d4d-2265038344e6",
  "type": "paylink",
  "serviceId": "SL-2265-0383",
  "description": "Paylink order",
  "reference": "REF1234",
  "orderId": "47601470092X44e6",
  "customerKey": "1fe2a644d006b4b18ac515be2209490b",
  "status": {
    "code": 100,
    "action": "PAID"
  },
  "receipt": null,
  "integration": {
    "pointOfInteraction": null,
    "test": false
  },
  "amount": {
    "value": 150,
    "currency": "EUR"
  },
  "payments": [
    {
      "id": "68e679c4-4744-8136-21e5-047601470092",
      "paymentMethod": {
        "id": 436,
        "input": []
      },
      "customerKey": null,
      "customerId": null,
      "customerName": null,
      "customerMethod": null,
      "ipAddress": "100.101.102.103",
      "status": {
        "code": -90,
        "action": "CANCEL"
      },
      "amount": {
        "value": 150,
        "currency": "EUR"
      }
    },
    {
      "id": "68e67c08-4744-858c-2f70-047601470092",
      "paymentMethod": {
        "id": 10,
        "input": []
      },
      "customerKey": "1fe2a644d006b4b18ac515be2209490b",
      "customerId": "NL23REVO1264023850",
      "customerName": "John Doe",
      "customerMethod": {
        "type": "iban",
        "data": {
          "iban": "NL23REVO1264023850",
          "name": "John Doe",
          "bic": "REVONL22"
        }
      },
      "ipAddress": "100.101.102.103",
      "status": {
        "code": 100,
        "action": "PAID"
      },
      "amount": {
        "value": 150,
        "currency": "EUR"
      }
    }
  ],
  "createdAt": "2025-10-08T14:44:50+00:00",
  "expiresAt": "2025-10-20T18:30:00+00:00",
  "completedAt": "2025-10-08T15:03:04+00:00",
  "links": {
    "status": "https://connect.pay.nl/v1/orders/68e678e2-4744-8f8d-1d4d-2265038344e6/status",
    "checkout": "https://checkout.pay.nl/to/return/68e678e2-4744-8f8d-1d4d-2265038344e6",
    "redirect": "https://checkout.pay.nl/to/return/68e678e2-4744-8f8d-1d4d-2265038344e6"
  }
}

The response is the same as when initiating the paylink transaction.

2.5 Exchange calls

When initiating the paylink, a variable called exchangeUrl is provided. This exchange URL (also known as IPN or webhook) is called every time the status of a paylink changes — for example, from PENDING (20) to PAID (100).

The body of the exchange call contains an object variable with the same data as the response from the Order.Status API.

We recommend however always performing an additional check within the exchange call to verify the payment status through the Order.Status API, unless you are using exchange signing. In that case, you can be certain that the request originates from our platform, and no additional status verification is required.

When the exchange call is triggered, you must return a valid response. This confirms that the exchange call has been successfully processed on your end. If a valid response is not received, a retry call will be performed, provided that retries have been configured for the sales location in our Admin Panel.

You can find more information about configuring and handling exchange calls here.

❗️

Polling instead of exchange calls?

We do not recommend using polling, where your system repeatedly requests the status of a Paylink from our platform. Using exchange calls ensures that you only call the Order.Status API when an actual status change occurs. This approach significantly reduces API traffic and improves efficiency.

2.6 Statuses

To determine whether the paylink has been successfully completed, you need to check the status variable. If status.code equals 100, you can be certain that the paylink has been successfully paid.

{
  "status": {
    "code": 100,
    "action": "PAID"
  }
}

The possible statuses of a paylink are: