Pix

Sign in Hub
Get help
Pix
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.

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
anchor

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.
  1. Selection at checkout
    Customer selects Pix at checkout.
  2. Payment initiation
    Customer is redirected to the Pix payment page, which contains a QR code.
  3. Authentication and authorization
    Customer scans the QR code using a banking app or enters the payment key.
  4. Payment confirmation
    Customer approves the payment.
  5. 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

  1. Selection at checkout
    Customer selects Pix at checkout to start Pix Automático.
  2. 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.
  3. 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.
  4. Payment confirmation
    Initial payment is confirmed. Solidgate then issues a token that the merchant uses for all subsequent recurring charges under the mandate.
  5. 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

  1. Payment initiation
    Merchant submits a recurring API using the token issued when the mandate was established.
  2. 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.
  3. 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.
Pix QR payment page example Pix QR payment page example Pix QR payment page example

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
anchor

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
anchor

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
anchor

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
anchor

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.
Looking for help? Contact us
Stay informed with Changelog