Pix

Accept Pix instant payments in Brazil with QR-code-based checkout, real-time fund transfers, and Central Bank-regulated settlement

CategoryAccount-to-account (A2A)

Payment flowDirectRedirect

Coverage

Countries	Brazil (BR)
Currencies	Brazilian Real (BRL)
Min amount	0.50 BRL
Max amount	Bank dependent

Checkout

Integration type	API v1
	Payment Form

Billing logics

One-time	Yes
1-click	No
Recurring	Yes
Unscheduled	No

Operations

Refund	Yes
Partial refunds	Yes
Multiple partial refunds	Yes
Chargeback	No

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.

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 payment is a per-cycle charge made using a token under BCB scheduling rules.

Pix QR One-time

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
Merchant receives a notification Webhook confirming the payment status.

Init payment API v1 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 in the payment form.

Pix Automático Recurring/MIT

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 v1 request with billing periods. Solidgate returns a QR code in payment_type_data.qr_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. Solidgate then issues a token that the merchant uses for all subsequent recurring charges under the mandate.
Merchant notification
Merchant receives a notification Webhook confirming the payment status.

Init payment API v1 must use pix-automatico in the payment_method field for this flow.

Recurring charges

Payment initiation
Merchant submits a recurring API v1 using the token issued when the mandate was established.
Payment confirmation
Solidgate schedules the charge for a due date at least 2 days ahead (BCB requirement). The payment is then processed automatically when that date is reached.
Merchant notification
You receive a notification Webhook confirming the final payment outcome after any automatic retry attempts are complete.

If a recurring charge fails, Solidgate retries it automatically according to the payment network's rules. Solidgate makes up to 3 attempts, one per day, within 7 days of the first failed charge. You do not need to submit a new charge request. The payment order stays in processing throughout the retry window. Solidgate sends one webhook after the final outcome. The order is approved when a retry is confirmed. It is declined when all 3 attempts fail or the 7-day window expires without confirmation.

Pix Automático is strictly for scheduled recurring charges on a fixed billing interval. One-click payments or upsells outside the billing schedule are not supported on the same token.

For Pix QR refunds, a connector can process the refund using the same Pix information the customer provided for the original payment.

However, this is only possible on the same day the Pix payment is confirmed.

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.

Pix payments are real-time transfers that expire after 1 hour, and any unpaid transactions are automatically cancelled.

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_usage.max_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.

Subscriptions

Pix Automático is a supported APM for Guide
Set up recurring payments with Solidgate subscriptions to create products, configure trial periods, and manage billing frequencies. subscriptions, so the same subscription_id flow used for card recurring billing also handles Pix Automático recurring charges through the recurring API v1 request.

Scheduling

When a recurring charge is due, Solidgate schedules it for a due date at least 2 days ahead, as required by BCB rules. The recurring API v1 request does not charge immediately. The customer can cancel the charge during this 2-day lead time. The payment is then processed automatically on that date.

and are not available for Pix Automático. Recovery follows the payment network's retry rules instead, as described in the Retries tab. The order stays in processing throughout the retry window.

Retries

If a recurring charge fails, Solidgate retries it automatically using the same token according to the payment network's rules. The 7-day window starts from the first failed charge. That date is the original due date, not the day of the recurring request. Solidgate makes up to 3 attempts, one per day, within that window. No merchant or subscription configuration is required. The subscription stays active , and the payment order stays in processing throughout the retry window.

and do not apply to Pix Automático. The payment network's retry rules apply instead, and Solidgate manages the retries within the original charge. The subscription does not enter the redemption status for this payment method.

If a retry succeeds, the subscription continues as normal. If all 3 attempts fail or the 7-day window expires without confirmation, the order is declined , and the subscription is cancelled with cancel code Solidgate sends one webhook after the final outcome. The Restore tab explains the available options after cancellation, including cases where the customer revoked the mandate.

Restore

A cancelled subscription can be through the Hub or API. Restoring changes the subscription status back to active and updates the billing period based on the expired_at value you provide.

For Pix Automático, restore works only while the BCB mandate linked to the recurring token remains valid. If the customer revoked the mandate or the token is unavailable, the next recurring charge fails. The subscription is then cancelled with cancel code or

If the subscription was cancelled after the retry window for a recurring charge expired, the BCB mandate might still be valid. However, the payment network does not allow another charge attempt within the same billing cycle. Set expired_at so the restored subscription's next charge falls in the following billing cycle.

Switch product

Pix Automático only supports scheduled recurring charges on a fixed billing interval. An existing mandate covers a only when the new product keeps the same billing_period as the current mandate. Switching to a product with a different billing_period is not supported on the same Pix Automático token. It requires a new mandate authorization.

A price change within the same billing_period stays under the existing mandate, as long as the new price does not exceed the authorization ceiling set by future_usage.max_amount. A new product price above that ceiling also requires a new mandate authorization.

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
Follow implementation best practices for the payment form including error handling, mobile optimization, and production validation steps. document number is correct and matches the required format.

Looking for help? Contact us

Stay informed with Changelog