An exchange call is a signal from PAY. to your webshop that indicates that the status of a payment has changed. The merchant can then update the payment in question to ensure its status matches the one in the PAY. Admin Panel. The signal that PAY. sends to your webshop is basically a script (URL) that we call on your server. When PAY. receives the correct response from this script, we know that your system has processed the new transaction status. The location that is called by PAY. is known as the exchange URL.

Exchange module version

Pay. has two versions of the exchange call, that work different, but follow the same procedure. 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.

• Old version: We send fields in the POST or GET, 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).
• New 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.

Via configuration or on transaction level

We recommend to set up the Exchange on transaction level. So you make sure that the initiator of the transaction is always in control of the right transaction status. The merchant can set up extra exchange locations in their <<glossary:Global Management System>> on sales location as well. That exchange is common use to send information to a merchant-specific endpoint; like accountancy platforms, loyalty systems or management reports.

On transaction level

In the Order:Create API call you can supply an exchangeURL. If submitted we will send a signal to that URL.

Select exchange settings via the sales location configuration.

Response on a exchange call

Sent a valid response on a exchange call so that the call will be marked as 'success'. If no valid response is received the Retry Scheme will be enabled and we will resent the exchange call (depending on the configuration in the sales location). More information about the retry schemes can be found here.

JSON Exchanges

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"
}

GET & POST Exchanges (legacy)

When using standard GET and POST methods we will mark an exchange as "success" if your server's response begins with the word "TRUE". Any response that does not start with "TRUE" will be marked as "failed".

Valid response:

TRUE

Valid response when using the exchange separator:

TRUE|YOUR COMMENT

📘

Update the Separator

If you like to use another Separator, update the settings in the <<glossary:GMS>>

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

FALSE|YOUR COMMENT

Invalid response, this will trigger the Retry Scheme:

ANYTHING OTHER THAN: TRUE

Logging

🚧

Exchange LOG retention policy

Exchange data is saved for max 35 days on the PAY platform, you can see the result on transaction level in the PAY.admin or in Report format.

Transaction details
Use the following steps to view the exchange requests of a single transaction:

• Go to my.pay.nl and select the option Transactions > Overview in the menu
• Look up the transaction whose exchange requests you want to view
• Click on the transaction’s “EX-code” or magnification glass icon. A popup appears that contains all the details of the transaction you selected
• You can view the results of the exchange requests that were carried out for this transaction at the bottom of the popup, under “Communication log.”

In the ''Payment state log'' which can be found in my.pay.nl when you navigate to Reports > Payment state log. you will also find the HTTP code. If the HTTP code does not contain the value 200, then an error has occurred.

With the link in the ''Options'' column you will get all the details of the exchange call, including the called URL and the full answer we have received from your server.

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.