> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Guia de Cash Out (PIX Out)

Este guia explica passo a passo como realizar transferências PIX (cash out) com
consulta prévia de chave. O pagamento de **boleto**, que é o outro cash out da
API, está em [Boleto Pay](/baas/guias/pagar/boleto-pay). Para pagar dezenas ou
milhares de PIX a partir de um arquivo, com conferência e aceite antes do
débito, veja [PIX em lote](/baas/guias/pagar/pix-em-lote).

## Visão Geral

O Cash Out permite enviar dinheiro via PIX para qualquer chave cadastrada no sistema PIX brasileiro. O fluxo recomendado é:

1. **Consultar a chave** - Validar e obter os dados do destinatário
2. **Confirmar os dados** - Exibir para o usuário para confirmação
3. **Executar a transferência** - Enviar o PIX

## Fluxo de Integração

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Consultar  │      │   Confirmar │      │   Executar  │
│    Chave    │ ───► │    Dados    │ ───► │ Transferência│
└─────────────┘      └─────────────┘      └─────────────┘
      │                     │                    │
      ▼                     ▼                    ▼
  Nome, Banco,           Usuário              E2E gerado,
  Conta, CPF/CNPJ        Confirma             Webhook enviado
```

## Tipos de Chave PIX

| Tipo    | Formato            | Exemplo                                |
| ------- | ------------------ | -------------------------------------- |
| `CPF`   | 11 dígitos         | `12345678901`                          |
| `CNPJ`  | 14 dígitos         | `12345678000199`                       |
| `EMAIL` | E-mail válido      | `joao@email.com`                       |
| `PHONE` | +55 + DDD + número | `+5511999998888`                       |
| `EVP`   | UUID               | `123e4567-e89b-12d3-a456-426614174000` |

## Passo 1: Consultar a Chave PIX (Opcional mas Recomendado)

Antes de transferir, consulte a chave para validar o destinatário e exibir os dados para confirmação do usuário:

```bash
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/key/12345678901" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"
```

> **Info**
>
> A API consulta a chave automaticamente durante a transferência — a consulta prévia é opcional, mas melhora a experiência do usuário. O resultado fica em cache por 24 h (use `?noCache=true` para forçar uma consulta nova ao DICT) e consome cota de consultas conforme as [políticas do tenant](/baas/guias/autenticacao/politicas#limites-de-dict-lookup). O consumo de DICT é medido em tempo real e acompanhado pela CorpX: antes de integrar, leia [Consultas de chave PIX](/baas/guias/pagar/consulta-dict).

### O que a transferência devolve

A resposta da transferência **não** repete os dados do destinatário: ela traz o desfecho da operação (`status`, `paymentId`, `endToEndId`). Nome e documento de quem recebeu aparecem no extrato e no lookup do pagamento.

## Passo 2: Executar a Transferência

Execute a transferência PIX via chave:

### Request

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfer-order-12345" \
  -d '{
    "amount": 100.00,
    "keyType": "CPF",
    "key": "12345678901",
    "description": "Service payment",
    "identifier": "order-12345"
  }'
```

### Parâmetros do Body

A conta de origem vem do path (`{accountId}`) e a moeda é sempre BRL — nenhum dos dois é enviado no body.

