One-time and recurring payments on Brazil's #1 payment method
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.
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.
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 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 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 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 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
.
If a recurring charge fails, the merchant may retry by submitting a new charge request with the same token. Retries are allowed within the 7-day window from the start of the billing cycle, as long as no previous charge in that cycle was successful. Each attempt can stay unresolved for up to 2 days, which limits how many retries fit inside the window.
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
Explore Solidgate subscriptions for seamless recurring customer payments.
subscriptions,
so the same subscription_id flow used for card recurring billing also handles Pix Automático recurring charges through the
recurring
API
request.
When a recurring charge is due, Solidgate schedules it for a due date at least 2 days ahead, as required by BCB rules. The payment is then processed automatically on that date. Solidgate applies this 2-day BCB lead time during the scheduling step, between the
recurring
API
request and the actual processing date.
When
Guide
Recover revenue with intelligent and data-driven retry logic.
smart retries
are configured for the product, the webhook payload may temporarily not include the next_charge_at value. If this happens, request the
subscription status
API
5–15 seconds after receiving the webhook, and up to 15 minutes later, to get next_charge_at.
If a recurring charge fails, you can retry with the same token within the 7-day window from the start of the billing cycle, as long as no earlier charge in that cycle was successful. Each attempt can stay unresolved for up to 2 days, which limits how many retries fit inside the window. When the subscription flow is used, retries are managed by
Guide
Recover revenue with intelligent and data-driven retry logic.
smart retries
or
Guide
Predefined retry flows applied during the subscription redemption period.
retry strategies
set on the product, and the subscription moves to the
redemption
status during retries.
If no charge succeeds within the 7-day window, smart retries or retry strategies can wait for the next billing cycle and try again inside its 7-day window. Alternatively, you can cancel the current subscription and ask the customer to authorize a new mandate. If all retry attempts during the redemption period are exhausted, the subscription is cancelled with cancel code
Guide
A recurring payment failed and all retry attempts during the redemption period were unsuccessful.
8.09.
A cancelled subscription can be
Guide
Restore cancelled subscriptions by providing the subscription ID and expiration date.
restored
from the Hub or via API. The restore changes the subscription status back to active and updates the billing period based on the expired_at value you provide.
For Pix Automático, the restore works only while the BCB mandate linked to the recurring token is still valid. If the customer has revoked the mandate at their bank or the token is no longer available, the next recurring charge fails. The subscription is then cancelled with cancel code
Guide
The customer revoked the billing token by contacting customer support or the bank.
8.11
or
Guide
The recurring token was not found in the system upon the recurring payment attempt.
8.15.
Pix Automático only supports scheduled recurring charges on a fixed billing interval. An existing mandate covers a
Guide
Upgrade your customers' product or service plans by switching to a new product.
product switch
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
Improve your approval ratio across countries by collecting and providing additional data.
document
number is correct and matches the required format.