> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Transferências e cash-out > Envie cash-out Pix pelo Plugin Pix Indireto via BTG: o fluxo de dois passos, iniciar e processar, que confirma o destino antes de mover os fundos. 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. > [!NOTE] > > Os dois passos aceitam uma chave `X-Idempotency`. Repita com a mesma chave para evitar transferências duplicadas. Veja [Novas tentativas e idempotência](https://docs.lerian.studio/pt/reference/retries-idempotency.md). ## 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](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-dict.md) 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](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-qrcodes.md). | | 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 ```json KEY theme={null} POST /v1/transfers/cashout/initiate X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d { "initiationType": "KEY", "key": "john.doe@example.com" } ``` ```json QR_CODE theme={null} POST /v1/transfers/cashout/initiate X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d { "initiationType": "QR_CODE", "emv": "00020126...5802BR5913Fulano..." } ``` ```json MANUAL theme={null} 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. Se você enviar um `endToEndId` que um Pix ou um agendamento já possui, o plugin responde `409` `PIX-0423`. ### Resposta A resposta retorna o `id` da iniciação (usado como `initiationId` no passo 2) e o `destination` resolvido: ```json theme={null} → 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" } ``` > [!NOTE] > > 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. > [!TIP] > > **Referência da API:** [Iniciar uma transferência Pix](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/initiate-a-pix-transfer.md) ## 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 (por exemplo `COMPLETED` ou `REJECTED`) chega depois por um webhook `TRANSFER` / `CASHOUT`. Monte seu fluxo para reagir a esse evento, não para esperar a resposta do processamento. Veja [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md). ### Requisição Passe o `id` da resposta de iniciação como `initiationId`, junto com o `amount` a transferir: ```json theme={null} 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. | | `WITHDRAWAL` | Quando a iniciação `QR_CODE` é uma cobrança de Pix Saque. | | `CHANGE` | Quando a iniciação `QR_CODE` é uma cobrança de Pix Troco. | > [!NOTE] > > **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 ```json theme={null} → 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" } ``` Se o resultado do débito no Midaz é desconhecido, a chamada responde `201` com o cash-out em `CREATED` em vez de `PROCESSING`. O plugin não envia nenhum Pix. A iniciação continua aberta, e uma nova tentativa da chamada de processamento responde este mesmo cash-out em vez de debitar de novo. Para um cash-out inter-PSP, abra um chamado de suporte com a Lerian e informe o id da transferência. > [!NOTE] > > Quando o destino pertence à sua própria instituição, o dinheiro nunca sai para o BTG. Ele liquida internamente em uma única transação no Midaz, como uma transferência P2P. Veja [Transferências intra-PSP](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-intra-psp.md). > [!TIP] > > **Referência da API:** [Processar uma transferência Pix](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/process-a-pix-transfer.md) ## Acompanhar uma transferência *** Uma transferência começa em `CREATED` e passa por `PENDING`/`PROCESSING` enquanto está em trânsito. Depois, ela chega a um `COMPLETED`, `FAILED`, `CANCELLED` ou `REJECTED` 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. ```json theme={null} 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`. Um cash-in que pagou um QR Code carrega `txId`, o txId que o QR Code declarou, nas leituras de transferência e no webhook `TRANSFER` / `CASHIN`. Para uma cobrança dinâmica, o plugin o conferiu com a cobrança. Para um QR Code estático, ele é apenas um rótulo de referência. Um cash-out e um pagamento sem QR Code não carregam `txId`. > [!TIP] > > **Referência da API:** [Listar transferências](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-pix-transfers.md) · [Consultar uma transferência](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/retrieve-a-pix-transfer.md) ## Pagamentos agendados *** Um pagamento agendado executa um cash-out Pix em uma data e hora futuras. Primeiro, inicie a transferência como no passo 1. Depois, passe o `id` da iniciação como `initiationId` para `POST /v1/schedules`, com o `amount` e a data e hora `scheduledFor`: ```json theme={null} POST /v1/schedules X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d X-Idempotency: 7b2c4f8a-3d1e-4c5b-9a6f-8e2d1c7b4a3f { "initiationId": "019c96a0-0c82-7c3d-8dcc-c180868b45c4", "scheduledFor": "2026-08-15T09:00:00Z", "amount": "100.50" } ``` O agendamento usa o destino da iniciação. `scheduledFor` deve estar pelo menos `SCHEDULE_MIN_FUTURE_SECONDS` no futuro e no máximo `SCHEDULE_MAX_FUTURE_DAYS` dias à frente. Você também pode passar uma `description` opcional (até 140 caracteres) e `maxAttempts` (`1` ou `2`). Se você omitir `maxAttempts`, o plugin usa `SCHEDULE_MAX_ATTEMPTS`. Um agendamento começa em `SCHEDULED`. No horário agendado, o worker de agendamento o move para `PROCESSING` e executa o cash-out. Depois, o agendamento termina em `EXECUTED`, `FAILED` ou `CANCELLED`. Para cancelar um agendamento, envie `DELETE /v1/schedules/{schedule_id}` enquanto ele está em `SCHEDULED`. Um agendamento que o plugin rearmou após uma tentativa travada não pode ser cancelado: o cancelamento responde `409`. O plugin envia um webhook `SCHEDULE` / `CASHOUT` com o tipo de evento `schedule.executed`, `schedule.failed` ou `schedule.cancelled`. > [!TIP] > > **Referência da API:** [Criar um agendamento Pix](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-a-pix-schedule.md) · [Listar agendamentos](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-pix-schedules.md) · [Consultar um agendamento](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/get-a-pix-schedule.md) · [Cancelar um agendamento](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/cancel-a-pix-schedule.md) ## Pix Automático (pagador) *** O Pix Automático permite que um recebedor debite a conta do pagador em uma agenda, depois que o pagador autoriza. O plugin cuida do lado do pagador. As chamadas recebem a conta do pagador no header `X-Account-Id`. Na listagem de autorizações, o header é opcional. Sem ele, a lista cobre todas as contas. | Tarefa | Endpoint | | - | - | | Ver as solicitações de autorização | `GET /v1/recurrences/payer/authorization-requests` lista as solicitações. `GET /v1/recurrences/payer/authorization-requests/{id}` retorna uma solicitação. | | Aceitar ou recusar uma solicitação | `POST /v1/recurrences/payer/authorization-requests/{id}/decision`, com `decision` igual a `ACCEPTED` ou `REJECTED`. | | Confirmar uma recorrência de um QR code | `POST /v1/recurrences/payer/qr/confirm`, com o `idRec` da recorrência lida, a `decision` e a `journey` (`J2` ou `J4`). | | Pagar e confirmar em uma chamada | `POST /v1/recurrences/payer/qr/pay-and-confirm`. Ele processa o cash-out da cobrança do QR code (`initiationId` e `amount`) e confirma a recorrência (`idRec`). Enquanto a solicitação ainda está em `INITIATED` e tem um cash-out, a chamada responde com o status desse cash-out. Quando esse cash-out falhou, ela responde `422` `PIX-0916`. Depois que a solicitação sai de `INITIATED`, ela responde `409` `PIX-0902`: leia a solicitação em vez de pagar de novo. Se outra chamada está pagando a mesma solicitação, a chamada responde `500`: tente de novo. | | Ver as autorizações | `GET /v1/recurrences/payer/authorizations` lista as autorizações, com `nextChargeAt` e `nextChargeAmount`. `GET /v1/recurrences/payer/authorizations/{id}` retorna uma autorização. | | Ver as cobranças | `GET /v1/recurrences/payer/authorizations/{authorizationId}/charges` lista as cobranças de uma autorização. `GET /v1/recurrences/payer/charges/{id}` retorna uma cobrança. | | Cancelar uma autorização | `POST /v1/recurrences/payer/authorizations/{id}/cancel`, com `reasonKind` igual a `PAYER` ou `FRAUD`. Com `FRAUD`, envie também `reasonText` e `cancelledBy`. | Quando você aceita uma solicitação, ela passa para `APPROVING`. A autorização começa quando o BTG a aprova. Quando o plugin aceita uma cobrança do recebedor, ele cria um [pagamento agendado](#scheduled-payments) para essa cobrança. O plugin envia webhooks `RECURRING` para as entidades `AUTHORIZATION_REQUEST`, `AUTHORIZATION` e `CHARGE`. Veja [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md). > [!TIP] > > **Referência da API:** [Listar solicitações de autorização](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-pix-automatico-authorization-requests.md) · [Decidir sobre uma solicitação](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/decide-on-a-pix-automatico-authorization-request.md) · [Confirmar uma recorrência lida](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/confirm-a-scanned-pix-automatico-recurrence.md) · [Pagar e confirmar](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/pay-and-confirm-a-scanned-pix-automatico-recurrence.md) · [Listar autorizações](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-pix-automatico-authorizations.md) · [Listar cobranças](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/list-pix-automatico-charges-by-authorization.md) · [Cancelar uma autorização](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/cancel-a-pix-automatico-authorization.md) ## 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`. Uma transferência ou devolução intra-PSP é uma única transação entre as contas da sua instituição, sem perna externa. 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` | | Cash-out intra-PSP | As chaves do cash-out, mais `intraPsp: true` e `payeeAccountAlias` | | Devolução intra-PSP | As chaves de uma devolução (saída), mais `intraPsp: true` | 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. > [!NOTE] > > 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. ## Verificação de fraude em Pix recebido *** O plugin pode consultar um endpoint de decisão que você opera antes de aceitar um Pix recebido ou uma devolução recebida. A verificação vem desligada por padrão. Para ligá-la, defina `ANTIFRAUD_HOOK_ENABLED=true` e as outras [variáveis da verificação de fraude](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-environment-variables.md#fraud-check-on-incoming-pix). O plugin envia uma requisição `POST` com um corpo JSON para `ANTIFRAUD_HOOK_URL`: * `contractVersion`: `1.0`. * `eventType`: `PIX_CASHIN` para um Pix recebido, ou `PIX_REFUND_CASHIN` para uma devolução recebida. * `approvalId`: um UUID que identifica a verificação. * `requestedAt` e `respondBy`: timestamps em UTC. `respondBy` é `requestedAt` mais `ANTIFRAUD_HOOK_TIMEOUT_MS`. * `cashin`, em `PIX_CASHIN`: `amount`, `endToEndId`, `transactionIdentification`, `transactionType`, `paymentType`, `initiationType`, `urgency`, `remittanceInformation`, `movementIds`, `debitParty`, `creditParty` e `account`. Cada parte tem `name`, `taxId`, `personType`, `bank`, `branch`, `account`, `accountType` e `key`. `cashin.account` tem `accountId`, `aliasId`, `holderId` e `document`. * `refundCashin`, em `PIX_REFUND_CASHIN`: `returnIdentification`, `originalEndToEndId`, `amount`, `reason`, `additionalInformation` e `originalTransaction`. `originalTransaction` tem `endToEndId`, `amount`, `createdAt` e `creditParty` com `name`, `taxId`, `bank`, `branch` e `account`. * `metadata`: um objeto vazio. O plugin omite `transactionIdentification`, `remittanceInformation`, `key`, `aliasId`, `holderId` e `additionalInformation` quando estão vazios. Cada requisição traz estes headers: * `X-Webhook-Timestamp`: o horário Unix, em segundos, em que o plugin assinou a requisição. * `X-Webhook-Signature`: `v1,sha256=`. `` é o HMAC-SHA256 de `v1:.` com `ANTIFRAUD_HOOK_HMAC_SECRET` como chave. `` é o valor de `X-Webhook-Timestamp`. * `Idempotency-Key`: o `approvalId`. Para verificar uma requisição, calcule o mesmo valor sobre o corpo bruto da requisição e compare-o com `X-Webhook-Signature`. Responda com um status `2xx` e um objeto JSON com `decision` e um `reason` opcional. O plugin registra `reason` como `antifraudReason`. Ele lê `decision` sem diferenciar maiúsculas de minúsculas: * `APPROVE` ou `ALLOW` aceita o Pix. * `REJECT`, `DENY` ou `REVIEW` recusa o Pix ao BTG com o código de motivo `FRAD`. Quando o plugin não recebe uma decisão, ele aplica a sua política de fallback. Isso acontece em um timeout, um erro de conexão, um status fora de `2xx`, uma resposta que ele não consegue ler ou um circuit breaker aberto. Também acontece quando um Pix recebido não traz dados do pagador. O plugin não faz a verificação em créditos e devoluções intra-PSP, nem em créditos de devolução MED (`INSTANT_PAYMENT_REFUND` e `REFUND_AUTOMATIC_PIX`). Um Pix recusado não cria cash-in nem devolução. O plugin registra cada decisão no webhook de entrada armazenado. [Consultar um webhook de entrada](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/get-an-inbound-webhook.md) retorna a decisão em `payload.metadata`: `antifraudDecision`, `antifraudSource`, `antifraudReason` e `antifraudLatencyMs`. Também retorna `antifraudRawDecision` quando o seu endpoint respondeu, ou `antifraudPolicy` quando o fallback decidiu. ## 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. > [!NOTE] > > O desbloqueio liquida uma transferência intra-PSP somente no Midaz, porque o BTG nunca a retém. Para o comportamento completo do desbloqueio e suas opções, veja [Operações de devolução](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-refund-operations.md). ## Próximos passos *** * [Transferências intra-PSP](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-intra-psp.md): Liquidação P2P interna * [QR Codes](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-qrcodes.md): Geração e decodificação de QR codes * [Operações de devolução](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-refund-operations.md): Devoluções e desbloqueio * [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md): Tratamento de eventos de cash-out e cash-in * [Referência da API](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/initiate-a-pix-transfer.md): Detalhes completos de requisição e resposta, headers e schemas de campos This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.