IPN

IPN is an automated payment notification mechanism that a payment gateway (e.g. SePay, PayPal, Stripe...) sends to your server when there is a change in transaction status — such as successful, failed, or canceled payment.


Configure IPN URL

  • Configure your IPN URL in the SePay merchant dashboard:
  1. Sign in to SePay
  2. Go to Payment Gateway → Settings → IPN
  3. Enter your endpoint URL to receive IPNs
  4. Save the configuration
Important
  • The IPN URL must use HTTPS.
  • Your endpoint must return HTTP status code 200 to acknowledge receipt.

Request from SePay to Merchant

POSThttps://your-url (the URL you configured in IPN)
  -H "X-Secret-Key: <secret_key>" \
  -H "Content-Type: application/json" \
Note

X-Secret-Key: Secret key used for authentication (only present when merchant config auth type = SECRET_KEY).

  • Parameter list
NameTypeRequiredDescription
timestamp
integerRequired

Unix timestamp when the notification was sent

notification_type
stringRequired

Type of notification: ORDER_PAID, RENEWAL_ORDER_PAID, TRANSACTION_VOID

order
objectRequired

Order information

transaction
objectRequired

Transaction information

customer
objectRequired

Customer information

  • Ví dụ request body:
REQUEST
{
  "timestamp": 1757058220,
  "notification_type": "ORDER_PAID",
  "order": {
    "id": "256",
    "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": "Recurring payment for Premium plan - September 2025"
  },
  "transaction": {
    "id": "189",
    "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": "45",
    "customer_id": "CUST_001"
  }
}
  • Xử lý IPN endpoint:
PHP
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);
});
  • Các loại thông báo (notification_type):
TypeWhen SentAction
ORDER_PAIDOne-time payment successfulUpdate order, activate service
RENEWAL_ORDER_PAIDAutomatic recurring payment (next cycle)Create new order, extend service
TRANSACTION_VOIDTransaction successfully voidedRefund, cancel or suspend service