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

200 success

{
  "code": "10000",
  "msg": "Success",
  "token": "psvt_upi_d3***c33",
  "type": "UPI",
  "timestamp": "2026-06-15 03:44:59"
}

Step 2: Submit Payin with Vault Token

Use the vault token returned from Step 1 to submit the India UPI Payin request.

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.

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 --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": "[e-mail]",
    "phone": "91***10"
  },
  "address": {
    "zip_code": "561134"
  }
}'

Response

200 success

{
  "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"
}

The customer needs to visit the returned pay_url to authorize the payment.

Refund

Refund is supported for this payment method.