> For the complete documentation index, see [llms.txt](https://docs.payrexx.com/developer/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payrexx.com/developer/ecr-information/endpoints.md).

# Reference

A list of endpoints and their compatibility with our POS-Terminals

{% hint style="warning" %}
Consult the [Merchant API](https://developers.payrexx.com/reference/rest-api#/) for more information.
{% endhint %}

Every endpoint requires your Payrexx instance name as the `instance` query parameter. This page describes API version 1.19.

| Endpoint                                                                                            | NexGo | Newland | Description                                                                                           |
| --------------------------------------------------------------------------------------------------- | ----- | ------- | ----------------------------------------------------------------------------------------------------- |
| **PAIRING**                                                                                         |       |         |                                                                                                       |
| [pair `GET`](https://developers.payrexx.com/reference/get-terminal-pairing#/)                       | ✅     | ✅       | Gets the pairing status for a specific terminal by serial number                                      |
| [pair `POST`](https://developers.payrexx.com/reference/pair-terminal#/)                             | ✅     | ✅ ¹     | Pairs the terminal to the serialnumber for further processing                                         |
| [pair `DELETE`](https://developers.payrexx.com/reference/unpair-terminal#/)                         | ✅     | ✅       | Frees the Terminal from the API pairing                                                               |
| **PAYMENT**                                                                                         |       |         |                                                                                                       |
| [payment `GET`](https://developers.payrexx.com/reference/get-terminal-payment#/)                    | ✅     | ✅       | retrieves a POS-Terminal payment by id                                                                |
| [payment `POST`](https://developers.payrexx.com/reference/initiate-terminal-payment#/)              | ✅     | ✅ ²     | Sends a Payment request to the POS-Terminal                                                           |
| [payment/cancel `POST`](https://developers.payrexx.com/reference/cancel-terminal-payment#/)         | ✅     | ✅ ³     | Cancels a POS-Terminal payment by id until the terminal has picked it up                              |
| [payment/void `POST`](https://developers.payrexx.com/reference/void-terminal-payment#/)             | ✅     | ✅ ⁴     | Voids a past POS-Terminal payment by id, in full                                                      |
| [payment/refund `POST`](https://developers.payrexx.com/reference/refund-terminal-payment#/)         | ✅ ⁵   | ⚠️ ⁶    | Refunds a POS-Terminal payment by id, in full or in part                                              |
| [payment/credit `POST`](https://developers.payrexx.com/reference/initiate-independent-credit#/)     | ✅ ⁷   | ❌ ⁸     | Credits a card with no original payment (independent credit)                                          |
| **ADDITIONAL**                                                                                      |       |         |                                                                                                       |
| [config `GET`](https://developers.payrexx.com/reference/get-terminal-config#/)                      | ✅     | ✅       | Retrieves the terminal configuration incl. accepted payment methods (supersedes `paymentMethods GET`) |
| [paymentMethods `GET`](https://developers.payrexx.com/reference/get-pament-methods-from-terminal#/) | ⚠️ ⁹  | ⚠️ ⁹    | retrieves payment options on the POS-Terminal (deprecated; use `config GET`)                          |

¹ No OTP: `pairingCode` and `cashierName` are optional and ignored. Newland terminals authorize automatically with the merchant's stored credentials. NexGo terminals require the `pairingCode`.

² TWINT is coming soon on Newland terminals: until it is available, `paymentMethod: "twint"` returns `400`, and a payment without `paymentMethod` runs as a card payment. Up to API version 1.18, `paymentMethod` is ignored on Newland terminals. An offline or busy Newland terminal may never pick the payment up: a payment not picked up within the hand-off window (at most 7 seconds) is cancelled and ends as `TERMINATED`.

³ While the payment is still `IN_PROGRESS`, Newland terminals answer `202` (cancel accepted but not completed yet); NexGo terminals answer `200` in the same case.

⁴ Newland terminals refuse a reversal while they are still completing the payment (e.g. printing its receipt), which ends as `reversalStatus: FAILED`. Wait a few seconds after `SUCCESS` and send the void again.

⁵ Full and partial refunds on NexGo terminals running the Pay-Connect app.

⁶ Full refunds only: routed through the same reversal as `void`. A partial `amount` returns `501` (up to API version 1.17: `200` with the error in the body).

⁷ API version 1.19 and later (earlier versions return `404`). Not idempotent, CHF only, at most CHF 50.00 per credit unless a different limit is set for your account, and it must be enabled for your account. See [Independent credit](#independent-credit).

⁸ Returns `501`.

⁹ Deprecated in favour of `config GET`. On API version 1.17 it returns the old per-provider format (always an empty list on Newland terminals); NexGo terminals running the Pay-Connect app answer `421`.

## Payment response

`payment GET`, `payment POST`, `payment/cancel`, `payment/void` and `payment/refund` return the same payment object. `payment/credit` returns the same body without the reversal fields. The most important fields:

| Field                                       | Values and notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                                    | `PAYMENT_REQUESTED`, `IN_PROGRESS`, `SUCCESS`, `DECLINED`, `UNDERPAID`, `TERMINATED`, `REVERTED`, `EXPIRED`, `FAILED`, `UNKNOWN`. `PAYMENT_REQUESTED`: the payment was sent, but the terminal has not picked it up yet (NexGo terminals report this as `IN_PROGRESS` up to API version 1.18). On NexGo terminals, if a payment stays `PAYMENT_REQUESTED` for a few seconds, cancel it and start a new payment only once the original one has a final status other than `SUCCESS`. |
| `type`                                      | `CHARGE` for a payment, `REFUND` once a void has reversed the payment (on Newland terminals also after a refund, which runs as a void; its `status` is then `REVERTED`), `CREDIT` for an independent credit. On NexGo terminals a refund, full or partial, is a transaction of its own: the payment keeps `CHARGE` and `status: SUCCESS`.                                                                                                                                         |
| `reversalStatus`                            | Present only once a void or refund has been initiated: `IN_PROGRESS`, `REVERTED`, `FAILED`, `UNKNOWN`. `FAILED` means the terminal refused the reversal; the payment is unchanged and the void or refund can be sent again.                                                                                                                                                                                                                                                       |
| `reversalSlip`                              | Receipt of the void or refund. Present like `reversalStatus`, and `null` until the receipt exists (NexGo: once `reversalStatus` is `REVERTED`). On NexGo a refund gets its own receipt, including the refunded amount in `reversalSlip.information.amount`.                                                                                                                                                                                                                       |
| `paymentMethod`                             | Payment method as reported by the terminal, e.g. `CARD`. `null` while the terminal has not reported it; NexGo terminals do not report it for card payments, use `cardBrand`.                                                                                                                                                                                                                                                                                                      |
| `cardBrand`, `cardLast4`, `cardEntryMethod` | `null` until the card has been read. `cardEntryMethod` is one of `CONTACTLESS`, `CHIP`, `SWIPE`, `MANUAL`.                                                                                                                                                                                                                                                                                                                                                                        |
| `authorizationCode`                         | Approval code of the acquirer, `null` until the payment has been approved.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `printSlip`                                 | The `printSlip` value used for the payment, `null` if none applies (e.g. refunds and credits on NexGo terminals). NexGo terminals print according to their own settings and ignore `printSlip`; the response then has a `warnings` entry.                                                                                                                                                                                                                                         |
| `payrexxTransactionId`                      | ID of the Payrexx transaction the payment is booked as. `null` until the payment has been booked, which can take a few seconds after `SUCCESS`.                                                                                                                                                                                                                                                                                                                                   |
| `warnings`                                  | Human-readable notices about request fields the terminal could not apply, e.g. `currency` (the terminal always uses its own configured currency) or `printSlip`. Empty when everything was applied. Meant for logging; do not parse the text.                                                                                                                                                                                                                                     |

## Independent credit

`payment/credit POST` credits a customer's card with no original payment, e.g. a goodwill credit at the till. It is available on NexGo terminals from API version 1.19.

* **Not idempotent.** Every call starts a new credit, also with a `referenceId` you have already used; `referenceId` is optional and only your own reference. After a timeout or a lost response, check the last credit with `payment GET` before you retry. Error responses carry the ID of your last payment or credit on the terminal as `lastPaymentId`.
* **Limits.** CHF only, at most CHF 50.00 per credit unless a different limit is set for your account, and the credit must be enabled for your account. A refused credit answers with a machine-readable `reason`, e.g. `max_amount_exceeded` (`422`).
* **Cancel and reversal.** A credit can be cancelled only until the terminal has picked it up. It cannot be voided or refunded (`400`).

## Errors

From API version 1.19, every error response of these endpoints also contains `lastPaymentId` once the request is authenticated: the ID of the last payment or credit you started on this terminal. Use it with `payment GET` to find out what happened after a failed call.

| HTTP  | When                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Invalid request, e.g. `pair POST` without `pairingCode` on a NexGo terminal, a refund larger than the payment's total, or a void or refund of an independent credit.                                                                                                                                                                                                                                                                                                                                                                           |
| `403` | `Terminal is not paired`: `payment GET`, `payment POST`, `payment/cancel`, `payment/void`, `payment/refund`, `payment/credit` and `config GET` on a terminal that is not paired. `payment/credit` also answers `403` with a `reason` if credits are not enabled for your account. `Terminal cannot take payments: …` on `payment POST` and `payment/credit`, followed by the reason: the merchant account is deactivated or blocked, payments are disabled for the merchant, the store is not approved or on hold, or the terminal is blocked. |
| `404` | `Terminal not found` for an unknown serial number. An unknown `paymentId` on `payment GET`, `payment/cancel`, `payment/void` and `payment/refund`.                                                                                                                                                                                                                                                                                                                                                                                             |
| `409` | `pair POST` on a terminal that is already paired or busy, or that is not active. `payment/credit` if your account has no payment account for the currency (`reason: account_not_found`).                                                                                                                                                                                                                                                                                                                                                       |
| `422` | `payment/credit` refused, e.g. above the per-credit limit, CHF 50.00 unless a different limit is set for your account (`reason: max_amount_exceeded`) or above the amount still creditable (`reason: insufficient_balance`).                                                                                                                                                                                                                                                                                                                   |
| `501` | A partial refund on a Newland terminal, or `payment/credit` on a Newland terminal.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
