Custom Integration

Custom Integration

1.Introduction

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

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 Settings/Account.

Note: The Payer Administration requires a valid user account. Are you missing or have lost your user details? Please contact the customer service at kundtjanst@payer.se.

3.Handle Callbacks

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.

3.1.Explanation

3.1.1.Authorize

The role of the Authorize Callback during the payment session is to notify that the payment is prepared and initially requested at the supplier.

This state may corresponds to e.g. a ticket reservation or a reservation during card payments. Note, however, that at this point has the money not been transferred yet. Furthermore, this state may also comprise credit and address checks.

Available URL parameters

Name Description
payer_callback_type Specifies the current state of the callback
payer_merchant_reference_id The merchants custom order reference id
payer_payment_type The final method used in the payment dialogue
payer_testmode Specifies if the transaction was processed during production or test mode
payer_unique_id This value corresponds to the authorization of the recurring session.

Note: Available during Recurring Payments.

3.1.2.Settlement

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

Name Description
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:

 
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:

  • 79.136.103.5
  • 94.140.57.180
  • 94.140.57.181
  • 94.140.57.184

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:

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.

Example:

 
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:

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.

Resource location:


Request Object

Name Type Description
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.

7.Models

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.

Suggest Edit