Transferências e cash-out

Um cash-out de Pix move dinheiro de uma conta para um destino externo. O Plugin de Pix Indireto (BTG) o executa 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 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 quem recebe o dinheiro. A resposta de iniciação retorna o titular da conta resolvido. Seu aplicativo pode exibir o nome real e permitir ao pagador confirmar primeiro.
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ça	Tipo de iniciação	O que o plugin faz
Uma chave Pix (CPF, CNPJ, email, telefone ou EVP)	`KEY`	Busca 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 via DICT. Consulte QR Codes.
Os dados completos da conta do beneficiário	`MANUAL`	Usa 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"
}

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 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 executa o cash-out a partir da iniciação que você confirmou. Debita a conta de origem e depois 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. O resultado final — concluído ou falho — chega depois por um webhook cashout. Construa seu fluxo para reagir a esse evento, não para 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 o motivo do cash-out. O valor padrão é TRANSFER quando omitido:

Valor	Quando usar
`TRANSFER`	Um cash-out de Pix comum — o padrão para pagamentos ordinários.
`INSTANT_PAYMENT_REFUND`	Quando 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: a iniciação pode ser um QR_CODE cujo payload EMV carrega um valor fixo. Nesse caso, 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á, recupere uma única pelo id. Você também pode 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&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 · Recuperar uma transferência

Como as transferências chegam ao Midaz

O plugin registra cada movimentação liquidada no Midaz como uma transação de ledger, com a perna externa contra a conta @external/BRL. O Midaz guarda o lançamento contábil e os metadados de correlação — não os detalhes 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), carimbada quando conhecida. O detalhe completo da contraparte fica no registro de transferência do plugin. Os metadados carimbados na transação 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 Midaz também carrega o endToEndId (ou o returnIdentification nas devoluções), então o identificador E2E fica visível diretamente no lançamento do ledger. A correlação funciona nos dois sentidos:

O plugin armazena os identificadores da transação e das operações Midaz nos próprios registros de transferência e devolução, e os usa para confirmar, cancelar ou reverter lançamentos no ledger.
A transação Midaz carrega chaves de correlação nos 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 é a alternativa comum — carrega o E2E ID nas transferências e a identificação de devolução nas devoluções.

Os metadados personalizados que você envia ao processar um cash-out (metadata) são armazenados com o registro de transferência do plugin e retornados pela API do próprio plugin. Eles não são copiados para a transação Midaz — as chaves de metadados do Midaz acima são fixas, definidas pelo plugin.

Quando uma transferência fica travada

Se a chamada de liquidação ao BTG expirar antes de o BTG confirmar, uma transferência pode ficar em PROCESSING com seus fundos retidos. O plugin oferece uma operação de unblock. O unblock reconsulta a transferência com o BTG e a leva ao status final correto. Liquida a transferência se o BTG confirmar, ou libera 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

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 unblock
Webhooks — Tratamento de eventos de cash-out e cash-in
Referência da API — Detalhes completos de requisição/resposta, headers e schemas de campos

Visão geral

Lerian SPI — mensageria nativa

JD — interface (Pix direto)

BTG — interface (Pix indireto)

Transferências e cash-out

Por que dois passos

Passo 1 — Iniciar: confirmar 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

Acompanhando uma transferência

Como as transferências chegam ao Midaz

Quando uma transferência fica travada

Próximos passos

​Por que dois passos

​Passo 1 — Iniciar: confirmar 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

​Acompanhando uma transferência

​Como as transferências chegam ao Midaz

​Quando uma transferência fica travada

​Próximos passos

Por que dois passos

Passo 1 — Iniciar: confirmar 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

Acompanhando uma transferência

Como as transferências chegam ao Midaz

Quando uma transferência fica travada

Próximos passos