> ## 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.

# POST /api/pix/cash-in

> Criar cobrança Pix; retorna 201 com id, status (geralmente PENDING) e opcionalmente pixCode (EMV).

## Resumo

Cria **cash-in** (cobrança / QR de recebimento). O valor no request vem em **BRL (float)**; a resposta pode incluir `valueCents` e campos irmãos (conforme padrão do serviço).

* **Método:** `POST`
* **Rota:** `/api/pix/cash-in`
* **Autenticação:** `Authorization: Bearer <seu_api_token>`

## Headers

| Nome               | Obrigatório              |
| ------------------ | ------------------------ |
| `Authorization`    | Sim                      |
| `Content-Type`     | Sim (`application/json`) |
| `X-Correlation-ID` | Recomendado              |

## Corpo (estrutura documentada)

```json theme={null}
{
  "transaction": {
    "value": 150.75,
    "externalId": "pedido-12345",
    "description": "string opcional",
    "expirationTime": 3600,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "João da Silva",
    "document": "123.456.789-00"
  }
}
```

## Exemplo (curl)

```bash theme={null}
curl -X POST https://api.clearpago.com.br/api/pix/cash-in \
  -H "Authorization: Bearer <seu_api_token>" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: req-001" \
  -d '{
    "transaction": {
      "value": 150.75,
      "externalId": "pedido-12345",
      "description": "Pagamento Pedido #12345",
      "expirationTime": 3600,
      "generateQrCode": true
    },
    "payer": {
      "fullName": "João da Silva",
      "document": "123.456.789-00"
    }
  }'
```

## Resposta `201`

```json theme={null}
{
    "id": "4bf105db-412f-408e-9880-52012e5519c0",
    "correlationId": "3e253523-d562-48b9-90ed-1b0b6ee41823",
    "externalId": "fc4a6d27-071a-4618-8d4f-5fc8e45c9499",
    "status": "PENDING",
    "pixCode": "00020101021226640014br.gov.bcb.pix2542pix.magenpay.io/cob/xd1WglxqSXGhmIFUz6BbQQ5204000053039865802BR5925PAGFACIL MEIOS DE PAGAMEN6005SINOP62070503***6304760D",
    "generateTime": "2026-04-23T15:40:24.575Z",
    "expirationDate": "2026-04-24T15:40:24.575Z",
    "providerTransactionId": "871673"
}
```

| Campo                   | Descrição                                                       |
| ----------------------- | --------------------------------------------------------------- |
| `id`                    | UUID do cash-in — **persista**; base de consultas e devoluções. |
| `correlationId`         | Reflete o `X-Correlation-ID` enviado na requisição.             |
| `externalId`            | Seu identificador enviado no request.                           |
| `status`                | `PENDING` na criação; avança via webhook.                       |
| `pixCode`               | String EMV para gerar o QR Code.                                |
| `generateTime`          | Timestamp ISO 8601 UTC da criação.                              |
| `expirationDate`        | Validade do QR; após essa data o cash-in expira.                |
| `providerTransactionId` | Referência interna do parceiro (para suporte).                  |

## HTTP e erros

* **201** Criado.
* **400** Validação (payload).
* **401** Token inválido.
* **409** Conflito (ex.: `externalId` duplicado) — tabela geral.
* **422** Regra de negócio.
* **500** Interno.

## Relacionado

* [Guia: receber cash-in](/guides/receive-pix-cash-in)
* [Listar e obter detalhe](/api-reference/list-cash-ins)