Balance Change Notification (IPN)

When receiving any transaction belonging to a bank account managed by the Merchant, SePay will notify the Merchant by calling the balance change notification API (IPN) that the Merchant provided earlier.

IPN URL Requirements

The Merchant can freely choose the path structure to receive balance change notifications and notify SePay to configure the integration.

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

Gateway name that executed the transaction. 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 applicable.

payment_codestring | null

Payment code, if applicable.

contentstring

Transaction content/description.

transfer_typestring

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

amountnumber

Transaction amount (non-negative number).

reference_codestring | null

FT reference code.

accumulatednumber

Balance after transaction (currently not supported, default = 0).

transaction_idstring

Transaction ID.

Response Requirements

Response content with Content-Type as application/json
JSON fragment format:

IPN JSON

{
   "success": true
}

Security Requirements

The IPN URL provided by the Merchant must support SSL
By default, SePay calls the Merchant's IPN with an Authorization header with value Apikey {API_KEY}, where {API_KEY} is the security key that SePay will provide to the Merchant beforehand. The Merchant can verify the correctness of the Authorization header to confirm that the request is from SePay.
Alternatively, the Merchant can filter the calling IP address. SePay will provide IP addresses for the Merchant to add to the whitelist.
Or the Merchant can apply both security layers above.

Conditions for SePay to Send IPN Notifications to Merchant

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

The company (organization) owning the receiving bank account must be in Active status (status: Active and active: 1). See more at API to query company (organization) details.
The transaction_amount configuration of the company (organization) owning the payment receiving bank account must have a value greater than 0 or value Unlimited. See more at API to query company (organization) configuration.

Retry Mechanism

SePay will retry notifying new transactions to the Merchant's IPN if and only if a network error occurs (network connection failure). The retry interval is in minutes, increasing according to the Fibonacci sequence.

Maximum retry attempts: 7 times
Maximum duration: 5 hours from the first failed call
SePay's network connect timeout: 5 seconds
SePay's maximum response wait time: 8 seconds

Transaction Deduplication Requirements

To avoid transaction duplication when issues occur with merchant's IPN connection during the retry mechanism, SePay recommends merchants implement transaction deduplication when receiving transaction change notifications from SePay through IPN

Next Steps

After configuring IPN successfully, you can:

Webhook Events - Receive notifications for account linking/unlinking events
Transaction List API - Query transaction history
Transaction Detail API - View specific transaction details
Update Webhook API - Manage webhook configuration

Note

Ensure you handle transaction deduplication by checking transaction_id before processing IPN.