Balance Change Notification (IPN)

When any transaction occurs on a bank account under the Merchant’s management, SePay will notify the Merchant by calling the Balance Change Notification API (IPN) endpoint previously provided by the Merchant.

IPN URL Requirement

The Merchant can freely choose the endpoint path structure to receive balance change notifications and inform SePay in advance for integration configuration.

IPN JSON Payload Format

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"
}

IPN JSON Description

gatewaystring

Execution gateway name. For example: MBBank, OCB.

transaction_datestring

Transaction received time (ISO 8601 or timestamp).

account_numberstring

Bank account number.

bank_account_xidstring

Corresponding bank account ID in the system.

vastring | null

Virtual Account number, if any.

payment_codestring | null

Payment code, if any.

contentstring

Transaction description/content.

transfer_typestring

Transaction type: credit (incoming) or debit (outgoing).

amountnumber

Transaction amount (non-negative number).

reference_codestring | null

FT reference code.

accumulatednumber

Account balance after the transaction (currently not supported, default value = 0).

transaction_idstring

Transaction ID.

Response Requirements

  • The response content type must be application/json
  • The JSON fragment must have the following format:
IPN JSON
{
  "success": true
}

Security Requirements

  • The Merchant’s IPN URL must support SSL (HTTPS).
  • By default, SePay calls the Merchant’s IPN endpoint with the Authorization header in the format Apikey {API_KEY}, where {API_KEY} is the security key previously provided by SePay. The Merchant can validate the Authorization header to confirm that the request originates from SePay.
  • Alternatively, the Merchant may filter incoming requests by IP address. SePay will provide a list of IP addresses for whitelisting.
  • The Merchant may also apply both security mechanisms simultaneously.

Conditions for SePay to Send IPN Notifications

For a company (organization) under the Merchant’s management to receive IPN notifications from SePay, all of the following conditions must be met:

  • The company (organization) that owns the bank account receiving notifications must be in Active status (status: Active and active: 1). See details at Get Company Details API.
  • The transaction_amount configuration of the company (organization) owning the receiving bank account must be greater than 0 or set to Unlimited. See details at Get Company Configuration API.

Retry Mechanism

SePay will retry sending transaction notifications to the Merchant’s IPN endpoint only in the event of a network error (connection failure). Retry intervals are measured in minutes and increase according to the Fibonacci sequence.

  • Maximum retry attempts: 7
  • Maximum retry duration: 5 hours from the first failed attempt
  • SePay network connection timeout: 5 seconds
  • Maximum response wait time: 8 seconds

Duplicate Transaction Prevention

To avoid duplicate transactions caused by IPN retry mechanisms during connection issues on the Merchant’s side, SePay recommends that Merchants implement deduplication logic when handling transaction balance change notifications received via IPN.

Previous page
—
Next page
—