Criar Pix

Cobrança Pix com QR Code e copia e cola.

POST/v1/paymentsChave de API

Criar uma cobrança Pix#

POST/v1/paymentsChave de API

Para criar um Pix, envie method, amount_centavos e os dados básicos do pagador. A identificação do pagador é usada na validação do processamento e na conciliação da cobrança.

Expiração#

Sem expires_in_seconds, a cobrança usa o padrão da plataforma (30 minutos). Você pode definir de 60 segundos a 30 dias. Ao vencer, o status vira expired e o evento payment.expired é enviado.

Campos relevantes para Pix

methodstringobrigatório

Fixo em pix.

amount_centavosintegerobrigatório

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

expires_in_secondsintegeropcional

De 60 a 2.592.000. Padrão de 1800 segundos.

customerobjectobrigatório

Nome, e-mail, CPF/CNPJ e telefone do pagador.

external_referencestringopcional

Seu id do pedido, para reconciliar depois.

Nunca confirme pelo front-end

O QR aparecer na tela não significa pagamento. Só marque o pedido como pago quando receber o webhook payment.paid ou confirmar por consulta à API.

POSTcobrança Pix

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",
    "expires_in_seconds": 1800,
    "customer": {
      "name": "Cliente Teste",
      "email": "cliente@example.com",
      "document": "12345678909",
      "phone": "11999999999"
    },
    "items": [{
      "name": "Pedido #8291",
      "quantity": 1,
      "price_centavos": 12990,
      "type": "DIGITAL"
    }]
  }'

200 OKresposta

{
  "data": {
    "id": "pay_3Kq8Zx91",
    "status": "pending",
    "method": "pix",
    "amount_centavos": 12990,
    "pix_qr_code": "iVBORw0KGgoAAAANSUh...",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
    "expires_at": "2026-08-11T19:30:00Z",
    "created_at": "2026-08-11T19:00:00Z"
  },
  "error": null,
  "request_id": "req_7f2c9a10"
}