IPN

An IPN (Instant Payment Notification) is an HTTP POST request sent by the gateway to your ipnUrl after a transaction event occurs. It delivers the final payment status, consumer details, subscription state, and any metadata you attached to the original request.

To learn how to handle IPNs, see the IPN processing guide.

IPN validation

Each IPN includes an x-signature in the headers, generated using a SHA-256 hash. This signature contains a parameter called s code, which acts as an authentication key. The s code is provided by our Merchant Support team and is used exclusively for IPN validation. To update your s code, contact Merchant Support.

To validate the IPN, both you and the Gateway each generate the x-signature, which you then compare. An identical x-signature indicates that the IPN can be trusted.

Transaction validation

For transaction events (sales, refunds, chargebacks):

SHA-256(s code + transactionId + status)

{
  "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"
  }
}

Subscription validation

For subscription events (rebills, recoveries, cancellations):

SHA-256(s code + subscription.id + subscription.status)

{
  "consumer": {
    "id": "111111954",
    "email": "[email protected]",
    "firstName": "Jonny",
    "lastName": "Sonny",
    "country": "USA",
    "zip": "11166"
  },
  "metadata": {
    "chargeId": "eef1fc1c-bfc1-110a-1111-15a14fa1111673"
  },
  "subscription": {
    "id": "111111222",
    "cycle": 0,
    "status": "canceled",
    "cancelDate": "2024-10-01 20:11:44",
    "timezone": "+02:00",
    "eventTime": "2024-09-30 17:32:25"
  }
}

IPN response format and retry policy

The gateway expects one of the following HTTP status codes in response to an IPN: 200, 201, or 202.

If your server fails to return one of these codes, the gateway retries the IPN five more times:

Retry	Delay after previous attempt
1st retry	5 seconds
2nd retry	55 seconds
3rd retry	60 seconds
4th retry	480 seconds
5th retry	900 seconds

Respond as quickly as possible and process the IPN asynchronously. If all five retries are exhausted without a successful acknowledgement, use the Feed API to poll the final transaction status.

IPN structure

Payment object

Attribute	Description
`action`	Payment type (`charge` , `credit`, `chargeback`)
`code`	Payment code according to which the payment has been created
`amount`	Payment amount
`currency`	Payment currency
`amountUsd`	Amount of operation in USD
`description`	Payment code description
`descriptor`	Name of the company/website that deducted money
`mode`	Payment mode (either `sale` or `auth`)
`orderId`	Unique order identifier
`source`	Payment method
`status`	Payment status (success, fail, or pending)
`transactionId`	Unique payment identifier
`url`	Link to the ACS in the issuer domain

Consumer object

Attribute	Description
`city`	Customer's city name
`country`	Customer's country name
`email`	Customer's email address
`externalId`	Unique customer identifier within the merchant's system
`firstName`	Customer's first name
`id`	Unique customer identifier within the Gateway's system
`lastName`	Customer's last name
`phone`	Customer's phone number
`state`	Customer's state name
`zip`	Zip code

Subscription object

📘
Note
There is no subscription object for one-time payments.

Attribute	Description
`cancelDate`	Subscription cancel date
`cycle`	Sequential number of recurring payments in a subscription (0 - subscription has an initial payment, n - subscription has n recurrent payments)
`id`	Subscription ID
`renewalDate`	Subscription renewal date
`status`	Subscription Status (active or canceled)

Source object

Attribute	Description
`method`	Payment method
`number`	Card or account number
`paymentAccountId`	Customer's payment details saved in the Gateway
`disabled`	Indicates whether `paymentAccountId` is enabled for a quick sale
`bankName`	Bank name
`bankCountry`	Bank country

Metadata object

Whatever you pass in the metadata field of the payment request is returned to you in the IPN. You can use this parameter to tie transactions to the orders in your system, for example.

Failed rebill IPN

A failed recurring charge emits a standard charge IPN with payment.status: "failed" and a subscription object. The subscription object is what distinguishes a rebill IPN (successful or failed) from a one-time payment IPN.

{
  "payment": {
    "code": 5046,
    "description": "Closed account",
    "action": "charge",
    "mode": "sale",
    "status": "failed",
    "codeCategory": 4,
    "amount": 99.99,
    "currency": "EUR",
    "amountUsd": 110.50,
    "orderId": "00000001",
    "transactionId": "900000001",
    "descriptor": "example_descriptor",
    "source": {
      "method": "card",
      "number": "411111****1111",
      "paymentAccountId": "00000000-0000-0000-0000-000000000000",
      "brand": "visa",
      "bankName": "EXAMPLE BANK",
      "bankCountry": "DEU",
      "expirationMonth": "12",
      "expirationYear": "30",
      "disabled": false
    },
    "timestamp": {
      "dateTime": "2026-01-01 12:00:00",
      "timezone": "+02:00",
      "unixTime": 1767268800
    },
    "vat": {
      "amount": 16.67,
      "amountUsd": 18.45
    }
  },
  "consumer": {
    "id": "CUST_100000001",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "country": "DEU"
  },
  "metadata": {
    "extra": "dummy_metadata_hash_value_1234567890"
  },
  "subscription": {
    "id": "100000001",
    "cycle": 1,
    "status": "active",
    "renewalDate": "2026-01-01 12:00:00",
    "timezone": "+02:00",
    "eventTime": "2025-01-01 10:00:00"
  }
}

Failed rebill events are also observable via the Feed API by querying transactions for the relevant subscription ID.