Changes for Version v.1.19

Affected endpoints

POS Cash Register (ECR):

POST https://developers.payrexx.com/reference/initiate-terminal-payment
GET https://developers.payrexx.com/reference/get-terminal-payment
POST https://developers.payrexx.com/reference/cancel-terminal-payment
POST https://developers.payrexx.com/reference/void-terminal-payment
POST https://developers.payrexx.com/reference/refund-terminal-payment
POST https://developers.payrexx.com/reference/initiate-independent-credit (new)
POST https://developers.payrexx.com/reference/pair-terminal
GET https://developers.payrexx.com/reference/get-terminal-pairing
DELETE https://developers.payrexx.com/reference/unpair-terminal
GET https://developers.payrexx.com/reference/get-terminal-config

Transaction:

GET https://developers.payrexx.com/reference/retrieve-a-transaction
GET https://developers.payrexx.com/reference/retrieve-transactions

The transaction webhook carries the new fields paymentType, payment.cardBin and payment.cardLast4 from webhook version 2026-10-26.

Summary

API version 1.19 returns the terminal receipt in one unified format for every terminal. slip and reversalSlip contain the structured receipt data (information) and print-ready receipt texts (print) in the same layout for every terminal. This change is breaking for ECR integrations that read slip or reversalSlip and switch to version 1.19.

The transaction endpoints additionally return the field paymentType, which states how a transaction was created (see Transaction: paymentType below). This change is not breaking.

Version 1.19 also adds the endpoint Initiate an independent credit, which credits a card without an original payment (see POS Cash Register: independent credit below). This is a new endpoint and changes nothing for existing integrations.

Every error response of the POS Cash Register endpoints additionally returns the field lastPaymentId, the ID of your last payment on the terminal (see POS Cash Register: lastPaymentId on errors below). This change is not breaking.

On Newland terminals, Initiate terminal payment now accepts paymentMethod; TWINT on Newland terminals is coming soon (see POS Cash Register: paymentMethod on Newland terminals below). This change is not breaking.

The payment object of the transaction endpoints additionally contains cardBin and cardLast4, the BIN and last four digits of the card the transaction was paid with, also for card readers and tap to pay transactions (see Transaction: cardBin and cardLast4 below). This change is not breaking.

Retrieve transactions accepts the new filter filterReference, which returns the transactions of a given reference or purpose (see Transaction: filterReference below). This change is not breaking.

On Newland terminals, version 1.19 also changes how Payrexx handles a payment request the terminal has not picked up yet (see POS Cash Register: a payment request is a hand-off below). Response fields and status values stay the same. This change is not breaking for integrations that poll Get terminal payment until a final status. An integration that treats PAYMENT_REQUESTED on Get terminal payment as final must keep polling.

On NexGo terminals, the ECR payment endpoints report a payment that the terminal has not accepted yet as PAYMENT_REQUESTED instead of IN_PROGRESS (see POS Cash Register: PAYMENT_REQUESTED for NexGo terminals below). This change is not breaking for integrations that already handle PAYMENT_REQUESTED, which Newland terminals return in every version. Integrations with NexGo terminals that do not handle it yet must treat it as a pending status before they switch to version 1.19.

On all endpoints, a wrong API key or API Signature is answered with 401 Unauthorized instead of 403 Forbidden (see All endpoints: 401 for a wrong API key or API Signature below). This change is breaking for integrations that check for 403 to detect a wrong API key and switch to version 1.19.


Up to version 1.18

The content of slip depends on the terminal family:

Terminal familyslipreversalSlip
NexGoObject with the provider's receipt fieldsRefunds only: object with the refund's receipt fields; not available for a void
NewlandArray of two print-ready strings: customer copy, merchant copySame as slip, for the reversal

Integrations that stay on version 1.18 or lower are not affected.

From version 1.19

slip and reversalSlip have the following shape for both terminal families:

"slip": {
    "information": { "...": "structured receipt data" },
    "print": {
        "customer": "customer copy",
        "merchant": "merchant copy"
    }
}
  • slip is null as long as no receipt exists yet (e.g. right after Initiate terminal payment).
  • reversalSlip is present once a void or refund has been initiated, for both terminal families, in the same way as reversalStatus. It is null until the reversal receipt exists; on NexGo terminals that is once the reversal has succeeded (reversalStatus: REVERTED), so it stays null while the reversal is IN_PROGRESS and if it FAILED.
  • If a receipt cannot be built, slip / reversalSlip is null. The rest of the response (status, amounts, card data, …) is always returned.

