Core concepts
Understand accounts, Pix charges, balances, environments and the API response model.
Understanding these concepts first prevents the most common integration mistakes.
Account and API key
An API key identifies both your company and its environment. Requests never accept a business_id; KyvoPay derives ownership from the key.
Pix charge and payment
A Pix charge represents the amount a customer must pay. Creation returns a QR Code and a copy-and-paste code. The initial status is normally pending; payment confirmation arrives asynchronously through a webhook.
Payout and refund
A payout sends available balance to a Pix destination. A refund returns all or part of a confirmed payment. Both are write operations and must use idempotency.
Balance and ledger
The balance is the current amount available to your account. The statement is an append-only view of entries that explain how the balance changed. Use the statement for reconciliation instead of calculating the balance from payment records.
Public identifiers
Store the public ids returned by the API. Use them for later lookups, support and reconciliation. Do not infer their format or generate your own.
Status changes
Treat status as a state machine. A resource can move from pending to completed or failed after the original request has returned. Your system must accept repeated notifications and must not assume events always arrive in order.