# Recurring Payment

## Recurring Payment

#### Request Base URL <a href="#request-base-url" id="request-base-url"></a>

```
  Test Environment : https://gateway-test.pagsmile.com
  Prod Environment : https://gateway.pagsmile.com
```

#### EndPoints <a href="#endpoints" id="endpoints"></a>

```
  /trade/recurring
```

#### Request Header <a href="#request-header" id="request-header"></a>

| Parameter     | Required    | Description                         |
| ------------- | ----------- | ----------------------------------- |
| Content-Type  | Recommended | application/json                    |
| Authorization | Yes         | Basic Base64(app\_id:security\_key) |

#### Request Parameters (JSON format) <a href="#request-parameters-json-format" id="request-parameters-json-format"></a>

<table><thead><tr><th>Parameter</th><th width="100.6666259765625">Type</th><th>Description</th><th>Max Length(or Default Value)</th></tr></thead><tbody><tr><td>app_id<mark style="color:red;">*</mark></td><td>string</td><td>App's ID is in dashboard</td><td>32</td></tr><tr><td>out_trade_no<mark style="color:red;">*</mark></td><td>string</td><td>Given by the Merchant (Is in their system)</td><td>64</td></tr><tr><td>method<mark style="color:red;">*</mark></td><td>string</td><td>CreditCard, PIX or Wallet</td><td>32</td></tr><tr><td>order_currency<mark style="color:red;">*</mark></td><td>string</td><td>Check <a href="recurring-payment/currency">here</a> for supported currency</td><td>3</td></tr><tr><td>order_amount<mark style="color:red;">*</mark></td><td>decimal</td><td>Request payment amount</td><td>CreditCard &#x26; Wallet: 0.01 ~ 99999999999999.99,<br>PIX: 0.1 ~ 50,000</td></tr><tr><td>subject<mark style="color:red;">*</mark></td><td>string</td><td>Payment reason or item title</td><td>128</td></tr><tr><td>content<mark style="color:red;">*</mark></td><td>string</td><td>Payment reason detail or item detail</td><td>255</td></tr><tr><td>trade_type<mark style="color:red;">*</mark></td><td>string</td><td>Response content type, WEB will return a checkout URL</td><td>WEB</td></tr><tr><td>timeout_express<mark style="color:red;">*</mark></td><td>string</td><td>m(minutes), h(hours), d(days), c(current day)</td><td>90m</td></tr><tr><td>format<mark style="color:red;">*</mark></td><td>string</td><td>Only JSON supported</td><td>JSON</td></tr><tr><td>timestamp<mark style="color:red;">*</mark></td><td>string</td><td>yyyy-MM-dd HH:mm:ss</td><td>19</td></tr><tr><td>version<mark style="color:red;">*</mark></td><td>string</td><td>Fix to 2.0</td><td>2.0</td></tr><tr><td>notify_url<mark style="color:red;">*</mark></td><td>string</td><td>IPN URL to merchant (start with http)</td><td></td></tr><tr><td>return_url<mark style="color:red;">*</mark></td><td>string</td><td>Web page return URL to merchant (start with http)</td><td></td></tr><tr><td>buyer_id<mark style="color:red;">*</mark></td><td>string</td><td>Merchant user's ID</td><td></td></tr><tr><td>interval<mark style="color:red;">*</mark></td><td>string</td><td>CreditCard &#x26; Wallet: D(day), W(week), M(month), Y(year)<br>PIX: W(week), M(month, only support 1M, 3M &#x26; 6M), Y(year)</td><td>1M</td></tr><tr><td>quantity<mark style="color:red;">*</mark></td><td>number</td><td>Quantity of recurring</td><td>0</td></tr><tr><td>trial_period<mark style="color:red;">*</mark></td><td>string</td><td>Trial period<br>- Not for PIX -</td><td></td></tr><tr><td>trial_amount<mark style="color:red;">*</mark></td><td>decimal</td><td>Trial amount (when trial_amount is not blank)<br>- Not for PIX -</td><td>> 0</td></tr></tbody></table>

#### Request Sample <a href="#request-sample" id="request-sample"></a>

