POSTback

POSTback is similar in function to Transparent Redirect, but instead of routing response data back through the web client’s browser, it sends the data directly to the merchant’s back-end system, securely, via HTTPS POST calls. POSTback can be done in addition to transparent redirect, or independently of transparent redirect.

Implementation

You first need to log into your account and modify the Merchant Account Setup/Configuration.

From the PayConex account settings (Settings – Manage Settings) page, you can view and modify the following (in the API Response Handling section): POST/CALLBACK radio buttons. Click Enable to reveal the URL field POST/CALLBACK URL – enter a valid HTTPS URL to receive POSTback data.

No change to the QSAPI implementation code is required.

Custom Process Flow

QSAPI requests are handled normally from the receipt of a request through the normal submission process.

When the QSAPI reply is ready, if “POSTback RESPONSE” is enabled in the merchant’s account, and a valid “POSTback URL” has been entered, QSAPI will do the following:

1. Store the transaction Postback data into a Messaging Queue.
2. Trigger an asynchronous posting of the transaction to the merchant’s Postback URL.
3. Include a validation hash to send with the Postback data, comprised of the following:
   1. account_id
   2. api_accesskey
   3. timestamp
      If a connection cannot be made to the merchant’s “Postback URL”, the Postback messaging sub-system will continue to retry the Postback periodically (interval TBD).

Upon successful connection and transmission, the messaging sub-system will record the response from the merchant’s system and tag the Postback as complete.

Because the Postback actually happens asynchronously, there is no delay in the response to the customer/client.

POSTback Response Payload

The POSTback response payload is a structured data object. It is comprised of five (5) main components:

• account_id The merchant Payconex account ID

• timestamp The UNIX timestamp of the POSTback

• count The number of transaction responses being sent

• hash The authentication hash (see above for description)

• responses An array of transaction responses. For the typical merchant this array will contain only one transaction. Merchants utilizing Enhanced Payment Pages, or performing Split Transactions via QSAPI, would receive multiple responses bundled together.
  The data format of the POSTback response can be controlled by passing a “response_format” parameter in the original transaction request. The following payload formats are supported:

• FORM HTTP query string key=value pairs (default)

• JSON (recommended)

• XML (pending)

POSTback responses will contain the same variables as the QSAPI response, just a different data format; however, it will also contain the account_id, timestamp, count, and a hash in case you need it. The hash is included so you can verify that the data sent back actually came from Bluefin. See example below.

POSTback Example Response

A typical POSTback payload could look like this (JSON format used):

{
  "account_id":"120908675309",
  "timestamp":1374346390,
  "count":1,
  "hash":"d3a0b8cddacab6b761fd61d9176013e9287384848b052362b6b4bc090a257c6a",
  "responses":[
     {
        "transaction_id":"000282870523",
        "tender_type":"CARD",
        "transaction_timestamp":"2018-07-20 13:53:09",
        "card_brand":"VISA",
        "transaction_type":"SALE",
        "last4":"4321",
        "card_expiration":"1218",
        "authorization_code":"096932",
        "authorization_message":"APPROVED",
        "request_amount":"345.98",
        "transaction_amount":"345.98",
        "first_name":"Robert",
        "last_name":"Smith",
        "keyed":"1",
        "swiped":"",
        "transaction_approved":"1",
        "cvv2_response":"N",
        "error":"",
        "error_code":"0",
        "error_message":"",
        "error_msg":"",
        "customer_feedback":"",
        "description":"Widgets: P/N BA-0523-C"
        "custom_id":"Customer 1234567890"
        "custom_data":"Widget BA-0523-C – Customer 1234567890"

      }
   ]
}