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

# Cobranças PIX (Inbound Payments)

> Geração de cobrança PIX instantânea com código Copia e Cola e QR Code.

## Criar Cobrança

`POST /v1/charges` (ou `/v1/payments`)  •  escopo `payments:write`

### Parâmetros da Requisição (Body JSON)

| Campo              | Tipo    | Obrigatório | Descrição / Validação                                                                                                                                                                          |
| ------------------ | ------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`           | string  | **Sim**     | Valor em Reais como **string decimal com duas casas** (ex: `"49.00"` para R\$ 49,00 ou `"0.49"` para 49 centavos). Números JSON puros são rejeitados — veja [Formato de Valores](/parametros). |
| `description`      | string  | Opcional    | Texto exibido para o pagador no app bancário.                                                                                                                                                  |
| `externalId`       | string  | Opcional    | ID do seu pedido para reconciliação automática.                                                                                                                                                |
| `expiresInMinutes` | integer | Opcional    | Tempo de validade em minutos (padrão: 30 minutos).                                                                                                                                             |
| `customer`         | object  | Opcional    | Objeto com name, document (CPF/CNPJ), email, phone.                                                                                                                                            |
| `metadata`         | object  | Opcional    | Metadados customizados devolvidos nas consultas e webhooks.                                                                                                                                    |
| `notification_url` | string  | Opcional    | URL HTTPS para receber o Webhook quando for pago.                                                                                                                                              |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.kavropay.online/v1/charges \
    -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: ped_998811_attempt1" \
    -d '{
      "amount": "49.00",
      "description": "Assinatura #998811",
      "externalId": "ped_998811",
      "customer": {
        "name": "Carlos Eduardo",
        "document": "12345678909",
        "email": "carlos@email.com"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.kavropay.online/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: (49).toFixed(2), // '49.00' — sempre envie como string
      description: 'Assinatura #998811',
      externalId: 'ped_998811',
      customer: { name: 'Carlos Eduardo', document: '12345678909', email: 'carlos@email.com' }
    })
  });
  const charge = await res.json();
  console.log('PIX Copia e Cola:', charge.pix_copy_paste);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.kavropay.online/v1/charges');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer sk_live_SUA_CHAVE_AQUI',
      'Content-Type: application/json'
  ]);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      'amount' => number_format(49, 2, '.', ''), // '49.00' — sempre string
      'description' => 'Assinatura #998811',
      'externalId' => 'ped_998811'
  ]));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $res = json_decode(curl_exec($ch), true);
  curl_close($ch);
  echo $res['pix_copy_paste'];
  ```

  ```python Python theme={null}
  import requests
  res = requests.post('https://api.kavropay.online/v1/charges',
      headers={'Authorization': 'Bearer sk_live_SUA_CHAVE_AQUI', 'Content-Type': 'application/json'},
      json={'amount': f'{49:.2f}', 'description': 'Assinatura #998811', 'externalId': 'ped_998811'}
  )
  print(res.json()['pix_copy_paste'])
  ```
</CodeGroup>

<Check>
  **Resposta de Sucesso (HTTP 201 Created)**

  ```json theme={null}
  {
    "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
    "amount": 49.00,
    "fee": 0.99,
    "net": 48.01,
    "status": "waiting_payment",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY9B1DEB4D3B7D4BAD9BDD2B520400005303986540549.005802BR5913KavroPay6009SAO PAULO62070503***6304D1A9",
    "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAR...",
    "source": "api",
    "externalId": "ped_998811",
    "external_reference": "ped_998811",
    "expires_at": "2026-08-26T12:30:00.000Z",
    "created_at": "2026-08-26T12:00:00.000Z"
  }
  ```
</Check>

<Warning>
  **Possível Resposta de Erro (HTTP 400 Bad Request)**

  ```json theme={null}
  {
    "statusCode": 400,
    "message": "Documento CPF inválido. O CPF deve conter 11 dígitos numéricos válidos.",
    "error": "Request Error",
    "timestamp": "2026-08-26T12:00:00.000Z",
    "path": "/v1/charges"
  }
  ```

  Veja o formato completo do corpo de erro em [Central de Erros & Status](/erros-status).
</Warning>

## Consultar Cobrança

`GET /v1/charges/{id}`  •  escopo `payments:read`

Busca os dados detalhados da cobrança. O parâmetro `{id}` pode ser o ID da KavroPay (`PAY...`) ou o seu `externalId`.

```bash theme={null}
curl https://api.kavropay.online/v1/charges/PAY9B1DEB4D3B7D4BAD9BDD2B \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

**Resposta (HTTP 200 OK)**

```json theme={null}
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "amount": 49.00,
  "fee": 0.99,
  "net": 48.01,
  "status": "paid",
  "paid_at": "2026-08-26T12:05:12.000Z",
  "end_to_end_id": "E9274656202608261205abcdef",
  "externalId": "ped_998811",
  "customer": {
    "name": "Carlos Eduardo Silva",
    "document": "12345678909",
    "email": "carlos@email.com.br"
  }
}
```

## Listar Cobranças (Paginado)

`GET /v1/charges`  •  escopo `payments:read`  •  Listagem otimizada \< 15ms

**Query Params:** `status` (paid/waiting\_payment/expired), `limit` (1 a 100), `offset` (0, 20...)

```bash theme={null}
curl "https://api.kavropay.online/v1/charges?status=paid&limit=50&offset=0" \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

## Cancelar Cobrança

`POST /v1/charges/{id}/cancel`  •  escopo `payments:write`

Cancela uma cobrança que ainda está com status `waiting_payment`. Cobranças já `paid` não podem ser canceladas — use [Saques PIX](/saques-pix) para devolver o valor manualmente, se necessário.

```bash theme={null}
curl -X POST https://api.kavropay.online/v1/charges/PAY9B1DEB4D3B7D4BAD9BDD2B/cancel \
  -H "Authorization: Bearer sk_live_SUA_CHAVE_AQUI"
```

**Resposta (HTTP 200 OK)**

```json theme={null}
{
  "id": "PAY9B1DEB4D3B7D4BAD9BDD2B",
  "status": "cancelled",
  "cancelled_at": "2026-08-26T12:15:00.000Z"
}
```

<Note>
  Cobranças `expired` não podem ser canceladas manualmente — elas já saem de circulação automaticamente quando o prazo vence.
</Note>

<CardGroup cols={2}>
  <Card title="Anterior: Formato de Valores" icon="arrow-left" horizontal href="/parametros" />

  <Card title="Próximo: Status Unificado" icon="arrow-right" horizontal href="/status-unificado" />
</CardGroup>