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. Pix QR One-time
  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 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 Pix QR button in the payment form. Pix Automático Recurring/MIT

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 and Solidgate issues a token 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 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), then processes the payment automatically when that date is reached.
  3. Merchant notification
    Solidgate notifies the merchant of the payment status update, which can be one of the statuses approved / declined / refunded .
If a recurring charge fails, the merchant may retry by submitting a new charge request with the same token. Retries within the same billing cycle are allowed as long as no previous charge in that cycle was successful. 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

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.

Handle Pix errors

Specific errors may occur when a Pix QR payment attempt fails.

  • 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 document number is correct and matches the required format.