Paylink-v3 Postback/Webhook Handling

On processing a Transaction Request, Paylink will optionally perform a HTTP POST operation to the provided Postback URL. The body of the POST call contains a  Transaction Response  represented by the content-type of the originating call (JSON, XML, URL). A postback is a pseudonym for a Webhook.

To accept Postback calls, the Merchant should optionally configure their firewall to accept HTTP or HTTPS addresses from our production IP addresses of 54.246.184.9554.246.184.93 and 54.246.184.81 as appropriate.

A Postback does contain integrity information which should also be checked to confirm that it is sent from a valid source.

Examples

JSON 

{
    "sha1": "+Yz7zrgtzI4AN1b9UOa7th2u+/4=",
    "cardScheme": "Visa Debit",
    "expYear": 2020,
    "authenticationResult": "?",
    "CSCResponse": "M",
    "digest": "BxNq3NffJGzVfqFLYfjm+w==",
    "email": "email@mail.com",
    "identifier": "shop_12345",
    "firstname": "Joe",
    "AVSResponse": "M",
    "cavv": "",
    "postcode": "JE3 1ZZ",
    "result": 1,
    "datetime": "2018-02-28T09:02:51.603Z",
    "errormessage": "Accepted Transaction",
    "country": "GB",
    "amount": 8192,
    "sha256": "qLYMh02W+Wjg1pN2r/TV8Al+YlcLwLn8exotfNYdRFA=",
    "maskedPan": "475117******5712",
    "lastname": "Smith",
    "expMonth": 11,
    "cac": 0,
    "status": "O",
    "errorid": "000",
    "currency": "GBP",
    "address": "1 street",
    "errorcode": "000",
    "mode": "live",
    "authcode": "460190",
    "cardSchemeId": "VD",
    "eci": "7",
    "title": "",
    "authorised": "true",
    "cac_id": "",
    "transno": 271696,
    "merchantid": 12345678
}

XML

An Xml packet is wrapped in a paylinkTransactionResult element.

<paylinkTransactionResult>
    <sha1>RHKJeRJn+EBSaaowXce4KcKTCIw=</sha1>
    <cardScheme>Visa</cardScheme>
    <expYear>2023</expYear>
    <authenticationResult>?</authenticationResult>
    <CSCResponse> </CSCResponse>
    <digest>8pEXNXUcCF6YQ4FQnMT4bg==</digest>
    <email>your@email.com</email>
    <identifier>xmlTest</identifier>
    <firstname>Joe</firstname>
    <AVSResponse> </AVSResponse>
    <cavv></cavv>
    <postcode>JE2 3NT</postcode>
    <result>1</result>
    <datetime>2018-01-06T15:40:15.807Z</datetime>
    <errormessage>Test Transaction</errormessage>
    <country>AU</country>
    <amount>123412</amount>
    <sha256>QhoBrnywFG4Vl8T5wOVwAPZslVrbL0kac9FzktxRw00=</sha256>
    <maskedPan>400000******0002</maskedPan>
    <lastname>Blogs</lastname>
    <expMonth>7</expMonth>
    <cac>0</cac>
    <status>O</status>
    <errorid>001</errorid>
    <currency>GBP</currency>
    <address>la rue de home</address>
    <errorcode>001</errorcode>
    <mode>test</mode>
    <authcode>A12345</authcode>
    <cardSchemeId>VE</cardSchemeId>
    <eci>7</eci>
    <title></title>
    <authorised>true</authorised>
    <cac_id></cac_id>
    <transno>65191</transno>
    <merchantid>12345678</merchantid>
</paylinkTransactionResult>

Configuration

Providing a Postback URL

A URL can be provided within the setup of your account and becomes the default URL. If a postback value is supplied in the Token Request, it will override the stored value. Should a value of none be supplied in the Token Request, no postback will be performed. The determination of whether a postback should be sent is performed on a transaction by transaction basis.

A URL can only be on ports HTTP 80 and HTTPS 443. This is due to PCI firewall compliance. If you wish to utilise multiple applications or use a different port, we recommend reverse proxying your calls via Apache or Nginx.

A URL likewise cannot be a local address and must be accessible across the Internet from our payments cloud. If you are developing an integration and testing Postback calls, you will need to setup firewall rules and allow a HTTP(S) endpoint to reach your development servers.

Postback Delivery Options

A Postback may be delivered at different points of the lifecycle of a transaction. If a transaction is authorised, you can expect a post back to be sent. A postback may be withheld such that, if a transaction is processed and either rejected or declined, Paylink will allow the cardholder to retry a different card or correct their values. Therefore a further attempt is made against the Paylink session with 1 or more transaction entries generated for the cardholder to reach payment. From an ordering perspective you will only want to know whether the transaction has been approved or not, therefore the last result is delivered. We determine what to deliver based on successful authorisation or timeout of the token. 

Connection Settings

We recommend your store is hosted behind a secure site using HTTPS. Paylink will accept all certificate authorities as standardised by Oracle's Java runtime. If you are developing your site or have an untrusted certificate authority, Paylink can be configured to trust all authorities. This is a configurable option and is not recommended however we understand for testing purposes it may be necessary to allow this setting.

Paylink will attempt a Postback and require a connection within 10 seconds. Once connected it will also wait for a response for 10 seconds. If we are unable to determine that the Postback has been received then the Postback is marked as failed.

Postback Response Handling

To confirm the Postback has been received by your servers, we expect a 20X response i.e. 200 OK to be returned. 

Strategy for Synchronization

A Postback call may be configured to be synchronous or asynchronous (default). 

Synchronous Postback 

If the Postback is synchronous, Paylink will execute the Postback before any response is delivered to the Customer's Browser. This ensures that the information has been delivered to your site before the result is presented to the Card Holder. The Postback call is attempted by default only once. This is to ensure that Paylink can respond to the Customer Browser within a reasonable period of time. Paylink however can be configured to retry. 

If we are unable to retrieve a response in this time period Paylink may

  1. Allow the transaction to continue but move the Postback to a background process which will retry asynchronously; or
  2. Email out a failure message

Asynchronous Postback

If the Postback is asynchronous, Paylink will execute the Postback in a background process. resulting in a faster user experience. The Postback call may be received by the Merchant Application an arbitrary period of time after the Transaction was concluded. While the actual period of time between the provision of a response is likely to be relatively small, a Merchant Application that uses asynchronous PostBack calls should be implemented to avoid reliance on the outcome of the Transaction until the Postback call is actually received.

In an asynchronous mode, a Postback is queued for delivery and may retry up to 10 times (configurable). A retry will be attempted every minute for the first 3 attempts, every 15 minutes for the next 3 attempts and every hour for every consequential retry.

+44 (0)1534 884000