How IPN works in SePay Payment Gateway

Configure IPN URL

IPN URL is configured on the merchant management page in SePay:

1. Log in to SePay
2. Go to Payment Gateway → Configuration → IPN
3. Enter your endpoint URL to receive IPN
4. Save configuration

Request from SePay to Merchant

Headers:

X-Secret-Key: <secret_key>
Content-Type: application/json

Parameter list

Example request body:

{
  "timestamp": 1757058220,
  "notification_type": "ORDER_PAID",
  "order": {
    "id": "e2c195be-c721-47eb-b323-99ab24e52d85",
    "order_id": "NPSETVI00101000042R",
    "order_status": "CAPTURED",
    "order_currency": "VND",
    "order_amount": "50000.00",
    "order_invoice_number": "SUB_202509_001",
    "custom_data": [],
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "ip_address": "14.xxx.xxx.xxx",
    "order_description": "Premium package recurring payment for September 2025"
  },
  "transaction": {
    "id": "384c66dd-41e6-4316-a544-b4141682595c",
    "payment_method": "CARD",
    "transaction_id": "68ba94ac80123",
    "transaction_type": "PAYMENT",
    "transaction_date": "2025-09-01 00:00:15",
    "transaction_status": "APPROVED",
    "transaction_amount": "50000",
    "transaction_currency": "VND",
    "authentication_status": "AUTHENTICATION_SUCCESSFUL",
    "card_number": "4111XXXXXXXX1111",
    "card_holder_name": "NGUYEN VAN A",
    "card_expiry": "12/26",
    "card_funding_method": "CREDIT",
    "card_brand": "VISA"
  },
  "customer": {
    "id": "bae12d2f-0580-4669-8841-cc35cf671613",
    "customer_id": "CUST_001"
  }
}

Handle IPN endpoint:

Route::post('/payment/ipn', function(Request $request) {
  // Verify secret key
  if ($request->header('X-Secret-Key') !== $secretKey) {
      return response()->json(['error' => 'Unauthorized'], 401);
  }
 
  $data = $request->json()->all();
 
  if ($data['notification_type'] === 'ORDER_PAID') {
      $order = Order::where('invoice_number', $data['order']['order_invoice_number'])->first();
      $order->status = 'paid';
      $order->save();
  }
 
  // Return 200 to acknowledge receipt
  return response()->json(['success' => true], 200);
});

The merchant Secret Key and how to regenerate it

The Payment Gateway has two different Secret Keys:

The two keys are independent: regenerating the merchant Secret Key does not change the Secret Key on the IPN tab, and vice versa.

When to regenerate

The merchant Secret Key is displayed only once, when it is created. After that the Merchant information page shows * characters only. Regenerate the key if you have lost it, or if it may have leaked (for example it was committed to Git, sent over chat, or someone who held it has left the company).

Steps

Only a SuperAdmin or Admin account of the company can do this.

1. Go to Payment Gateway → Configuration → Merchant information (Cổng thanh toán → Cấu hình → Thông tin đơn vị).
2. Check the Test Mode switch in the top right corner. You can only regenerate the key of the environment currently selected; to regenerate the LIVE key, turn Test Mode off first.
3. Click Tạo lại (Regenerate) on the Secret Key row.
4. In the confirmation dialog, check the environment badge (LIVE or Test mode).
5. Type your merchant code (Merchant ID, shown under the merchant name) into the confirmation field, then click Tạo lại Secret Key (Regenerate Secret Key).
6. Copy the new key from the dialog that opens, then click Tôi đã lưu key (I have saved the key).

After regenerating

The new key works immediately for both the checkout pages and the API; there is no period in which both keys work. Update the new key everywhere the old one was used:

• Environment variables or configuration files on your server.
• The WooCommerce or Haravan plugin, or any other CMS integration.
• PHP / Node.js SDK configuration.
• Internal services that sign payment forms themselves.

Limits and common errors