Criar cobrança PIX

curl -X POST https://api.kavropay.com.br/v1/charges \
  -H "Authorization: Bearer kvk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ped_84920" \
  -d '{
    "amount": "149.90",
    "description": "Curso Fullstack - Matrícula #84920",
    "expiresInMinutes": 60,
    "customer": {
      "name": "Mariana Costa Ribeiro",
      "document": "52998224725",
      "email": "mariana.ribeiro@email.com",
      "phone": "11987654321"
    },
    "metadata": {
      "order_id": "ped_84920"
    }
  }'

const res = await fetch('https://api.kavropay.com.br/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer kvk_live_SUA_CHAVE_AQUI',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ped_84920'
  },
  body: JSON.stringify({
    amount: "149.90", // ou amountCents: 14990
    description: "Curso Fullstack - Matrícula #84920",
    expiresInMinutes: 60,
    customer: {
      name: "Mariana Costa Ribeiro",
      document: "52998224725",
      email: "mariana.ribeiro@email.com",
      phone: "11987654321"
    },
    metadata: {
      order_id: "ped_84920"
    }
  })
});

const data = await res.json();
console.log('ID:', data.id);
console.log('Pix Copia e Cola:', data.pix_copy_paste);

import requests

payload = {
    "amount": "149.90",
    "description": "Curso Fullstack - Matrícula #84920",
    "expiresInMinutes": 60,
    "customer": {
        "name": "Mariana Costa Ribeiro",
        "document": "52998224725",
        "email": "mariana.ribeiro@email.com",
        "phone": "11987654321"
    },
    "metadata": {
        "order_id": "ped_84920"
    }
}

res = requests.post(
    "https://api.kavropay.com.br/v1/charges",
    headers={
        "Authorization": "Bearer kvk_live_SUA_CHAVE_AQUI",
        "Content-Type": "application/json",
        "Idempotency-Key": "ped_84920"
    },
    json=payload
)
print(res.json())

{
  "id": "PAY8829F1A4BC",
  "status": "waiting_payment",
  "amount": 149.90,
  "fee": 0.50,
  "net": 149.40,
  "environment": "live",
  "livemode": true,
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY8829F1A4BC5204000053039865406149.905802BR5916KavroPay Gateway6009Sao Paulo62070503***6304ABCD",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPAAAADw...",
  "expires_at": "2026-10-15T22:30:00.000Z",
  "created_at": "2026-10-15T21:30:00.000Z"
}

POST

charges

curl -X POST https://api.kavropay.com.br/v1/charges \
  -H "Authorization: Bearer kvk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ped_84920" \
  -d '{
    "amount": "149.90",
    "description": "Curso Fullstack - Matrícula #84920",
    "expiresInMinutes": 60,
    "customer": {
      "name": "Mariana Costa Ribeiro",
      "document": "52998224725",
      "email": "mariana.ribeiro@email.com",
      "phone": "11987654321"
    },
    "metadata": {
      "order_id": "ped_84920"
    }
  }'

const res = await fetch('https://api.kavropay.com.br/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer kvk_live_SUA_CHAVE_AQUI',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ped_84920'
  },
  body: JSON.stringify({
    amount: "149.90", // ou amountCents: 14990
    description: "Curso Fullstack - Matrícula #84920",
    expiresInMinutes: 60,
    customer: {
      name: "Mariana Costa Ribeiro",
      document: "52998224725",
      email: "mariana.ribeiro@email.com",
      phone: "11987654321"
    },
    metadata: {
      order_id: "ped_84920"
    }
  })
});

const data = await res.json();
console.log('ID:', data.id);
console.log('Pix Copia e Cola:', data.pix_copy_paste);

import requests

payload = {
    "amount": "149.90",
    "description": "Curso Fullstack - Matrícula #84920",
    "expiresInMinutes": 60,
    "customer": {
        "name": "Mariana Costa Ribeiro",
        "document": "52998224725",
        "email": "mariana.ribeiro@email.com",
        "phone": "11987654321"
    },
    "metadata": {
        "order_id": "ped_84920"
    }
}

res = requests.post(
    "https://api.kavropay.com.br/v1/charges",
    headers={
        "Authorization": "Bearer kvk_live_SUA_CHAVE_AQUI",
        "Content-Type": "application/json",
        "Idempotency-Key": "ped_84920"
    },
    json=payload
)
print(res.json())

{
  "id": "PAY8829F1A4BC",
  "status": "waiting_payment",
  "amount": 149.90,
  "fee": 0.50,
  "net": 149.40,
  "environment": "live",
  "livemode": true,
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY8829F1A4BC5204000053039865406149.905802BR5916KavroPay Gateway6009Sao Paulo62070503***6304ABCD",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPAAAADw...",
  "expires_at": "2026-10-15T22:30:00.000Z",
  "created_at": "2026-10-15T21:30:00.000Z"
}

Gera um QR Code dinâmico com código Pix Copia e Cola em sub-segundo (< 800ms) com conciliação automática, suporte a idempotência e opção de checkout público hospedado.

A API também aceita a rota equivalente POST /v1/payments.

Parâmetros da Requisição

string

Valor da cobrança em Reais com duas casas decimais (ex: "149.90" ou "0.50"). Também aceita valor numérico. Obrigatório se amountCents não for informado. Mínimo de R$ 0,05.

