Thông báo biến động số dư (IPN)

Khi nhận bất kỳ giao dịch nào thuộc tài khoản ngân hàng mà thuộc quyền quản lý của Merchant, SePay sẽ thực hiện thông báo cho Merchant bằng cách gọi API nhận biến động số dư (IPN) mà Merchant cung cấp trước đó.

Yêu cầu IPN URL

Phía Merchant có thể tùy ý lựa chọn cấu trúc đường dẫn để nhận biến động số dư và thông báo lại cho SePay để cấu hình tích hợp.

Định dạng IPN JSON payload

IPN JSON

{
  "gateway": "string",
  "transaction_date": "Y-m-d H:i:s",
  "account_number": "string",
  "bank_account_xid": "string",
  "va": "string | null",
  "payment_code": "string | null",
  "content": "string",
  "transfer_type": "credit | debit",
  "amount": "number",
  "reference_code": "string",
  "accumulated": "number",
  "transaction_id": "string"
}

Mô tả IPN JSON

gatewaystring

Tên cổng thực hiện. Ví dụ: MBBank, OCB.

transaction_datestring

Thời gian nhận giao dịch (ISO 8601 hoặc timestamp).

account_numberstring

Số tài khoản ngân hàng.

bank_account_xidstring

ID tài khoản ngân hàng tương ứng trong hệ thống.

vastring | null

Số VA (Virtual Account), nếu có.

payment_codestring | null

Mã thanh toán, nếu có.

contentstring

Nội dung giao dịch.

transfer_typestring

Loại giao dịch: credit (tiền vào) hoặc debit (tiền ra).

amountnumber

Số tiền giao dịch (số không âm).

reference_codestring | null

Mã tham chiếu FT.

accumulatednumber

Số dư sau giao dịch (hiện chưa hỗ trợ, mặc định = 0).

transaction_idstring

ID giao dịch.

Yêu cầu Response

Nội dung trả về với Content-Type là application/json
JSON fragment có dạng:

IPN JSON

{
  "success": true
}

Yêu cầu bảo mật

URL IPN phía Merchant cung cấp phải hỗ trợ SSL
Mặc định, SePay gọi tới IPN của Merchant kèm với header Authorization với giá trị là Apikey {API_KEY}, trong đó {API_KEY} là khóa bảo mật mà SePay sẽ cung cấp cho phía Merchant trước đó. Merchant có thể kiểm tra tính đúng đắn của header Authorization để xác nhận đó là request từ SePay.
Hoặc phía Merchant có thể lọc địa chỉ IP gọi tới, SePay sẽ cung cấp các IP address để Merchant thêm vào whitelist.
Hoặc Merchant có thể áp dụng cả 2 lớp bảo mật trên.

Điều kiện SePay thông báo IPN tới Merchant

Để một công ty (tổ chức) thuộc quyền quản lý của Merchant có thể nhận thông báo IPN từ SePay phải đạt đủ các điều kiện sau đây:

Công ty (tổ chức) sở hữu tài khoản ngân hàng nhận thông báo phải ở trạng thái Hoạt động (status: Active và active: 1), xem thêm tại API truy vấn chi tiết công ty (tổ chức).
Cấu hình transaction_amount của công ty (tổ chức) sở hữu tài khoản ngân hàng nhận thanh toán phải có giá trị lớn hơn 0 hoặc giá trị Unlimited, xem thêm tại API truy vấn cấu hình công ty (tổ chức).

Cơ chế retry

SePay sẽ thực hiện retry thông báo có giao dịch mới tới IPN của Merchant khi và chỉ khi bị lỗi mạng (kết nối mạng thất bại). Thời gian gọi cách nhau bằng phút, tăng dần theo dãy số Fibonacci.

Số lần gọi lại tối đa là 7 lần
Tối đa là 5 giờ kể từ khi gọi lần đầu thất bại
Network connect timeout của SePay là 5 giây
Thời gian chờ phản hồi tối đa của SePay là 8 giây

Yêu cầu chống trùng lặp giao dịch

Để tránh trùng lặp giao dịch khi phát sinh các sự cố với kết nối IPN của phía merchant tại cơ chế retry. SePay khuyến nghị merchant xử lý chống trùng lặp giao dịch khi nhận thông báo biến động giao dịch từ SePay thông qua IPN