Skip to content

IPN (Instant Payment Notification)

We send payment notifications to the IPN URL you provide when initiating payments. This applies to both HPP (Hosted Payment Page) and H2H (Host-to-Host) payment flows. The IPN will contain the payment details and status updates.

IPN Parameters

Parameter Description Example
identifier The unique identifier of the payment that you have sent when initiating the payment "YOUR_UNIQUE_IDENTIFIER"
status Status of the event the notification is about "success"
signature Hash for the authentication. Uppercase of sha256 of {identifier}{timestamp} signed with your secret_key
timestamp The timestamp when the IPN was sent. Use it to generate and check signature 1631533200
data The payment details. See Payment Details parameters

Signature Generation

To generate the signature, you should hash the concatenation of the identifier and timestamp with your secret_key using sha256 and convert it to uppercase.

Security Recommendation

You should always verify the signature of the IPN to ensure that the notification is authentic.

Code Examples

The PHP example is the "source of truth" for the signature generation:

$signature = strtoupper(hash_hmac('sha256', $identifier.$timestamp, $secret_key));

const signature = crypto.createHmac('sha256', secret_key).update(`${identifier}${timestamp}`).digest('hex').toUpperCase();

IPN Types

  • Checkout - type: "checkout"
  • Chargeback Initiated - type: "chargeback_initiated"
  • Chargeback Resolved - type: "chargeback_resolved"

Checkout IPN Data

Parameter Description Example
trx The internal unique identifier of the payment. DO NOT use this to generate and check signature. "UNIQUE_PAYMENT_ID"
amount The amount of the payment or chargeback related to the IPN 100.00
currency The currency of the payment or chargeback related to the IPN "USD"
type The type of the IPN. "checkout"
timestamp The timestamp of the payment or chargeback related to the IPN. DO NOT use this to generate and check signature "2021-04-05 00:00:00"

Chargeback Initiated IPN Data

Parameter Description Example
trx The internal unique identifier of the payment. DO NOT use this to generate and check signature. "UNIQUE_PAYMENT_ID"
amount The amount of the chargeback 100.00
type The type of the IPN. "chargeback_initiated"
initiated_at The timestamp of the chargeback initiation. DO NOT use this to generate and check signature "2021-04-05 00:00:00"
message The message of the chargeback. "Chargeback initiated on this transaction"
timestamp The timestamp of the related payment URL creation. DO NOT use this to generate and check signature "2021-04-05 00:00:00"
currency The currency of the chargeback "USD"

Chargeback Resolved IPN Data

Parameter Description Example
trx The internal unique identifier of the payment. DO NOT use this to generate and check signature. "UNIQUE_PAYMENT_ID"
amount The amount of the chargeback 100.00
type The type of the IPN. "chargeback_resolved"
in_favor_of The party in favor of the chargeback. "client", "merchant"
timestamp The timestamp of the chargeback resolution. DO NOT use this to generate and check signature "2021-04-05 00:00:00"
currency The currency of the chargeback "USD"

Handling IPN

When you receive an IPN, you should:

  1. Verify the signature using your secret_key
  2. Check the identifier matches a payment you initiated
  3. Process the payment status according to the IPN type
  4. Return HTTP 200 to acknowledge receipt

Example IPN Handler (PHP)

<?php
// Get IPN data
$ipn_data = json_decode(file_get_contents('php://input'), true);

// Extract parameters
$identifier = $ipn_data['identifier'];
$timestamp = $ipn_data['timestamp'];
$signature = $ipn_data['signature'];
$status = $ipn_data['status'];
$data = $ipn_data['data'];

// Verify signature
$expected_signature = strtoupper(hash_hmac('sha256', $identifier.$timestamp, $your_secret_key));

if ($signature === $expected_signature) {
    // Signature is valid, process the payment
    if ($status === 'success') {
        // Payment successful
        // Update your database, fulfill order, etc.
    } else {
        // Payment failed or other status
        // Handle accordingly
    }

    // Return 200 to acknowledge
    http_response_code(200);
    echo "OK";
} else {
    // Invalid signature
    http_response_code(400);
    echo "Invalid signature";
}
?>

Next Steps