integer

Valor da cobrança em centavos inteiros (ex: 14990 para R$ 149,90). Alternativa direta ao campo amount.

string

required

Descrição do pagamento exibida no comprovante e no app bancário do pagador.

string

Identificador único da transação no seu sistema interno para reconciliação automática (também aceito como external_reference).

integer

default:"30"

Tempo de validade do QR Code em minutos (padrão: 30 minutos). Alternativamente, use expiration_seconds para definir em segundos.

boolean

default:"false"

Quando definido como true, a KavroPay gera automaticamente uma página de checkout pública hospedada para o cliente realizar o pagamento.

string

URL de redirecionamento para onde o cliente será enviado após concluir o pagamento na página pública.

object

Dados cadastrais do cliente pagador.

Show Propriedades do pagador

string

Nome completo do cliente pagador.

string

CPF ou CNPJ válido do pagador (apenas números ou formatado).

string

E-mail para envio de comprovante e recibo de pagamento.

string

Telefone celular do pagador com DDD.

string

URL de webhook HTTPS específica para receber as notificações desta cobrança (escopo isolado tx:<id>). Não sobrescreve nem interfere nos webhooks globais da empresa.

string

Opcional. Segredo personalizado para assinar as notificações desta cobrança. Se não informado, a KavroPay gera automaticamente um segredo seguro de 32 bytes (whsec_...).

object

Objeto JSON livre com pares chave-valor para armazenamento de dados customizados (ex: ID de carrinho, UTMs, SKU). Devolvido intacto nas consultas e webhooks.

Cabeçalhos de Idempotência

Para prevenir cobranças duplicadas em caso de instabilidade de rede ou retry automático, envie o cabeçalho:

Idempotency-Key: ped_84920_tentativa1

(A API também reconhece x-idempotency-key de forma intercambiável).

Resposta de Sucesso

string

Identificador único da cobrança na KavroPay (ex: PAY8829F1A4BC).

string

Status inicial da cobrança (waiting_payment).

number

Valor total da cobrança em Reais.

number

Taxa de intermediação da KavroPay.

number

Valor líquido creditado na conta após dedução da taxa.

string

Código Pix Copia e Cola (EMV payload) para ser colado no aplicativo bancário do cliente.

string

Imagem do QR Code codificada em base64 (data:image/png;base64,...).

string

Ambiente da cobrança ("sandbox" ou "live").

boolean

true para Produção, false para Sandbox.

string

Data e hora de expiração do QR Code no padrão ISO 8601 UTC.

string

Data e hora de emissão da cobrança no padrão ISO 8601 UTC.

string

URL de callback configurada para esta cobrança específica.

string

Chave secreta criptográfica (formato whsec_...) gerada para validar as assinaturas HMAC (X-KavroPay-Signature) das notificações desta transação.

curl -X POST https://api.kavropay.com.br/v1/charges \
  -H "Authorization: Bearer kvk_live_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ped_84920" \
  -d '{
    "amount": "149.90",
    "description": "Curso Fullstack - Matrícula #84920",
    "expiresInMinutes": 60,
    "customer": {
      "name": "Mariana Costa Ribeiro",
      "document": "52998224725",
      "email": "mariana.ribeiro@email.com",
      "phone": "11987654321"
    },
    "metadata": {
      "order_id": "ped_84920"
    }
  }'

const res = await fetch('https://api.kavropay.com.br/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer kvk_live_SUA_CHAVE_AQUI',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'ped_84920'
  },
  body: JSON.stringify({
    amount: "149.90", // ou amountCents: 14990
    description: "Curso Fullstack - Matrícula #84920",
    expiresInMinutes: 60,
    customer: {
      name: "Mariana Costa Ribeiro",
      document: "52998224725",
      email: "mariana.ribeiro@email.com",
      phone: "11987654321"
    },
    metadata: {
      order_id: "ped_84920"
    }
  })
});

const data = await res.json();
console.log('ID:', data.id);
console.log('Pix Copia e Cola:', data.pix_copy_paste);

import requests

payload = {
    "amount": "149.90",
    "description": "Curso Fullstack - Matrícula #84920",
    "expiresInMinutes": 60,
    "customer": {
        "name": "Mariana Costa Ribeiro",
        "document": "52998224725",
        "email": "mariana.ribeiro@email.com",
        "phone": "11987654321"
    },
    "metadata": {
        "order_id": "ped_84920"
    }
}

res = requests.post(
    "https://api.kavropay.com.br/v1/charges",
    headers={
        "Authorization": "Bearer kvk_live_SUA_CHAVE_AQUI",
        "Content-Type": "application/json",
        "Idempotency-Key": "ped_84920"
    },
    json=payload
)
print(res.json())

{
  "id": "PAY8829F1A4BC",
  "status": "waiting_payment",
  "amount": 149.90,
  "fee": 0.50,
  "net": 149.40,
  "environment": "live",
  "livemode": true,
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136PAY8829F1A4BC5204000053039865406149.905802BR5916KavroPay Gateway6009Sao Paulo62070503***6304ABCD",
  "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAPAAAADw...",
  "expires_at": "2026-10-15T22:30:00.000Z",
  "created_at": "2026-10-15T21:30:00.000Z"
}

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Criar cobrança PIX

Parâmetros da Requisição

Cabeçalhos de Idempotência

Resposta de Sucesso