Configure the SePay webhook and API key to accept payments

This guide walks through collecting the configuration values from SePay so your backend can accept bank-transfer payments: generate a static QR code (VietQR) and receive a webhook whenever money arrives in the account. The end result is 4 environment variables in your .env file. The SePay dashboard is in Vietnamese, so menu labels are quoted as they appear, with a translation.

Throughout, replace <bank-account-number>, <account-holder> and <api-key> with your real values; https://api.example.com/webhooks/sepay is an example backend webhook URL, and <ngrok-url> is your tunnel address when running locally.

Quick reference

The application needs these 4 environment variables to work:

SEPAY_BANK_NAME="MBBank"                        # Or another bank short name (e.g. Vietcombank, ACB)
SEPAY_ACCOUNT_NUMBER="<bank-account-number>"    # Account number
SEPAY_ACCOUNT_NAME="<account-holder>"           # Account holder name
SEPAY_WEBHOOK_API_KEY="<api-key>"               # Created under Webhook integration => Authentication type: API Key

1. Add a bank account

These details are used to generate the QR code and to reconcile bank transactions.

1. Log in to SePay.
2. Open the Tài khoản ngân hàng (Bank accounts) menu and click Thêm tài khoản ngân hàng (Add bank account).
3. Enter the bank and the account number. SePay usually looks up the account holder name automatically.
4. Copy the details into .env:
   • SEPAY_BANK_NAME: use the bank's short name or BIN code (e.g. MBBank, Vietcombank, Techcombank).
   • SEPAY_ACCOUNT_NUMBER: your account number.
   • SEPAY_ACCOUNT_NAME: the name shown on the account.

2. Configure the webhook and get the API key

The webhook lets SePay push a notification to your server every time someone completes a transfer. The authentication string you create here becomes SEPAY_WEBHOOK_API_KEY.

1. Open the Tích hợp Webhook (Webhook integration) menu and click Thêm Webhook (Add webhook).
2. Fill in the sections as follows:
   • Tên (Name): anything you like (e.g. MyApp Webhook).
   • (1) Chọn sự kiện (Event): under "Bắn WebHooks khi" (Fire webhooks when), choose Có tiền vào (Money in).
   • (2) Chọn điều kiện (Conditions):
     • Select the bank account you added in step 1.
     • For "Bỏ qua nếu nội dung giao dịch không có Code?" (Skip if the transfer note has no code?), choose Không (No) - the server extracts the code itself.
   • (3) Thuộc tính WebHooks (Webhook properties):
     • Gọi đến URL (Call URL): your backend's webhook endpoint (e.g. https://<ngrok-url>/webhooks/sepay when running locally, or https://api.example.com/webhooks/sepay in production).
     • Là WebHooks xác thực thanh toán? (Is this a payment verification webhook?): choose Không (No).
     • Gọi lại WebHooks khi? (Retry webhooks when?): tick HTTP Status Code không nằm trong phạm vi từ 200 đến 299 (status code outside 200-299) so SePay retries if your server has a temporary error.
   • (4) Cấu hình chứng thực WebHooks (Webhook authentication) - REQUIRED:
     • Kiểu chứng thực (Authentication type): choose API Key (or Bearer Token).
     • Giá trị (Value): a randomly generated secret string, or one you pick yourself. You will copy this string into .env.
     • Request Content type: application/json.
   • Trạng thái (Status): Kích hoạt (Enabled).
3. Click Thêm / Lưu (Add / Save).
4. Copy the value from section (4) into the SEPAY_WEBHOOK_API_KEY variable in .env.

Why is there no SEPAY_API_TOKEN?

With the static QR (VietQR) model, where payment results arrive from SePay through the webhook, you do not need an API key for calling back into SePay (SEPAY_API_TOKEN). The QR code can be generated from the base details alone (account number, bank, recipient name, amount), and SEPAY_WEBHOOK_API_KEY authenticates the webhook calls SePay makes to your server - that is enough to stay secure.

Troubleshooting