Pix processes more transactions than any other payment method in Brazil. Built and regulated by the Central Bank, it enables instant account-to-account transfers via QR code - 24/7, with no intermediaries and near-zero failure rates. Over 75% of Brazilians use Pix as their primary payment rail.
With Solidgate, merchants can accept both one-time Pix QR payments and Pix Automático recurring mandates through a single integration. This means real-time settlement, higher approval rates, and access to Brazil’s largest active payment audience.
Payment type Online
Payment flow Direct / Redirect
Integration type API Reference / Payment Form
Countries Brazil (BR)
Currencies Brazilian Real (BRL)
Min amount 0.5 BRL
Max amount Bank dependent
Recurring Yes
Refund Yes
Partial refunds Yes
Multiple partial refunds Yes
Chargeback No
Principle of operation
Pix QR is a one-time payment with a QR code or payment key.
Pix Automático is a BCB (Central Bank of Brazil) recurring mandate with one QR and further charges by token. Pix Automático recurring payments is each billing cycle using that token under BCB scheduling rules.
- Selection at checkout
Customer selects Pix at checkout. - Payment initiation
Customer is redirected to the Pix payment page, which contains a QR code. - Authentication and authorization
Customer scans the QR code using a banking app or enters the payment key. - Payment confirmation
Customer approves the payment. - Merchant notification
Solidgate notifies the merchant of the payment status update, which can be one of the Guide
Efficiently manage and track alternative payments with real-time updates. statuses approved / declined / refunded
Init payment API request must be sent with the pix-qr parameter to the payment_method field. In return, the response contains a method-specific payload, including
payment_type_data with qr_code_value and qr_code_expiration_date. You can also integrate the
Guide
Enable the Pix QR button on the payment form for one-time Pix QR checkout. Pix QR button in the payment form.
Initial charge and mandate authorization
- Selection at checkout
Customer selects Pix at checkout to start Pix Automático. - Payment initiation
Merchant sends an init payment API request with billing periods. Solidgate returns a QR code inpayment_type_dataqr_code_value , valid for 1 hour. - Authentication and authorization
Customer scans the QR code in the banking app, reviews the recurring mandate terms, and approves the mandate together with the initial payment. - Payment confirmation
Initial payment is confirmed and Solidgate issues atokenthe merchant uses for all subsequent recurring charges under the mandate. - Merchant notification
Solidgate notifies the merchant of the payment status update, which can be one of the Guide
Efficiently manage and track alternative payments with real-time updates. statuses approved / declined / refunded .
Init payment API must use pix-automatico in the payment_method field for this flow.
Recurring charges
- Payment initiation
Merchant submits a recurring API using thetokenissued when the mandate was established. - Payment confirmation
Solidgate schedules the charge for a due date at least 2 days ahead (BCB requirement), then processes the payment automatically when that date is reached. - Merchant notification
Solidgate notifies the merchant of the payment status update, which can be one of the Guide
Efficiently manage and track alternative payments with real-time updates. statuses approved / declined / refunded .
For Pix QR refunds, a connector can process the refund using the same Pix information the customer provided for the original payment.
If this time frame has passed, the connector emails the customer to request their bank information or Pix key to issue the refund.
- Pix key can be a CPF/CNPJ (Tax ID, Entity ID), an email address, a phone number, or a randomly generated key consisting of up to 32 characters.
Billing periods
Pix Automático is governed by strict BCB rules that define the allowed recurring intervals. Only the combinations of billing_period
unit
and billing_period
value
below are accepted.
| billing_period unit | billing_period value | Interval |
|---|---|---|
| day | 7 | Weekly |
| week | 1 | Weekly |
| month | 1 | Monthly |
| month | 3 | Quarterly |
| month | 6 | Semi-annually |
| month | 12 | Annually |
| year | 1 | Annually |
These rules apply when the billing period is sent directly in future_usage
billing_period
and when you use
product_id
, the product configuration must match the table.
When using product_id with a trial, the trial period must be at least 2 days, so the first charge can fall at least 2 days after mandate authorization, per BCB rules.
Authorization ceiling
future_usage
max_amount
is the maximum amount, in minor units, the customer pre-authorizes for any single future charge when the mandate is set up.
- The customer cannot set a bank authorization limit lower than this value but may authorize a higher limit.
- This field is required if no product_id is provided.
When both future_usage
max_amount
and
product_id
are provided:
- If
max_amount
is greater than the product price,
future_usagemax_amount is used, for example, to allow future price increases without a new mandate. - If max_amount is lower than the product price, max_amount is ignored and the product price is used as the limit.
Handle Pix errors
Specific errors may occur when a Pix QR payment attempt fails.
-
Guide
This error indicates an issue with the provided data format. 2.01 Invalid data
The decline may be related to an invalid or incorrectly formatted payer identification document (CPF). Retry the transaction and verify that the Guide
Improve your approval ratio across countries by collecting and providing additional data. document number is correct and matches the required format.