3. Initiate a refund transaction

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

📘
Is the refund POS contract active?
If you want to offer POS refund transactions, the refund feature must be activated on the terminal. You can check whether a POS refund contact is active via the Terminal:Browse endpoint. The terminals.paymentTypes should be set to REFUND.

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

3.2 Authentication

Authentication is conducted via Basic Authentication using:

Token code (AT-….) as the username and the API token (hash of 40 characters) as the password

You can find the Token code and the API token under the "Merchant" -> "Company information" tab in the PAY. Admin Panel.

3.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 QVQtMTIzNC01Njc4OmFiYzEyMw==' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": {
    "value": 995,
    "currency": "EUR"
  },
  "paymentMethod": {
    "input": {
      "terminalCode": "TH-1234-5678"
    },
    "id": 2351
  },
  "serviceId": "SL-1234-5678",
  "reference": "REF1234",
  "exchangeUrl": "https://demo.pay.nl/exchange.php"
}
'

In this example, a 9,95 EUR POS refund transaction is initiated on terminal TH-1234-5678 via sales location SL-1234-5678. You should use 2351 as the paymentMethod.id. Then, you specify through the variable paymentMethod.input.terminalCode on which terminal (TH-….) the POS refund transaction should be initiated

3.4 Response

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

{
  "id": "67f531c2-5114-8d75-136c-2265038314b2",
  "type": "credit",
  "serviceId": "SL-1234-5678",
  "description": null,
  "reference": "REF1234",
  "manualTransferCode": "9000 0510 0785 6048",
  "orderId": "51007856048X14b2",
  "uuid": "ae8c2265-0383-14b0-5100-7856048a14b0",
  "customerKey": null,
  "status": {
    "code": 20,
    "action": "PENDING"
  },
  "receipt": null,
  "integration": {
    "pointOfInteraction": "IN_PERSON",
    "test": false
  },
  "amount": {
    "value": 995,
    "currency": "EUR"
  },
  "payments": [
    {
      "id": "67f531c2-5114-8389-203a-051007856049",
      "paymentMethod": {
        "id": 2351,
        "input": {
          "terminalCode": "TH-1234-5678",
          "terminalPin": null
        }
      },
      "customerType": null,
      "customerKey": null,
      "customerId": null,
      "customerName": null,
      "ipAddress": null,
      "secureStatus": false,
      "paymentVerificationMethod": 0,
      "status": {
        "code": 20,
        "action": "PENDING"
      },
      "currencyAmount": {
        "value": 995,
        "currency": "EUR"
      },
      "amount": {
        "value": 995,
        "currency": "EUR"
      },
      "supplierData": null
    }
  ],
  "createdAt": "2025-04-08T16:25:06+02:00",
  "modifiedAt": "2025-04-08T16:25:06+02:00",
  "expiresAt": "2025-05-06T16:25:06+02:00",
  "links": {
    "status": "https://connect.pay.nl/v1/orders/67f531c2-5114-8d75-136c-2265038314b2/status",
    "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 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
`type`	Type of transaction that has been initiated: sale: POS transaction credit**: POS refund transaction
`payments.id`	The unique reference of a payment
`serviceId`	The service ID of the sales location for which the POS refund transaction was initiated.
`reference`	A unique reference to the merchant's internal order ID.
`amount.value`	The amount for which the POS refund transaction was initiated.
`payments.paymentMethod.input.terminalCode`	The terminal (TH-...) on which the POS refund transaction was initiated.
`links.status`	Endpoint to verify the status of a POS refund transaction.
`links.redirect`	Endpoint of a graphical representation of the progress and status of a refund transaction. This can optionally be displayed on the cash register screen, tablet, etc.

3.5 Recipe

This recipe provides a quick, step-by-step guide to help you easily use the Order.Create API to execute a POS refund transaction on a terminal.