Receber PIX

Criar cobrança

Use POST /v1/payments.

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 #4821",
    "idempotency_key": "pedido-4821"
  }'

amount_centavos é obrigatório. Os dados do pagador são opcionais: bots, automações e integrações simples podem gerar a cobrança sem customer e sem customer_id.

Para sites, SaaS e checkouts que já coletam os dados do comprador, você pode enviar customer com name, document (CPF de 11 ou CNPJ de 14 dígitos) e, opcionalmente, email. Se o cliente já existe, também pode usar customer_id de POST /v1/customers.

{
  "amount_centavos": 4990,
  "idempotency_key": "pedido-4821",
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@example.com",
    "document": "12345678909"
  }
}

description e idempotency_key são opcionais, mas use sempre a chave de idempotência: ela é o que impede uma cobrança duplicada quando você repete a chamada. Veja Idempotência.

Para atribuir a venda a uma campanha, envie tracking com o que você capturou na página (utm_source, utm_medium, utm_campaign, utm_content, utm_term, src, sck, fbp, fbc, event_source_url, ip e user_agent do comprador). Todos os campos são opcionais. Eles seguem para os plugins UTMify e Meta Pixel que você instalar no painel; sem plugin, ficam guardados na cobrança e não vão a lugar nenhum.

A resposta traz o public_id da cobrança, o status e o Pix para o pagador: pix_copy_paste (copia e cola) e pix_qr_code. Guarde o public_id junto do pedido no seu sistema — é com ele que você reconcilia os eventos.

Confirmação

Criar o QR Code não significa que o pagamento foi concluído. Considere o pedido pago somente quando receber o evento payment.paid (ver Webhooks) e conferir o public_id.

A API pública não tem rota para consultar uma cobrança: o aviso de pagamento chega pelo webhook, e o histórico completo está no painel.

Dividir o valor entre recebedores

Para repartir uma cobrança, anexe uma regra de divisão com POST /v1/payments/{paymentId}/split. Veja a referência.