| Campo         | Tipo   | Obrigatório | Descrição                                                                                                                    |
| ------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `amount`      | number | Sim         | Valor em BRL (ex.: 100.00)                                                                                                   |
| `keyType`     | string | Sim         | Tipo da chave: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`                                                                        |
| `key`         | string | Sim         | Chave PIX do destinatário                                                                                                    |
| `description` | string | Não         | Descrição da transferência (máximo 140 caracteres)                                                                           |
| `identifier`  | string | Não         | Identificador fornecido pelo integrador para rastreamento e conciliação. Aparece no extrato quando o pagamento é conciliado. |

### Resposta de Sucesso

O status HTTP reflete o desfecho: **200** (`COMPLETED`), **422** (`FAILED`),
**202** (`TIMEOUT`/`PENDING` — indeterminado; confira o extrato antes de
reenviar).

Rejeições imediatas do liquidante (antifraude ou saldo insuficiente na
liquidação) retornam `422 FAILED` na hora, com `errorCode`
(`partner_rejected` / `insufficient_funds`) e `errorReason` preenchidos.
Transferências retidas no banco liquidante aparecem como
`PENDING_APPROVAL` nas consultas e aguardam o desfecho por até \~25 minutos
antes de marcar `TIMEOUT`; o resultado chega pelos webhooks
`pix.out.completed` / `pix.out.failed` / `pix.out.timeout`.

Nesse estado a consulta e o `pix.out.timeout` trazem `hold`
(`owner: "partner"` + `reason`) e o estado bruto em
`partnerStatus`/`partnerStatusId`. `PENDING_APPROVAL` **nunca** significa
aprovação pendente do seu lado ou do nosso: a decisão é do liquidante.
E `TIMEOUT` não é o fim — seguimos consultando por até 7 dias e, se ele
liquidar ou recusar, você recebe `pix.out.completed` / `pix.out.failed`
com `late: true` e o mesmo `paymentId`.

```json
{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "transactionId": "txn-abc123-def456",
  "endToEndId": "E12345678202301011234abcdefghijkl",
  "status": "COMPLETED",
  "completedAt": "2026-01-28T15:00:02Z",
  "identifier": "order-12345",
  "workflowId": "pix-out-{accountId}-{identifier}"
}
```

| Campo                       | Descrição                                                  |
| --------------------------- | ---------------------------------------------------------- |
| `paymentId`                 | ID interno da intenção de pagamento (rastreio/conciliação) |
| `transactionId`             | ID da transação                                            |
| `endToEndId`                | ID E2E BACEN (presente após liquidar)                      |
| `status`                    | `COMPLETED`, `FAILED`, `TIMEOUT`, `PENDING`, `PROCESSING`  |
| `errorCode` / `errorReason` | preenchidos quando `FAILED`                                |

### Resposta de Erro

```json
{
  "errorCode": "insufficient_funds",
  "message": "Saldo insuficiente na conta do liquidante para concluir a operação."
}
```

### Timeout no fluxo síncrono

Se o liquidante não confirmar dentro da janela, a API responde **202** com
`status: "TIMEOUT"` e um campo `warning` — não existe `207`. O PIX pode ter
sido enviado: consulte o extrato ou o lookup do pagamento antes de reenviar.
O desfecho tardio chega por webhook (`pix.out.completed` / `pix.out.failed`).

### Fluxo assíncrono (recomendado para alto volume)

Use `POST /v1/accounts/{accountId}/pix/out/async` para agendar o pagamento e receber `202` imediato:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/async" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfer-order-async-12345" \
  -d '{
    "amount": 100.00,
    "keyType": "CPF",
    "key": "12345678901",
    "description": "Service payment",
    "identifier": "order-12345-async"
  }'
```

Resposta:

```json
{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "workflowId": "pix-out-{accountId}-{identifier}",
  "runId": "b7c1f0e2-...",
  "idempotencyKey": "transfer-order-async-12345",
  "identifier": "order-12345-async",
  "status": "ACCEPTED"
}
```

