Pix supports recurring payments with their solution Pix Automático, and we streamline this process for you with our payment agreements API.

Features

Billing cycles

Weekly, monthly, and yearly billing cycles are allowed as per the schedule outlined below. Any submission with an unsupported billing schedule will result in the rejection of the agreement.

Schedule	Frequency type	Frequency interval
Weekly	`WEEKLY`	1
Monthly	`MONTHLY`	1
Quarterly	`MONTHLY`	3
Semiannual	`MONTHLY`	6
Annual	`YEARLY`	1

Duration

Pix Automático supports an optional end date for time-bounded subscriptions. No payments will be possible after this date.

📘
Pix Automático will ignore the time component of any start or end date.

Amounts

Fixed (EXACT) and variable (MAX)recurring amounts are supported.

Recurring payments

Recurring payments must be created 10 to 2 days before the payment due date. Payment Charges go to ASYNC_AUTHORIZATION and on the due date, Pix notifies PPRO with the result. PPRO relays this information via Webhooks.

❗️
scanBy defintion
The scanBy date must be set no more than 72 hours before the expected date of the first charge.

Retries

In the event of an unsuccessful charge attempt, PPRO handles retries automatically. No additional action is required from customer side. The system will manage retry attempts within the permitted timeframe and constraints, ensuring compliance with the recurring payment agreement.

Please note:

Retry attempts are initiated exclusively by our system.
The original payment amount will remain unchanged during retries.
Final payment status will be communicated via standard webhooks.

📘
The Pix payment system in Brazil operates within the Brasília Standard Time (BRT).

Create the payment agreement

To create a Pix payment agreement, provide the following information when calling our /v1/payment-agreements API:

Field Name	Required	Description
paymentMethod	M	`PIX`
frequency.type	M	Recurring frequency to be applied: `WEEKLY`, `MONTHLY` or `YEARLY`. Other frequencies are not supported.
frequency.interval	O	Combined with `frequency.type` to defines the schedule. For example, type = MONTHLY and interval = 3 for a quarterly subscription. This is an optional field that defaults to 1.
startDate	M	Date of first payment. Format: `YYYY-MM-DDTHH:MM:SSZ` The `time` component will be ignored - only the date will be considered.
endDate	O	End date of the agreement, no payments will be possible after this value. Format: `YYYY-MM-DDTHH:MM:SSZ` The `time` component will be ignored - only the date will be considered.
amountType	O	Pix Automático supports both fixed and variable amounts: `EXACT`should be used when the amount remains the same throughout the recurring cycle. Example: BRL 90 per month until the end of the cycle. `MAX` should be used when the amount may vary. `MAX`defines the maximum initial amount. Subsequent charges can be equal to or higher than the initial amount set when the agreement is created. Example: BRL 90 for the first 12 months, with a price adjustment due to inflation starting from the 13th month. The default information one is `EXACT`
amount.value	M	The amount to be charged for each cycle
amount.currency	M	`BRL`
consumer.name	M	Full name of the consumer.
consumer.email	M	Email of the consumer.
consumer.country	M	The country from which the consumer is shopping.
consumer.taxIdentification	M	Consumer tax ID. It can be the CPF for natural persons or CNPJ for legal persons.
authenticationSettings.type	M	Supply settings for the support authentication flows:`SCAN_CODE`, `REDIRECT`
merchantPaymentAgreementReference	M	The agreement ID created by the customer.
description	O	The agreement description.
authenticationSettings: SCAN_CODE settings.scanBy	O	Due date in ISO 8601 format. Examples: 2025-08-08T16:09:29Z 2025-08-08T16:09:29-03:00 If no value is passed, it will assume the scanBy to 24 hours from the moment of the agreement creation.

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify:

The exact amount.value and amount.currency of the first payment

If you don't include an initialPaymentCharge during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the first charge.

Request

POST /v1/payment-agreements

{
  "paymentMethod": "PIX",
  "merchantPaymentAgreementReference": "123456",
  "description": "Product subscription",
  "frequency": {
    "type": "MONTHLY",
    "interval": "1"
  },
  "startDate": "2025-05-26T20:24:27Z",
  "endDate": "2026-04-26T20:24:27Z",
  "amountType": "EXACT",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
   "consumer": {
   "name": "John Smith",
   "country": "BR",
   "taxIdentification": 93248261668  
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://www.webshop.com/order-results-page"
      }
    }
  ]
}

{
  "paymentMethod": "PIX",
  "merchantPaymentAgreementReference": "123456",
  "description": "Product subscription",
  "frequency": {
    "type": "MONTHLY",
    "interval": "1"
  },
  "startDate": "2025-05-26T20:24:27Z",
  "endDate": "2026-04-26T20:24:27Z",
  "amountType": "EXACT",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "consumer": {
    "name": "John Smith",
    "country": "BR",
    "taxIdentification": 93248261668
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://www.webshop.com/order-results-page"
      }
    }
  ],
  "initialPaymentCharge": {
    "amount": {
      "value": 1000,
      "currency": "BRL"
    }
  }
}

Response

You'll receive our standard payment charge response with the available authentication methods:

