Referência da API/Pagamentos
POST

Criar cobrança Pix

Gera uma cobrança Pix e retorna o QR Code e o código copia e cola.

POST/v1/payments
https://integrate.api.kyvopay.com.br
cURL
curl -X POST 'https://integrate.api.kyvopay.com.br/v1/payments' \
  -H 'X-API-Key: ky_XXXXX-XXXXX-XXXXX' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_centavos": 4990,
    "description": "Pedido #12345",
    "idempotency_key": "pedido-12345"
  }'
Resposta200 OK
{
  "data": {
    "id": "pay_8a97747d-5c94-4cc1-aec3-a83a48b01374",
    "public_id": "pay_8a97747d-5c94-4cc1-aec3-a83a48b01374",
    "status": "pending",
    "amount_centavos": "4990",
    "platform_fee_centavos": "40",
    "provider_fee_centavos": "15",
    "net_centavos": "4950",
    "pix_qr_code": "000201010212...",
    "pix_copy_paste": "000201010212..."
  },
  "error": null,
  "request_id": "req_01HZ8K3M5N"
}

Autenticação

X-API-Keystring · headerobrigatório

Use a chave ky_... criada em Integrações → Chaves de API no painel KyvoPay.

Requisição

Corpo da requisição

amount_centavosintegerobrigatório

Valor da cobrança em centavos. Por exemplo, R$ 49,90 deve ser enviado como 4990. O valor mínimo é 1.

descriptionstring

Descrição da cobrança usada para conciliação e identificação do pedido.

idempotency_keystring

Identificador único da operação. Repetir a mesma requisição com a mesma chave evita criar uma cobrança duplicada.

customerobject

Dados opcionais do pagador. Útil para sites, SaaS e checkouts que já coletam a identificação do comprador. Bots e automações podem omitir este objeto.

customer_idstring

ID opcional de um cliente já cadastrado em POST /v1/customers. Use este campo no lugar de customer quando quiser associar a cobrança a um cliente salvo.

trackingobject

Dados opcionais de atribuição como UTM, fbp, fbc, IP, User-Agent e URL de origem.

Objeto customer

namestring

Nome do pagador. Quando quiser enviar identificação para o Pix, envie junto com document. Máximo de 160 caracteres.

emailstring

E-mail opcional do pagador.

documentstring

CPF com 11 dígitos ou CNPJ com 14 dígitos, somente números. Quando enviado para identificação do Pix, use junto com name.

Dica

Para bots e automações, customer e customer_id não são obrigatórios: basta enviar o valor (e, de preferência, uma idempotency_key). Em sites, SaaS e checkouts, você pode enviar customer para associar nome, CPF/CNPJ e, opcionalmente, e-mail à cobrança.

Exemplo com pagador identificado

{
  "amount_centavos": 4990,
  "idempotency_key": "pedido-12345",
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@example.com",
    "document": "12345678909"
  }
}
Precisa de ajuda? Fale com o suporte
© 2026 KyvoPay