4. Poll status from the POS device

4.1 API reference

The link.status URL, including the option to execute real-time requests, can be found in the response body of a Order:create at: https://developer.pay.nl/reference/api_create_order-1

4.2 Authentication

Authentication is not needed to retrieve the payment status of a POS transaction.
Sensitive information will be stripped out from the response.

📘
Status with complete payload?
Please use the order:status call with authentication for the full response with supplier information.
This API call is not intented for polling
Retrieve supplier data

4.3 Request

A request via the link.status URL looks something like this:

fetch("https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b1/status")

In this example, the status of order 67f531c2-5114-8d75-136c-2265038314b1 is being requested. The API URL being called is the one you receive through the order:create response when initiating a transaction:

4.4 Response

A response via the link.status URL looks something like this:

{
  "id": "69d8a134-4411-8cac-1b2b-491247531167",
  "type": "sale",
  "serviceId": "SL-4912-4753",
  "description": null,
  "reference": null,
  "manualTransferCode": "7000 0441 1753 7094",
  "orderId": "44117537094X1167",
  "uuid": "a9ab4912-4753-1167-4411-7537094a1167",
  "customerKey": "********************************",
  "status": {
    "code": 100,
    "action": "PAID"
  },
  "receipt": "WyIgS29waWUgS2FhcnRob3VkZXIiLCIgIiwiICBKYXNwZXIncyBCZWRyaWpmICAiLCIgICAgICAgICAgICAgICAgRW5zY2hlZGUgICAgICAgICAgICAgICAgIiwiTWVyY2hhbnQgUmVmLjogNzAwMCAwNDQxIDE3NTMgNzA5NCAgICAgICIsIiAiLCJUZXJtaW5hbDogOFhETjZMICAgIE1lcmNoYW50OiA2MTgwODggICAgIiwiUGVya45514512gICA8942jdGllOiAwMTAwMjEwMCIsIkNvbnRhY3Rsb3plIGJldGFsaW5nIiwiTWFlc3RybyAoQTAwMDAwMDAwNDMwNjApIiwiQUJOIEFNUk8gQkFOSyAgICAgICAiLCJLYWFydDogNjczNDAweHh4eHh4eHh4MDM1NyIsIkthYXJ0bnI6IDAzICAgICAiLCIgIiwiQkVUQUxJTkciLCIxMC8wNC8yMDI2IDA5OjA1ICAgIEF1dGguIGNvZGU6ICAgRjkwNjIwIiwiICIsIlRvdGFhbDogICAgIDAsMDEgRVVSIiwiICIsIiAgICAgIEFLS09PUkQiXQ==",
  "integration": {
    "pointOfInteraction": "IN_PERSON",
    "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": 1,
    "currency": "EUR"
  },
  "checkoutData": null,
  "payments": [
    {
      "id": "69d8a134-4411-87b2-22d4-044117537094",
      "paymentMethod": {
        "id": 1927,
        "input": null
										 
							 
		 
      },
      "billingLineId": 1630,
      "customerType": null,
      "customerKey": "********************************",
      "customerId": "*******************",
      "customerName": null,
      "customerMethod": null,
      "ipAddress": null,
      "secureStatus": false,
      "paymentVerificationMethod": null,
      "status": {
        "code": 100,
        "action": "PAID"
      },
      "currencyAmount": {
        "value": 1,
        "currency": "EUR"
      },
      "amount": {
        "value": 1,
        "currency": "EUR"
      },
      "authorizedAmount": {
        "value": 0,
        "currency": "EUR"
      },
      "capturedAmount": {
        "value": 1,
        "currency": "EUR"
      },
      "supplierData": null,
      "recurring": false
    }
  ],
  "createdAt": "2026-04-10T07:05:24+00:00",
  "createdBy": "AT-0111-7701",
  "modifiedAt": "2026-04-10T07:05:52+00:00",
  "modifiedBy": null,
  "expiresAt": "2026-05-08T07:05:24+00:00",
  "completedAt": "2026-04-10T07:05:52+00:00",
  "links": {
    "status": "https://connect.pay.nl/v1/orders/69d8a134-4411-8cac-1b2b-491247531167/status",
    "abort": "https://connect.pay.nl/v1/orders/69d8a134-4411-8cac-1b2b-491247531167/abort",
    "approve": "*****************************************************************************",
    "decline": "*****************************************************************************",
    "void": "**************************************************************************",
    "capture": "*****************************************************************************",
    "captureAmount": "************************************************************************************",
    "captureProducts": "**************************************************************************************",
    "debug": "************************************************************************************************************************",
    "checkout": "https://checkout.pay.nl/to/return/69d8a134-4411-8cac-1b2b-491247531167",
    "redirect": "https://checkout.pay.nl/to/return/69d8a134-4411-8cac-1b2b-491247531167"
  }
}

4.5 Polling

To determine the status of the POS transaction, you will use the polling mechanism. This means you will keep calling this link.status URL as long as status.action has the value 'PENDING'.

📘
Status Retrieval from POS Environment
The order status URL should be called from the local POS (kassa) environment, and NOT from the cloud server where transactions are initiated from.
This ensures that:

Transaction initiation and status retrieval originate from different network contexts (IP addresses)

Rate limiting applied to one flow does not impact the other

Payment processing remains stable under load

When the customer completes the payment, the status.action variable will have the value 'PAID'. If the transaction fails, the status will be 'CANCEL'. You can stop polling at this point, as the final status is known.

📘
Polling Frequency
We allow a maximum of one status request per second. This should be sufficient within the POS payment process. Polling more frequently than once per second may be permitted under specific circumstances upon request.
Since the POS process is never completed instantly, we recommend performing the first status check only 3 seconds after the transaction has been initiated on the payment terminal.

We also recommend implementing the exchange call as a fallback

4.6 Unsuccessful transactions

If a POS transaction is not successfully processed, you will receive the reason why it could not be processed via the variables payment.supplierData.incident_code and payment.supplierData.incident_text. Please check Retrieve supplier data