> 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/recurring-payment/recurring-payment.md).

# 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

<mark style="color:green;">POST</mark> `https://gateway-test.pagsmile.com/trade/recurring`

#### Request headers

<table><thead><tr><th width="160.3125">Header</th><th width="164.6171875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td>Recommended</td><td>Fixed value: <code>application/json</code>.</td></tr><tr><td><code>Authorization</code></td><td>Yes</td><td>Basic authentication using <code>Base64(app_id:security_key)</code>.</td></tr></tbody></table>

#### Request parameters

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

{% hint style="warning" %}
The unit `M` in `interval` and `trial_period` means month. The unit `m` in `timeout_express` means minute.
{% endhint %}

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

#### Method-specific requirements

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

#### General request example

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

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

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

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

{% tabs %}
{% tab title="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"
}
```

{% endtab %}

{% tab title="Failure example" %}

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

{% endtab %}
{% endtabs %}

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

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

### 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](https://docs.pagsmile.com/reference/payin/recurring-payment/notification).

### Cancel a recurring payment

Use this endpoint to cancel an existing recurring payment order.

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

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

#### Response example

{% tabs %}
{% tab title="Success" %}

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

{% endtab %}

{% tab title="Failure" %}

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

{% endtab %}
{% endtabs %}