5. Exchange calls

5.1 Exchange module version

Pay. has two versions of the exchange call, that work different, but follow the same procedure. If the status of a transaction is changed, we check in the settings of your sales location what kind of messages you like to receive and send that signal to the exchange URL.

Legacy versions: We send fields in a POST or GET call, you receive and determine if you like to perform an action. If you like to do, you call Pay., with your security tokens to retrieve the information of the transaction (also client specific information).
Active version: We get all the data of the transaction and sign that with the secret of the sales location. You check the signature, if it's valid you can proceed and process the data request. Click here for more information.

Type	Descriptions	Version
TXT_GET	Parameters are sent via GET variables	LEGACY
TXT_POST	Parameters are sent via POST variables	LEGACY
JSON_GET	Parameters are sent via GET variables	LEGACY
JSON_POST	Parameters are sent via POST variables, you need to check the real status based on a secure status retrieval	LEGACY
SIGNED_JSON_POST	Parameters via POST, data, that is signed. Click here for more information	ACTIVE
ENCRYPTED	Data SSL Encrypted via POST, transactionId and reference	BETA

5.2 JSON Exchanges

Starting transaction on our Multicore with our API's returns API calls in the following format:

{
    "event": "status_changed",
    "type": "order",
    "version": 1,
    "id": "68595063-5034-86b9-199f-737862303481",
    "object": {
        "id": "68595063-5034-86b9-199f-737862303481",
        "type": "sale",
        "serviceId": "SL-1234-1234",
        "description": "PAY03351656565",
        "reference": "traala",
        "manualTransferCode": "1000 0508 0610 5020",
        "orderId": "50806105020X3481",
        "uuid": "a63f7378-6230-3481-5080-6105020a3481",
        "customerKey": "fbfb1bbb1531f7efe12aeffa3af91542",
        "status": {
            "code": 100,
            "action": "PAID"
        },
        "receipt": null,
        "integration": {
            "pointOfInteraction": "IN_PERSON",
            "test": false
        },
        "stats": {
            "extra1": null,
            "extra2": null,
            "extra3": null,
            "tool": null,
            "info": null,
            "object": null,
            "promotorId": null,
            "domainId": null
        },
        "transferData": {},
        "amount": {
            "value": 3,
            "currency": "EUR"
        },
        "authorizedAmount": {
            "value": 0,
            "currency": "EUR"
        },
        "capturedAmount": {
            "value": 3,
            "currency": "EUR"
        },
        "checkoutData": null,
        "payments": [
            {
                "id": "68595091-5034-83c8-22c5-050806105020",
                "paymentMethod": {
                    "id": 10,
                    "input": []
                },
                "billingLineId": 10,
                "customerType": "consumer",
                "customerKey": "fbfb1bbb1531f7efe12aeffa3af91542",
                "customerId": "NL13ABCA0123456789",
                "customerName": "John Doe",
                "customerMethod": {
                    "type": "iban",
                    "data": {
                        "iban": "NL13ABCA0123456789",
                        "name": "John Doe",
                        "bic": "ABCANL2A"
                    }
                },
                "ipAddress": "127.0.0.1",
                "secureStatus": true,
                "paymentVerificationMethod": 0,
                "status": {
                    "code": 100,
                    "action": "PAID"
                },
                "currencyAmount": {
                    "value": 3,
                    "currency": "EUR"
                },
                "amount": {
                    "value": 3,
                    "currency": "EUR"
                },
                "authorizedAmount": {
                    "value": 0,
                    "currency": "EUR"
                },
                "capturedAmount": {
                    "value": 3,
                    "currency": "EUR"
                },
                "supplierData": null
            }
        ],
        "createdAt": "2025-06-23T13:02:27+00:00",
        "createdBy": "AT-1234-1234",
        "modifiedAt": "2025-06-23T13:12:47+00:00",
        "modifiedBy": null,
        "expiresAt": "2025-06-30T13:02:27+00:00",
        "completedAt": "2025-06-23T13:03:35+00:00",
        "links": {
            "status": "<status-url>",
            "abort": "<abort-url>",
            "approve": "<approve-url>",
            "decline": "<decline-url>",
            "void": "<void-url>",
            "capture": "<capture-url>",
            "captureAmount": "<capture-amount-url>",
            "captureProducts": "<capture-product-url>",
            "debug":"<debug-url>",
            "checkout": "<checkout-url>",
            "redirect": "<redirect-url>"
        }
    }
}

When exchanging with JSON we'll expect the response to be in JSON format. Herein on the main level the "result" key is used to determine a "success" or "failed" exchange.

Valid response:

{
  "result": true
}

Valid result with custom data:

{
  "result": true,
  "description": "Exchange is marked as successful"
}

Valid but failed response, this will trigger the Retry Scheme:

{
  "result": false,
  "description": "Exchange is marked as failed"
}

Invalid response, this will trigger the Retry Scheme

{
  "description": "Exchange is marked as failed"
}

Slow exchange calls (timeout) The default timeout time of the exchange is 5000 ms (5 seconds). In very exceptional cases, we can increase this time for you. If your exchange is slow, the user will have to wait after the payment until the exchange responds or until the timeout time has expired. If you choose a timeout of more than 5 seconds, then there is a good chance that your customer will either refresh or close the page completely.

📘
Want to know more about how our platform works? Please check Our platform