> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/payin/submit-a-payin/vietnam/vaultwallet.md).

# VaultWallet

## 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.

{% hint style="info" %}
Vault Wallet payins in Vietnam support refund.
{% endhint %}

{% hint style="info" %}
Vault Wallet payins in Vietnam support real-time payment processing.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

***

## Step 1: Create Vault

<mark style="color:green;">`POST`</mark> `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

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

## Request Sample

```json
{
  "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

```json
{
  "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

<mark style="color:green;">`POST`</mark> `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](#create-vault)             | The vault token returned from the Create Vault request.     |

## Request Sample

```json
{
  "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

```json
{
  "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

<mark style="color:green;">`POST`</mark> `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

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

## Response

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