Skip to main content

​
Visão geral

Crie transferências PIX de saída em contas BRL com POST /api/v1/br/transactions/outbound. Exige saldo líquido suficiente. A transação inicia em processing se aceita, ou cancelled se não puder ser criada.

​
Campos obrigatórios

  • accountId, amount
  • name — nome do beneficiário
  • keyType — document, email, evp, phone ou cnpj
  • keyPix — chave PIX de destino conforme keyType (obrigatória; não pode ser omitida)

​
Campos opcionais

  • document — CPF ou CNPJ do beneficiário (11 ou 14 dígitos). Encaminhado ao provedor PIX quando informado. Você pode enviar valores formatados (por exemplo 123.456.789-01); a HG.Cash normaliza para dígitos antes de chamar o provedor.

​
Cash-in vs cash-out

O cash-in PIX exige document do pagador. Payouts de saída exigem keyType + keyPix porque a API do provedor de saque por chave usa pixKey (obrigatório) e document (opcional). O document opcional no cash-out identifica o titular da chave quando enviado — não substitui keyPix. Quando keyType é document ou cnpj, envie keyPix como chave de destino. A HG.Cash remove pontuação antes de encaminhar chaves CPF/CNPJ ao provedor.

​
Atualizações de status

Webhooks de status usam o corpo de movimentação de conta (topic TRANSACTION, eventType status_change). Um identificador end-to-end de PIX armazenado é enviado como endToEndId e omitido quando vazio. Veja Identificador end-to-end PIX.

​
Exemplos

Chave email:
Chave CPF (keyType: document). Você pode enviar CPF com ou sem máscara em keyPix; a HG.Cash encaminha apenas dígitos:

​
Ciclo do payout

Um payout aceito inicia em processing. Vai para done quando a transferência PIX é liquidada, ou para cancelled quando o provedor rejeita ou falha. Resultados do provedor como FAILED e REJECTED da Zetta/Bankizi são normalizados para cancelled. A HG.Cash não expõe um status failed separado nos payouts do Brasil. Use polling (GET /api/v1/br/transactions/{id}/status) ou seu webhook para reagir às mudanças.

​
Status da conta

A conta de origem deve estar Operativa. Requisições contra contas Bloqueada ou Cerrada retornam 403 com code: ACCOUNT_NOT_OPERATIVE.