VaultWallet

How to use Vault Wallet to submit a payin in Vietnam.

Payin by Vault Wallet

This endpoint allows you to submit a payin by Vault Wallet in Vietnam.

Vault Wallet payins in Vietnam require the customer to bind the wallet account before submitting the payin request.

The Vault Wallet flow contains three steps:

1. Create a vault token.

2. Submit a payin using the vault token.

3. Void the vault token when the wallet account no longer needs to be used.

Vault Wallet payins in Vietnam support refund.

Vault Wallet payins in Vietnam support real-time payment processing.

ZaloPay AutoDebit supports a minimum debit amount of 1,000 VND, a maximum debit amount of 20,000,000 VND per transaction, and a monthly accumulated limit of 100,000,000 VND.

There is no separate daily limit or transaction count limit. If max_amount is set to 0 when creating a binding, no fixed binding cap is applied. The actual debit amount is still limited by the user's available balance.

---

Step 1: Create Vault

POST https://gateway-test.pagsmile.com/vault/create

Use this endpoint to create a vault token for the customer's ZaloPay wallet account.

After the request is submitted successfully, redirect the customer to the auth_url returned in the response to complete wallet authorization.

Request Body

Parameter	Type	Required	Constraints	Description
app_id	string	Yes	Max length: 32 characters	The merchant application ID assigned by Pagsmile.
timestamp	string	Yes	Format: yyyy-MM-dd HH:mm:ss; max length: 19 characters	Request timestamp.
version	string	Yes	Fixed value: 2.0	API version.
type	string	Yes	Fixed value: wallet_account	Vault account type.
wallet_account.region	string	Yes	Fixed value: VNM	Wallet account region.
wallet_account.method	string	Yes	Fixed value: Wallet	Payment method.
wallet_account.channel	string	Yes	Fixed value: Zalopay	Wallet channel.
wallet_account.uid	string	Yes	Merchant-defined unique ID	The unique customer ID in the merchant system.
wallet_account.device_type	string	Yes	Example: WEB	Customer device type.
wallet_account.return_url	string	Yes	Valid URL	The URL to redirect the customer after wallet authorization.

Request Sample

{
  "app_id": "1668********80",
  "timestamp": "2022-01-01 03:54:01",
  "version": "2.0",
  "type": "wallet_account",
  "wallet_account": {
    "region": "VNM",
    "method": "Wallet",
    "channel": "Zalopay",
    "uid": "test001",
    "device_type": "WEB",
    "return_url": "https://demo.return.url"
  }
}

Response

{
  "code": "10000",
  "msg": "Success",
  "auth_url": "https://binding.zalopay.vn/?binding_token=260********Qan",
  "token": "wa_b74********7364e",
  "type": "wallet_account",
  "timestamp": "2026-07-01 02:20:07"
}

---

Step 2: Pay with Vault

POST https://gateway.pagsmile.com/trade/pay

Use the vault_token returned from Step 1 to submit a ZaloPay Vault Wallet payin.

Request Body

Parameter	Type	Required	Constraints	Description
app_id	string	Yes	Max length: 32 characters	The merchant application ID assigned by Pagsmile.
out_trade_no	string	Yes	Max length: 64 characters; must be unique	The merchant-side order ID.
method	string	Yes	Fixed value: Wallet	Payment method.
channel	string	Yes	Fixed value: Zalopay	Wallet channel.
order_amount	string	Yes	Amount range to be confirmed	Payment amount.
order_currency	string	Yes	Fixed value: VND	Payment currency.
subject	string	Yes	Max length: 128 characters	Order title or product name.
content	string	Yes	Max length: 255 characters	Order description.
notify_url	string	Yes	Valid URL	The URL used to receive asynchronous payment notifications.
return_url	string	Yes	Valid URL	The URL to redirect the customer after payment.
buyer_id	string	Yes	Merchant-defined unique ID	The unique customer ID in the merchant system.
timestamp	string	Yes	Format: yyyy-MM-dd HH:mm:ss; max length: 19 characters	Request timestamp.
vault_token	string	Yes	Token get from Create Vault	The vault token returned from the Create Vault request.

Request Sample

{
  "app_id": "166********280",
  "out_trade_no": "out_no_57********91",
  "method": "Wallet",
  "channel": "Zalopay",
  "order_amount": "100",
  "order_currency": "VND",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "notify_url": "http://merchant/callback/success",
  "return_url": "https://www.merchant.com",
  "buyer_id": "test001",
  "timestamp": "2022-01-01 03:54:01",
  "vault_token": "wa_b74********64e"
}

Response

{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "b25y********787D4",
  "trade_no": "2026********010",
  "out_trade_no": "out_no_574********291",
  "web_url": "",
  "trade_status": "PROCESSING"
}

---

Step 3: Void Vault

POST https://gateway.pagsmile.com/vault/void

Use this endpoint to void a ZaloPay wallet vault token.

Request Body

Parameter	Type	Required	Constraints	Description
app_id	string	Yes	Max length: 32 characters	The merchant application ID assigned by Pagsmile.
timestamp	string	Yes	Format: yyyy-MM-dd HH:mm:ss; max length: 19 characters	Request timestamp.
version	string	Yes	Fixed value: 2.0	API version.
vault_token	string	Yes	Not specified	The vault token to be voided.
type	string	Yes	Fixed value: wallet_account	Vault account type.

Request Sample

{
  "app_id": "16********280",
  "timestamp": "2022-01-01 03:54:01",
  "version": "2.0",
  "vault_token": "wa_b74********64e",
  "type": "wallet_account"
}

Response

{
  "code": "10000",
  "msg": "Success",
  "token": "wa_b748********364e",
  "type": "wallet_account",
  "timestamp": "2026-07-01 02:24:26"
}