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.

PIX Automatic payments do not support refunds.

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:

Create a PIX vault. Call POST /vault/create to obtain a vault token for the user.
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.
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

POST 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

Field

Type

Required

Description

app_id

string

Yes

App ID assigned to the merchant application.

timestamp

string

Yes

Request time in yyyy-MM-dd HH:mm:ss format.

version

string

Yes

Fixed value: 2.0.

type

string

Yes

Fixed value: pix.

pix.region

string

Yes

Fixed value: BRA.

pix.method

string

Yes

Fixed value: PIXAutomatic.

pix.uid

string

Yes

Unique user identifier in the merchant system.

{
  "app_id": "16***61",
  "timestamp": "2026-07-23 17:21:51",
  "version": "2.0",
  "type": "pix",
  "pix": {
    "region": "BRA",
    "method": "PIXAutomatic",
    "uid": "117**41"
  }
}

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

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.

Step 2: Authorize and process payments

POST 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

Field

Type

Required

Description

app_id

string

Yes

App ID assigned to the merchant application.

timestamp

string

Yes

Request time in yyyy-MM-dd HH:mm:ss format.

method

string

Yes

Fixed value: PIXAutomatic.

version

string

Yes

Fixed value: 2.0.

order_amount

number

Yes

Payment amount. No payment is collected during an authorization-only request.

order_currency

string

Yes

Fixed value: BRL.

out_trade_no

string

Yes

Unique transaction ID generated by the merchant. Generate a new value for every request.

subject

string

Yes

Payment reason or order title.

notify_url

string

Yes

Merchant endpoint that receives asynchronous authorization and payment results.

return_url

string

Yes

URL to which the user is redirected after the checkout flow.

buyer_id

string

Yes

Unique user identifier in the merchant system.

timeout_express

string

Transaction expiration period. Supported units include minutes (m), hours (h), days (d), and the current day (c).

customer.identification.type

string

Yes

User identification type. The examples use CPF.

customer.identification.number

string

Yes

User identification number.

customer.name

string

Yes

User name.

vault_token

string

Yes

Token returned by POST /vault/create.

first_payment

boolean

Yes

Whether the authorization includes an immediate first payment.

The following fields are required when creating the initial authorization. They are not included in subsequent recurring payment requests.

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.

Field

Type

Required

Description

plan.interval

string

Yes

Recurring billing interval. Example: 1W: every week 1M: every month 3M: every three months 6M: every six months 1Y: every year

plan.start_date

string

Yes

Start date of the first recurring billing cycle, in yyyy-MM-dd format. It must be at least two days after authorization and after any immediate first payment.

plan.end_date

string

Yes

End date of the recurring payment plan, in yyyy-MM-dd format.

plan.minimum_amount

number

Minimum amount allowed for a recurring payment.

plan.maximum_amount

number

Maximum amount allowed for a recurring payment.

Field

Type

Required

Description

scheduled_deduct_date

string

Conditional

Required for recurring payment requests. Set it to the scheduled deduction date in yyyy-MM-dd format and submit the request 2–8 days before this date.

For recurring payment requests:

Include scheduled_deduct_date.

Payloads

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

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

Response

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

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

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

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

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

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

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

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.

Void a PIX vault

POST https://gateway-test.pagsmile.com/vault/void

Use this endpoint to invalidate an existing PIX vault token.

Request body

Field

Type

Required

Description

app_id

string

Yes

App ID assigned to the merchant application. Maximum length: 32 characters.

timestamp

string

Yes

Request time in yyyy-MM-dd HH:mm:ss format. Maximum length: 19 characters.

version

string

Yes

Fixed value: 2.0.

type

string

Yes

Fixed value: PIX

vault_token

string

Yes

Vault token to invalidate.

Request Sample

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

Response

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

PreviousBrazil NextIndia

Last updated 17 days ago