Introduction

KyvoPay provides a straightforward HTTP API for creating and tracking Pix payments, sending payouts, issuing refunds, managing balances and receiving real-time events.

This documentation is organized as a practical path: understand the basics, make your first sandbox request, implement webhooks and only then move to production.

Base URL

All authenticated integration requests use the following base address:

https://integrate.api.kyvopay.com.br/v1

Authentication

Send your API key in the X-API-Key header. Keep the key on your server; it must never be exposed in a browser or mobile application.

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

Core concepts

• Sandbox and production are isolated. Each environment has its own API key and data.
• Amounts are integer cents. BRL 49.90 is sent as 4990.
• Writes must be idempotent. Reuse a stable idempotency_key when retrying a request.
• Webhooks are the source of truth. Fulfill an order only after receiving and validating the payment event.
• Every response has a request ID. Save request_id in your logs to make support and diagnostics faster.

Recommended integration path

1. Create a sandbox API key

   Generate a test key in the dashboard and store it in a server-side environment variable.

2. Create a Pix charge

   Send the amount in cents and your order identifier as the idempotency key.

3. Display the payment

   Show both the QR Code and Pix copy-and-paste string returned by the API.

4. Confirm through a webhook

   Validate the signature, process the event once and return HTTP 200 quickly.

5. Move to production

   Create a production key, repeat the full flow with a small amount and monitor the first transactions.

Standard response envelope

Successful and failed requests share the same predictable envelope:

{
  "data": {},
  "error": null,
  "request_id": "req_01..."
}

Continue with Your first integration or browse the API Reference.