reversalSlip on NexGo terminals

  • Refund: a refund is a terminal transaction of its own, and reversalSlip is its receipt. transactionId and authorizationCode are those of the refund, not of the payment, the amounts are the refunded amount (for a partial refund not the payment's total), and revertedAt is when the refund completed. The refund is booked without the card, so cardEntryMethod and aid are null and the receipt prints no entry method.
  • Void: a void has no receipt of its own. reversalSlip repeats the payment's receipt data with the reversal status and revertedAt, without authorizationCode. This also applies to a payment that was reversed directly on the terminal. A void that the terminal provider carries out as a refund of the full amount gets that refund's receipt instead (see Refund).
  • If the receipt of a partial refund cannot be read from the terminal provider, reversalSlip is null rather than showing the payment's full amount. Retrieve the payment again later to get it.

information

Fields that the terminal does not report are null.

FieldTypeDescription
transactionIdstringTransaction ID of the terminal provider.
statusstringStatus the receipt documents. On slip the payment status (SUCCESS also if the payment was reverted later), on reversalSlip the reversal status.
merchantNamestringMerchant name.
merchantAddressstringStreet of the store. Printed on the customer copy only.
merchantPostalCodestringPostal code of the store.
merchantCitystringCity of the store.
merchantCountrystringCountry of the store, ISO 3166-1 alpha-2.
merchantRegistrationIdstringCompany registration number, e.g. CHE-123.456.789.
pointOfSalestringName of the store / point of sale.
terminalIdstringTerminal ID at the terminal provider (TERM).
terminalSerialstringSerial number of the terminal.
terminalSoftwareVersionstringSoftware version of the terminal.
acquirerTerminalIdstringTerminal ID at the acquirer (TID).
amountintegerAmount without tip, in cents.
tipAmountintegerTip in cents: tip sent with the request plus any tip added on the terminal.
totalAmountintegerTotal amount charged, in cents.
currencystringCurrency, ISO 4217.
paymentMethodstringPayment method.
cardBrandstringCard brand, e.g. mastercard, visa.
maskedPanstringMasked card number, e.g. 535220******4337.
binstringFirst six digits of the card number.
cardLast4stringLast four digits of the card number.
applicationLabelstringApplication label of the card issuer, e.g. Debit Mastercard. Display only: issuers choose the text freely, so it is not a reliable debit/credit indicator.
cardEntryMethodstringCONTACTLESS, CHIP, SWIPE or MANUAL.
cardholderVerificationstringNO_CVM, PIN, SIGNATURE or CDCVM.
authorizationModestringONLINE or OFFLINE.
aidstringEMV application identifier.
applicationCryptogramstringEMV application cryptogram (AC).
authorizationCodestringAuthorization code of the issuer (AUT).
receiptNumberstringReceipt number of the terminal provider (DOC).
createdAtstringCreation time, ISO 8601 UTC.
completedAtstringCompletion time, ISO 8601 UTC.
revertedAtstringReversal time, ISO 8601 UTC. Set on reversalSlip only.

NexGo terminals currently do not report bin, cardholderVerification, applicationCryptogram, receiptNumber, applicationLabel and terminalSoftwareVersion; these fields are null there. Missing merchant data is completed from the store data in Payrexx.

print

FieldTypeDescription
customerstringCustomer copy.
merchantstringMerchant copy. Contains a signature line if the cardholder verified by signature.

Both texts are rendered by Payrexx in one layout for every terminal: 40 columns, monospace font, lines separated by \n, in the merchant's language. Currency and amount are joined by a non-breaking space.

Example

Response data object of Get terminal payment (version 1.19, fields unrelated to this change are omitted):

{
    "paymentId": "4b1c9e2a-7d3f-4e8a-9c1b-2f6d8a0e5c71",
    "status": "SUCCESS",
    "amount": 1250,
    "tipAmount": 150,
    "currency": "CHF",
    "slip": {
        "information": {
            "transactionId": "4b1c9e2a-7d3f-4e8a-9c1b-2f6d8a0e5c71",
            "status": "SUCCESS",
            "merchantName": "Café Muster GmbH",
            "merchantAddress": "Bahnhofstrasse 1",
            "merchantPostalCode": "3600",
            "merchantCity": "Thun",
            "merchantCountry": "CH",
            "merchantRegistrationId": "CHE-123.456.789",
            "pointOfSale": "Café Muster Bahnhof",
            "terminalId": "7f0ee11d",
            "terminalSerial": "NA9C00642859",
            "terminalSoftwareVersion": "2.12.10.3-payrexx",
            "acquirerTerminalId": "M6032023",
            "amount": 1250,
            "tipAmount": 150,
            "totalAmount": 1400,
            "currency": "CHF",
            "paymentMethod": "card",
            "cardBrand": "mastercard",
            "maskedPan": "535220******4337",
            "bin": "535220",
            "cardLast4": "4337",
            "applicationLabel": "Debit Mastercard",
            "cardEntryMethod": "CONTACTLESS",
            "cardholderVerification": "PIN",
            "authorizationMode": "ONLINE",
            "aid": "A0000000041010",
            "applicationCryptogram": "F09EBFDF3170F585",
            "authorizationCode": "271125",
            "receiptNumber": "30086018",
            "createdAt": "2026-10-15T12:48:51Z",
            "completedAt": "2026-10-15T12:49:00Z",
            "revertedAt": null
        },
        "print": {
            "customer": "              Kundenbeleg              \nCafé Muster GmbH\n…",
            "merchant": "              Händlerbeleg              \nCafé Muster GmbH\n…"
        }
    }
}

Customer copy as printed:

              Kundenbeleg
Café Muster GmbH
Nationale Händler Id CHE-123.456.789
Bahnhofstrasse 1
3600 Thun
SERIAL: NA9C00642859
VERSION: 2.12.10.3-payrexx
TERM: 7f0ee11d
15.10.26 14:49
KAUF:                          CHF 12.50
TRINKGELD:                      CHF 1.50
GESAMT:                        CHF 14.00
                        ONL - KONTAKTLOS
MASTERCARD 535220******4337

Debit Mastercard
                     MIT PIN VERIFIZIERT

DOC: 30086018
AUT: 271125
TID: M6032023
AC: F09EBFDF3170F585
AID: A0000000041010

POS Cash Register: independent credit

Up to version 1.18

There is no way to credit a card from a terminal without an original payment. POST /ecr/{serialNumber}/payment/{paymentId}/refund always reverses a payment you already took, so paying a customer out at the till — a returned item bought elsewhere, a goodwill credit — is not possible through the API.

From version 1.19

POST /ecr/{serialNumber}/payment/credit credits a customer's card with no original transaction. It is available on NexGo terminals only; Newland terminals return 501. On API versions below 1.19 the path returns 404.

The credit must be enabled for the account (KYC setting "Independent Credit") and is checked against a per-transaction limit and the account balance before the terminal is contacted, so a refused credit never reaches the terminal. The resulting transaction carries paymentType: independent-credit (see below) and cannot be refunded.

Request

FieldTypeDescription
amountintegerRequired. Amount to credit, in cents. Must be positive.
referenceIdstringRequired. Your own reference, and the idempotency key — see below.
currencystringISO 4217. Defaults to the terminal's configured currency. CHF only.
paymentMethodstringCARD only for now.
purposestringFree-text purpose stored on the transaction.

A credit has no tip, no basket and no receipt routing, so tipAmount, shopItems and printSlip are not accepted.

referenceId is the idempotency key

A credit is money leaving the account with nothing to reverse it, so repeating the call must never credit the card twice. Calling the endpoint again with a referenceId this terminal has already credited returns that first credit and its current status, rather than taking a second one. Retrying after a timeout or a lost response is therefore safe.

A genuinely new credit needs a new referenceId — including after a decline, since the declined attempt keeps the reference.

If the status read fails

The card is credited the moment the terminal accepts the request. If the status read that follows it fails, the call still answers 200 with the paymentId and status: IN_PROGRESS instead of an error. Poll GET /ecr/{serialNumber}/payment/{paymentId} for the outcome — the credit is recorded before that read, so it is never lost.

Declines

A refused credit answers {status, reason, message}, where reason is machine-readable:

reasonHTTPMeaning
no_kyc403The account has no completed KYC.
feature_disabled403The "Independent Credit" setting is off for this account.
invalid_amount400The amount is missing, zero or negative.
currency_not_supported400Only CHF is supported.
max_amount_exceeded422Above the per-transaction limit; the message names the limit.
insufficient_balance422The message names the amount still creditable.
account_not_found409No payment account for this currency.

Example

{
    "amount": 1000,
    "currency": "CHF",
    "referenceId": "credit-2026-00184",
    "purpose": "Goodwill credit"
}

Response data object (fields unrelated to this change are omitted):

{
    "paymentId": "4b1c9e2a-7d3f-4e8a-9c1b-2f6d8a0e5c71",
    "status": "IN_PROGRESS",
    "type": "CREDIT",
    "amount": 1000,
    "currency": "CHF",
    "paymentMethod": "CARD",
    "referenceId": "credit-2026-00184",
    "purpose": "Goodwill credit"
}

POS Cash Register: lastPaymentId on errors

Up to version 1.18

An error response of a POS Cash Register endpoint only contains status, message and, for some errors, reason. If a call fails (e.g. a timeout or a terminal error after the payment was started), the cash register cannot tell from the response which payment the terminal last worked on.

From version 1.19

Every error response of a POS Cash Register endpoint also contains lastPaymentId, once the request is authenticated.

FieldTypeDescription
lastPaymentIdstring or nullID of the last payment or independent credit you started on this terminal (the paymentId returned by Initiate terminal payment / Initiate an independent credit). null if you have no payment on this terminal yet or the terminal could not be identified (e.g. unknown serial number).
  • The field is present on every error response of these endpoints, including 500 Internal Server Error. Errors returned before the request is authenticated (e.g. an invalid signature, a missing API license or maintenance) do not contain it.
  • Only your own payments are returned. If the terminal was used by someone else before, their payments are never returned.
  • It is the last payment of the terminal, not necessarily of the failed request. Use Get terminal payment with it to find out the payment's current status, and cancel it if needed.
  • Successful responses are unchanged.

Example

{
    "status": "error",
    "message": "An error occurred: Terminal is not paired",
    "lastPaymentId": "4b1c9e2a-7d3f-4e8a-9c1b-2f6d8a0e5c71"
}

POS Cash Register: paymentMethod on Newland terminals

Up to version 1.18

paymentMethod on POST /ecr/{serialNumber}/payment is ignored on Newland terminals: the payment always runs as a card payment. The response's paymentMethod is CARD.

From version 1.19

Newland terminals accept paymentMethod:

ValueResult
omittedCard payment. Once TWINT is available, a terminal set up for TWINT asks on screen whether to pay by card or TWINT.
CARDCard payment.
a card brand from paymentMethods, e.g. visaCard payment. The brand is detected from the card presented, not preselected.
twintComing soon — see below.
anything the terminal's paymentMethods does not list400

The accepted values are CARD and the card brands and twint from the terminal's paymentMethods (GET /ecr/{serialNumber}/config). Values are not case-sensitive.

TWINT on Newland terminals is coming soon. Until it is available, paymentMethod: "twint" returns 400 ("not yet available on this terminal"), and an omitted paymentMethod runs a card payment as before. Once it is available, the same requests work without any change on your side.

TWINT also requires the terminal to be set up for TWINT payments with Payrexx. On a terminal that is not, paymentMethod: "twint" returns 400 ("not set up for this terminal"), and an omitted paymentMethod always runs a card payment.

The response's paymentMethod reports what the terminal actually ran — CARD or TWINT — and is null until the terminal reports it. Once TWINT is available, a payment that can only run one way (an explicit paymentMethod, or a terminal not set up for TWINT) reports that method right away. The card brand stays in cardBrand.

This change is not breaking: a request without paymentMethod behaves as before.


Transaction: paymentType

Up to version 1.18

The transaction object does not state its payment type. Whether a transaction is a one-time payment, a subscription payment, a reservation or a tokenization can only be derived indirectly from other fields.

From version 1.19

The transaction object contains the field paymentType. It states how the transaction was created and does not change over the lifetime of the transaction; the progress of a transaction is still described by status. Refund transactions carry the payment type of the transaction they belong to.

FieldTypeDescription
paymentTypestringPayment type of the transaction, see values below. null for older transactions without a payment type.

Values of paymentType

ValueDescription
one-timeOne-time payment. Where it was processed is stated in type.
subscriptionPayment of a subscription, both the initial and the recurring payments.
reservationPre-authorization: the amount is reserved and charged later.
authorizationTokenization: the payment method is stored for later charges.
independent-creditIndependent credit: a credit without an original payment. Its amount is negative and it cannot be refunded.

Example

Response data object of Retrieve a transaction (version 1.19, fields unrelated to this change are omitted):

{
    "id": 28320358,
    "uuid": "e0606679",
    "amount": 100,
    "status": "confirmed",
    "time": "2026-09-30T18:42:05+02:00",
    "mode": "TEST",
    "paymentType": "one-time",
    "type": "E-Commerce",
    "refundable": true,
    "partiallyRefundable": true
}

Transaction: filterReference

Up to version 1.18

Retrieve transactions can only be filtered by time (filterDatetimeUtcGreaterThan, filterDatetimeUtcLessThan) and by API key (filterMyTransactionsOnly). To find the transactions of a reference, the list has to be searched within a time range. A filterReference parameter is ignored.

From version 1.19

Retrieve transactions accepts the parameter filterReference.

ParameterTypeDescription
filterReferencestringReturns only transactions whose invoice reference (referenceId) or purpose matches this value.
  • Only full matches are returned, there is no partial search. Matching is not case-sensitive (order-4711 also returns ORDER-4711).
  • A reference can belong to several transactions (e.g. a payment and its refund); all of them are returned.
  • offset, limit and orderByTime apply as usual, and the filter can be combined with the other filters.
  • Only transactions of the instance are returned.
  • The parameter takes a single value. Passing it more than once (e.g. filterReference[]=…) returns 400 Bad Request.
  • An empty value (or one consisting only of spaces) and a value longer than 255 characters return 400 Bad Request.

Example

curl --request GET "https://api.payrexx.com/v1.19/Transaction/?instance=YOUR_INSTANCE_NAME&filterReference=ORDER-4711" \
--header "X-API-KEY: YOUR_API_SECRET"

Transaction: cardBin and cardLast4

Up to version 1.18

The payment object contains the truncated card number cardNumber (e.g. 411111xxxxxx1111) only for pre-authorized transactions and subscription payments, and only if the card expiry is known. Card terminal transactions never carry card data.

From version 1.19

The payment object additionally contains cardBin and cardLast4. Unlike cardNumber, both fields are set whenever the card data is known, including card terminal transactions without an expiry. A transaction charged on a pre-authorization carries the card of the pre-authorization. Only the BIN and the last four digits are returned, never the full card number.

FieldTypeDescription
payment.cardBinstringBIN (first digits) of the card. Usually six digits; older transactions may only carry the first four. null if the transaction was not paid by card or no BIN is known.
payment.cardLast4stringLast four digits of the card. Always four digits, leading zeros included (e.g. 0123). null if the transaction was not paid by card or the digits are not known.

Both fields are strings so that leading zeros are kept.

Example

Response data object of Retrieve a transaction for a card terminal payment (version 1.19, fields unrelated to this change are omitted):

{
    "id": 28320358,
    "uuid": "e0606679",
    "amount": 1250,
    "status": "confirmed",
    "type": "POS",
    "payment": {
        "brand": "mastercard",
        "wallet": null,
        "cardBin": "535220",
        "cardLast4": "0337"
    }
}

POS Cash Register: a payment request is a hand-off

Initiate terminal payment hands the payment to the terminal. It does not guarantee that the payment shows up on the terminal screen: a terminal that is offline, has a bad connection or is busy may never fetch it. The response of Initiate terminal payment is the state at the end of a short hand-off window, not a confirmation that the customer sees the payment.

This section applies to Newland terminals.

Keep polling Get terminal payment until the status is final (SUCCESS, DECLINED, TERMINATED, FAILED, …). PAYMENT_REQUESTED means the payment was handed to the terminal but not picked up yet. On Newland terminals, Payrexx cancels a payment the terminal never picks up; it ends as TERMINATED and does not show up on the terminal later.

NexGo terminals can also report PAYMENT_REQUESTED from version 1.19, but Payrexx does not cancel those payments by itself; the POS decides (see POS Cash Register: PAYMENT_REQUESTED for NexGo terminals).

Up to version 1.18

SituationBehavior
Initiate terminal paymentWaits for the terminal to pick the payment up, for 10 status checks. The wait grows with the response time of the terminal provider. A payment that was not picked up in time is cancelled.
Get terminal payment while the status is PAYMENT_REQUESTEDEvery request waits for the pick-up again (about 4 to 7 seconds) and cancels the payment if it was not picked up in that time.
Cancellation refused because the terminal picked the payment up meanwhileThe response follows after up to four more status checks.

Integrations that stay on version 1.18 or lower are not affected.

From version 1.19

SituationBehavior
Initiate terminal paymentWaits for the pick-up for at most 7 seconds from the moment the payment was handed to the terminal. A payment that was not picked up by then is cancelled before the response is sent: the response is TERMINATED, or a non-final status (IN_PROGRESS, UNKNOWN) while the cancellation completes.
Get terminal payment within 20 seconds of Initiate terminal paymentReturns the current status at once, also PAYMENT_REQUESTED. The payment is not cancelled.
Get terminal payment later than 20 secondsA payment still not picked up is cancelled exactly once, by this request or by Payrexx in the background, whichever comes first. The status is non-final (IN_PROGRESS, UNKNOWN) while the cancellation completes, then TERMINATED.
Cancellation refused because the terminal picked the payment up meanwhileThe response returns the actual status of the payment at once (e.g. IN_PROGRESS, SUCCESS, DECLINED). The payment continues normally. This also applies to Cancel terminal payment.

If a cancellation cannot be sent (e.g. a timeout at the terminal provider), the response stays PAYMENT_REQUESTED and Payrexx retries the cancellation in the background.

Which of the two behaviors applies depends on the API version the payment was initiated with, not on the version of a later Get terminal payment or Cancel terminal payment request. A payment initiated with version 1.19 keeps the version 1.19 behavior when it is polled with version 1.18, and a payment initiated with version 1.18 keeps the version 1.18 behavior when it is polled with version 1.19.

Example

Response data object of Get terminal payment within 20 seconds of Initiate terminal payment, for a payment the terminal has not picked up yet (version 1.19, fields unrelated to this change are omitted):

{
    "paymentId": "4b1c9e2a-7d3f-4e8a-9c1b-2f6d8a0e5c71",
    "status": "PAYMENT_REQUESTED",
    "amount": 1250,
    "currency": "CHF",
    "slip": null
}

POS Cash Register: PAYMENT_REQUESTED for NexGo terminals

Up to version 1.18

On NexGo terminals, status is IN_PROGRESS both for a payment that the terminal has not accepted yet and for a payment that is running on the terminal. The two cases cannot be told apart.

From version 1.19

On NexGo terminals, a payment that was sent but that the terminal has not accepted yet has the status PAYMENT_REQUESTED, as on Newland terminals. As soon as the terminal accepts the payment, the status changes to IN_PROGRESS.

statusMeaning
PAYMENT_REQUESTEDThe payment was sent, but the terminal has not accepted it yet.
IN_PROGRESSThe payment is running on the terminal.

This applies to every ECR payment response: Initiate terminal payment, Initiate an independent credit, Get terminal payment, Cancel terminal payment, Void terminal payment and Refund terminal payment. All other status values are unchanged.

Recommendation for POS integrations

A NexGo terminal that has lost its connection, e.g. after a longer idle time on Wi-Fi, may not receive a payment. If a payment stays PAYMENT_REQUESTED for a few seconds:

  1. Cancel it with Cancel terminal payment.
  2. If the response does not show a final status yet, poll Get terminal payment until it does.
  3. Start a new payment only if the final status is not SUCCESS (usually it is TERMINATED). If the status changes to IN_PROGRESS in the meantime, the terminal has received the payment: keep polling and do not start a new one.

Payrexx does not cancel or repeat a NexGo payment by itself: a payment repeated while the terminal can still receive the first one could charge the customer twice. The decision stays with the POS.

Example

Response data object of Get terminal payment (version 1.19, NexGo terminal, fields unrelated to this change are omitted):

{
    "paymentId": "4b1c9e2a-7d3f-4e8a-9c1b-2f6d8a0e5c71",
    "status": "PAYMENT_REQUESTED",
    "type": "CHARGE",
    "amount": 1250,
    "currency": "CHF",
    "slip": null
}

All endpoints: 401 for a wrong API key or API Signature

Up to version 1.18

A request with a wrong API key or a wrong ApiSignature is answered with 403 Forbidden. The same status is used when an authenticated request is not permitted (e.g. a missing API license), so the two cases cannot be told apart by the status code.

From version 1.19

A request with a wrong API key or a wrong ApiSignature is answered with 401 Unauthorized. 403 Forbidden is only used when the request is authenticated but not permitted for this account (e.g. a missing API license, or no_kyc / feature_disabled on Initiate an independent credit).

  • The version is read from the request path (/v1.19/…). Requests to version 1.18 or lower keep getting 403.
  • The response body is unchanged.
  • Check your signature (GET /SignatureCheck/) follows the same rule, so it answers 401 for a wrong API key from version 1.19.

Example

GET https://api.payrexx.com/v1.19/SignatureCheck/?instance=INSTANCE_NAME with a wrong API key:

HTTP/1.1 401 Unauthorized
{
    "status": "error",
    "message": "An error occurred: The API secret is not correct."
}