PIX

Type: Instant Bank Transfer / QR Code Payment Method (Brazil)

Payment Flow:

Customer selects PIX at checkout.

The merchant creates or confirms a PaymentIntent with payment_method_data.type = pix.

UseePay returns next_action.redirect.url when customer action is required.

The customer is redirected to the PIX payment page, or the PIX page is displayed in the checkout flow.

Customer completes the payment using a Brazilian bank app or wallet.

After payment completion, the user is returned to the merchant site, and the merchant receives the payment result by webhook.

Refunds: Supports full and partial refunds; refund processing time depends on channel and acquiring rules.

Notes:

Before enabling PIX payments, please contact UseePay customer service to apply for PIX activation.

PIX is primarily used for Brazilian customers.

Use BRL as the transaction currency unless adaptive pricing or DCC has been enabled for the merchant.

Set billing.address.country = BR when confirming the PaymentIntent.

pix.identification_number is required. Use a valid Brazilian taxpayer identification number: CPF for individuals or CNPJ for businesses.

For subscription or recurring scenarios, PIX must be enabled for the merchant, and the initial PaymentIntent should be created in subscription mode.

Supported Transaction Types

Product Support

Supported Countries

One-time Payment
Recurring Payment

Amount Ranges

🌍 Supported Countries and Currencies

Country / Region	Currency	Example Supported Payment Methods
🇧🇷 Brazil	BRL	PIX QR Code / Hosted PIX Page

💳 Payment Methods and Amount Limits

1. PIX

Currency	Minimum Amount	Maximum Amount
BRL	Depends on channel configuration	Depends on channel configuration

💡 PIX amount limits may vary depending on the merchant configuration, acquiring channel, and risk rules.

Integration Guide

Required Fields

Field	Required	Description
`currency`	Required	Use `BRL` for PIX payments.
`payment_method_data.type`	Required	Must be `pix`.
`payment_method_data.pix.identification_number`	Required	Brazilian CPF or CNPJ.
`payment_method_data.billing.address.country`	Required	Use `BR`.
`payment_method_data.billing.address.email`	Required	.
`payment_method_data.billing.address.fisrt_name`	Required	.
`payment_method_data.billing.address.last_name`	Required	.
`return_url`	Required	URL to return the customer after payment authentication.
`device_data.ip_address`	Recommended	Customer IP address for risk analysis.

Create and Confirm a PaymentIntent

Create and confirm a PaymentIntent with payment_method_data.type = pix.

{
  "amount": 10,
  "currency": "BRL",
  "merchant_order_id": "order_202606080001",
  "confirm": true,
  "auto_capture": true,
  "return_url": "https://example.com/return",
  "customer": {
    "email": "customer@example.com",
    "first_name": "Maria",
    "last_name": "Silva",
    "address": {
      "country": "BR"
    }
  },
  "payment_method_data": {
    "type": "pix",
    "billing": {
      "email": "customer@example.com",
      "name": "Maria Silva",
      "first_name": "Maria",
      "last_name": "Silva",
      "phone": "+5511999999999",
      "address": {
        "country": "BR",
        "city": "Sao Paulo",
        "state": "SP",
        "postcode": "01001000",
        "line1": "Praca da Se 1"
      }
    },
    "pix": {
      "identification_number": "08024192918"
    }
  },
  "device_data": {
    "ip_address": "203.0.113.10",
    "browser": {
      "user_agent": "Mozilla/5.0"
    }
  }
}

When the PaymentIntent requires customer action, the response includes next_action.redirect.

{
  "id": "1012606080000000001",
  "status": "requires_customer_action",
  "currency": "BRL",
  "amount": 10,
  "next_action": {
    "type": "redirect",
    "redirect": {
      "method": "GET",
      "url": "https://pay.dlocal.com/gmf-apm/payments/N-example"
    }
  }
}

Redirect the customer to next_action.redirect.url to complete the payment.

For some PIX flows, the returned redirect URL may point to a Smart PIX page. The integration behavior is the same: follow next_action.redirect.url and wait for the final payment result.

Subscription Guide

PIX can be used for subscription payments when enabled for the merchant.

For the first subscription payment:

Create the PaymentIntent with mode = subscription.

Provide subscription_id and invoice_id when they are created by the subscription flow.

Provide payment_method_data.type = pix.

Provide payment_method_data.pix.identification_number.

Example:

{
  "amount": 10,
  "currency": "BRL",
  "merchant_order_id": "sub_order_202606080001",
  "confirm": true,
  "auto_capture": true,
  "mode": "subscription",
  "subscription_id": "sub_xxx",
  "invoice_id": "inv_xxx",
  "return_url": "https://example.com/return",
  "payment_method_data": {
    "type": "pix",
    "billing": {
      "email": "customer@example.com",
      "first_name": "Maria",
      "last_name": "Silva",
      "address": {
        "country": "BR"
      }
    },
    "pix": {
      "identification_number": "08024192918"
    }
  }
}

For subsequent invoice payments, use the invoice payment flow. UseePay will use the saved PIX payment method data from the first payment when creating the recurring payment request.

Testing

Use the sandbox environment and a test CPF/CNPJ value provided by UseePay.

The customer action URL returned in next_action.redirect.url should be opened to complete the PIX payment simulation.

Pix

PIX

PIX Supported Countries / Currencies / Amount Ranges

🌍 Supported Countries and Currencies

💳 Payment Methods and Amount Limits

1. PIX

Integration Guide

Required Fields

Create and Confirm a PaymentIntent

Subscription Guide

Testing

Flowchart

One-time Payment

Subscription Payment

Pix

PIX#

PIX Supported Countries / Currencies / Amount Ranges#

🌍 Supported Countries and Currencies#

💳 Payment Methods and Amount Limits#

1. PIX#

Integration Guide#

Required Fields#

Create and Confirm a PaymentIntent#

Subscription Guide#

Testing#

Flowchart#

One-time Payment#

Subscription Payment#

PIX

PIX Supported Countries / Currencies / Amount Ranges

🌍 Supported Countries and Currencies

💳 Payment Methods and Amount Limits

1. PIX

Integration Guide

Required Fields

Create and Confirm a PaymentIntent

Subscription Guide

Testing

Flowchart

One-time Payment

Subscription Payment