Brazil

Before you start

Authorization

How to sign your requests with the API token.

Create payment

The base order request that this page extends.

This payment method is not enabled for all merchants. Check availability with your manager.

Overview

Currency	Country code	Payment methods
`BRL`	`BR`	PIX (QR code) · Card · Boleto

Three integration options are available in Brazil. They require different payer details; which one is enabled for your account is determined by the terminal settings.

Not sure which option you have? Check with your manager.

This is a host-to-host flow: you get the PIX QR link directly from the API and render it in your own interface.

Create an order

Create a regular order in BRL and save its id.

Request the QR link

POST /v1/orders/{orderId}/h2h/pix

curl -X POST "https://api.1capital.capital/v1/orders/{orderId}/h2h/pix" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: YOUR_API_TOKEN"

The QR link is generated on the provider side. Set the request timeout to 30 seconds or more.

Response:

{
  "qrLink": "https://pix.com.br/..."
}

Show the QR code

Render qrLink as a QR code, or open it as a link on mobile devices. The payer confirms the transfer in their banking app.

Wait for the result

The order status changes to COMPLETED when the transfer is confirmed. You receive a webhook or can poll the order by ID.

Order status and webhooks

The payer is redirected to paymentLink and enters the card details on the payment page. The result is usually known right away; the final status arrives by webhook.

The payer's document, email and full address are passed in the customer object. The bank reviews a card payment against the payer's details and declines it without the address — even for digital goods. An order with missing fields, a document that fails the check-digit validation or a state not given as its two-letter code is rejected with 400.

Pass the payer's real address. A generic or someone else's address worsens the fraud checks. The phone is optional, but pass it too: some risk checks decline payers without one.

Customer object fields

Field	Type	Required	Description
`document`	string	✅ Yes	Payer's CPF (11 digits) or CNPJ (14 digits), with or without punctuation
`email`	string	✅ Yes	Payer's email
`postcode`	string	✅ Yes	CEP: 8 digits, with or without the hyphen
`street`	string	✅ Yes	Street
`addressNumber`	string	✅ Yes	House number
`neighborhood`	string	✅ Yes	Neighborhood (bairro)
`city`	string	✅ Yes	City
`state`	string	✅ Yes	State as the two-letter code (`SP`). The full name (`São Paulo`) is not accepted
`addressComplement`	string	❌ No	Apartment, suite, floor
`phone`	string	❌ No	Phone with the area code (DDD): 10–11 digits, the `55` country code allowed. Recommended
`documentType`	string	❌ No	`CPF` or `CNPJ`. When passed, it must match `document`
`firstName`	string	❌ No	First name. Without the name, the one on the card is used
`lastName`	string	❌ No	Last name
`ip`	string	❌ No	Payer's IP address. Recommended: it is used by the fraud checks

Request example

{
  "purpose": "Payment for order #1234",
  "amount": "150",
  "currency": "BRL",
  "externalId": "external_id",
  "externalUserId": "external_user_id",
  "successUrl": "https://example.com/success",
  "failUrl": "https://example.com/fail",
  "callbackUrl": "https://example.com/webhooks/payments",
  "isFeeOnUser": false,
  "customer": {
    "firstName": "Ana",
    "lastName": "Souza",
    "email": "ana.souza@example.com",
    "document": "12345678909",
    "phone": "11999998888",
    "postcode": "01310-100",
    "street": "Av. Paulista",
    "addressNumber": "1578",
    "addressComplement": "Apto 12",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}

The payer is redirected to paymentLink. The payment page shows the boleto: its payment line (linha digitável) with a copy button, a link to the PDF, and the PIX of the same boleto as a faster alternative.

A boleto is registered with the bank in the payer's name, so the complete payer details are required in the customer object: a valid document, contacts and the full address. An order with missing or invalid fields is rejected with 400.

Pass the CPF or CNPJ of the actual payer. The document is validated by its check digits, and the boleto is registered in the name of the person it identifies.

Customer object fields

Field	Type	Required	Description
`firstName`	string	✅ Yes	First name
`lastName`	string	✅ Yes	Last name
`document`	string	✅ Yes	Payer's CPF (11 digits) or CNPJ (14 digits), with or without punctuation
`email`	string	✅ Yes	Payer's email
`phone`	string	✅ Yes	Phone with the area code (DDD): 10–11 digits, the `55` country code allowed
`postcode`	string	✅ Yes	CEP: 8 digits, with or without the hyphen
`street`	string	✅ Yes	Street
`addressNumber`	string	✅ Yes	House number
`neighborhood`	string	✅ Yes	Neighborhood (bairro)
`city`	string	✅ Yes	City
`state`	string	✅ Yes	State: the two-letter code (`SP`) or the full name (`São Paulo`)
`addressComplement`	string	❌ No	Apartment, suite, floor
`documentType`	string	❌ No	`CPF` or `CNPJ`. When passed, it must match `document`

Request example

{
  "purpose": "Payment for order #1234",
  "amount": "150",
  "currency": "BRL",
  "externalId": "external_id",
  "externalUserId": "external_user_id",
  "successUrl": "https://example.com/success",
  "failUrl": "https://example.com/fail",
  "callbackUrl": "https://example.com/webhooks/payments",
  "isFeeOnUser": false,
  "customer": {
    "firstName": "Maria",
    "lastName": "Santos",
    "document": "12345678909",
    "email": "maria.santos@example.com",
    "phone": "11999998888",
    "postcode": "01310-100",
    "street": "Av. Paulista",
    "addressNumber": "1578",
    "addressComplement": "Apto 12",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}

Due date and confirmation

The boleto is due 3 calendar days after it is issued, Brasília time. The order stays PENDING until the end of the due date and then becomes EXPIRED.
A paid boleto is confirmed by the bank within about one business day. A payment by the PIX of the boleto is confirmed in seconds.
Banks keep accepting a boleto for some time after its due date. When such a payment is confirmed, the expired order moves to COMPLETED and you receive a webhook.

Response

The response is a standard order object. The order is created with the CREATED status; redirect the payer to paymentLink to complete the payment.

Order object fields

Order statuses

Status	Final	Description
`CREATED`	No	Order created, payment link not yet opened
`PENDING`	No	Awaiting payment
`COMPLETED`	Yes	Payment successful, funds received
`FAILED`	Conditionally	Payment error
`CANCELED`	Conditionally	Order canceled by the system
`EXPIRED`	Conditionally	Order expired before it was paid
`BLOCKED`	Conditionally	Transaction blocked by the bank
`REFUND`	Yes	Payment refunded to the payer (e.g. your refund is completed). Set after `COMPLETED`
`CHARGEBACK`	Yes	Payment disputed by the payer and reversed by the bank. Set after `COMPLETED`

FAILED, CANCELED, EXPIRED and BLOCKED are not strictly final. If the bank confirms the payment later because of an error on its side, the order moves to COMPLETED and the webhook for this change is sent automatically. Be ready to receive COMPLETED for an order you have already marked as unsuccessful.

Brazil

Before you start

Authorization

Create payment

Overview

Create an order

Create payment

Request the QR link

Show the QR code

Wait for the result

Order status and webhooks

Customer object fields

Request example

Customer object fields

Request example

Due date and confirmation

Response

Order object fields

Order statuses

See also

Order status and webhooks

Payouts: Brazil (PIX)

On this page

Brazil

Authorization

Create payment

Create payment

Order status and webhooks

Response example

Order object fields

Order status and webhooks

Payouts: Brazil (PIX)

On this page