For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Response


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

Response


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

Response

Last updated