{
  "id": "agr_TQWvK6UY55P7qZlh4iuWW",
  "status": "AUTHENTICATION_PENDING",
  "merchantPaymentAgreementReference": "123456",
  "description": "Product subscription",
  "paymentMethod": "PIX",
  "frequency": {
    "type": "MONTHLY",
    "interval": 1
  },
  "startDate": "2025-05-26T20:24:27.000Z",
  "endDate": "2026-04-26T20:24:27.000Z",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "instrumentId": "instr_gOgJiwasXPogsdh5duoLu",
  "amountType": "EXACT",
  "consumer": {
    "name": "John Smith",
    "country": "BR",
    "taxIdentification": "93248261668"
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    },
    {
      "details": {
        "codeType": "QR",
        "codeImage": "https://qr.ppro.com/image.png?payload=aWQ9YWJjJmFtb3Vuk9VVNEJmZyb209UVI",
        "codePayload": "pix://open/paymentrequest?amount=1000&currency=BRL&from=QR",
        "codeDocument": "cdn.ppro.com//linktocodedocument",
      },
      "type": "SCAN_CODE"
    }
  ],
  "history": [
    {
      "id": "ahist_amrnTTREiMK7XpGkNx2bE",
      "status": "AUTHENTICATION_PENDING",
      "createdAt": "2025-04-15T17:23:29.615Z"
    }
  ],
  "createdAt": "2025-04-15T17:23:29.614Z",
  "updatedAt": "2025-04-15T17:23:29.614Z"
}

{
  "id": "agr_GBar8Nc2pBYIHYEm691d9",
  "status": "AUTHENTICATION_PENDING",
  "merchantPaymentAgreementReference": "123456",
  "description": "Product subscription",
  "paymentMethod": "PIX",
  "frequency": {
    "type": "MONTHLY",
    "interval": 1
  },
  "startDate": "2025-05-26T20:24:27.000Z",
  "endDate": "2026-04-26T20:24:27.000Z",
  "amount": {
    "value": 10000,
    "currency": "BRL"
  },
  "instrumentId": "instr_RWO5A8FuLUsUMyTKQ4QyD",
  "amountType": "EXACT",
  "consumer": {
    "name": "John Smith",
    "country": "BR",
    "taxIdentification": "93248261668"
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    },
    {
      "details": {
        "codeType": "QR",
        "codeImage": "https://qr.ppro.com/image.png?payload=aWQ9YWJjJmFtb3Vuk9VVNEJmZyb209UVI",
        "codePayload": "pix://open/paymentrequest?amount=1000&currency=BRL&from=QR",
        "codeDocument": "cdn.ppro.com//linktocodedocument",
      },
      "type": "SCAN_CODE"
    }
  ],
  "history": [
    {
      "id": "ahist_vcjfoLx62cnGsbh6v4j93",
      "status": "AUTHENTICATION_PENDING",
      "createdAt": "2025-04-15T17:31:54.601Z"
    }
  ],
  "initialPaymentChargeId": "charge_dh2PymaSYqP48gltztPyo",
  "createdAt": "2025-04-15T17:31:54.601Z",
  "updatedAt": "2025-04-15T17:31:54.601Z"
}

Pick the desired authentication method

REDIRECT

Redirect your consumer to the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestUrl.
For example, with the value of https://redirection-target.ppro.com/ using the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestMethod HTTP method.
The consumer will finalize the agreement and/or the payment process on the redirected page.

SCAN_CODE

Render the QR code using one of the techniques available.
The consumer will scan the QR code to complete the agreement and/or payment.

Handling the result

REDIRECT

Once the consumer has confirmed the agreement and/or payment, they are redirected to the returnUrl provided in the payment agreement creation request.
After the consumer is redirected back to your site, check the agreement and/or payment status and use the Status that you received to display the outcome to the consumer.
GET /v1/payment-agreements/{agreement-id}
GET /v1/payment-charges/{paymentChargeId}
Webhooks are also sent to inform you of the agreement and/or payment outcome. If the shopper closes the browser and doesn't return to your website, you can rely on webhooks to receive the result.
Store the Payment Agreement ID for subsequent payments.

SCAN_CODE

Check the agreement and/or payment status and use the Status that you received to display the outcome to the consumer.
GET /v1/payment-agreements/{agreement-id}
GET /v1/payment-charges/{paymentChargeId}
Webhooks are also sent to inform you of the agreement and/or payment outcome.
Store the Payment Agreement ID for subsequent payments.

Create a recurring payment

To initiate a subsequent recurring payment, send a request against an active agreement /v1/payment-agreements/{agreement-id}/payment-charges

❗️
Recurring Pix payments must be created 10 to 2 days before the payment due date. Payment charges go to ASYNC_AUTHORIZATION and on the due date, Pix notifies PPRO with the result. PPRO relays this information via Webhooks.

Request

POST /v1/payment-agreements/{agreement-id}/payment-charges

{
  "amount": {
    "value": 1000,
    "currency": "BRL"
  }
}

Response

{
  "id": "charge_xyz123",
  "status": "AUTHORIZATION_ASYNC",
  "amount": {
    "value": 1000,
    "currency": "BRL"
  }
}

The payment charge status is AUTHORIZATION_ASYNC while awaiting the payment outcome from Pix, as determined by the agreement schedule.

Once Pix communicates the payment outcome, a webhook is dispatched to notify your system of the result.