❌Recurring Payment

Unlike PIX Automatic—a Brazil-only, vault-token-based PIX authorization flow that requires the merchant to submit each scheduled deduction—this API creates a recurring plan through /trade/recurring for supported Credit Card, Wallet, PIX, and UPI methods.

Use the Recurring Payment API to create a payment plan that charges a customer according to a defined interval and number of cycles.

After a recurring payment order is created successfully, Pagsmile returns a web_url. Redirect the customer to the complete URL to finish the initial payment and recurring-payment authorization.

Supported targets and currencies

Target	Method	Order currency	Notes
TNGD	Wallet	MYR	Availability depends on the merchant application configuration.
Gcash	Wallet	PHP	Availability depends on the merchant application configuration.
DANA	Wallet	IDR	Availability depends on the merchant application configuration.
TrueMoney	Wallet	THB	Availability depends on the merchant application configuration.
Rabbit-Line Pay Co., Ltd	Wallet	THB	Availability depends on the merchant application configuration.
Kakaopay	Wallet	KRW	Availability depends on the merchant application configuration.
Zalopay – Vietnam	Wallet	VND	Use channel=Zalopay.
Credit Card	CreditCard	BRL, USD, EUR	Availability depends on the merchant application configuration.
Credit Card – India	CreditCard	INR	India recurring Credit Card flow.
UPI – India	UPI	INR	India recurring UPI flow.
PIX	PIX	BRL	Trial periods and trial amounts are not supported.

Create a recurring payment

Endpoint

POST https://gateway-test.pagsmile.com/trade/recurring

Request headers

Header	Required	Description
Content-Type	Recommended	Fixed value: application/json.
Authorization	Yes	Basic authentication using Base64(app_id:security_key).

Request parameters

Parameter	Type	Required	Constraints	Description
app_id	string	Yes	Maximum 32 characters.	Merchant application ID assigned by Pagsmile.
timestamp	string	Yes	Format: yyyy-MM-dd HH:mm:ss; maximum 19 characters.	Time at which the request is sent.
version	string	Yes	Fixed value: 2.0.	API version.
format	string	No	If provided, the only supported value is JSON.	Request and response format.
out_trade_no	string	Yes	Maximum 64 characters; must be unique for the merchant application.	Merchant recurring order number.
method	string	Yes	One of CreditCard, Wallet, PIX, or UPI.	Recurring payment method.
channel	string	Conditional	Required for Vietnam Wallet; fixed value: Zalopay.	Wallet channel. Channel availability is determined by the merchant application configuration.
order_currency	string	Yes	Three-letter currency code. The value must match a supported method-and-currency combination listed above.	Recurring order currency.
order_amount	decimal string	Yes	Minimum 0.01; maximum 9,999,999,999,999.99; supports up to 13 integer digits and two decimal places. Method- or country-specific limits override this range.	Amount charged for each regular recurring cycle.
subject	string	Yes	Maximum 128 characters.	Payment reason or order title.
content	string	Conditional	Maximum 255 characters. Required by the general and India flows; optional for Vietnam Wallet.	Payment content or order description.
trade_type	string	Yes	Fixed value: WEB.	Indicates that Pagsmile returns a checkout URL for customer authorization.
timeout_express	string	No	Supports m (minutes), h (hours), d (days), and c (end of the current day). The default is 90m.	Time allowed to complete the initial payment authorization.
notify_url	string	Yes	Must be a valid HTTP or HTTPS URL; HTTPS is recommended.	Endpoint that receives asynchronous payment notifications.
return_url	string	Yes	Must be a valid HTTP or HTTPS URL; HTTPS is recommended.	URL to which the customer is redirected after checkout.
buyer_id	string	Yes	Maximum 64 characters for the country-specific flows documented below.	Merchant-side customer ID.
interval	string	Yes	An integer from 1 to 99, followed by D, W, M, or Y for day, week, month, or year. Example: 1M. PIX has additional restrictions described below.	Time between recurring charges.
quantity	integer	Yes	Non-negative integer. Use a positive integer to specify a fixed number of recurring cycles; the base API default is 0.	Number of recurring payment cycles.
trial_period	string	Conditional	Not supported for PIX. For supported methods, use an integer from 1 to 99, followed by D, W, M, or Y.	Time before the first regular recurring charge.
trial_amount	decimal string	Conditional	Not supported for PIX. Must be greater than 0 when provided and supports up to two decimal places. Country-specific limits may apply.	Amount charged during the trial period.
recurring	string	Conditional	Included in the India Credit Card and UPI flows; fixed value: on.	Indicates a recurring India payment.

The unit M in interval and trial_period means month. The unit m in timeout_express means minute.

The channel and recurring fields are retained for compatibility with the current Vietnam and India integrations. The corresponding method and channel must also be enabled for the merchant application.

Method-specific requirements

Method or market	order_amount	Trial	Interval	Additional requirements
Credit Card	From 0.01 to 9,999,999,999,999.99 unless a country-specific limit applies.	Supported.	D, W, M, or Y.	Use method=CreditCard.
Wallet	From 0.01 to 9,999,999,999,999.99 unless a channel-specific limit applies.	Supported.	D, W, M, or Y.	The available wallet is determined by the merchant application configuration.
PIX	From 0.1 to 50,000 BRL.	Not supported.	W; 1M, 3M, or 6M; or Y.	Use method=PIX and order_currency=BRL.
Vietnam Wallet	From 1 to 20,000,000 VND.	trial_amount must be from 1 to 20,000,000 VND.	For example, 1D.	Use method=Wallet, channel=Zalopay, and order_currency=VND. quantity must be a positive integer.
India Credit Card	Supports up to two decimal places; no country-specific minimum or maximum is stated on the current country page.	trial_amount supports up to two decimal places.	For example, 1M.	Use method=CreditCard, order_currency=INR, and recurring=on.
India UPI	Supports up to two decimal places; no country-specific minimum or maximum is stated on the current country page.	trial_amount supports up to two decimal places.	For example, 1M.	Use method=UPI, order_currency=INR, and recurring=on.

