Pix Automático is a payment solution developed by the Central Bank of Brazil for Pix that enables merchant initiated recurring transactions. 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.

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

Only fixed (EXACT) recurring amounts are supported.

Pix asynchronously authorizes Payment Charges against Pix Agreements

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.

Retries

If a payment charge is not authorized, Pix Automático allows retries in the following scenario:

• On the same day, the retry should be done between the hours of 18:00 and 21:00

An additional three retries may be attempted, subject to the following rules:

• Up to 7 days from the original date (provided that it does not surpass the day immediately before the start date of the following cycle or, in the case of the last cycle, the end of the agreement)
• Occur, at most, on three different dates
• Present the same amount as the original payment amount

📘

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:

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",
  "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"
      }
    },
    {
      "type": "SCAN_CODE"
    }
  ]
}

{
  "paymentMethod": "PIX",
  "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"
      }
    },
    {
      "type": "SCAN_CODE"
    }
  ],
  "initialPaymentCharge": {
    "amount": {
      "value": 1000,
      "currency": "BRL"
    }
  }
}

Response

You'll receive our standard payment charge response (see potential responses in the API Reference) with the available authentication methods.

{
  "id": "agr_TQWvK6UY55P7qZlh4iuWW",
  "status": "AUTHENTICATION_PENDING",
  "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",
  "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

1. 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.
2. The consumer will finalize the agreement and/or the payment process on the redirected page.

SCAN_CODE

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

Handling the result

REDIRECT

1. Once the consumer has confirmed the agreement and/or payment, they are redirected to the returnUrl provided in the initial payment agreement creation request.
2. 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}
3. 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.
4. Store the Payment Agreement ID for subsequent payments.

SCAN_CODE

1. 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}
2. Webhooks are also sent to inform you of the agreement and/or payment outcome.
3. 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.