ReloadBankDocs
Criar conta

PIX

Criar cobrança PIX

Gera uma cobrança PIX (cash-in) com BR Code “copia e cola”, imagem do QR Code e uma página de pagamento hospedada. A transação nasce como PENDING e muda para PAID quando o pagador concluir o PIX.
POST/api/v1/pix/cash-in

Parâmetros do corpo

CampoTipoObrigatórioDescrição
amountnumberSimValor em reais, até 2 casas decimais (ex.: 100 ou 49.9). Mínimo R$ 5,00 e máximo R$ 50.000,00 (limites padrão). O valor precisa ser maior que a taxa.
external_idstringNãoSeu identificador único (1–100 caracteres: letras, números e _ - . :). Garante idempotência.
descriptionstringNãoDescrição exibida ao pagador (até 140 caracteres).
expires_inintegerNãoValidade da cobrança em segundos, de 60 a 604800 (7 dias). Padrão: 3600.
postback_urlstringNãoURL HTTPS (até 500 caracteres) que receberá os webhooks desta transação, no lugar da URL configurada na conta.
payerobjectNãoDados do pagador (opcionais). Enviados à instituição parceira, exibidos no dashboard e devolvidos em payer.
payer.namestringNãoNome do pagador (2–120 caracteres).
payer.documentstringNãoCPF ou CNPJ válido, com ou sem pontuação. É armazenado apenas com dígitos.
payer.emailstringNãoE-mail do pagador (até 160 caracteres).
metadataobjectNãoAté 20 pares chave/valor livres (string até 500 caracteres, número, booleano ou null). Devolvido na transação e nos webhooks.

Resposta

Retorna 201 Created com o objeto Transação do tipo PIX_IN. Campos específicos de PIX:

CampoDescrição
pix.qr_codeBR Code (PIX copia e cola). Gere o QR Code a partir dele ou exiba para o cliente copiar.
pix.qr_code_imageImagem PNG do QR Code em data URL (data:image/png;base64,...), pronta para usar em <img src>. Presente apenas na resposta de criação.
pix.txidIdentificador da cobrança na instituição parceira. Trate como texto opaco.
pix.expires_atData/hora de expiração. Após ela, o status muda para EXPIRED.
pix.end_to_end_idID end-to-end do Banco Central, preenchido após o pagamento.
checkout_urlPágina de pagamento hospedada pela Reload Bank com QR Code e status em tempo real.

Taxas

fee é a taxa da operação e net_amount o valor líquido que será creditado no seu saldo disponível assim que o pagamento for confirmado (net_amount = amount − fee). Taxa padrão de recebimento: 1,00% + R$ 0,75; a da sua conta aparece no painel, em Taxas.

Ciclo de vida

  • PENDING → PAID: pagamento confirmado; o líquido entra no saldo disponível e o webhook transaction.paid é enviado.
  • PENDING → EXPIRED: prazo de expires_in esgotado sem pagamento; webhook transaction.expired.

Testando a integração

Crie uma cobrança de R$ 5,00 e pague com a sua própria conta pelo app do banco (ou abra o checkout_url para ver a página que o cliente verá). O pagamento é real: o líquido fica no seu saldo.

Erros comuns

StatusCódigoMotivo
422validation_errorCampo inválido (ex.: CPF do pagador, amount com 3 casas, postback_url sem HTTPS).
422amount_too_lowAbaixo do mínimo ou valor não cobre a taxa.
422amount_too_highAcima do máximo por cobrança.
409duplicate_external_idexternal_id já utilizado.
403account_pendingConta ainda em análise.
502provider_unavailableA instituição parceira não gerou o PIX agora. Tente novamente com o mesmo external_id.
Requisição
curl -X POST "https://reloadbank.app/api/v1/pix/cash-in" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 100,
  "external_id": "pedido-1042",
  "description": "Pedido #1042",
  "expires_in": 3600,
  "postback_url": "https://seusite.com.br/webhooks/reloadbank",
  "payer": {
    "name": "Maria Silva",
    "document": "123.456.789-09",
    "email": "[email protected]"
  },
  "metadata": {
    "order_id": 1042,
    "channel": "site"
  }
}'
Resposta
{
  "id": "cm2r8x1qz0004lk08abcd1234",
  "external_id": "pedido-1042",
  "type": "PIX_IN",
  "status": "PENDING",
  "amount": 100,
  "fee": 1.75,
  "net_amount": 98.25,
  "description": "Pedido #1042",
  "pix": {
    "txid": "K7Q2M9X4T1B8N6R3W5Z0C2V7H",
    "end_to_end_id": null,
    "qr_code": "00020101021226580014br.gov.bcb.pix013600000000-0000-0000-0000-0000000000005204000053039865406100.005802BR5912LOJA EXEMPLO6009SAO PAULO62290525K7Q2M9X4T1B8N6R3W5Z0C2V7H63040000",
    "expires_at": "2026-10-16T15:30:00.000Z",
    "qr_code_image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUAAAAFACAYAAADNkKWqAAAAAklEQVR4AewaftIAAA..."
  },
  "checkout_url": "https://reloadbank.app/pay/cm2r8x1qz0004lk08abcd1234",
  "payer": {
    "name": "Maria Silva",
    "document": "12345678909",
    "email": "[email protected]"
  },
  "failure_reason": null,
  "metadata": {
    "order_id": 1042,
    "channel": "site"
  },
  "paid_at": null,
  "refunded_at": null,
  "created_at": "2026-10-16T14:30:00.000Z",
  "updated_at": "2026-10-16T14:30:00.000Z"
}