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

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.

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 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.

Processing exchange call

It is essential that you process the transaction via the exchange URL, not via the return URL. Not every customer reaches the return URL, because some people close the payment screen immediately after completing the payment. The return URL is therefore only intended to let customers know whether their payment was successful.

Contrary to the return URL, the exchange URL is always called. This is therefore where you can process orders in your back office, e.g. by updating its status in your database, sending an invoice or email, et cetera.

Verifying status
You should always verify the status of a transaction using the order_id parameter, just like in the PHP code example. Do not use the action parameter to determine the transaction’s status, as it may have been changed manually in the URL.

📘

With many payment methods, the exchange URL is called in the Payment process. If the exchange response within the MAX-exhange-timeout, your platform will know the status before the user get's back on the Return URL. If you fail to respons,

<?php 
# Setup API Url
$strUrl = "https://rest-api.pay.nl/v7/Transaction/info/array_serialize?"; 

# Add arguments
$arrArguments = array();
$arrArguments['transactionId'] = filter_var(
$_GET['order_id']);

# Prepare complete API URL
$strUrl = $strUrl . http_build_query($arrArguments);
$objCurl = curl_init($strUrl);
curl_setopt($objCurl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($objCurl, CURLOPT_USERAGENT, "Pay.nl 
Api Example");
curl_setopt($objCurl, CURLOPT_TIMEOUT, 5
);
curl_setopt($objCurl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($objCurl, "AT-XXXX-XXXX:<your-api-token>");
$strReturnData = curl_exec($objCurl);
curl_close($objCurl);

# Process result
$strMessage = '';
$arrResult = unserialize($strReturnData);
if(isset($arrResult['paymentDetails']['stateName'])) {

    if($arrResult['paymentDetails']['stateName'
] == 'PAID') {
        # Execute code to process the order       

        $strMessage = 'Order processed';
    }
    elseif($arrResult['paymentDetails']['stateName'] == 'CANCEL') {
        # Payment canceled, restock items

        $strMessage = 'Order canceled';
    }
}

echo 'TRUE|'.$strMessage;

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.