> 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/vault/india/upi.md).
# UPI
This page describes how to submit an India UPI payment with a vault token.
For India UPI vault payments, merchants need to create a UPI vault token first, and then submit the Payin request with the returned vault token. The customer needs to visit the `pay_url` returned in the Payin response to authorize the payment.
## Step 1: Create a UPI Vault Token
Create a UPI vault token for the customer.
### Endpoint
`POST` `https://gateway-test.pagsmile.com/vault/create`
### Request Body
| Parameter | Type | Required | Constraints | Description |
| ------------------------ | ------ | -------- | -------------------------------------------- | ------------------------------------------------- |
| app\_id | string | Yes | Max 32 chars. | The merchant application ID assigned by Pagsmile. |
| timestamp | string | Yes | Format: `yyyy-MM-dd HH:mm:ss`. Max 19 chars. | Request timestamp. |
| version | string | Yes | Fixed value: `2.0`. | API version. |
| type | string | Yes | Fixed value: `UPI`. | Payment type. |
| upi.region | string | Yes | Fixed value: `IND`. | UPI region. |
| upi.method | string | Yes | Fixed value: `UPI`. | UPI payment method. |
| upi.uid | string | Yes | Merchant-generated user ID. | The unique user ID generated by the merchant. |
| upi.plan.internal | string | Yes | One of: `1W`, `1M`, `3M`, `6M`, `1Y`. | Billing cycle. |
| upi.plan.start\_date | string | Yes | Format: `yyyy-MM-dd`. | The start date of the UPI vault plan. |
| upi.plan.end\_date | string | Yes | Format: `yyyy-MM-dd`. | The end date of the UPI vault plan. |
| upi.plan.minimum\_amount | number | Yes | - | Minimum payment amount allowed for the plan. |
| upi.plan.maximum\_amount | number | Yes | - | Maximum payment amount allowed for the plan. |
### Request Sample
```curl
curl --location --request POST 'https://gateway-test.pagsmile.com/vault/create' \
--header 'Authorization: Basic Base64(app_id:security_key)' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_id": "162************43",
"timestamp": "2026-06-15 11:44:58",
"version": "2.0",
"type": "UPI",
"upi": {
"region": "IND",
"method": "UPI",
"uid": "398261538962300",
"plan": {
"internal": "1W",
"start_date": "2026-06-05",
"end_date": "2027-04-26",
"minimum_amount": 0.1,
"maximum_amount": 5
}
}
}'
```
### Response
{% tabs %}
{% tab title="200 success" %}
```json
{
"code": "10000",
"msg": "Success",
"token": "psvt_upi_d3***c33",
"type": "UPI",
"timestamp": "2026-06-15 03:44:59"
}
```
{% endtab %}
{% endtabs %}
## Step 2: Submit Payin with Vault Token
Use the vault token returned from Step 1 to submit the India UPI Payin request.
{% hint style="info" %}
For India UPI vault payments, capture is not completed immediately after order creation. It usually takes around 25 hours from order creation to capture. The actual capture time may be delayed when banks are under high processing pressure.
{% endhint %}
### Endpoint
`POST` `https://gateway-test.pagsmile.com/trade/pay`
### Request Body
| Parameter | Type | Requirement | Constraints | Description |
| ----------------- | ------- | ----------- | --------------------------------------------------- | ----------------------------------------------------------- |
| app\_id | string | Optional | Max 32 chars. | The merchant application ID assigned by Pagsmile. |
| timestamp | string | Optional | Format: `yyyy-MM-dd HH:mm:ss`. Max 19 chars. | Request timestamp. |
| method | string | Optional | Fixed value: `UPI`. | Payment method. |
| version | string | Optional | Fixed value: `2.0`. | API version. |
| order\_amount | decimal | Optional | Range: `1–500000`. Supports up to 2 decimal places. | The order amount. |
| order\_currency | string | Optional | Fixed value: `INR`. | Order currency. |
| out\_trade\_no | string | Optional | Max 64 chars. | The unique order number generated by the merchant. |
| subject | string | Optional | Max 128 chars. | The order subject. |
| notify\_url | string | Optional | Valid URL. | The URL used to receive asynchronous payment notifications. |
| return\_url | string | Optional | Valid URL. | The URL to redirect the customer after payment. |
| buyer\_id | string | Optional | Merchant-generated user ID. | The unique customer ID generated by the merchant. |
| vault\_token | string | Optional | Returned from Create Vault. | The UPI vault token returned from Step 1. |
| customer.name | string | Required | - | Customer's name. |
| customer.email | string | Required | Valid email address. | Customer's email address. |
| customer.phone | string | Required | - | Customer's phone number. |
| address.zip\_code | string | Required | - | Customer's ZIP/postal code. |
### Request Sample
```curl
curl --location --request POST 'https://gateway-test.pagsmile.com/trade/pay' \
--header 'Authorization: Basic Base64(app_id:security_key)' \
--header 'Content-Type: application/json' \
--data-raw '{
"app_id": "162************43",
"timestamp": "2026-06-15 11:44:59",
"method": "UPI",
"version": "2.0",
"order_amount": 1.14,
"order_currency": "INR",
"out_trade_no": "out_3***00",
"subject": "subject",
"notify_url": "http://merchant/callback/success",
"return_url": "https://www.merchant.com",
"buyer_id": "39***00",
"vault_token": "psvt_upi_d3***33",
"customer": {
"name": "user name",
"email": "user05@example.com",
"phone": "91***10"
},
"address": {
"zip_code": "561134"
}
}'
```
### Response
{% tabs %}
{% tab title="200 success" %}
```json
{
"code": "10000",
"msg": "Success",
"prepay_id": "Ykx2***186",
"trade_no": "2026***63",
"out_trade_no": "out_3***0",
"web_url": "",
"pay_url": "upi://mandate?pa=pagsm***lock=N",
"trade_status": "PROCESSING"
}
```
{% endtab %}
{% endtabs %}
The customer needs to visit the returned `pay_url` to authorize the payment.
## Refund
Refund is supported for this payment method.