Postback Handling

When Paylink processes a transaction request, it initiates an HTTP POST operation to the specified postback URL. The POST request includes a Transaction Response that matches the content type (JSON, XML) of the original call. This procedure is also referred to as a webhook or callback.

To ensure the reception of postback calls, merchants must configure their firewalls to accept HTTP or HTTPS traffic from our production IP addresses.

Postback URL

A default postback URL can be set in your Paylink profile, which can be overridden by any URL specified in the Token Request. If none is specified as the value in the Token Request, no postback will be executed. Postback execution is determined by the result of the transaction.

URL Restrictions:

Only standard HTTP (port 80) and HTTPS (port 443) are supported. For utilising multiple applications or different ports, consider using reverse proxy solutions like Apache, Nginx, or AWS Application Load Balancer.

Development and Testing:

Merchant internal or localhost addresses, typically used for development, must be made publicly accessible. During the integration phase, tools like ngrok.com are recommended for creating a secure tunnel to your local development environment.

URL Requirements:

• Must not be an empty string.
• Must comply with RFC 1738.
• Must be a valid, reachable port, such as port 443.

Understanding Postback Delivery in Transaction Lifecycle

A postback is sent at various stages throughout a transaction's lifecycle. If a transaction is authorised, you will receive a postback confirming the event. In cases where a transaction is either rejected or declined, Paylink holds off on the postback to allow the cardholder an opportunity to retry with a different card or correct any input errors. This enables multiple attempts under the same Paylink session, generating one or more transaction entries as the cardholder works toward successful payment.

Key Considerations for Transaction Results:

From a transaction management perspective, the primary concern is whether the transaction has been approved. Consequently, only the final result is communicated. This decision is based on either a successful authorisation, a cancelled transaction by the cardholder or a timeout of the payment token.

Payload Integrity

Each postback includes SHA256 integrity information. This should be verified by the merchant to confirm the authenticity of the source.

Connection Settings

Secure Hosting:

It is recommended that your store is hosted on a secure site using HTTPS. For development or when using an untrusted certificate authority, Paylink can be configured to trust all authorities. Although not recommended for production environments, this configuration may be necessary during integration phases.

Timeout Settings:

Paylink attempts a postback and requires a connection to be established within 10 seconds. Once connected, it waits an additional 10 seconds for the response. If Paylink cannot confirm that the postback has been received, it marks the postback as failed.

Postback Response Handling

Confirmation of Receipt:

To confirm receipt of a postback, your servers should return a simple 20X status code, such as 200 OK.

Synchronization Strategy

Postback Configuration:

A postback call can be configured as either synchronous or asynchronous (default). The postback_policy configuration parameter can be set as follows:

• none - No postback is sent.
• sync - Postback is synchronous.
• async - Postback is asynchronous (default setting).

Synchronous Postback:

If set to synchronous, Paylink will execute the postback before delivering any response to the customer's browser, this ensures that the information reaches your site before the result is shown to the cardholder. By default, the call is attempted only once to maintain a reasonable response time. If a response is not retrieved within the designated period, Paylink may:

1. Allow the transaction to continue while moving the postback to a background process for asynchronous retry; or
2. Send an email notification about the failure.

Asynchronous Postback:

In asynchronous mode, the postback is processed in the background, enhancing the user experience by not delaying the browser response. The postback may be delivered to the Merchant Application sometime after the transaction concludes. The timing isn’t fixed but is generally short.

Merchant Applications utilising asynchronous postbacks should be designed not to depend on the transaction outcome until the postback is actually received. Asynchronous postbacks are queued for delivery and may retry up to 10 times.

The retry schedule is as follows:

• Every minute for the first three attempts.
• Every 15 minutes for the next three attempts.
• Every hour for any subsequent retries.

Transaction Response parameters are returned in a postback and optionally in a redirection URL.

{
    "amount": 11056,
    "authcode": "021079",
    "authenticationResult": "Y",
    "authorised": "true",
    "cac": 0,
    "cac_id": "",
    "cardScheme": "Visa Debit",
    "cardSchemeId": "VD",
    "cavv": "AJkBBQNSNgAAACswgmICdAAAAAA=",
    "country": "",
    "currency": "GBP",
    "datetime": "2023-07-21T08:34:46.065Z",
    "digest": "i0JoTkP2Q3Ah3mGr7qeqqg==",
    "eci": "5",
    "email": "transactions@citypay.com",
    "errorcode": "000",
    "errorid": "000",
    "errormessage": "Accepted Transaction",
    "expMonth": 8,
    "expYear": 2025,
    "firstname": "",
    "identifier": "RT-00000-181",
    "lastname": "",
    "maskedPan": "Visa***3028",
    "merchantid": 123456,
    "mode": "live",
    "name_on_card": "MR N E PERSON",
    "postcode": "",
    "result": 1,
    "sha1": "+DVBFjo5qw2PT6tYy9CkzBv8uJE=",
    "sha256": "JnJ/J456xCEnCeb2cCgROG7rsxF2HMBJiJRN4qkehz0=",
    "status": "O",
    "title": "Mr",
    "transno": 82101
}