API Reference/Payment links
POST

Create a payment link

Create a payment link. See the request, response and integration notes.

POST/v1/payment-links
https://integrate.api.kyvopay.com.br
cURL
curl -X POST https://integrate.api.kyvopay.com.br/v1/payment-links \
  -H "X-API-Key: ky_XXXXX-XXXXX-XXXXX" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_centavos": 4990,
  "collect_customer_data": false,
  "description": "Order #12345",
  "expires_at": "2026-01-01T12:30:00Z",
  "max_sales": 0,
  "min_amount_centavos": 4990,
  "name": "Example Customer",
  "slug": "string"
}'
Resposta200 OK
{
  "data": {
    "amount_centavos": "4990",
    "checkouts_started": 0,
    "collect_customer_data": false,
    "description": "Pedido #12345",
    "expires_at": "2026-01-01T12:30:00Z",
    "id": "01HZ8K3M5N",
    "max_sales": "string",
    "min_amount_centavos": "4990",
    "name": "Cliente Exemplo",
    "revenue_centavos": "4990",
    "sales_count": 0,
    "slug": "string",
    "starts_at": "2026-01-01T12:00:00Z",
    "status": "pending",
    "visits": 0
  },
  "error": {
    "code": "string",
    "details": {},
    "message": "string"
  },
  "request_id": "req_01HZ8K3M5N"
}

Authentication

X-API-Keystring · headerrequired

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

Use this endpoint to create a payment link. 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