> 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/brazil/pix-automatic.md).

# PIX Automatic

## Overview

PIX Automatic enables merchants to collect recurring Pix payments after the user authorizes a recurring payment plan in their bank application.

For each billing cycle, the merchant submits a payment request under the active authorization. The payer's bank validates the request and processes the payment on the scheduled deduction date without requiring the user to authorize the charge again.

{% hint style="warning" %}
PIX Automatic payments do not support refunds.
{% endhint %}

<figure><img src="/files/D2UgkyGKqfNRr0ABj9sN" alt=""><figcaption></figcaption></figure>

### Supported payment scenarios

PIX Automatic supports two authorization scenarios. Recurring payments follow the same processing flow after either scenario.

* **Authorization with an immediate first payment:** The customer authorizes the recurring payment plan and completes the first payment in the same checkout flow.
* **Authorization without an immediate payment:** The customer authorizes the recurring payment plan without being charged during the authorization flow. The first recurring payment is collected in the first billing cycle, on the date specified by `plan.start_date`. This scenario can support business models such as subscriptions with a free trial.

### How it works

PIX Automatic uses three API operations:

1. **Create a PIX vault.** Call `POST /vault/create` to obtain a vault token for the user.
2. **Authorize and process payments.** Call `POST /trade/pay` with the vault token and recurring plan. Set `first_payment` according to the selected scenario:

   * Set `first_payment` to `true` to collect an immediate first payment.
   * Set `first_payment` to `false` to authorize the plan without an immediate payment.

   `scheduled_deduct_date` is not required when creating the authorization. It is required only for subsequent recurring payment requests.
3. **Recurring Payments.** For each billing cycle, call `POST /trade/pay` again 2–10 days before the scheduled deduction date. Use the asynchronous notification sent to `notify_url` to determine the final `trade_status`.

### Step 1: Create a PIX vault

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

Create a PIX vault for the user. The response returns the token required to create the authorization and submit recurring payments.

#### Request body

<table><thead><tr><th width="142.9453125">Field</th><th width="98.5625">Type</th><th width="115.3046875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Yes</td><td>App ID assigned to the merchant application.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Yes</td><td>Request time in <code>yyyy-MM-dd HH:mm:ss</code> format.</td></tr><tr><td><code>version</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>2.0</code>.</td></tr><tr><td><code>type</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>pix</code>.</td></tr><tr><td><code>notify_url</code></td><td>string</td><td>Yes</td><td>Where Pagsmile will send notification to</td></tr><tr><td><code>pix.region</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>BRA</code>.</td></tr><tr><td><code>pix.method</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>PIXAutomatic</code>.</td></tr><tr><td><code>pix.uid</code></td><td>string</td><td>Yes</td><td>Unique user identifier in the merchant system.</td></tr></tbody></table>

{% tabs %}
{% tab title="Sample Request" %}

```json
{
  "app_id": "16***61",
  "timestamp": "2026-07-23 17:21:51",
  "version": "2.0",
  "type": "pix",
  "notify_url":"http://demo.gemini-tiger.cn/callback/success"
  "pix": {
    "region": "BRA",
    "method": "PIXAutomatic",
    "uid": "117**41"
  }
}
```

{% endtab %}

{% tab title="Sample Response" %}

```json
{
  "code": "10000",
  "msg": "Success",
  "token": "pa_c3***s0",
  "type": "pix",
  "timestamp": "2026-07-23 09:21:51"
}
```

{% endtab %}
{% endtabs %}

Store `token` securely and associate it with the correct merchant user. Send this value as `vault_token` in Step 2.

