Create a PIX charge

POST/v1/pix

Creates a dynamic PIX charge and returns the copy-and-paste payload for payment.

Request

Headers

Header	Required	Description
`Authorization`	yes	`Bearer <YOUR_API_KEY>`
`Content-Type`	yes	`application/json`

Body

{
  "amountCents": 1000,
  "externalRef": "order-123",
  "expiresInDays": 2,
  "customer": {
    "name": "Maria Silva",
    "email": "maria@example.com",
    "phone": "11999998888",
    "document": {
      "number": "12345678901",
      "type": "cpf"
    }
  }
}

Field	Type	Req.	Description
`amountCents`	integer	yes	Amount in cents. Minimum: `100` (R$ 1.00).
`customer`	object	yes	Payer data (see below).
`customer.name`	string	yes	Payer name. Max 100 characters.
`customer.email`	string	yes	Valid payer email. Max 254 characters.
`customer.phone`	string	yes	Payer phone with area code (10 or 11 digits, digits only).
`customer.document.number`	string	yes	Document. Accepts digits, dots, dashes and slashes (formatting is stripped). Must have 11 digits for `cpf` or 14 digits for `cnpj` after stripping.
`customer.document.type`	string	yes	`"cpf"` or `"cnpj"`. Variations in case and whitespace are normalized — `"CNPJ"`, `"Cpf"`, `" cnpj "` are accepted. Lowercase is recommended.
`externalRef`	string	no	Identifier on your system. Used as idempotency key.
`expiresInDays`	integer	no	Validity in days (1 to 30). Default: `2`.

Idempotency via externalRef

Resending the same externalRef returns the original charge with "idempotent": true. Use it whenever possible, especially on timeout retries.

Response `201 Created`

{
  "transactionId": "Q4t9aV...",
  "status": "pending",
  "pixPayload": "00020126580014BR.GOV.BCB.PIX...6304ABCD",
  "expiresAt": 1715000000,
  "amountCents": 1000
}

Field	Description
`transactionId`	Internal transaction ID. Use to query status.
`status`	Always `"pending"` at creation.
`pixPayload`	PIX copy-and-paste string (BR Code EMV). Show it to the payer or generate the QR Code from it.
`expiresAt`	Unix timestamp in seconds for expiration.
`amountCents`	Echo of the amount sent.

Response `200 OK` (idempotent)

When externalRef was already used before:

{
  "transactionId": "Q4t9aV...",
  "status": "pending",
  "pixPayload": "...",
  "expiresAt": 1715000000,
  "amountCents": 1000,
  "idempotent": true
}

Errors

HTTP	`error`
400	`"amountCents deve ser inteiro ≥ 100 (R$1,00 mínimo)."`
400	`"customer.name obrigatório."`
400	`"customer.document.number e customer.document.type obrigatórios."`
400	`"customer.document.type é obrigatório."`
400	`"customer.document.type deve ser 'cpf' ou 'cnpj'. Recebido: '<value>'."`
400	`"customer.document.number deve ter 11 dígitos para cpf. Recebido: <N> dígitos."`
400	`"customer.document.number deve ter 14 dígitos para cnpj. Recebido: <N> dígitos."`
400	`"customer.email é obrigatório e deve ser válido."`
400	`"customer.phone é obrigatório (DDD + número, 10 ou 11 dígitos)."`
400	`"Valor abaixo do mínimo (R$ X,YY)."`
400	`"Valor acima do máximo (R$ X,YY)."`
401	`"API key inválida ou revogada."`
403	`"Conta não está aprovada para uso da API."`
403	`"IP de origem não autorizado para esta chave."`
429	`"Limite de requisições atingido. Tente em 1 hora."`
502	`"Erro ao comunicar com gateway. Tente novamente."`

Examples

curl -X POST https://api.internationalfinance.com.br/v1/pix \
  -H "Authorization: Bearer $INFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 1000,
    "externalRef": "order-123",
    "expiresInDays": 2,
    "customer": {
      "name": "Maria Silva",
      "email": "maria@example.com",
      "phone": "11999998888",
      "document": { "number": "12345678901", "type": "cpf" }
    }
  }'

const res = await fetch('https://api.internationalfinance.com.br/v1/pix', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.INFI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amountCents: 1000,
    externalRef: 'order-123',
    expiresInDays: 2,
    customer: {
      name: 'Maria Silva',
      email: 'maria@example.com',
      phone: '11999998888',
      document: { number: '12345678901', type: 'cpf' },
    },
  }),
})
if (!res.ok) throw new Error(`INFI ${res.status}: ${(await res.json()).error}`)
const charge = await res.json()

import os, requests
 
res = requests.post(
    "https://api.internationalfinance.com.br/v1/pix",
    headers={
        "Authorization": f"Bearer {os.environ['INFI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "amountCents": 1000,
        "externalRef": "order-123",
        "expiresInDays": 2,
        "customer": {
            "name": "Maria Silva",
            "email": "maria@example.com",
            "phone": "11999998888",
            "document": {"number": "12345678901", "type": "cpf"},
        },
    },
)
res.raise_for_status()
charge = res.json()

<?php
$client = new GuzzleHttp\Client();
$res = $client->post('https://api.internationalfinance.com.br/v1/pix', [
  'headers' => [
    'Authorization' => 'Bearer ' . getenv('INFI_API_KEY'),
    'Content-Type'  => 'application/json',
  ],
  'json' => [
    'amountCents'   => 1000,
    'externalRef'   => 'order-123',
    'expiresInDays' => 2,
    'customer' => [
      'name'  => 'Maria Silva',
      'email' => 'maria@example.com',
      'phone' => '11999998888',
      'document' => ['number' => '12345678901', 'type' => 'cpf'],
    ],
  ],
]);
$charge = json_decode($res->getBody(), true);

Next step

Show pixPayload to the payer (copy-and-paste or generate the QR Code from it). Wait for the transaction.paid webhook or poll GET /v1/transactions/:id.

Idempotency Initiate a PIX withdrawal