API Reference/Payments
POST

Create a Pix charge

Create a Pix charge. See the request, response and integration notes.

POST/v1/payments
https://integrate.api.kyvopay.com.br
cURL
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": "Order #12345",
    "idempotency_key": "order-12345"
  }'
Resposta200 OK
{
  "amount_centavos": 4990,
  "idempotency_key": "pedido-12345",
  "customer": {
    "name": "Cliente Exemplo",
    "email": "cliente@example.com",
    "document": "12345678909"
  }
}

Authentication

X-API-Keystring · headerrequired

Use the ky_... key created under Integrations → API Keys in the KyvoPay dashboard.

Use this endpoint to create a pix charge. For safe retries, reuse the same idempotency key for the same business operation.

Request

Note

Private endpoints require the X-API-Key header. Keep credentials on your backend and log the response request_id for diagnostics.

Response

Implementation notes

  • Validate required input before sending the request.
  • Store returned public identifiers without assuming their format.
  • Treat 4xx validation errors as non-retryable until the request is corrected.
  • Retry timeouts, 429 and temporary 5xx responses with exponential backoff.
  • Keep the idempotency key stable across retries.
Need help? Contact support
© 2026 KyvoPay