API v4.14
Markdown

Postback Service v2.13

Real-time server-to-server notifications for purchases, rebills, subscription changes, reversals, chargebacks, and account updater events.

Not in the SDKs yet

Postback parsing and signature verification are not implemented in any of the four SDKs. There is no Postback model, no HMAC-verification helper, and no event-type enum for PURCHASE/RENEWAL/CHARGEBACK/etc. in any language's source tree. The gateway pushes postbacks to your endpoint independently of any outbound SDK call, so parse and verify them with your own HTTP framework and HMAC library, as shown below. See the SDKs.

Postback is our way of communicating important payment processing and customer related information to your system in real-time. A Postback is triggered by events such as new purchase requests, rebills, subscription cancellations, transaction reversal, chargebacks, and others. Merchants must provide us with a valid webpage URL that will accept Postback data.

Successful Response & Retries

In order to tell the service that the postback request was received successfully, merchants must simply reply with the string, 100 inside the <BODY> of the response. Note that anything other than "100" will be considered as a failed response. This does not reference the HTTPS response header.

In the event of a failed postback response, the service will attempt the postback three additional times:

  • 2nd attempt: 5 minutes after first failed attempt
  • 3rd attempt: 1 hour after the second failed attempt
  • 4th attempt: 1 day after the third failed attempt
DATA REPOST WARNING

Merchants must be aware that some data may be reposted for any reason. Your system should verify if a postback with the exact same data (e.g., Order ID / PO_ID) has already been recorded and prevent duplicate ledger entries.

Postback Event Types

The TYPE element describes the type of postback, corresponding to specific system or user actions:

Event Type Action Description
PURCHASE Product purchase, Reactivate subscription, Upgrade subscription, Capture transaction. Also used for 3D Secure approved transactions.
RENEWAL Subscription Renewal/Rebill.
SUBSCRIPTION TERMINATION REQUEST User requests subscription cancellation.
SUBSCRIPTION TERMINATION System cancels subscription.
CREDIT Credit transaction. Also triggered when TC40, RDR, Ethoca, or Verifi alerts result in automated refunds.
REVERSAL Void transaction.
CHARGEBACK Chargeback transaction.
BLACKLIST PAYMENT NUMBER Add credit card to black list.
PAYMENT AAU UPDATE Automatic Account Updater (e.g., Closed Account, Expiration Date Change, New Account Number).
TRANSACTION STATUS UPDATE Status changes from DECLINE to APPROVED. Also used for 3DS declined or failed transactions.
TRANSACTION ARN UPDATE ARN (acquirer reference number) value updated on a previously authorized transaction.
VERIFY Postback URL verification.
TC40 / RDR / RDR STANDALONE Chargeback Mitigation Alert Events (TC40 Alerts, RDR Disputes).

Postback Top-Level Elements

Element Name Description
TYPE Postback Event Type Name (Example: "PURCHASE").
CUSTOMER Contains customer record information (CUST_ID, CUST_EMAIL, CUST_BRCPFCNPJ, etc.).
MEMBERSHIP Contains membership (subscription) record information. Includes SITE and ORIGINAL_TRANSACTION_DATA sub-elements.
PURCHASE_ORDER Contains purchase order (invoice record) information (PO_ID, PO_VALUE, CURRENCY, XTL_UDFxx, etc.).
LINE_ITEM Contains line item parameters (LI_AMOUNT, LI_TYPE, PROD_ID, etc.).
BILL_ADDRESS / SHIP_ADDRESS Contains billing and shipping address parameters.
PAYMENT Contains billing account information (PAYMENT_TYPE, PMT_BIN, PAYMENT_HASH, MERCH_ACCT_ID, etc.).
TRANSACTION Contains important transaction information (TRANS_ID, TRANS_STATUS_NAME, PROCESSOR_RESPONSE, etc.).
SOURCE / MESSAGE Contains the originating source of the event (used in Alerts: "TC40", "RDR", "ETHOCA", "VERIFI") and a short description.

Acknowledging a postback

Reply to every postback with the literal body text 100 to acknowledge receipt. Anything else is treated as a failure and retried per the schedule above.

100

Verifying the postback signature

Postback signature validation is available on v2.9+ to enhance security. The gateway computes an HMAC-SHA256 over the raw JSON body using your postback secret; recompute the same HMAC on your end and compare it to the signature the gateway sends so you can reject forged postback traffic.

<?php
/* Postback signature is available on v2.9+ to enhance security. */
$secret = "1a63f9840a0a16b14d11ce386ac8123a";
$body = '{"EVENT": {"secret":"1a63f9840a0a16b14d11ce386ac8123a", "TYPE":"PURCHASE"}}';
$sig = hash_hmac('sha256', $body, $secret);
echo($sig);
?>

Example postback payloads

Postbacks are pushed by the gateway to your merchant URL, so they aren't modeled as outbound REQUEST_ACTION calls the way the payment API is. Below is one representative PURCHASE event body. VERIFY postbacks (used to confirm your endpoint is reachable), CHARGEBACK postbacks (populated TRANSACTION fields describing the dispute), and PAYMENT AAU UPDATE postbacks (populated PAYMENT fields describing the card change) follow the same top-level shape with different TYPE values and populated sub-elements.

{
  "TYPE": "PURCHASE",
  "CUSTOMER": {
    "CUST_ID": 9928102,
    "CUST_EMAIL": "customer@example.com",
    "CUST_BRCPFCNPJ": ""
  },
  "PURCHASE_ORDER": {
    "PO_ID": 77281920,
    "PO_VALUE": 49.99,
    "CURRENCY": "USD",
    "XTL_UDF01": "INV-999"
  },
  "LINE_ITEM": {
    "LI_AMOUNT": 49.99,
    "LI_TYPE": "PRODUCT",
    "PROD_ID": "SKU-992"
  },
  "BILL_ADDRESS": {
    "CUST_ADDRESS1": "123 Main St",
    "CUST_CITY": "Austin",
    "CUST_STATE": "TX",
    "CUST_ZIP": "78701",
    "CUST_COUNTRY": "US"
  },
  "PAYMENT": {
    "PAYMENT_TYPE": "CREDITCARD",
    "PMT_BIN": "411111",
    "PAYMENT_HASH": "a1b2c3d4e5f6",
    "MERCH_ACCT_ID": 110203
  },
  "TRANSACTION": {
    "TRANS_ID": 8839201112,
    "TRANS_STATUS_NAME": "APPROVED",
    "PROCESSOR_RESPONSE": "AUTH99"
  }
}