When the `vault_token` is no longer required, use `POST /vault/void` to invalidate the token. See [Void a PIX vault](#void-a-pix-vault).

### Step 2: Authorize and process payments

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

Use this endpoint to:

* Create the initial authorization.
* Process an immediate first payment when `first_payment` is `true`.
* Submit subsequent recurring payments.

#### Request body

{% tabs %}
{% tab title="Transaction fields" %}

<table><thead><tr><th width="289.71484375">Field</th><th width="120.828125">Type</th><th width="128.2734375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Yes</td><td>App ID assigned to the merchant application.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Yes</td><td>Request time in <code>yyyy-MM-dd HH:mm:ss</code> format.</td></tr><tr><td><code>method</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>PIXAutomatic</code>.</td></tr><tr><td><code>version</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>2.0</code>.</td></tr><tr><td><code>order_amount</code></td><td>number</td><td>Yes</td><td>Payment amount. No payment is collected during an authorization-only request.</td></tr><tr><td><code>order_currency</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>BRL</code>.</td></tr><tr><td><code>out_trade_no</code></td><td>string</td><td>Yes</td><td>Unique transaction ID generated by the merchant. Generate a new value for every request.</td></tr><tr><td><code>subject</code></td><td>string</td><td>Yes</td><td>Payment reason or order title.</td></tr><tr><td><code>notify_url</code></td><td>string</td><td>Yes</td><td>Merchant endpoint that receives asynchronous authorization and payment results.</td></tr><tr><td><code>return_url</code></td><td>string</td><td>Yes</td><td>URL to which the user is redirected after the checkout flow.</td></tr><tr><td><code>buyer_id</code></td><td>string</td><td>Yes</td><td>Unique user identifier in the merchant system.</td></tr><tr><td><code>timeout_express</code></td><td>string</td><td>No</td><td>Transaction expiration period. Supported units include minutes (<code>m</code>), hours (<code>h</code>), days (<code>d</code>), and the current day (<code>c</code>).</td></tr><tr><td><code>customer.identification.type</code></td><td>string</td><td>Yes</td><td>User identification type. The examples use <code>CPF</code>.</td></tr><tr><td><code>customer.identification.number</code></td><td>string</td><td>Yes</td><td>User identification number.</td></tr><tr><td><code>customer.name</code></td><td>string</td><td>Yes</td><td>User name.</td></tr><tr><td><code>vault_token</code></td><td>string</td><td>Yes</td><td>Token returned by <code>POST /vault/create</code>.</td></tr><tr><td><code>first_payment</code></td><td>boolean</td><td>Yes</td><td>Whether the authorization includes an immediate first payment.</td></tr></tbody></table>
{% endtab %}

{% tab title="Authorization plan" %}
The following fields are required when creating the initial authorization. They are not included in subsequent recurring payment requests.&#x20;

Use `plan.minimum_amount` and `plan.maximum_amount` to define the permitted amount range for recurring payments.

Set both fields to the same value for a fixed amount, or use different values when the amount may change, such as after a subscription upgrade or downgrade.

<table><thead><tr><th width="215.87890625">Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>plan.interval</code></td><td>string</td><td>Yes</td><td>Recurring billing interval. Example: <code>1W</code>: every week<br><code>1M</code>: every month<br><code>3M</code>: every three months<br><code>6M</code>: every six months<br><code>1Y</code>: every year</td></tr><tr><td><code>plan.start_date</code></td><td>string</td><td>Yes</td><td>Start date of the first recurring billing cycle, in <code>yyyy-MM-dd</code> format. It must be at least two days after authorization and after any immediate first payment.</td></tr><tr><td><code>plan.end_date</code></td><td>string</td><td>Yes</td><td>End date of the recurring payment plan, in <code>yyyy-MM-dd</code> format.</td></tr><tr><td><code>plan.minimum_amount</code></td><td>number</td><td>No</td><td>Minimum amount allowed for a recurring payment.</td></tr><tr><td><code>plan.maximum_amount</code></td><td>number</td><td>No</td><td>Maximum amount allowed for a recurring payment.</td></tr></tbody></table>
{% endtab %}

{% tab title="Recurring payment" %}

<table><thead><tr><th width="243.0078125">Field</th><th width="88.6640625">Type</th><th width="138.9375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>scheduled_deduct_date</code></td><td>string</td><td>Conditional</td><td>Required for recurring payment requests. Set it to the scheduled deduction date in <code>yyyy-MM-dd</code> format and submit the request 2–8 days before this date.</td></tr></tbody></table>

For recurring payment requests:

* Include `scheduled_deduct_date`.
  {% endtab %}
  {% endtabs %}

### Payloads

{% tabs %}
{% tab title="Authorize with first payment" %}
Use this payload to create the authorization and collect the first payment in the same flow.

* Set `first_payment` to `true`.
* Include `plan`.
* Do not include `scheduled_deduct_date`.
* Redirect the user to the returned `check_url`.

**Request**

```json
{
  "app_id": "16***24",
  "timestamp": "2026-07-27 14:21:51",
  "method": "PIXAutomatic",
  "version": "2.0",
  "order_amount": 0.25,
  "order_currency": "BRL",
  "out_trade_no": "out_1***0",
  "subject": "subject",
  "notify_url": "http://demo.gemini-tiger.cn/callback/success",
  "return_url": "https://pagsmile.com/",
  "buyer_id": "11***50",
  "timeout_express": "10190m",
  "customer": {
    "identification": {
      "type": "CPF",
      "number": "11***2"
    },
    "name": "user name"
  },
  "vault_token": "pa_c3***s0",
  "first_payment": true,
  "plan": {
    "interval": "1W",
    "start_date": "2026-07-29",
    "end_date": "2027-08-26",
    "minimum_amount": 0.1,
    "maximum_amount": 5
  }
}
```

&#x20;**Response**

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "bUJ***852",
  "trade_no": "2026***33",
  "out_trade_no": "out_11***0",
  "pay_url": "",
  "trade_status": "INITIAL",
  "check_url": "https://checkout.pagsmile.com?prepay_id=bU***0=852&token=pa_c3***790"
}
```

{% endtab %}

{% tab title="Authorization only(free trail)" %}
Use this payload to authorize the recurring payment plan without collecting an immediate payment.

* Set `first_payment` to `false`.
* Include `plan`.
* Do not include `scheduled_deduct_date`.
* Redirect the user to the returned `check_url`.

**Request**

```json
{
  "app_id": "161***4",
  "timestamp": "2026-07-27 16:53:11",
  "method": "PIXAutomatic",
  "version": "2.0",
  "order_amount": 1.11,
  "order_currency": "BRL",
  "out_trade_no": "ou***3",
  "subject": "subject",
  "notify_url": "http://demo.gemini-tiger.cn/callback/success",
  "return_url": "https://pagsmile.com/",
  "buyer_id": "17***33",
  "customer": {
    "identification": {
      "type": "CPF",
      "number": "11***2"
    },
    "name": "user name"
  },
  "vault_token": "pa***11",
  "first_payment": false,
  "plan": {
    "interval": "1W",
    "start_date": "2026-07-29",
    "end_date": "2027-08-29",
    "minimum_amount": 0.1,
    "maximum_amount": 5
  }
}
```

**Response**

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "bUJ***852",
  "trade_no": "2026***33",
  "out_trade_no": "out_11***0",
  "trade_status": "INITIAL",
  "check_url": "https://checkout.pagsmile.com?prepay_id=bU***0=852&token=pa_c3***790"
}
```