```
curl --location --request POST 'https://gateway.pagsmile.com/trade/recurring' \
--header 'Authorization: Basic Base64(appid:security_key)' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "app_id": "1639****096",
    * "timestamp": "2024-05-20 13:42:06",
    * "version": "2.0",
    * "method": "Wallet", //Wallet, CreditCard, or PIX
    * "order_amount": "16.66",
    * "order_currency": "CNY",
    * "trial_amount":"6.66", //Not available for PIX
    * "trial_period":"5m", //Not available for PIX
    * "interval":"30m",
    * "quantity":3,
    * "out_trade_no": "out_29****00",
    * "subject": "trade pay test",
    * "content": "trade pay test conent",
    * "trade_type": "WEB",
    * "notify_url": "http://demo.gemini-tiger.cn/callback/success",
    * "return_url": "https://pagsmile.com/zh/",
    * "buyer_id": "299****600",
    * "timeout_express":"10900m"
}'
```

#### Http Response (JSON format) <a href="#http-response-json-format" id="http-response-json-format"></a>

| Parameter      | Type   | Description                  |
| -------------- | ------ | ---------------------------- |
| code           | string | Return code                  |
| msg            | string | Return msg                   |
| sub\_code      | string | Return sub code (only error) |
| sub\_msg       | string | Return sub msg (only error)  |
| out\_trade\_no | string | Request out\_trade\_no       |
| trade\_no      | string | Pagsmile trade NO.           |
| web\_url       | string | Checkout URL                 |

#### Return Code (Success) <a href="#return-code-success" id="return-code-success"></a>

```
{
    "code": "10000",
    "msg": "Success",
    "out_trade_no": "{out_trade_no}",
    "trade_no": "{trade_no}",
    "web_url": "http://checkout.pagsmile.com?prepay_id={$prepay_id}",
    "prepay_id": "{$prepay_id}"
}
```

#### Return Code (Fail) <a href="#return-code-fail" id="return-code-fail"></a>

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

## IPN Notifications <a href="#ipn-notifications" id="ipn-notifications"></a>

Check the [Notification page](https://docs.pagsmile.com/payin/recurring-payment/notification).

## Cancel Recurring Payment&#x20;

#### Request Base URL <a href="#request-base-url" id="request-base-url"></a>

```
  Test Environment : https://gateway-test.pagsmile.com
  Prod Environment : https://gateway.pagsmile.com
```

#### EndPoints <a href="#endpoints" id="endpoints"></a>

```
  /trade/recurring/cancel
```

#### Request Header <a href="#request-header" id="request-header"></a>

| Parameter     | Required    | Description                         |
| ------------- | ----------- | ----------------------------------- |
| Content-Type  | Recommended | application/json                    |
| Authorization | Yes         | Basic Base64(app\_id:security\_key) |

#### Request Parameters (JSON format) <a href="#request-parameters-json-format" id="request-parameters-json-format"></a>

<table><thead><tr><th>Parameter</th><th width="128.6666259765625">Type</th><th>Description</th><th>Max Length(or Default Value)</th></tr></thead><tbody><tr><td>app_id<mark style="color:red;">*</mark></td><td>string</td><td>App's ID is in dashboard</td><td>32</td></tr><tr><td>timestamp<mark style="color:red;">*</mark></td><td>string</td><td>yyyy-mm-dd HH:mm:ss</td><td>19</td></tr><tr><td>version<mark style="color:red;">*</mark></td><td>string</td><td>fix to 2.0</td><td>2.0</td></tr><tr><td>out_trade_no<mark style="color:red;">*</mark></td><td>string</td><td>Given by the Merchant (Is in their system)</td><td>64</td></tr></tbody></table>

#### Request Sample <a href="#request-sample" id="request-sample"></a>

```
curl --location --request POST 'https://gateway.pagsmile.com/trade/recurring/cancel' \
--header 'Authorization: Basic Base64(appid:security_key)' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "app_id": "app_id",
    * "timestamp": "{{datetime}}",
    * "version": "2.0",
    * "out_trade_no": "{{$randomUUID}}"
}'
```

#### Http Response (JSON format) <a href="#http-response-json-format" id="http-response-json-format"></a>

| Parameter         | Type   | Description                 |
| ----------------- | ------ | --------------------------- |
| code              | string | Return code                 |
| msg               | string | Return msg                  |
| sub\_code         | string | Return sub code(only error) |
| sub\_msg          | string | Return sub msg(only error)  |
| out\_trade\_no    | string | Request out\_trade\_no      |
| recurring\_status | string | Recurring status            |

#### Return Code (Success) <a href="#return-code-success" id="return-code-success"></a>

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

#### Return Code (Fail) <a href="#return-code-fail" id="return-code-fail"></a>

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