PIX

Saque PIX

Transfere valores do seu saldo disponível para uma chave PIX (cash-out). O valor e a taxa são reservados no momento da solicitação, e o resultado final chega por webhook.

POST/api/v1/pix/cash-out

Parâmetros do corpo

Campo	Tipo	Obrigatório	Descrição
`amount`	number	Sim	Valor em reais que o beneficiário recebe. Mínimo R$ 10,00. A taxa de saque é cobrada à parte.
`pix_key`	string	Sim	Chave PIX de destino (até 100 caracteres).
`pix_key_type`	enum	Sim	Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `EVP` (chave aleatória).
`external_id`	string	Não	Seu identificador único (1–100 caracteres: letras, números e `_ - . :`). Garante idempotência.
`description`	string	Não	Descrição interna do saque (até 140 caracteres).
`postback_url`	string	Não	URL HTTPS (até 500 caracteres) que receberá os webhooks desta transação, no lugar da URL configurada na conta.

Tipos de chave e normalização

A chave é validada e normalizada antes do envio. O valor normalizado é o que aparece em pix.key.

Tipo	Aceita	Normalizado como
CPF	11 dígitos com dígito verificador válido, com ou sem pontuação	`12345678909`
CNPJ	14 dígitos válidos, com ou sem pontuação	`11222333000181`
EMAIL	E-mail válido com até 77 caracteres	minúsculas — `[email protected]`
PHONE	DDD + número (10 ou 11 dígitos), com ou sem +55	formato E.164 — `+5511999998888`
EVP	UUID (chave aleatória)	minúsculas — `7d9f0c3e-...-a1b2`

Chaves que não correspondem ao tipo informado retornam 422 invalid_pix_key.

Chaves EMAIL, PHONE e EVP

Nesses tipos de chave, a instituição parceira exige o CPF/CNPJ do recebedor, e a Reload Bank informa o CPF/CNPJ do titular da sua conta. Use-os apenas para chaves de sua titularidade; para pagar outra pessoa ou empresa, use a chave CPF ou CNPJ do recebedor.

Status do saque

Status	Significado
`AWAITING_APPROVAL`	Aguardando a análise manual da equipe Reload Bank.
`PROCESSING`	Saque aprovado e enviado à instituição parceira, aguardando a liquidação.
`COMPLETED`	PIX liquidado no destino. pix.end_to_end_id preenchido quando informado pela instituição parceira. Webhook transaction.completed.
`FAILED`	A instituição parceira não concluiu o saque (ex.: chave inexistente). Valor + taxa voltam ao saldo disponível. Motivo em failure_reason. Webhook transaction.failed.
`CANCELED`	Saque recusado na análise. Valor + taxa voltam ao saldo disponível. Webhook transaction.canceled.

Todo saque passa por aprovação manual

Neste momento, todo saque é criado com status AWAITING_APPROVAL e analisado pela equipe antes do envio. O valor fica reservado em blocked durante a análise: se aprovado, segue para PROCESSING → COMPLETED/FAILED; se recusado, vira CANCELED.

O saque é assíncrono: a resposta 201 confirma apenas que ele foi registrado. O resultado final (COMPLETED, FAILED ou CANCELED) chega pelos webhooks — ou consulte GET /transactions/{id}. Mesmo uma resposta 201 pode terminar em FAILED: sempre verifique o status final.

Débito e taxas

No momento da solicitação, amount + fee sai do saldo available e fica reservado em blocked até o resultado final.
Em saques, net_amount representa o total debitado (amount + fee). Taxa padrão: 1,00% + R$ 0,75 por saque; a da sua conta aparece no painel, em Taxas.
Sem saldo suficiente para valor + taxa, a API retorna 422 insufficient_balance e nada é debitado.
A conta precisa ter a verificação em duas etapas (2FA) ativa. Sem ela, a API retorna 403 two_factor_required e nada é debitado.

2FA obrigatório para saques

Ative o 2FA em Configurações → Verificação em duas etapas no painel. Saques feitos pelo painel são confirmados com o código do app autenticador; pela API, a autenticação continua sendo o Bearer token. Recomendamos restringir as credenciais usadas para saque a IPs fixos (allowlist).

Confira a chave antes de enviar

Um PIX liquidado não pode ser desfeito pela API. Valide a chave de destino no seu sistema antes de solicitar o saque.

Requisição

curl -X POST "https://reloadbank.app/api/v1/pix/cash-out" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 250,
  "pix_key": "11.222.333/0001-81",
  "pix_key_type": "CNPJ",
  "external_id": "saque-889",
  "description": "Repasse parceiro"
}'

Resposta

{
  "id": "cm2r9b7vd0009lk08wxyz5678",
  "external_id": "saque-889",
  "type": "PIX_OUT",
  "status": "AWAITING_APPROVAL",
  "amount": 250,
  "fee": 3.25,
  "net_amount": 253.25,
  "description": "Repasse parceiro",
  "pix": {
    "key": "11222333000181",
    "key_type": "CNPJ",
    "end_to_end_id": null
  },
  "payer": null,
  "failure_reason": null,
  "metadata": null,
  "paid_at": null,
  "refunded_at": null,
  "created_at": "2026-10-16T14:45:01.000Z",
  "updated_at": "2026-10-16T14:45:01.000Z"
}

Webhook do resultado

{
  "event": "transaction.completed",
  "data": {
    "id": "cm2r9b7vd0009lk08wxyz5678",
    "external_id": "saque-889",
    "type": "PIX_OUT",
    "status": "COMPLETED",
    "amount": 250,
    "fee": 3.25,
    "net_amount": 253.25,
    "description": "Repasse parceiro",
    "pix": {
      "key": "11222333000181",
      "key_type": "CNPJ",
      "end_to_end_id": "E00000000202610161445Q3V8TN2KD7A"
    },
    "payer": null,
    "failure_reason": null,
    "metadata": null,
    "paid_at": "2026-10-16T14:47:30.000Z",
    "refunded_at": null,
    "created_at": "2026-10-16T14:45:01.000Z",
    "updated_at": "2026-10-16T14:47:30.000Z"
  },
  "created_at": "2026-10-16T14:47:30.412Z"
}