Start the free trial only after receiving the authorization webhook with `trade_status=AUTHORIZED`.
{% endtab %}

{% tab title="Recurring payment" %}
Use this payload for every recurring payment after authorization, regardless of which authorization scenario was used.

* Set `first_payment` to `false`.
* Include `scheduled_deduct_date`.
* Submit the request 2–8 days before the scheduled deduction date.

**Request**

```json
{
  "app_id": "16***4",
  "timestamp": "2026-07-27 16:49:48",
  "method": "PIXAutomatic",
  "version": "2.0",
  "order_amount": 0.33,
  "order_currency": "BRL",
  "out_trade_no": "out_1***33",
  "subject": "subject",
  "notify_url": "http://demo.gemini-tiger.cn/callback/success",
  "return_url": "https://pagsmile.com/",
  "buyer_id": "17***3",
  "timeout_express": "10190m",
  "customer": {
    "identification": {
      "type": "CPF",
      "number": "11***2"
    },
    "name": "test uuu"
  },
  "vault_token": "pa_c3***s0",
  "scheduled_deduct_date": "2026-07-31"
}
```

**Response**

```json
{
  "code": "10000",
  "msg": "Success",
  "prepay_id": "R2FJ***F514a2",
  "trade_no": "202***00",
  "out_trade_no": "out_19***66",
  "trade_status": "PROCESSING"
}
```

