Pular para o conteúdo principal
Um cash-out de Pix move dinheiro de uma conta para um destino externo. O Plugin de Pix Indireto (BTG) faz isso em dois passos deliberados —iniciar e depois processar— para que você sempre confirme para onde o dinheiro está indo antes de qualquer valor sair do ledger.

​
Por que dois passos

Dividir um cash-out em iniciar e processar cria um ponto de verificação entre “quem é o beneficiário?” e “enviar o dinheiro”:
  • Verifique o destino primeiro. Iniciar valida e resolve a conta do beneficiário sem tocar nos saldos. Uma chave Pix incorreta ou uma conta inválida falha aqui — antes de qualquer dinheiro se mover.
  • Mostre ao pagador para quem ele está pagando. A resposta de iniciação retorna o titular da conta resolvido, para que seu aplicativo exiba o nome real e permita ao pagador confirmar antes de se comprometer.
  • Mova fundos apenas com confirmação. Nada é debitado até você processar a transferência. Se o pagador abandonar o fluxo, não há nenhuma reversão a fazer — nunca houve movimentação a desfazer.
Isso reflete como uma boa experiência de pagamento funciona: buscar o destino, confirmar os detalhes e então pagar.
Ambos os passos são idempotentes — é seguro repeti-los sem criar transferências duplicadas. Consulte Retentativas e idempotência.

​
Passo 1 — Iniciar: confirmar o destino

Iniciar uma transferência cria um registro de curta duração que valida e resolve o beneficiário sem mover fundos. Como o plugin encontra o destino depende do que você tem em mãos:
Com o que você começaTipo de iniciaçãoO que o plugin faz
Uma chave Pix (CPF, CNPJ, email, telefone ou EVP)KEYBusca a chave no DICT e resolve a conta de destino para você.
Um QR code (BR Code)QR_CODEDecodifica o código e resolve o destino via DICT. Consulte QR Codes.
Os dados completos da conta do beneficiárioMANUALUsa a agência, conta, participante e documento do titular que você fornece — sem consulta ao DICT.
Para KEY e QR_CODE, você nunca fornece o destino. O plugin o resolve e o retorna na resposta, pronto para mostrar ao pagador para confirmação.

​
Requisição — escolha a aba do seu tipo de iniciação

POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "KEY",
  "key": "john.doe@example.com"
}
Os valores de type de conta são CACC (corrente), SVGS (poupança), TRAN (transacional) e OTHR (outra). endToEndId é opcional para todos os tipos — é gerado automaticamente quando omitido.

​
Resposta

A resposta retorna o id da iniciação (usado como initiationId no passo 2) e o destination resolvido: 
→ 201 Created
{
  "id": "019c96a0-0c82-7c3d-8dcc-c180868b45c4",
  "initiationType": "KEY",
  "endToEndId": "E1234567820240101000001234567890",
  "destination": { "account": { ... }, "owner": { ... } },
  "expiresAt": "2024-01-15T11:00:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}
As iniciações expiram. A resposta inclui um timestamp expiresAt — processe a transferência antes que ela expire, ou inicie novamente. Isso evita que um destino confirmado fique obsoleto entre a busca e o pagamento.
Referência da API: Iniciar uma Transferência Pix

​
Passo 2 — Processar: mover o dinheiro

Processar pega a iniciação que você acabou de confirmar e executa o cash-out: debita a conta de origem e roteia o pagamento para o BTG para liquidação com o BACEN. A liquidação com a rede Pix é assíncrona. A transferência retorna como PROCESSING enquanto o BTG liquida, e o resultado final — concluído ou falho — chega depois por um webhook cashout. Construa seu fluxo para reagir a esse evento em vez de esperar pela resposta de processamento. Consulte Webhooks.

​
Requisição

Passe o id da resposta de iniciação como initiationId, junto com o amount a transferir: 
POST /v1/transfers/cashout/process
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
X-Purpose: TRANSFER
{
  "initiationId": "019c96a0-0c82-7c3d-8dcc-c180868b45c4",
  "amount": "100.50"
}
amount é obrigatório. Você também pode enviar um description opcional (máximo 140 caracteres) e metadata (atributos chave-valor personalizados).

​
O header X-Purpose

Use o header opcional X-Purpose para declarar por que o cash-out está acontecendo. O valor padrão é TRANSFER quando omitido:
ValorQuando usar
TRANSFERUm cash-out de Pix comum — o padrão para pagamentos ordinários.
INSTANT_PAYMENT_REFUNDQuando o cash-out está devolvendo um pagamento instantâneo recebido anteriormente, para que a rede o classifique como uma devolução em vez de uma nova transferência.
QR codes de valor fixo: quando a iniciação é um QR_CODE cujo payload EMV carrega um valor fixo, o amount que você envia para processar deve ser igual a esse valor codificado. Uma divergência é rejeitada antes de qualquer movimentação de fundos.

​
Resposta

→ 201 Created
{
  "id": "019c96a0-0c21-71f9-a487-66a1258278a1",
  "endToEndId": "E1234567820240101000001234567890",
  "amount": "100.50",
  "status": "PROCESSING",
  "type": "CASHOUT",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
Quando o destino pertence à sua própria instituição, o dinheiro nunca sai para o BTG — ele é liquidado internamente como uma transferência P2P. Consulte Transferências intra-PSP.
Referência da API: Processar uma Transferência Pix

​
Acompanhando uma transferência

Toda transferência segue um ciclo de vida previsível: começa em PENDING/PROCESSING enquanto está em andamento, e depois alcança um status terminal COMPLETED, FAILED ou CANCELLED. Para verificar em que ponto uma transferência está, você pode recuperar uma única pelo id, ou listar transferências filtrando por status, tipo (cash-out ou cash-in) ou intervalo de datas. 
GET /v1/transfers?type=CASHOUT&status=COMPLETED&limit=10&offset=0
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
Os filtros de listagem incluem status, type (CASHOUT/CASHIN), end_to_end e modified_after/modified_before, além da paginação limit/offset/sort_order.
Referência da API: Listar transferências · Recuperar uma transferência

​
Quando uma transferência fica travada

Se a chamada de liquidação ao BTG expirar antes de confirmar, uma transferência pode ficar em PROCESSING com seus fundos ainda retidos. O plugin oferece uma operação de unblock que reconsulta a transferência com o BTG e a leva ao status final correto — liquidando-a se o BTG confirmar, ou liberando a retenção se o BTG nunca a recebeu.
Unblock não se aplica a transferências intra-PSP — não há nenhuma transação do BTG para reconsultar. Para o comportamento completo do unblock e suas opções, consulte Operações de devolução.

​
Próximos passos