6. Backend Status Calls (optional)

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

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

📘
Use Authentication!
Note: it is important to use authentication with this Order.Status API; otherwise, you will only receive the basic transaction details and miss out on some important instore data.

6.3 Request

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

curl --request GET \
     --url https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b1/status \
     --header 'accept: application/json' \
     --header 'authorization: Basic dG9rZW46OGQyZDNkNzJmODhhYjZlOGZlMjZmZjYyNjgzNThiZGJiMQ=='

In this example, the status of order 67f531c2-5114-8d75-136c-2265038314b1 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 transaction:

6.4 Response

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

{
  "id": "67f531c2-5114-8d75-136c-2265038314b1",
  "type": "sale",
  "serviceId": "SL-1234-5678",
  "description": null,
  "reference": "REF1234",
  "manualTransferCode": "9000 0510 0785 6048",
  "orderId": "51007856048X14b0",
  "uuid": "ae8c2265-0383-14b0-5100-7856048a14b0",
  "customerKey": null,
  "status": {
    "code": 100,
    "action": "PAID"
  },
  "receipt": "WyIgQ3VzdG9tZXIncyByZWNlaXB0IiwiICIsIiAgSmFzcGVyJ3MgQmVkcmlqZiAgIiwiI=",
  "integration": {
    "pointOfInteraction": "IN_PERSON",
    "test": false
  },
  "amount": {
    "value": 150,
    "currency": "EUR"
  },
  "checkoutData": null,
  "payments": [
    {
      "id": "67f531c2-5114-8389-203a-051007856049",
      "paymentMethod": {
        "id": 1927,
        "input": {
          "terminalCode": "TH-1234-5678",
          "terminalPin": null
        }
      },
      "customerType": null,
      "customerKey": "a6d9da63e3d54bf3f2f6dcd081ee0974",
      "customerId": "679107xxxxxxxxx2449",
      "customerName": null,
      "ipAddress": null,
      "secureStatus": false,
      "paymentVerificationMethod": 17,
      "status": {
        "code": 100,
        "action": "PAID"
      },
      "currencyAmount": {
        "value": 150,
        "currency": "EUR"
      },
      "amount": {
        "value": 150,
        "currency": "EUR"
      },
      "supplierData": {
        "incident_code": "0000",
        "incident_text": "AKKOORD",
        "authorization_code": "F01914",
        "signature": false,
        "ticket_data": {
          "shop_logo": "",
          "shop_location": "",
          "terminal": "8XDN6L",
          "merchant": "618088",
          "period": "5164",
          "transaction": "02002204",
          "card_brand_label_name": "Maestro",
          "application_identifier": "A0000000043060",
          "issuer_label_name": "MAESTRO",
          "formatted_card_number": "679107xxxxxxxxx2449",
          "card_number": "679107xxxxxxxxx2449",
          "card_sequence_number": "00",
          "valid_thru": null,
          "cardholder_name_extended": "",
          "cardholder_name": null,
          "service_identifier": "BETALING (Contactloze betaling)",
          "date_time": "13/06/2025 10:18",
          "authorization_code": "F01914",
          "merchant_reference": "9000 0510 0785 6048",
          "acquirer_zone": "",
          "transaction_amount": 150,
          "transaction_currency": "EUR",
          "dcc_exchange_rate_information": "",
          "dcc_billing_amount": null,
          "cardholder_billing_currency_name": "",
          "dcc_label_1": "",
          "dcc_value_1": "",
          "dcc_label_2": "",
          "dcc_value_2": "",
          "reading_mode_text": "",
          "pin_status_text": "",
          "signature_label_text": "",
          "legal_id": "",
          "dcc_disclaimer": "",
          "ticket_footer_line_1": "",
          "ticket_footer_line_2": ""
        }
      }
    }
  ],
  "createdAt": "2025-04-08T16:25:06+02:00",
  "createdBy": "AT-1234-5678",
  "modifiedAt": "2025-04-08T16:25:06+02:00",
  "modifiedBy": null,
  "expiresAt": "2025-05-06T16:25:06+02:00",
  "completedAt": null,
  "links": {
    "status": "https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b1/status",
    "abort": "https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b1/abort",
    "approve": "https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b1/approve",
    "decline": "https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b1/decline",
    "void": "https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b1/void",
    "capture": "https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b1/capture",
    "checkout": "https://checkout.pay.nl/to/payment/67f531c2-5114-8389-203a-051007856049",
    "redirect": "https://checkout.pay.nl/to/payment/67f531c2-5114-8389-203a-051007856049"
  }
}

The response is the same as when starting the POS transaction. Once the final status is known, the response is supplemented with the payment.supplierData object. This object contains the following relevant POS data.

Variable	Description
`payment.supplierData.incident_code`	Contains the incident code if the transaction has a final status where the card transaction was not successfully completed.
`payment.supplierData.incident_text`	Contains the incident text if the transaction has a final status where the card transaction was not successfully completed.
`payment.supplierData.authorization._code`	The authorization code from the transaction processor.
`payment.supplierData.signature`	0: No signature required for the receipt. 1: Signature required from the enduser for the receipt.

6.5 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. The following values are possible:

Incident code	Incident text	Description
`1803`	TIMEOUT_EXPIRATION	The transaction was not completed within the maximum number of seconds.
`2629`	USER_CANCELLATION	The enduser canceled the transaction on the terminal.
`2630`	DEVICE_CANCELLATION	An error occurred in the terminal causing the transaction to be aborted
`2631`	HOST CANCELLATION	The host declined the transaction
`4100`	NO_PURSE_IN_READER_AND_TIMEOUT_E	A timeout occurred
`1822`	CONNECTION_FAILURE	A connection issue occurred
`1811`	TECHNICAL_PROBLEM	A technical issue occurred
`4101`	TIMEOUT_ON_FALLBACK_CARD_READING	A timeout occurred.
`1802`	UNEXPECTED_MESSAGE	An unexpected error occurred
`1000`	UNSUPPORTED_MESSAGE	An undefined error occurred