This section describes the default way to interact with Payer and initiate a purchase through the payment dialogue. The customized integration origins from the core layer which makes it possible to perform a more customized pay flow. This integration may be preferable if flow control is an important aspect.
The principally payment flow consists an initial payment inquiry followed by two callbacks (Authorize and Settlement) which makes the shop conscious of the current state. An overview of the flow is illustrated below.
Pay flow illustration
2.Retrieve your Credentials
To be able to perform the payment you need to have your personal Payer Credentials ready. Your credentials is accessible through the administration portal under
Note: The Payer Administration requires a valid user account. Are you missing or have lost your user details? Please contact the customer service at firstname.lastname@example.org.
During the payment session a total of two callbacks will be sent back to the shop. The callbacks will consists various and necessary parameters in the url (HTTP GET) for further order state updates at the merchant.
The two different callback types are:
To be able to do a full purchase through Payer, you have to create these callback resource endpoints at your side.
During the payment session a final callback will be sent back to the payment requestor to inform that the payment has succeeded. At this point you are expected to update the final order status and take care of other necessary statements for your app.
Available URL parameters
|payer_added_fee||Contains any extra fees added by Payer|
|payer_callback_type||Specifies the current state of the callback|
|payer_merchant_reference_id||The merchants custom order reference id|
|payer_payment_id||The unique identification number of the payment|
|payer_payment_type||The final method used in the payment dialogue|
|payer_testmode||Specifies if the transaction was processed during production or test mode|
3.2.Create a Resource
A Resource is expected to perform validation of the source and the data sent back to the merchant, and signal that back to Payer on success. All the Resources are expected to be expressed according to the following example:
if VALID CALLBACK IP
if VALID CALLBACK URL
Validating the source address
This filtering has to check the IP address of the callback requestor to secure that the inquiry comes from Payer or an other allowed source such as a custom proxy server.
Add the following IP addresses if the callback is expected to come from Payer directly:
Note: If you are using an additional layer between the payment requestor and Payer, such as a Proxy server, you have to take care of the IP address in the filtering.
Validating the source data
Next step is to validate the data sent from the source. This is done by calculating a hash value of the callback url including the parameters and compare it with the hash sum sent by Payer.
The total amount of parameters available in the url varies and depends on the callback type. Please see the explanation section above for more details.
An example of how the hash should be calculated:
MD5(YOUR_KEY_1 + THE_CALLBACK_URL + YOUR_KEY_2)
Note: The ‘md5sum’ parameter in the callback url should be excluded from the hash calculation.
If the recent calculated hash value is equal to the value sent by Payer, the callback source is interpreted as a trusted source.
4.Setup the XML data
In the subsequent payment request to Payer, the ingoing data is expected to be formatted according to a particular format.
You can get more details about how the data should be formatted under the Models section.
<?xml version="1.0" encoding="ISO-8859-1"?>
<payread_post_api_0_2 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="payread_post_api_0_2.xsd">
Click here to get the extended XML Schema Definition.
5.Calculate the checksum
The last step before initiating the payment is to calculate the hash value that is used by Payer to secure the identity of the requestor.
The MD5 hash value is generated according to the following example:
MD5(YOUR_KEY_1 + THE_BASE64_ENCODED_DATA + YOUR_KEY_2)
6.Perform the HTTP request
As a last step we will perform the final call to initiate the payment at Payer. The inquiry is made by a standard HTTP request using the POST method. Upon success the payment dialogue will be returned in the response.
|payer_agentid||string||The registration id at Payer|
|payer_xml_writer||string||The API version. The default value is set to '30'|
|payer_data||string||The base64 encoded XML data|
|payer_charset||string||The charset used on the client side. The default value is set to 'ISO-8859-1'|
|payer_checksum||string||The authorization hash. See Section 5.|
The models are reusable structure definitions that describes how the XML post data should be formatted in the HTTP POST request when initiating a payment session through Payer.
Click here to view the XML models.