Process IPNs

An IPN (Instant Payment Notification), also referred to as a postback or callback, provides essential transaction details after a payment event. The information it contains includes payment status, transaction amount, currency, customer details, and any metadata you attached to the original request.

For the full IPN structure, validation algorithm, and retry policy, see IPN reference.

Determine the transaction outcome

There are two options to determine whether a transaction was successful or failed.

Option 1: Run IPN-handling code in PHP

A payment.code of 0 always indicates a successful transaction. Any other value indicates a decline.

The following PHP example automates this check:

$ipn = json_decode(file_get_contents('php://input'));
if ($ipn->payment->code === 0) {
    // save success
} else {
    // save decline
}

If the transaction is unsuccessful, you will see a specific decline code, instead of 0 and the respective code description.

For example:

"code": 5013,
"description": "Invalid amount"

See Issuer decline codes & Merchant Advice Codes and Gateway decline codes for the full list of codes.

Option 2: Inspect mode and status manually

In the IPN, look for payment.mode and payment.status:

• mode indicates the payment type: sale or auth.
• status indicates the outcome: success, fail, or pending.

For example, a successful sale looks like this:

"mode": "sale",
"status": "success"

Also, check if code=0 which indicates a successful transaction.

Acknowledge the IPN

Respond with HTTP 200, 201, or 202 as quickly as possible to acknowledge receipt. If your server does not return one of these codes, the gateway retries the IPN. Respond immediately and handle any processing asynchronously.

Example IPN payload

The following is an example of a declined card payment delivered over IPN:

{
  "payment": {
    "code": 5082,
    "description": "Negative online CAM, dCVV, iCVV, CVV, or CAVV results or Offline PIN authentication interrupted",
    "action": "charge",
    "mode": "sale",
    "status": "fail",
    "codeCategory": 3,
    "amount": 12.09,
    "currency": "USD",
    "orderId": "2525616924",
    "transactionId": "718641118",
    "descriptor": "TRO***029",
    "source": {
      "method": "card",
      "number": "518868****7707",
      "paymentAccountId": "1ac7f157-a334-4276-ae52-67f7e70e96c4",
      "brand": "mastercard",
      "expirationMonth": "**",
      "expirationYear": "**",
      "disabled": false,
      "bankName": "BENDIGO AND ADELAIDE BANK, LTD.",
      "bankCountry": "AUS"
    },
    "apiPaymentSource": "paymentAccountId",
    "timestamp": {
      "dateTime": "2025-10-21 11:50:34",
      "timezone": "+02:00",
      "unixTime": 1761040234
    },
    "vat": {
      "amount": 0,
      "amountUsd": 0
    }
  },
  "consumer": {
    "id": "151925232",
    "email": "lc***[email protected]",
    "firstName": "Lachlan",
    "lastName": "C",
    "country": "AUS",
    "state": "NSW",
    "zip": "***"
  },
  "metadata": {
    "orderId": "6***1"
  }
}