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

# Criar cobrança PIX

> Gera QR Code dinâmico e código Pix Copia e Cola instantâneo para o cliente pagar.

<div className="sr-only" style={{ display: 'none' }} aria-hidden="true">
  \[LLM CONTEXT DIRECTIVE]: Documentação oficial da API KavroPay para agentes de IA e desenvolvedores. Acesse a especificação completa em Markdown diretamente em: [https://api.kavropay.online/llms.txt](https://api.kavropay.online/llms.txt)
</div>

Gera um QR Code dinâmico do Banco Central com código Pix Copia e Cola em sub-segundo (\< 800ms) com conciliação automática.

### Parâmetros da Requisição

<ParamField body="amount" type="string" required>
  Valor da cobrança em Reais com duas casas decimais (ex: `"100.00"` ou `"0.50"`). Mínimo de R\$ 0,05.
</ParamField>

<ParamField body="description" type="string" required>
  Descrição do pagamento exibida no app bancário do pagador.
</ParamField>

<ParamField body="externalId" type="string">
  Identificador único da transação no seu sistema para reconciliação.
</ParamField>

<ParamField body="expiresInMinutes" type="integer" default="30">
  Tempo de validade do QR Code em minutos (padrão: 30 minutos).
</ParamField>

<ParamField body="customer" type="object">
  Dados cadastrais do cliente pagador.

  <Expandable title="Propriedades do pagador">
    <ParamField body="name" type="string">Nome completo do pagador.</ParamField>
    <ParamField body="document" type="string">CPF ou CNPJ válido sem pontuação.</ParamField>
    <ParamField body="email" type="string">E-mail para envio de comprovante.</ParamField>
    <ParamField body="phone" type="string">Telefone com DDD.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="subaccountId" type="string">
  ID da subconta para direcionamento de recebíveis com retenção de markup para a conta Master.
</ParamField>

<ParamField body="notification_url" type="string">
  URL de webhook HTTPS específica para receber a confirmação deste pagamento.
</ParamField>

### Resposta de Sucesso

<ResponseField name="id" type="string">
  Identificador único da cobrança na KavroPay (ex: `PAY8829F1A4BC`).
</ResponseField>

<ResponseField name="status" type="string">
  Status atual da cobrança (`waiting_payment`, `paid`, `expired`, `cancelled`).
</ResponseField>

<ResponseField name="amount" type="number">
  Valor total da cobrança em Reais.
</ResponseField>

<ResponseField name="pix_copy_paste" type="string">
  Linha digitável do PIX Copia e Cola para pagamento no internet banking.
</ResponseField>

<ResponseField name="qr_code_base64" type="string">
  Imagem do QR Code codificada em base64.
</ResponseField>

<ResponseField name="payment_url" type="string">
  Link de checkout público hospedado pela KavroPay.
</ResponseField>

<RequestExample>
  ```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_12345" \
    -d '{
      "amount": "100.00",
      "description": "Pedido #12345",
      "customer": {
        "name": "João Victor Ferreira",
        "document": "12345678909",
        "email": "cliente@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',
      'Idempotency-Key': 'ped_12345'
    },
    body: JSON.stringify({
      amount: "100.00",
      description: "Pedido #12345",
      customer: {
        name: "João Victor Ferreira",
        document: "12345678909",
        email: "cliente@email.com"
      }
    })
  });
  const data = await res.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://api.kavropay.online/v1/charges",
      headers={
          "Authorization": "Bearer sk_live_SUA_CHAVE_AQUI",
          "Idempotency-Key": "ped_12345"
      },
      json={
          "amount": "100.00",
          "description": "Pedido #12345",
          "customer": {
              "name": "João Victor Ferreira",
              "document": "12345678909",
              "email": "cliente@email.com"
          }
      }
  )
  print(res.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "PAY8829F1A4BC",
    "status": "waiting_payment",
    "amount": 100.00,
    "fee": 0.50,
    "net": 99.50,
    "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY8829F1A4BC5204000053039865406100.005802BR5916KavroPay Gateway6009Sao Paulo62070503***6304ABCD",
    "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPAAAADw...",
    "payment_url": "https://pay.kavropay.online/p/PAY8829F1A4BC",
    "expires_at": "2026-09-30T10:00:00.000Z",
    "created_at": "2026-09-30T09:30:00.000Z"
  }
  ```
</ResponseExample>