Use the payment result webhook sent to `notify_url` to determine the final result:

* `SUCCESS`: update or renew the subscription.
* `FAILED`: handle the failed payment according to the merchant's retry or customer-notification process.
  {% endtab %}
  {% endtabs %}

{% hint style="info" %}
The synchronous API response confirms that Pagsmile accepted the request. Always use the asynchronous webhook sent to `notify_url` to determine the final payment result.
{% endhint %}

### Void a PIX vault

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

Use this endpoint to invalidate an existing PIX vault token.&#x20;

#### Request body

<table><thead><tr><th width="146.36328125">Field</th><th width="108.328125">Type</th><th width="113.58984375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Yes</td><td>App ID assigned to the merchant application. Maximum length: 32 characters.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Yes</td><td>Request time in <code>yyyy-MM-dd HH:mm:ss</code> format. Maximum length: 19 characters.</td></tr><tr><td><code>version</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>2.0</code>.</td></tr><tr><td><code>type</code></td><td>string</td><td>Yes</td><td>Fixed value: <code>PIX</code></td></tr><tr><td><code>vault_token</code></td><td>string</td><td>Yes</td><td>Vault token to invalidate.</td></tr></tbody></table>

**Request Sample**

```
{
  "app_id": "16***38",
  "timestamp": "2026-07-30 14:30:00",
  "version": "2.0",
  "type": "PIX",
  "vault_token": "wa_***"
}
```

**Response**

```json
{
  "code": "10000",
  "msg": "Success",
  "token": "wa_***",
  "type": "PIX",
  "timestamp": "yyyy-MM-dd HH:mm:ss"
}
```

#### Query the PIX vault status

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

Use this endpoint to check whether a PIX vault token is pending authorization, active, or canceled. Vault status is separate from the status of an individual recurring payment.

Use Basic Authentication with your App ID as the username and Security Key as the password.

**Request body**

<table><thead><tr><th width="152.36328125">Field</th><th width="110.25">Type</th><th width="95.546875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Yes</td><td>App ID assigned to the merchant application.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Yes</td><td>Request time in <code>yyyy-MM-dd HH:mm:ss</code> format.</td></tr><tr><td><code>version</code></td><td>string</td><td>No</td><td>API version. Default: <code>2.0</code>.</td></tr><tr><td><code>vault_token</code></td><td>string</td><td>Yes</td><td>PIX vault token returned by <code>POST /vault/create</code>.</td></tr></tbody></table>

**Sample request**

```bash
{
  "app_id": "<APP_ID>",
  "timestamp": "2026-08-20 10:30:00",
  "version": "2.0",
  "vault_token": "pa_***"
}
```

**Sample response**

```json
{
  "code": "10000",
  "msg": "Success",
  "token": "pa_***",
  "timestamp": "2026-08-20 10:30:01",
  "status": "TOKEN_ACTIVATED"
}
```

**Vault statuses**

<table><thead><tr><th width="173.74609375">Status</th><th>Description</th><th>Merchant action</th></tr></thead><tbody><tr><td><code>TOKEN_CREATED</code></td><td>The PIX vault has been created, but the recurring payment authorization is not yet active.</td><td>Wait for the user to complete the authorization before submitting recurring payments.</td></tr><tr><td><code>TOKEN_ACTIVATED</code></td><td>The authorization is active.</td><td>The token can be used to submit recurring payments within the authorized plan.</td></tr><tr><td><code>TOKEN_CANCELED</code></td><td>The authorization associated with the token has been canceled.</td><td>Stop using the token. A new PIX vault and authorization are required before recurring payments can resume.</td></tr></tbody></table>

{% hint style="info" %}
A payment `trade_status`, such as `SUCCESS`, `REFUSED`, `CANCEL`, or `EXPIRED`, describes an individual payment. It does not represent the status of the PIX Automatic authorization. Use `POST /vault/query` to check the authorization status.
{% endhint %}