Transferências e cash-out

Um cash-out Pix move dinheiro de uma conta para um destino externo. O Plugin Pix Indireto (BTG) executa isso em dois passos: iniciar e depois processar. Você confirma para onde o dinheiro vai antes de qualquer valor sair do ledger.

Por que dois passos

Dividir um cash-out em iniciar e processar dá a você um ponto de verificação entre “quem é o recebedor?” e “envie o dinheiro”:

Confirme o destino primeiro. A iniciação valida e resolve a conta do recebedor sem tocar em saldos. Uma chave Pix errada ou uma conta inválida falha aqui, antes de qualquer dinheiro se mover.
Mostre ao pagador quem recebe o dinheiro. A resposta da iniciação retorna o titular resolvido da conta. Seu app pode mostrar o nome real e deixar o pagador confirmar antes.
Mova os fundos apenas na confirmação. O plugin não debita nada até você processar a transferência. Se o pagador abandonar o fluxo, não há movimentação a desfazer.

Os dois passos são idempotentes. Você pode repeti-los sem criar transferências duplicadas. Veja Novas tentativas e idempotência.

Passo 1: iniciar (confirme o destino)

Iniciar uma transferência cria um registro de vida curta que valida e resolve o recebedor sem mover fundos. Como o plugin encontra o destino depende do que você tem no começo:

Você começa com	Tipo de iniciação	O que o plugin faz
Uma chave Pix (CPF, CNPJ, email, telefone ou EVP)	`KEY`	Consulta a chave no DICT e resolve a conta de destino para você.
Um QR code (BR Code)	`QR_CODE`	Decodifica o código e resolve o destino pelo DICT. Veja QR Codes.
Os dados completos da conta do recebedor	`MANUAL`	Usa a agência, a conta, o participante e o documento do titular que você informa — sem consulta ao DICT.

Para KEY e QR_CODE, você nunca informa 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"
}

POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "QR_CODE",
  "emv": "00020126...5802BR5913Fulano..."
}

POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "MANUAL",
  "destination": {
    "account": {
      "branch": "0001",
      "number": "123456789",
      "participant": "12345678",
      "type": "CACC"
    },
    "owner": {
      "document": "12345678901",
      "name": "John Doe"
    }
  }
}

Os valores de type da conta são CACC (corrente), SVGS (poupança), TRAN (transacional) e OTHR (outra). endToEndId é opcional para todos os tipos. O plugin gera um quando você o omite.

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 de novo. Isso impede que um destino confirmado fique desatualizado entre a consulta e o pagamento.

Referência da API: Iniciar uma transferência Pix

Passo 2: processar (mover o dinheiro)

O processamento executa o cash-out a partir da iniciação que você confirmou. Ele debita a conta de origem e depois roteia o pagamento ao BTG para liquidação com o BACEN. A liquidação com a rede Pix é assíncrona. A transferência volta como PROCESSING enquanto o BTG liquida. O resultado final (concluído ou falho) chega depois por um webhook cashout. Monte seu fluxo para reagir a esse evento, não para esperar a resposta do processamento. Veja 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 passar um description opcional (máximo de 140 caracteres) e metadata (atributos chave-valor customizados).

O header `X-Purpose`

Use o header X-Purpose opcional para declarar o motivo do cash-out. Ele assume TRANSFER como padrão quando é omitido:

Valor	Quando usar
`TRANSFER`	Um cash-out Pix comum — o padrão para pagamentos ordinários.
`INSTANT_PAYMENT_REFUND`	Quando o cash-out devolve um pagamento instantâneo recebido antes, para que a rede possa classificá-lo como devolução e não como nova transferência.

QR codes de valor fixo: a iniciação pode ser um QR_CODE cujo payload EMV carrega um valor fixo. Nesse caso, o amount que você envia ao processar deve ser igual ao valor codificado. Uma divergência é rejeitada antes de qualquer fundo se mover.

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 liquida internamente como uma transferência P2P. Veja Transferências intra-PSP.

Referência da API: Processar uma transferência Pix

Acompanhar uma transferência

