Create Webhooks

Instructions for creating and explaining how Webhooks work. Every time a transaction occurs, SePay will fire WebHooks, your sales application will know that the customer has paid and change the order status.

Sandbox Environment

If you need a test environment, register an account at my.dev.sepay.vn. Here you can create simulated transactions and webhooks for development purposes. After registration, please contact SePay to activate your account.

Steps to Integrate WebHooks

Access WebHooks

Go to the WebHooks menu on SePay dashboard.

Add a New WebHook

Click the + Add webhooks button at the top right.

Configure WebHook Settings

Fill in the following information:

1. Name: Any name to identify the webhook.

2. Select Event: Choose when to trigger the webhook: money in, money out, or both.

3. Select Conditions:

When bank account is: Choose the bank account(s) that will trigger webhooks. To filter by specific virtual accounts (VA), check Filter by virtual account and select the desired VAs.
Ignore if no payment code found: If selected, SePay will NOT send webhooks when the payment code is not detected in the transfer content.

Tip

Configure payment code recognition under Company → General Settings → Payment Code Structure.

4. WebHook Attributes:

Call URL: The endpoint that will receive webhooks. To build a custom receiver, see the programming guide.
Is this a payment verification WebHook?: Select Yes if this webhook is used to verify payments for your website/application.
Retry WebHook when: SePay will automatically retry if the HTTP Status Code is not between 200 and 299.

5. Authentication Configuration:

OAuth 2.0: Requires Access Token URL, Client ID, and Client Secret. See configuration guide.
API Key: SePay sends the header Authorization: Apikey YOUR_API_KEY. You must select a Request Content Type.
No authentication: SePay does not send any authentication header. You must select a Request Content Type.

Supported Request Content Types

application/json, multipart/form-data, application/x-www-form-urlencoded

Complete

Click Add to finish the integration.

WebHook Payload Data

SePay sends a POST request with the following JSON payload:

JSON

{
  "id": 92704,
  "gateway": "Vietcombank",
  "transactionDate": "2023-03-25 14:02:37",
  "accountNumber": "0123499999",
  "code": null,
  "content": "transfer to buy iphone",
  "transferType": "in",
  "transferAmount": 2277000,
  "accumulated": 19077000,
  "subAccount": null,
  "referenceCode": "MBVCB.3278907687",
  "description": ""
}

idinteger

Transaction ID on SePay

gatewaystring

Bank brand name

transactionDatestring

Transaction time from the bank

accountNumberstring

Bank account number

codestring

Payment code, automatically detected by SePay based on Company → General Settings. Can be null if not detected.

contentstring

Transfer description

transferTypestring

Transaction type: in = deposit, out = withdrawal

transferAmountinteger

Transaction amount (VND)

accumulatedinteger

Account balance (accumulated)

subAccountstring

Sub-account (virtual account / VA). Can be null.

referenceCodestring

Reference code from SMS

descriptionstring

Full SMS message content

Recognizing Successful WebHooks

When receiving a webhook from SePay, your server must respond correctly for SePay to mark it as successful:

OAuth 2.0

Response body: {"success": true} — HTTP Status Code: 201

API Key

Response body: {"success": true} — HTTP Status Code: 200 or 201

No authentication

Response body: {"success": true} — HTTP Status Code: 200 or 201

Important

If the response does not meet these conditions, SePay will consider the webhook failed.

Testing WebHooks

Demo account: Go to Transactions → Simulate Transaction to create a test transaction. See the Simulate Transaction guide.
Real account: Send a small amount to your bank account to trigger a real transaction.
View logs: Go to Logs → WebHooks Log to see all sent webhooks.
Per-transaction view: Go to Transactions → Auto column → select Pay to see webhooks for each transaction.

Automatic Retry

SePay automatically retries webhooks when the network connection fails, or when your configured retry conditions are met. Retry intervals increase following the Fibonacci sequence. Retry Parameters:

Max retry attempts

Max retry duration

5 hours — From the first failed attempt

Connection timeout

5 seconds

Response timeout

8 seconds — Maximum wait time for a response

Note

SePay will NOT retry a webhook if the network connection succeeds but the webhook status is failed, unless retry conditions you configured are met.

Preventing Duplicate Transactions

Recommendation

To avoid processing duplicate transactions during retries, validate the uniqueness of the id field, or combine it with referenceCode, transferType, and transferAmount from the webhook payload.

Manual Retry

You can manually trigger a webhook retry in two ways:

Go to Transaction Details → Sent WebHooks → Retry
Go to Logs → WebHooks Log → Retry