KyvoPay

Criar pagamento

Cria uma cobrança Pix. Cartão e boleto ficam disponíveis futuramente.

POST/v1/paymentsChave de API

Criar pagamento#

POST/v1/paymentsChave de API

Este é o endpoint central da API. O meio liberado para integração é o Pix. Use pix no campo method.

Corpo da requisição#

methodstringobrigatório

Use pix.

amount_centavosintegerobrigatório

Valor total em centavos. Mínimo 500 (R$ 5,00) e máximo 100000 (R$ 1.000,00).

descriptionstringopcional

Descrição exibida ao cliente e no painel. Até 255 caracteres.

external_referencestringopcional

Seu identificador do pedido. Até 120 caracteres.

customerobjectobrigatório

Dados do comprador: name, email (obrigatórios no objeto), document e phone. Clientes são reaproveitados pelo e-mail.

itemsarrayobrigatório

Itens do pedido, cada um com name, quantity, price_centavos e type (DIGITAL ou PHYSICAL).

deliveryobjectopcional

Obrigatório quando há item PHYSICAL. Contém fee_centavos e address.

installmentsintegeropcional

Reservado para cartão. Sem efeito no Pix; cartão está inativo por enquanto.

expires_in_secondsintegeropcional

Validade da cobrança, de 60 a 2.592.000 segundos.

metadataobjectopcional

Chaves livres suas. Voltam na consulta e nos webhooks.

cardobjectopcional

Reservado para a futura ativação de cartão. Não envie este campo enquanto o método estiver inativo.

boletoobjectopcional

Reservado para a futura ativação de boleto. Não envie este campo enquanto o método estiver inativo.

splitsarrayopcional

Divisão entre subcontas KyvoPay, cada item com subaccount_id e percent_bp ou amount_centavos.

Cartão e boleto em breve

A documentação dessas modalidades fica visível na navegação apenas como referência de roadmap, mas as páginas e o uso pela API estão desabilitados enquanto os meios não forem liberados.

Conta aprovada

Criar cobrança em produção exige a conta verificada. Em sandbox, com uma chave kyvo_test_, o endpoint funciona desde o primeiro dia.
POST/v1/payments
curl https://api.kyvopay.com.br/v1/payments \
  -H "X-API-Key: $KYVO_API_KEY" \
  -H "Idempotency-Key: pedido-8291" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "pix",
    "amount_centavos": 12990,
    "description": "Pedido #8291",
    "external_reference": "8291",
    "customer": {
      "name": "Ana Ribeiro",
      "email": "ana@exemplo.com",
      "document": "12345678909"
    },
    "metadata": { "pedido": "8291" }
  }'
200 OKresposta
{
  "data": {
    "id": "pay_3Kq8Zx91",
    "status": "pending",
    "provider_status": "waiting_payment",
    "method": "pix",
    "amount_centavos": 12990,
    "net_centavos": null,
    "platform_fee_centavos": 45,
    "provider_fee_centavos": 0,
    "refunded_centavos": 0,
    "installments": 1,
    "currency": "BRL",
    "description": "Pedido #8291",
    "pix_qr_code": "iVBORw0KGgoAAAANSUh...",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
    "boleto_barcode": null,
    "boleto_digitable_line": null,
    "boleto_pdf_url": null,
    "card_brand": null,
    "card_last4": null,
    "end_to_end_id": null,
    "origin": "api",
    "metadata": { "pedido": "8291" },
    "paid_at": null,
    "expires_at": "2026-08-11T19:30:00Z",
    "created_at": "2026-08-11T19:00:00Z"
  },
  "error": null,
  "request_id": "req_7f2c9a10"
}

Campos da resposta#

idstringopcional

Identificador público da cobrança. É o que aparece nos webhooks.

statusstringopcional

Estado interno da cobrança. Veja status na referência.

provider_statusstringopcional

Estado bruto informado pelo processador. Use apenas para diagnóstico.

net_centavosintegeropcional

Valor líquido depois das taxas. Só é preenchido após a confirmação.

platform_fee_centavosintegeropcional

Taxa da KyvoPay aplicada a esta transação.

refunded_centavosintegeropcional

Total já devolvido nesta cobrança.

end_to_end_idstringopcional

Identificador do Pix na rede do Banco Central, quando aplicável.

originstringopcional

Como a cobrança nasceu: api, checkout, link ou panel.

Erros comuns#

CódigoStatusCausa
forbidden403Conta ainda não aprovada para receber em produção.
amount_below_minimum422Valor abaixo do mínimo aceito.
provider_not_connected422Nenhum processador ativo para este meio de pagamento.
rate_limited429Muitas requisições no mesmo minuto.