General request example

{
  "app_id": "1639****096",
  "timestamp": "2026-08-20 13:42:06",
  "version": "2.0",
  "method": "CreditCard",
  "order_amount": "16.66",
  "order_currency": "BRL",
  "trial_amount": "6.66",
  "trial_period": "1D",
  "interval": "1M",
  "quantity": 3,
  "out_trade_no": "out_29****00",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "trade_type": "WEB",
  "notify_url": "https://merchant.example.com/payment-notifications",
  "return_url": "https://merchant.example.com/payment-result",
  "buyer_id": "299****600",
  "timeout_express": "90m"
}

Vietnam Wallet example

Vietnam recurring Wallet payments currently support Zalopay, real-time payment processing, and refunds.

{
  "app_id": "166***280",
  "timestamp": "2026-08-20 18:50:42",
  "version": "2.0",
  "method": "Wallet",
  "channel": "Zalopay",
  "order_amount": "10",
  "order_currency": "VND",
  "trial_amount": "1000",
  "trial_period": "1D",
  "interval": "1D",
  "quantity": 30,
  "trade_type": "WEB",
  "out_trade_no": "out_trade_no_101***791",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "notify_url": "https://merchant.example.com/payment-notifications",
  "return_url": "https://merchant.example.com/payment-result",
  "buyer_id": "buyer123"
}

India Credit Card example

{
  "app_id": "162***43",
  "timestamp": "2026-07-16 17:35:05",
  "version": "2.0",
  "method": "CreditCard",
  "order_amount": "1.33",
  "trial_amount": "1.02",
  "trial_period": "1D",
  "order_currency": "INR",
  "out_trade_no": "out_61***5",
  "recurring": "on",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "trade_type": "WEB",
  "notify_url": "https://merchant.example.com/payment-notifications",
  "return_url": "https://merchant.example.com/payment-result",
  "buyer_id": "610625",
  "interval": "1M",
  "quantity": 3,
  "timeout_express": "10900m"
}

India UPI example

{
  "app_id": "162***43",
  "timestamp": "2026-07-16 17:35:46",
  "version": "2.0",
  "method": "UPI",
  "order_amount": "1.72",
  "trial_amount": "1.22",
  "trial_period": "1D",
  "order_currency": "INR",
  "out_trade_no": "out_61***83",
  "recurring": "on",
  "subject": "trade pay test",
  "content": "trade pay test content",
  "trade_type": "WEB",
  "notify_url": "https://merchant.example.com/payment-notifications",
  "return_url": "https://merchant.example.com/payment-result",
  "buyer_id": "61071083",
  "interval": "1M",
  "quantity": 3,
  "timeout_express": "10900m"
}

Response example

Success example

{
  "code": "10000",
  "msg": "Success",
  "out_trade_no": "out_61***083",
  "trade_no": "202607***93",
  "web_url": "https://checkout.pagsmile.com?prepay_id=UkdwS**656e6&return_url=https://merchant.example.com/payment-result",
  "prepay_id": "UkdwS1**=-77c656e6"
}

Failure example

{
  "code": "40002",
  "msg": "Business Failed",
  "sub_code": "invalid-signature",
  "sub_msg": "invalid signature"
}

Complete the authorization

1. Read the complete web_url from the successful response.

2. Redirect the customer's browser to that URL without constructing or modifying it.

3. Allow the customer to complete the initial payment and recurring-payment authorization.

4. Use asynchronous notifications to determine the payment and recurring status.

A successful creation response confirms that the recurring order was created. It does not by itself confirm that the customer completed the authorization or that a payment was successful.

IPN notifications

Pagsmile sends recurring payment events to the notify_url supplied when the recurring order is created. Implement signature verification and idempotent event handling before processing an event.

For notification fields and recurring status values, see Recurring Payment Notification.

Cancel a recurring payment

Use this endpoint to cancel an existing recurring payment order.

POST https://gateway-test.pagsmile.com/trade/recurring/cancel

Request headers

Header	Required	Description
Content-Type	Recommended	Fixed value: application/json.
Authorization	Yes	Basic authentication using Base64(app_id:security_key).

Request parameters

Parameter	Type	Required	Constraints	Description
app_id	string	Yes	Maximum 32 characters.	Merchant application ID assigned by Pagsmile.
timestamp	string	Yes	Format: yyyy-MM-dd HH:mm:ss; maximum 19 characters.	Time at which the cancellation request is sent.
version	string	Yes	Fixed value: 2.0.	API version.
out_trade_no	string	Yes	Maximum 64 characters. Use the merchant recurring order number supplied when the recurring payment was created.	Recurring order to cancel.

Request example

{
  "app_id": "app_id",
  "timestamp": "2026-08-20 15:30:00",
  "version": "2.0",
  "out_trade_no": "out_29****00"
}

Response example

Success

{
  "code": "10000",
  "msg": "Success",
  "out_trade_no": "out_29****00",
  "recurring_status": "CANCEL"
}

Failure

{
  "code": "40002",
  "msg": "Business Failed",
  "sub_code": "invalid-signature",
  "sub_msg": "invalid signature"
}