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

# Cobranças

> Criação e gerenciamento de cobranças (pagamentos únicos) na plataforma 4Selet Pay.

## Visão Geral

As **Cobranças** representam transações de pagamento únicas. São o núcleo do processamento de pagamentos da plataforma, suportando os métodos:

| Método       | Descrição                                |
| ------------ | ---------------------------------------- |
| `CreditCard` | Cartão de crédito (parcelado ou à vista) |
| `PIX`        | Pagamento instantâneo via PIX            |

***

## Header obrigatório

Todas as rotas de cobranças exigem o header `account` com o código da conta:

```http theme={null}
account: acc_abc123xyz
```

***

## Formato de resposta padrão

A maioria das rotas retorna respostas no formato padrão da API (exceto a listagem paginada):

```json theme={null}
{
  "mensagem": "Mensagem descritiva",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 200,
  "id": "00000000-0000-0000-0000-000000000000",
  "data": { ... }
}
```

| Campo           | Tipo    | Descrição                                             |
| --------------- | ------- | ----------------------------------------------------- |
| `mensagem`      | string  | Mensagem descritiva da operação                       |
| `erro`          | boolean | `false` em caso de sucesso, `true` em caso de erro    |
| `mensagenserro` | array   | Lista de mensagens de erro (vazia em caso de sucesso) |
| `codigoretorno` | integer | Código HTTP de retorno                                |
| `id`            | string  | ID do recurso criado/afetado ou GUID vazio            |
| `data`          | mixed   | Dados retornados (objeto, array ou vazio)             |

***

## Fluxo de uma cobrança

```
POST /v1/charge → HTTP 201
    │
    ├─ Validação de dados (422 se inválido)
    ├─ Verificação de fraude (bloqueio de IP/email/CPF/BIN)
    ├─ Rate limiting por cliente
    │
    ├─ [PIX] → QR Code gerado → aguardar pagamento (status: Pending)
    └─ [CreditCard] → Autorização no gateway
              │
              ├─ Approved → Pedido aprovado (HTTP 201)
              ├─ Declined → Pedido recusado (HTTP 400)
              └─ Challenged → Verificação adicional requerida (HTTP 202)
```

***

## Campos do cliente

| Campo                    | Tipo   | Req.  | Descrição                                           |
| ------------------------ | ------ | ----- | --------------------------------------------------- |
| `client.name`            | string | Sim   | Nome completo do cliente (máx. 255)                 |
| `client.email`           | string | Sim   | E-mail do cliente                                   |
| `client.phone.ddi`       | string | Sim   | Código do país (DDI)                                |
| `client.phone.ddd`       | string | Sim   | Código de área (DDD)                                |
| `client.phone.number`    | string | Sim   | Número do telefone                                  |
| `client.document.type`   | string | Não   | Tipo: `CPF`, `CNPJ`, `passport`, `undefined`        |
| `client.document.number` | string | Não   | Número do documento                                 |
| `client.gender`          | string | Não   | `Male`, `Female`, `Other`, `Undefined`              |
| `client.birthdate`       | date   | Não   | Data de nascimento (YYYY-MM-DD)                     |
| `client.address.*`       | object | Não\* | Endereço (\* todos os campos obrigatórios entre si) |

***

## Campos do pagamento

| Campo                          | Tipo    | Req.       | Descrição                          |
| ------------------------------ | ------- | ---------- | ---------------------------------- |
| `payment.type`                 | string  | Sim        | `CreditCard` ou `PIX`              |
| `payment.pix_expiration`       | integer | Não        | Expiração em segundos (mín. 1)     |
| `payment.card.number`          | string  | CreditCard | Número do cartão (mín. 13 dígitos) |
| `payment.card.name`            | string  | CreditCard | Nome no cartão                     |
| `payment.card.month`           | string  | CreditCard | Mês de validade (MM)               |
| `payment.card.year`            | string  | CreditCard | Ano de validade (YY)               |
| `payment.card.security_code`   | string  | CreditCard | CVV                                |
| `payment.card.installments`    | integer | CreditCard | Número de parcelas                 |
| `payment.card.soft_descriptor` | string  | Não        | Texto na fatura (3-50 chars)       |

***

## Exemplo: Pagamento PIX

```json Request theme={null}
{
  "client": {
    "name": "Maria Santos",
    "email": "maria@exemplo.com.br",
    "phone": { "ddi": "55", "ddd": "21", "number": "988887777" }
  },
  "payment": {
    "type": "PIX",
    "pix_expiration": 3600
  },
  "items": [
    { "id": "curso_001", "description": "Curso Online", "amount": 297.00, "quantity": 1 }
  ]
}
```

```json Resposta PIX (HTTP 201) theme={null}
{
  "mensagem": "Aguardando Pagamento",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 201,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "code": "pur_abc123xyz",
    "status": "Pending",
    "value": 297.00,
    "orders": [
      {
        "code": "ord_abc123xyz",
        "status": "Pending",
        "charges": [
          {
            "code": "chg_abc123",
            "status": "Pending",
            "payment": {
              "code": "pix_code_123",
              "copy_paste": "00020126580014br.gov.bcb.pix...",
              "expiration": "2026-03-11T11:00:00.000000Z",
              "payment_type": "PIX"
            }
          }
        ]
      }
    ]
  }
}
```

<Tip>
  Para pagamentos PIX, o status inicial será `Pending`. Use webhooks para ser notificado quando o pagamento for confirmado.
</Tip>

<Warning>
  A criação de cobranças passa por verificações de fraude. Clientes com IP, e-mail, CPF ou BIN do cartão bloqueados terão a cobrança rejeitada com status 400.
</Warning>

***

## Estorno de cobranças

O endpoint de estorno aceita um campo `value` opcional do tipo **inteiro** (em centavos). Se omitido, o estorno é total.

```json Estorno parcial de R$ 50,00 theme={null}
{
  "value": 5000
}
```

<Warning>
  O prazo e as condições para estorno dependem do gateway de pagamento utilizado. Cobranças já estornadas por completo não podem ser estornadas novamente.
</Warning>