Toda transferência segue o mesmo ciclo de vida. Ela começa em PENDING/PROCESSING enquanto está em trânsito e depois chega a um COMPLETED, FAILED ou CANCELLED terminal. Para ver em que ponto uma transferência está, consulte uma delas pelo id. Você também pode listar transferências filtradas por status, tipo (cash-out ou cash-in) ou período.

GET /v1/transfers?type=CASHOUT&status=COMPLETED&limit=10&page=1
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 page/limit/sort_order.

Referência da API: Listar transferências · Consultar uma transferência

Como as transferências chegam ao Midaz

O plugin lança toda movimentação liquidada no Midaz como uma transação no ledger, com a perna externa contra a conta @external/BRL. O Midaz registra o lançamento e os metadados de correlação, não os dados bancários completos da transferência. Agência, número da conta, tipo de conta e chave Pix da contraparte nunca chegam ao Midaz. A única exceção é a identidade do pagador no cash-in (sourceBank, sourceDocument, sourceName), gravada quando é conhecida. O detalhe completo da contraparte fica no registro de transferência do plugin. Os metadados gravados na transação do Midaz dependem do fluxo:

Fluxo	Chaves de metadados
Cash-out	`initiationId`, `endToEndId`, `accountId`, `transferType: CASHOUT`, `paymentType`, `initiationType`
Cash-in	`endToEndId`, `accountId`, `transferType: CASHIN`, `paymentType`, `initiationType` — mais `sourceBank`, `sourceDocument` e `sourceName` quando o pagador é conhecido
Devolução (saída)	`refundId`, `originalEndToEndId`, `returnIdentification`, `accountId`, `transferType: REFUND_CASHOUT`, `refundType`, `reason`
Devolução (entrada)	As mesmas chaves de devolução com `transferType: REFUND_CASHIN`

O code da transação no Midaz também carrega o endToEndId (ou a returnIdentification nas devoluções), então o identificador E2E fica visível direto no lançamento do ledger. A correlação funciona nos dois sentidos:

O plugin guarda os identificadores de transação e de operação do Midaz nos seus próprios registros de transferência e de devolução, e os usa para confirmar, cancelar ou reverter lançamentos.
A transação do Midaz carrega chaves de correlação nos seus metadados: filtre por metadata.endToEndId para cash-outs e cash-ins, ou por metadata.originalEndToEndId / metadata.returnIdentification para devoluções. O code da transação é o fallback comum. Ele carrega o ID E2E nas transferências e a identificação de devolução nas devoluções.

O metadata customizado que você passa ao processar um cash-out é guardado com o registro de transferência do plugin e retornado pela API do próprio plugin. Ele não é copiado para a transação do Midaz. O plugin fixa as chaves de metadados do Midaz listadas acima.

Quando uma transferência trava

Se a chamada de liquidação ao BTG der timeout antes de o BTG confirmar, uma transferência pode ficar em PROCESSING com os fundos retidos. O plugin oferece uma operação de desbloqueio. O desbloqueio reconsulta a transferência no BTG e a leva ao estado final correto. Ele liquida a transferência se o BTG confirmar, ou libera a retenção se o BTG nunca a tiver recebido.

O desbloqueio não se aplica a transferências intra-PSP. Não há transação no BTG para reconsultar. Para o comportamento completo do desbloqueio e suas opções, veja Operações de devolução.

Próximos passos

Transferências intra-PSP: Liquidação P2P interna
QR Codes: Geração e decodificação de QR codes
Operações de devolução: Devoluções e desbloqueio
Webhooks: Tratamento de eventos de cash-out e cash-in
Referência da API: Detalhes completos de requisição e resposta, headers e schemas de campos

​Por que dois passos

​Passo 1: iniciar (confirme o destino)

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

​Resposta

​Passo 2: processar (mover o dinheiro)

​Requisição

​O header X-Purpose

​Resposta

​Acompanhar uma transferência

​Como as transferências chegam ao Midaz

​Quando uma transferência trava

​Próximos passos

Por que dois passos

Passo 1: iniciar (confirme o destino)

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

Resposta

Passo 2: processar (mover o dinheiro)

Requisição

O header `X-Purpose`

Resposta

Acompanhar uma transferência

Como as transferências chegam ao Midaz

Quando uma transferência trava

Próximos passos