Instant Payment Notification V2 (IPN)

What is IPN?

Instant Payment Notification (IPN) is a service that notifies you of events related to Paygol transactions. You can use it to automate back-office and administrative functions, such as fulfilling orders, inserting points or coins, upgrading membership, tracking customers, and providing status and other information related to a transaction.

 

Information about the payment

Paygol will make a GET request to your IPN file when your customer completes a transaction. You can use this notification to kick-off order fulfillment, enable digital media downloads, store information in a customer relationship management (CRM) or accounting system, and so on.

 

How to receive the IPN information in my web page?

Paygol provides samples of Instant Payment Notification (IPN) code for popular development environments. For custom IPN files, you can use the following sample code as a starting point.

 

Example of implementation

<?php 

use Paygol\Notification;

/**
 * Merchant service ID
 *
 * @var int
 */
$service_id = "123";
/**
 * Merchant shared secret
 *
 * @var string
 */
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";

$ipn = new Notification($service_id, $shared_secret);

try {
    $ipn->validate();

    $params = $ipn->getParams();

    var_dump($params);
    
    // do something

    // Confirm reception
    $ipn->sendResponse(['OK'], 200);
} catch (\Exception $e) {
    $ipn->sendResponse(['error' => 'Validation error'], 400);
}

The above command returns JSON structured like this:

{
  "country": "ES",
  "currency": "USD",
  "custom": "Producto 1 - Producto 2 - Producto 3",
  "method": "teleingreso",
  "price": "10.00",
  "service_id": "123",
  "status": "completed",
  "transaction_id": "ZISS-A7Q8-RE2Z-S73W"
}

Notification handling

Handling notifications correctly is crucial to making sure your integration’s business logic works as expected.

 

Acknowledge notifications immediately

If your notification script performs complex logic, or makes network calls, it’s possible that the script would time out before Paygol sees its complete execution. Ideally, your notification handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that event.

 

Handle duplicate notifications

IPN endpoints might occasionally receive the same notification more than once. We advise you to guard against duplicated notifications receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.