Your first integration

This guide covers the smallest reliable integration. Complete every step in sandbox before using real funds.

Before you begin

You need a KyvoPay account, access to the dashboard and a backend capable of making HTTPS requests. Never call the API directly from browser code.

1. Create a sandbox key

   In the dashboard, open Integrations → API keys and create a sandbox key. Copy it immediately: the full value is displayed only once.

2. Test authentication

   Request GET /v1/balance. HTTP 200 means the key works; 401 means it is missing or invalid, while 403 usually points to permissions or an IP allowlist.

3. Publish your webhook endpoint

   Create an HTTPS endpoint that reads the raw body, validates the signature, stores the event id and answers HTTP 200 quickly.

4. Create a Pix charge

   Call POST /v1/payments with an amount in cents and a stable idempotency key derived from your order id.

5. Present the payment

   Display both pix_qr_code and pix_copy_paste. Do not mark the order as paid yet.

6. Process the payment event

   After signature validation, update your order atomically and ignore repeated deliveries of the same event.

Authentication check

curl https://integrate.api.kyvopay.com.br/v1/balance \
  -H "X-API-Key: ky_XXXXX-XXXXX-XXXXX"

Production checklist

• The production key lives only in a secret manager or server environment variable.
• Every write operation has a deterministic idempotency key.
• Webhook signatures are validated before any business action.
• Duplicate and out-of-order webhook events are handled safely.
• Amounts use integer cents from end to end.
• request_id, your order id and KyvoPay public ids are recorded together.
• Alerts exist for repeated 4xx/5xx responses and webhook delivery failures.