> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar Pix por chave (Cash-out)

> Fluxo completo de envio por chave Pix: criação, reserva, despacho, confirmação, falha e reconciliação.

## Visão geral do fluxo

```mermaid theme={null}
sequenceDiagram
  participant S as Seu sistema
  participant CP as ClearPago
  participant B as BaaS

  S->>CP: POST /api/pix/cash-out
  CP-->>S: 201 {id, status inicial}
  CP->>CP: Reserva criada
  CP->>B: Despacha transferência
  alt Resposta imediata
    B-->>CP: CONFIRMED ou FAILED
    CP->>S: Webhook pix_cash_out
  else Resposta ambígua (timeout/5xx)
    CP->>CP: PROVIDER_RESULT_UNKNOWN
    CP->>B: Reconciliação periódica
    B-->>CP: Resultado final
    CP->>S: Webhook pix_cash_out
  end
```

## Passo 1 — Criar o envio

```bash theme={null}
curl -X POST https://api.clearpago.com.br/api/pix/cash-out \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: req-cashout-001" \
  -d '{
    "transaction": {
      "value": 500.00,
      "externalId": "saque-789",
      "description": "Pagamento Fornecedor ABC"
    },
    "recipient": {
      "name": "Maria Oliveira",
      "document": "987.654.321-00",
      "pixKey": "maria@email.com",
      "pixKeyType": "email"
    }
  }'
```

**Resposta `201`:**

```json theme={null}
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "CREATED",
  "externalId": "saque-789"
}
```

<Warning>
  **Persista o `id` imediatamente.** Ele é necessário para monitoramento e reconciliação.
</Warning>

### Tipos de chave Pix suportados

| `pixKeyType` | Formato                           |
| ------------ | --------------------------------- |
| `cpf`        | `123.456.789-00` ou `12345678900` |
| `cnpj`       | `00.000.000/0001-00` ou numérico  |
| `email`      | `usuario@dominio.com`             |
| `phone`      | `+5511999999999`                  |
| `evp`        | UUID (chave aleatória)            |

### Parâmetros importantes

| Campo                    | Obrigatório | Notas                                                 |
| ------------------------ | ----------- | ----------------------------------------------------- |
| `transaction.value`      | Sim         | Valor em **BRL**.                                     |
| `transaction.externalId` | Sim         | Único por operação. `409` em duplicata.               |
| `recipient.pixKey`       | Sim         | Chave do destinatário.                                |
| `recipient.pixKeyType`   | Sim         | Tipo da chave (ver tabela acima).                     |
| `recipient.document`     | Não         | CPF/CNPJ do destinatário (recomendado para rastreio). |

## Passo 2 — Monitorar o pipeline

Após o `201`, o cash-out passa por um pipeline interno. O status no `POST` reflete o estado no momento do commit — **não é necessariamente `PENDING`**.

| Status                                      | Significado                                            |
| ------------------------------------------- | ------------------------------------------------------ |
| `CREATED` / `RESERVED` / `DISPATCH_PENDING` | Pipeline interno; aguardando despacho ao BaaS.         |
| `DISPATCHED`                                | BaaS aceitou; aguardando confirmação final.            |
| `CONFIRMED`                                 | Transferência **confirmada** — estado de sucesso.      |
| `FAILED`                                    | Falha definitiva; reserva liberada.                    |
| `PROVIDER_RESULT_UNKNOWN`                   | Resposta ambígua; reconciliação em andamento.          |
| `RECONCILIATION_REQUIRED`                   | Tentativas de reconciliação esgotadas; requer atenção. |
| `REVERSED`                                  | Revertido pelo destinatário após confirmação.          |

## Passo 3 — Receber o webhook

```http theme={null}
POST https://seu-sistema.com/webhooks/pix
Content-Type: application/json
Digital-Signature: <base64 ECDSA P-256 SHA-256>

{
  "event_type": "pix_cash_out",
  "event": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "external_id": "saque-789",
    "status": "CONFIRMED",
    "value_cents": 50000,
    "end_to_end_id": "E07136847202504011200O7654ABCD12",
    "fee_amount_cents": 10,
    "confirmed_at": "2026-04-01T12:30:00.000000000Z",
    "created_at": "2026-04-01T12:00:00.000000000Z"
  }
}
```

Sempre [verifique a assinatura](/guides/verify-webhook-signatures) antes de processar. Responda `2xx` rapidamente.

## Passo 4 — Confirmar via GET (fall-back)

```bash theme={null}
curl https://api.clearpago.com.br/api/pix/cash-out/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer <seu_api_token>"
```

Use quando o webhook não chegou ou o status está em estado intermediário.

## Estados ambíguos

Se o cash-out ficar em `PROVIDER_RESULT_UNKNOWN` ou `RECONCILIATION_REQUIRED`:

* **Não** cancele ou reenvie sem análise — o dinheiro pode ter saído.
* **Monitore** a idade do estado com `GET /api/pix/cash-out/{id}`.
* **Aguarde** a reconciliação automática. Se persistir, acione o [suporte](/go-live/production-checklist#contato-de-suporte).
* Veja o [guia de reconciliação](/guides/reconcile-transactions).

## Reversão (cash-out reversal)

Um cash-out `CONFIRMED` pode ser revertido pelo destinatário. Nesse caso, você recebe `pix_cash_out_reversal` e o status vai para `REVERSED`. Veja [Lidar com reversão de cash-out](/guides/handle-cash-out-reversal).

## Reconciliação com o ledger

Após `CONFIRMED`, um lançamento de débito é criado no ledger. Após `REVERSED`, um crédito de reversão é criado. Consulte [Ledger e reconciliação](/ledger-and-reconciliation/ledger-overview).

## Referências

* [POST /api/pix/cash-out](/api-reference/create-cash-out)
* [GET /api/pix/cash-out/{id}](/api-reference/get-cash-out)
* [Modelo de status (cash-out)](/core-concepts/status-model)
* [Reconciliação operacional](/guides/reconcile-transactions)