DocsDeveloperTicket
API Reference
PricingSignup

Changes for Version v.1.18

Affected endpoints

Transaction:

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

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

The transaction webhook is not affected by this version.

Summary

API version 1.18 contains two independent changes:

  1. Transaction endpoints: the transaction object exposes five fields.
  2. POS Cash Register (ECR) endpoints: the two merchant-reference fields of a terminal payment are renamed to match the Gateway API (paymentReference becomes referenceId, transactionDescriptor becomes purpose), and purpose is now stored as the purpose of the resulting Payrexx transaction. This change is breaking for ECR integrations that switch to version 1.18.

1. Transaction: additional fields in the response

Starting with API version 1.18, the transaction object returned by Retrieve a Transaction and Retrieve Transactions contains the following additional fields:

  • invoice.purpose
  • originalTransactionId and originalTransactionUuid
  • invoice.originalAmount and invoice.refundedAmount

New fields on the transaction object

FieldTypeDescription
originalTransactionIdintegerInternal ID of the original payment transaction a refund belongs to. Only present on refund transactions
originalTransactionUuidstringPublic UUID of the original payment transaction a refund belongs to.

Background: every refund creates a separate transaction with a negative amount and status refunded (full refund) or partially-refunded (partial refund). The original payment keeps its own ID and status. These two fields let you link such a refund transaction back to the payment it refunds without an additional lookup.

New fields on the invoice object

FieldTypeDescription
invoice.purposestringThe purpose that was passed when creating the Gateway, Paylink or Invoice (or, as of this version, the purpose of a terminal payment, see section 2). An empty string "" if no purpose was set.
invoice.originalAmountintegerThe total amount of the initial payment in the smallest unit of the currency, before any refunds.
invoice.refundedAmountintegerThe sum of all refunds issued for this payment so far, in the smallest unit of the currency. 0 if nothing has been refunded.

Examples

A partial refund transaction of CHF 25.00 on a CHF 100.00 payment:

{
    "id": 4712,
    "uuid": "e5f6a7b8",
    "status": "partially-refunded",
    "amount": -2500,
    "originalTransactionId": 4711,
    "originalTransactionUuid": "a1b2c3d4",
    "invoice": {
        "purpose": "Order 2026-1234",
        "totalAmount": 10000,
        "originalAmount": 10000,
        "refundedAmount": 2500,
        "currencyAlpha3": "CHF"
    }
}

2. POS Cash Register (ECR): referenceId and purpose replace paymentReference and transactionDescriptor

Up to and including API version 1.17, a terminal payment carries its merchant-reference data in the fields paymentReference and transactionDescriptor. Starting with API version 1.18 these fields are renamed so that the ECR API uses the same names as Create a Gateway:

Up to v1.17From v1.18TypeDescription
paymentReferencereferenceIdstringOptional. The merchant's own reference for the payment (e.g. an order number).
transactionDescriptorpurposestringOptional. Free-text purpose / descriptor of the payment.

The rename applies to:

  • the request body of Initiate terminal payment (POST /ecr/{serialNumber}/payment), and
  • the data object of the response of all five payment endpoints listed above (Initiate, Get, Cancel, Void and Refund terminal payment).

This is a breaking change for version 1.18. The old names are no longer part of the contract:

  • In requests sent with version 1.18, paymentReference and transactionDescriptor are ignored. Only referenceId and purpose are read.
  • In responses returned with version 1.18, paymentReference and transactionDescriptor are no longer present. The values are returned as referenceId and purpose instead.

Integrations that stay on version 1.17 or lower are not affected and keep using the old names. Both terminal families (NexGo and Newland) behave identically.

Changed mapping onto the Payrexx transaction

The rename also changes how the two values end up on the Payrexx transaction that is created once the terminal payment has been settled, and therefore what you see in the merchant backend, in Retrieve a Transaction and in the transaction webhook:

Payrexx transaction fieldUp to v1.17From v1.18
referenceId ("Reference ID")paymentReferencereferenceId
invoice.purpose ("Purpose")paymentReference (the descriptor was not stored)purpose

In other words, from version 1.18 the ECR API behaves like the Gateway API: referenceId becomes the reference ID of the transaction and purpose becomes its purpose. The version of the request that initiated the payment is persisted together with the terminal payment, so the mapping is applied consistently even though the settlement happens asynchronously.

Example

Request (POST /ecr/{serialNumber}/payment, version 1.18):

{
    "amount": 100,
    "currency": "CHF",
    "referenceId": "ORDER1234",
    "purpose": "Custom Transaction Descriptor",
    "printSlip": true
}

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

{
    "paymentId": "pay_123456",
    "status": "SUCCESS",
    "type": "CHARGE",
    "amount": 100,
    "currency": "CHF",
    "referenceId": "ORDER1234",
    "purpose": "Custom Transaction Descriptor",
    "terminal": "1234567890"
}

The same payment under version 1.17 would be sent and returned with paymentReference and transactionDescriptor instead.

Updated 4 days ago

Updated 4 days ago