A resposta `202` inclui o header `Location` apontando para
`/v1/accounts/{accountId}/payments/{identifier}` — um alias mantido por
compatibilidade, que responde com headers `Deprecation`. A rota canônica de
consulta é `GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=`.
O resultado final (sucesso/falha) é entregue por webhook e também pode ser
consultado por `identifier`/`paymentId`. Para não consultar essa rota em
laço, passe `waitForFinalStatus` — a chamada segura a conexão até o
desfecho. Ver [Esperar o desfecho em vez de fazer polling](#esperar-o-desfecho-em-vez-de-fazer-polling).

## Passo 3: Consultar Status da Transferência

Após executar uma transferência, você pode consultar seu status usando o ID E2E:

### Request

```bash
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/transactions?endToEndId=E12345678202301011234abcdefghijkl" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"
```

### Parâmetros de Query

| Parâmetro    | Tipo   | Obrigatório | Descrição                               |
| ------------ | ------ | ----------- | --------------------------------------- |
| `endToEndId` | string | Sim\*       | ID E2E da transação                     |
| `identifier` | string | Sim\*       | Identificador da cobrança ou referência |

\*Pelo menos um dos dois (endToEndId ou identifier) é obrigatório. O `accountId` vai no path, não na query.

### Resposta de Sucesso (200 OK)

Esta rota responde no **mesmo envelope do extrato** (`items[]`), com 0 ou 1
item. Os horários (`timestamp`) saem em horário de Brasília (`-03:00`).
Transação inexistente não é `404`: vem `200` com `items: []`.

```json
{
  "accountId": "{accountId}",
  "source": "live",
  "page": 0,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1,
  "hasNext": false,
  "items": [
    {
      "partnerId": "a697b489-681a-451c-a043-d4ae65be8c80",
      "endToEndId": "E12345678202301011234abcdefghijkl",
      "direction": "OUT",
      "transactionType": "D",
      "operation": "PIX",
      "status": "COMPLETED",
      "amount": -100.00,
      "currency": "BRL",
      "description": "PIX - MARIA DA SILVA",
      "identifier": "order-12345",
      "timestamp": "2026-01-28T15:00:00-03:00",
      "counterParty": {
        "name": "MARIA DA SILVA",
        "document": "12345678900",
        "bankCode": "001"
      }
    }
  ],
  "fetchedAt": "2026-01-28T18:00:05Z"
}
```

> **Tip**
>
> Para receber **um único objeto** (em vez do envelope `items[]`), use
> `GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=...` (ou
> `?endToEnd=...`).

### Esperar o desfecho em vez de fazer polling

O parâmetro `waitForFinalStatus` substitui o laço de consultas que o
integrador faria no lookup de pagamento
(`GET /v1/accounts/{accountId}/pix/payments/lookup`). Só essa rota aceita o
parâmetro; a `/pix/transactions` do exemplo acima o ignora. Em vez de chamar
o lookup a cada poucos segundos, chame uma vez com `waitForFinalStatus`
(segundos, no máximo 10). A API segura a conexão e consulta o liquidante até
o pagamento chegar a `COMPLETED`, `FAILED` ou `REVERSED`, ou até o prazo
acabar. A primeira consulta sai 1 s depois da chamada, dentro do prazo: logo
depois do `POST` o liquidante costuma ainda não ter o pagamento.

```bash
curl -X GET "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/payments/lookup?identifier=order-12345&waitForFinalStatus=10" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"
```

O shape da resposta não muda. Acima de 10 vale 10, e o header
`X-Wait-Seconds` devolve o prazo aplicado (não o tempo que a chamada levou).
Sem o parâmetro, ou com `0`, a rota responde na hora, como antes.

Quando o prazo acaba antes do desfecho:

* Se o pagamento foi lido ao menos uma vez, a resposta é `200` com o último
  estado (`PROCESSING`, `PENDING_APPROVAL`...). Não é erro: chame de novo ou
  aguarde o webhook.
* Se o pagamento nunca foi lido, a resposta é a da última consulta:
  `404 not_found` quando o liquidante não o encontrou, ou o erro do
  liquidante quando ela falhou. Logo depois de um `POST .../pix/out/async`,
  o `404` quer dizer que o liquidante ainda não registrou o pagamento — ou
  que o `identifier` está errado.

Se o liquidante não encontra o pagamento, mas ele já tem desfecho na CorpX
(concluído, recusado antes de chegar ao liquidante ou devolvido), a resposta
é `200` com esse status, com ou sem `waitForFinalStatus`. Com o pagamento em
andamento, o `404` continua querendo dizer que o liquidante ainda não o
registrou.

Na recusa (`FAILED`), o lookup traz `errorCode` com o mesmo código do webhook
`pix.out.failed` (`insufficient_funds`, `limit_exceeded_transaction`,
`limit_exceeded_daily`, `partner_rejected`…) e o motivo em `errorMessage`.
Decida pelo código, não pelo texto: é ele que separa falta de saldo de limite
estourado na mensagem que você mostra ao seu cliente.

Uma recusa definitiva do liquidante (`4xx`, fora `408` e `429`) volta na hora,
sem esperar o prazo. Só falha transitória (`5xx`, `408`, `429`, timeout) é
repetida.

A resposta pode chegar alguns segundos depois do prazo: uma consulta ao
liquidante que já tinha começado quando o prazo acabou termina antes da
resposta (até 5 s). Configure o timeout do seu cliente HTTP em pelo menos
`waitForFinalStatus` + 10 s — 20 s para `waitForFinalStatus=10`.

O webhook continua sendo o caminho autoritativo. O `waitForFinalStatus` é
para quem precisa do desfecho na mesma chamada.

### Status Possíveis

| Status             | Descrição                                                                                                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMPLETED`        | Liquidada com sucesso                                                                                                                                                            |
| `PROCESSING`       | Em processamento no parceiro                                                                                                                                                     |
| `PENDING_APPROVAL` | Retida dentro do banco liquidante (fila de autorização interna dele ou análise de risco). Leia `hold.owner` / `hold.reason` — não há aprovação pendente do seu lado nem do nosso |
| `FAILED`           | Falhou / rejeitada                                                                                                                                                               |
| `REVERSED`         | Estornada / devolvida                                                                                                                                                            |
| `UNKNOWN`          | Status do parceiro fora do mapeamento                                                                                                                                            |

### Fluxo de estados

```mermaid
flowchart LR
    A["Cliente envia PIX<br />POST /pix/out"] --> B{"Avaliação de<br />risco e saldo"}

    B -- "Aprovado" --> C["<code>PROCESSING</code>"]
    C --> D["Liquidação BACEN"]
    D --> E["<code>COMPLETED</code> · HTTP 200<br />Webhook <code>pix.out.completed</code>"]

    B -- "Rejeitado" --> F["<code>FAILED</code> · HTTP 422<br /><code>errorCode</code> + <code>errorReason</code><br />Webhook <code>pix.out.failed</code>"]

    B -- "Saldo insuficiente" --> F

    B -- "Em análise" --> G["<code>PENDING_APPROVAL</code> · HTTP 202"]
    G -- "Aprovada" --> D
    G -- "Cancelada" --> F

    C -. "Sem confirmação<br />na janela" .-> H["<code>TIMEOUT</code> · HTTP 202<br />Consulte GET /payments<br />antes de reenviar"]
    G -. "Sem desfecho<br />em ~25 min" .-> H
    H -. "Liquidante decide<br />em até 7 dias" .-> I["<code>COMPLETED</code>/<code>FAILED</code> tardio<br />Webhook com <code>late: true</code>"]

    style E fill:#d4f7dc,stroke:#2e7d32,color:#1b5e20
    style F fill:#fde3e3,stroke:#c62828,color:#8e0000
    style G fill:#fff4d6,stroke:#f9a825,color:#795500
    style H fill:#ffe8d6,stroke:#ef6c00,color:#8c4600
```

* O resultado final chega pelos webhooks `pix.out.completed` /
  `pix.out.failed`. Em caso de `TIMEOUT`, a API também emite
  `pix.out.timeout` (estado indeterminado — confira o extrato; um
  `completed`/`failed` tardio ainda pode chegar depois, com `late: true`
  e o mesmo `paymentId`).
* Reenvio com a **mesma** `Idempotency-Key` devolve o desfecho registrado e
  **não** executa o pagamento de novo: em `FAILED`, a mesma recusa; em
  `TIMEOUT`, o estado indeterminado. Para tentar de novo depois de um
  `FAILED`, use `Idempotency-Key` nova e `identifier` novo. Depois de um
  `TIMEOUT`, confira o extrato antes: com chave nova você pode duplicar o
  envio. Detalhes em [Idempotência](/baas/guias/comece-aqui/idempotencia).

> **Tip**
>
> Sempre salve o `identifier` das transferências e consulte o status por ele — é o ID que você define, estável e disponível desde a criação (o `endToEndId` só existe após a liquidação).

## Exemplo Completo: Script de Cash Out

```bash
#!/bin/bash

# Configuration
API_URL="https://tenant.api.corpx.com"
TOKEN="your_token_here"
TENANT_ID="tenant-suaempresa"
ACCOUNT_ID="your_account"

# Transfer details
PIX_KEY="12345678901"
PIX_KEY_TYPE="CPF"
AMOUNT=100.00

echo "=== PIX CASH OUT ==="
echo ""
echo "PIX Key: $PIX_KEY ($PIX_KEY_TYPE)"
echo "Amount: R$ $AMOUNT"
echo ""

# 1. Confirm (in production, wait for user confirmation)
read -p "Confirm transfer? (y/n): " confirm
if [ "$confirm" != "y" ]; then
  echo "Transfer cancelled"
  exit 0
fi

# 2. Execute transfer
echo ""
echo "Executing transfer..."
IDEMPOTENCY_KEY="cashout-$(date +%s)-$RANDOM"

transfer_response=$(curl -s -X POST "$API_URL/v1/accounts/$ACCOUNT_ID/pix/out" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d "{
    \"amount\": $AMOUNT,
    \"keyType\": \"$PIX_KEY_TYPE\",
    \"key\": \"$PIX_KEY\",
    \"description\": \"Transfer via script\"
  }")

# Check result
STATUS=$(echo "$transfer_response" | jq -r '.status')
E2E=$(echo "$transfer_response" | jq -r '.endToEndId')

if [ "$STATUS" = "COMPLETED" ]; then
  echo ""
  echo "=== TRANSFER COMPLETED ==="
  echo "Status: $STATUS"
  echo "E2E: $E2E"
  echo "$transfer_response" | jq
else
  echo ""
  echo "=== RESULT ==="
  echo "$transfer_response" | jq
fi
```

## Consultar QR Code (Decode)

Antes de pagar, você pode decodificar o QR Code para exibir os dados do beneficiário ao usuário:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/qr-code/decode" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{
    "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000..."
  }'
```

Resposta (QR dinâmico imediato):

```json
{
  "key": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 150.00,
  "originalAmount": 150.00,
  "identifier": "8e4d8c19-1d3f-4b22-bf6f-79a4d0e1f001",
  "decodeId": "8e4d8c19-1d3f-4b22-bf6f-79a4d0e1f001",
  "qrCodeType": "dynamic-immediate",
  "qrCodeTypeId": 1,
  "allowChange": false,
  "description": "Compra online",
  "payeeName": "EMPRESA EXEMPLO LTDA",
  "payeeDocument": "12345678000190",
  "bankIspb": "50871921",
  "bankBranch": "0001",
  "bankAccount": "123456-7",
  "accountType": "CHECKING"
}
```

Para QR de cobrança com vencimento (`dynamic-due-date`), o response
inclui também os componentes do valor (`discount`, `deduction`,
`interest`, `penalty`), `originalAmount` (valor de face antes dos
ajustes), `dueDate`, `paymentDeadline` e `payeeTradeName` (nome
fantasia da PJ). Veja o exemplo correspondente no [OpenAPI](/baas/referencia).

Você pode reutilizar `decodeId` no body do `POST /pix/out/qr-code/async`
para pular um segundo decode na hora do pagamento.

Após confirmar, use o endpoint de pagamento abaixo para executar.

## Pagar QR Code (PIX Out via EMV)

Se você possui um código EMV (QR Code copia e cola), use o endpoint
**assíncrono** (canônico):

### Fluxo assíncrono (recomendado)

`POST /v1/accounts/{accountId}/pix/out/qr-code/async` — resposta **202** imediata:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/out/qr-code/async" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay-qr-async-12345" \
  -d '{
    "emv": "00020126580014br.gov.bcb.pix...",
    "amount": 150.00,
    "description": "QR Code payment",
    "identifier": "pay-qr-async-12345"
  }'
