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

# Criar Cobrança

> Cria uma nova cobrança PIX

## Descrição

Cria uma cobrança PIX. A VisePag gera o UUID da cobrança no backend e devolve no campo `id`. A cobrança vale 24 horas.

> [!NOTE]
>
> O campo `amount` é sempre enviado e devolvido em **centavos**. Por exemplo, `1000` = R\$ 10,00.

**Rate Limit:** 60 requisições/minuto

***

## Headers

**Authorization** `string` *required* (default: Bearer YOUR\_API\_KEY)

Bearer token de autenticação. Formato: `Bearer YOUR_API_KEY`

**Content-Type** `string` *required*

Deve ser `application/json`

***

## Body

**amount** `integer` *required*

Valor em centavos. O mínimo é `500` (R$ 5,00) e o máximo <code>10000000</code> (R$ 100.000,00).

**description** `string` *required*

Descrição da cobrança, até 140 caracteres.

**customerName** `string` *required*

Nome do pagador, até 200 caracteres.

**customerDocument** `string` *required*

CPF (11 dígitos) ou CNPJ (14 dígitos) válido do pagador, só números.

**customerEmail** `string`

E-mail do pagador.

***

## PIX

### Requisição

```bash cURL theme={null}
curl -X POST https://api.visepag.com/v1/payins \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "description": "Pedido #1234",
    "customerName": "João Silva",
    "customerDocument": "52998224725",
    "customerEmail": "joao@email.com"
  }'
```

```javascript Node.js theme={null}
const response = await fetch('https://api.visepag.com/v1/payins', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1000,
    description: 'Pedido #1234',
    customerName: 'João Silva',
    customerDocument: '52998224725',
    customerEmail: 'joao@email.com'
  })
});

const charge = await response.json();
```

### Resposta 201 Created

**id** `string`

UUID da cobrança, gerado pela VisePag.

**status** `string`

Status da cobrança. Na criação, `pending`. Veja [Status](https://docs.visepag.com/concepts/status.md).

**method** `string`

Sempre `pix`.

**amount** `integer`

Valor em centavos.

**platformFee** `integer`

Taxa da VisePag, em centavos.

**pixCopy** `string`

Código PIX copia-e-cola.

**pixQrCode** `string | null`

Imagem do QR Code (PNG em base64), ou `null`. O copia-e-cola sempre vale sozinho.

**expiresAt** `string`

Expiração em ISO 8601.

```json 201 theme={null}
{
  "id": "54e2b712-aca0-4230-b69a-d6dd8542c925",
  "status": "pending",
  "method": "pix",
  "amount": 1000,
  "platformFee": 70,
  "description": "Pedido #1234",
  "customerName": "João Silva",
  "customerDocument": "52998224725",
  "customerEmail": "joao@email.com",
  "pixCopy": "00020101021226...",
  "pixQrCode": "data:image/png;base64,iVBORw0KGgo...",
  "createdAt": "2026-09-12T23:59:59Z",
  "paidAt": null,
  "expiresAt": "2026-09-13T23:59:59Z",
  "currency": "brl",
  "livemode": true
}
```

***

## Erros

| Status | Código | Descrição |
| - | - | - |
| 400 | `invalid_amount` | `amount` deve ser um inteiro positivo em centavos |
| 400 | `description_required` | `description` é obrigatória |
| 400 | `customer_name_required` | `customerName` é obrigatório |
| 400 | `customer_document_required` | `customerDocument` é obrigatório |
| 400 | `invalid_customer_document` | CPF ou CNPJ inválido |
| 400 | `invalid_customer_email` | E-mail inválido |
| 401 | `missing_authorization` | Header `Authorization` ausente |
| 401 | `invalid_api_key` | Chave de API inválida |
| 422 | `amount_below_minimum` | Valor abaixo de R\$ 5,00 |
| 429 | `rate_limit_exceeded` | Limite de 60 requisições/minuto excedido |
| 502 | `provider_rejected` | A adquirente recusou a cobrança |
| 502 | `charge_creation_uncertain` | A adquirente não confirmou a criação |
| 503 | `provider_unavailable` | Adquirente indisponível no momento |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.