Skip to main content

​
Objetivo

Enviar Pix para CPF, CNPJ, e-mail, telefone (E.164) ou chave aleatória (evp) via POST /api/pix/cash-out.

​
Request (exemplo)

{
  "transaction": {
    "value": 500.00,
    "externalId": "saque-789",
    "description": "Pagamento Fornecedor ABC"
  },
  "recipient": {
    "name": "Maria Oliveira",
    "document": "987.654.321-00",
    "pixKey": "maria@email.com",
    "pixKeyType": "email"
  }
}
CampoObrigatórioDescrição
transaction.valueSimValor > 0 (BRL no request, conforme convenção).
transaction.externalIdSimÚnico por operação.
recipient.nameSimNome do favorecido.
recipient.pixKeySimChave.
recipient.pixKeyTypeSimcpf, cnpj, email, phone, evp.
recipient.documentNãoDocumento.

​
Tipos de chave

pixKeyTypeFormato
cpfCom ou sem máscara.
cnpjCom ou sem máscara.
emailE-mail válido.
phoneE.164, ex. +5511999999999.
evpUUID (chave aleatória).

​
Reserva de saldo e tarifa

Na criação, a plataforma pode reservar valor + teto de tarifa (domínio: max_fee_cents / reserved_total_cents) para que a confirmação não dependa de saldo “livre” imediato no instante exato do webhook. Detalhes numéricos no GET /api/pix/cash-out/{id}.

​
Resposta imediata

A resposta do 201 reflete o estado no momento do commit: pode ser um dos estados de domínio (incluindo pipeline: CREATED, RESERVED, DISPATCH_PENDING, DISPATCHED, PROVIDER_RESULT_UNKNOWN, etc. — status), e não necessariamente apenas a palavra PENDING (há nota de compatibilidade com PENDING legado).

​
Outbox, despacho e confirmação

Após o 201, o cash-out percorre reserva → fila (outbox) → despacho ao BaaS. Falhas ambíguas na chamada HTTP (timeout, 5xx, EOF) não liberam a reserva de forma imprudente: entram em reconciliação (fluxo de reconciliação). O webhook pix_cash_out ao comerciante acompanha confirmação/falha terminal de liquidação quando aplicável.

​
Falha ambígua e consulta

Se o estado estiver PROVIDER_RESULT_UNKNOWN ou RECONCILIATION_REQUIRED, não conclua “pago” ou “falhou” com base em suposição única. Use reconcilição e consulta de detalhe com correlação operacional.

​
Diferença do pagamento via QR (EMV)

Para pagar a partir de pix copia e cola (EMV), use cash-out por QR Code. O ciclo e webhooks seguem a mesma família; no detalhe, paymentType indica key vs qrcode.

​
API reference