```

Resposta:

```json
{
  "paymentId": "pay_2f4a0f88-2147-49f2-a4e2-4f7b9f6c0f7a",
  "workflowId": "pix-out-{accountId}-{identifier}",
  "runId": "b7c1f0e2-...",
  "idempotencyKey": "pay-qr-async-12345",
  "identifier": "pay-qr-async-12345",
  "status": "ACCEPTED"
}
```

A resposta `202` inclui o header `Location` apontando para o lookup do
pagamento. O resultado final (sucesso/falha/timeout) chega por webhook
(`pix.out.completed`, `pix.out.failed`, `pix.out.timeout`) e também pode
ser consultado por `identifier`/`paymentId`.

### Endpoint síncrono (deprecated)

> **Deprecated**
>
> `POST /v1/accounts/{accountId}/pix/out/qr-code` (sync) está **deprecated**.
> Continue funcionando por compatibilidade e devolve headers `Deprecation`,
> `Sunset` e `Link` (sunset previsto: **2026-11-21**). Migre para
> `/pix/out/qr-code/async`.

## Webhook de Transferência

Após a transferência, você receberá um webhook no envelope canônico
(`id`, `type`, `occurredAt`, `schemaVersion`, `data`):

```json
{
  "id": "pix-out-9ccd1869-7593-4feb-9602-e525e818ab8e",
  "type": "pix.out.completed",
  "occurredAt": "2026-09-16T20:58:46.258668746Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "{accountId}",
  "data": {
    "paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
    "tenantId": "tenant-suaempresa",
    "accountId": "{accountId}",
    "status": "SUCCESS",
    "endToEnd": "E36741675202601281500001234567",
    "transactionId": "162982-pix",
    "amount": 100.00,
    "currency": "BRL",
    "description": "Pagamento fornecedor",
    "identifier": "order-12345",
    "originalTransactionId": "",
    "initiatedAt": "2026-09-16T20:58:42.646763686Z",
    "completedAt": "2026-09-16T20:58:46.258668746Z",
    "key": {
      "type": "CPF",
      "key": "12345678901"
    },
    "payee": {
      "name": "MARIA DA SILVA",
      "document": "12345678901",
      "bankCode": "001",
      "bankIspb": "00000000",
      "branch": "0001",
      "accountNumber": "12345678"
    }
  }
}
```

O evento equivalente de falha é `pix.out.failed` (com `error` no `data`) e o
de estado indeterminado é `pix.out.timeout`. A referência completa dos campos
está em [Webhooks](/baas/guias/conta/webhooks).

## BigPix (descontinuado)

> **Descontinuado**
>
> O limite de R\$ 15.000 por transação foi removido — `POST /v1/accounts/{accountId}/pix/out`
> agora aceita **qualquer valor** em uma única transação. O BigPix (que dividia valores
> grandes em múltiplos PIX) não é mais necessário e está **descontinuado**.
>
> Os endpoints `/pix/out/bigpix` e `/pix/out/bank-account/bigpix` continuam funcionais
> por retrocompatibilidade, mas retornam o header `Deprecation: true`. Migre para
> `POST /pix/out` (ou `/pix/out/bank-account`). A data de remoção definitiva será
> anunciada no changelog com antecedência.

## Erros Comuns

| Erro                                                                                                        | HTTP | Causa                                                         | Solução                                                                                                          |
| ----------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `key_not_found`                                                                                             | 404  | Chave PIX não existe no DICT                                  | Verifique a chave e seu tipo                                                                                     |
| `invalid_pix_key`                                                                                           | 422  | Chave malformada ou incompatível com o tipo informado         | Use: CPF, CNPJ, EMAIL, PHONE, EVP                                                                                |
| `insufficient_funds`                                                                                        | 422  | Saldo insuficiente apurado pelo liquidante                    | Verifique o saldo da conta                                                                                       |
| `limit_exceeded_daily` / `limit_exceeded_nightly` / `limit_exceeded_monthly` / `limit_exceeded_transaction` | 422  | Limite da conta excedido na janela indicada                   | Aguarde a virada da janela ou solicite aumento                                                                   |
| `partner_rejected`                                                                                          | 422  | Recusa do liquidante por risco/antifraude                     | Veja o bloco `partner` com o motivo                                                                              |
| `policy_denied`                                                                                             | 422  | Uma regra de política do tenant/conta recusou a transferência | Veja `violations` no corpo e ajuste a regra no painel — [Políticas e Regras](/baas/guias/autenticacao/politicas) |

A lista completa com mensagens e semântica está em [Erros](/baas/guias/referencia/erros).

> **Note**
>
> Reenviar a mesma `Idempotency-Key` em PIX out **não** devolve `409`: a API
> retorna o resultado já registrado, inclusive quando ele é uma recusa
> (`FAILED`).

## Boas Práticas

1. **Sempre consulte a chave** antes de transferir para validar o destinatário
2. **Confirme com o usuário** os dados antes de executar
3. **Use uma Idempotency Key única** por transferência — e reutilize a mesma chave ao repetir a requisição, nunca uma nova
4. **Salve o E2E** para rastreamento e suporte
5. **Configure webhooks** para receber confirmações assíncronas
6. **Implemente retry** com exponential backoff para falhas temporárias

## Limites

O valor é limitado pelo teto da conta. A leitura, as janelas e o pedido
de aumento estão no [guia de limites](/baas/guias/pagar/limites).
`GET .../pix/limits` está deprecated.

## Próximos Passos

* [Guia de Devolução](/baas/guias/pagar/devolucao) - Estornar transferências recebidas
* [Webhooks](/baas/guias/conta/webhooks) - Configurar notificações
* [Erros](/baas/guias/referencia/erros) - Lista completa de códigos de erro