Exchange Handling

An exchange call is a signal from PAY. to your webshop that indicates that the status of an order has changed. The merchant can then update the order 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.

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 serviceId as well. That exchange is common use to send information to a merchant-specific endpoint; like accountancy platforms, loyalty systems or management reports.

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 on serviceId 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 serviceId. You check the signature, if it's valid you can proceed and process the data request.

		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_SJON_POST	Parameters via POST, data, that is signed `<https://developer.pay.nl/docs/signing>`	ACTIVE
ENCRYPTED	Data SSL Encrypted via POST, transactionId and reference.	BETA

🚧
Phase out legacy exchange methods
The legacy exchanges are supported until October, 30th 2023.
Legacy <<glossary:Behaviourfee>> of 1 cent per request until November, 30th 2024
fully decommissioned from November, 31st 2024

Select exchange settings via the sale locations configuration.

Parameters

When calling the exchange / communication URL, PAY. includes a number of POST / GET parameters.

Example exchange call <https://www.domain.com/exchange/?action=pending&order_id=819034534X2b5a00&payment_session_id=819034534&ip_address=1.2.3.4amount=9.99&extra1=order%20123&extra2=klant%20123&extra3=factuur%20123&info=facebook_campaign>

The actual call may include more parameters, depending on the selected payment option.

Parameter	Description
action	The action that has occurred. Click here for more information about the moment of calling.
order_id	The order ID with which you can verify the order's current status.
payment_session_id	The order’s payment session ID
ip_address	The user’s IP address
amount	The amount of the transaction
extra1	Free variable “extra1” that can be traced in the statistics. This variable may be included when starting the transaction.
extra2	Free variable “extra2” that can be traced in the statistics. This variable may be included when starting the transaction.
extra3	Free variable “extra3” that can be traced in the statistics. This variable may be included when starting the transaction.
info	Free variable “info” that can be traced in the statistics. This variable may be included when starting the transaction.

Required response

To verify whether a request was received properly, we expect a response for your server in the TXT format. This response must consist of the word TRUE. If the correct response is not received, PAY. will consider the call failed and the <<glossary:Retry Scheme>> will be initiated (if one was set up).

HTTP status code must be 200 for a correct Exchange call, if we receive any other result, we mark the request as failed an the retry sceme will resend the request.

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 the Admin Panel and select the option Transactions » Complete overview in the menu
Look up the transaction whose exchange requests you want to access
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 information.”

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

Bug fixes In the ''Payment state log'' you will also find the HTTP code. If the HTTP code does not contain the value 200, then an error has occured. With the help of the online checklist you can figure out how to solve the most common problems.

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.

Is the exchange call mostly slow? Please read our blogspost where we share solutions for this problem.