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:
- Sign in to SePay
- Go to Payment Gateway → Settings → IPN
- Enter your endpoint URL to receive IPNs
- 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
POST
https://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
Name | Type | Required | Description |
---|---|---|---|
timestamp | integer | Required | Unix timestamp when the notification was sent |
notification_type | string | Required | Type of notification: ORDER_PAID, RENEWAL_ORDER_PAID, TRANSACTION_VOID |
order | object | Required | Order information |
transaction | object | Required | Transaction information |
customer | object | Required | 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):
Type | When Sent | Action |
---|---|---|
ORDER_PAID | One-time payment successful | Update order, activate service |
RENEWAL_ORDER_PAID | Automatic recurring payment (next cycle) | Create new order, extend service |
TRANSACTION_VOID | Transaction successfully voided | Refund, cancel or suspend service |