# Kuaryx > Kuaryx is a non-custodial payment API for the XRP Ledger, aimed at Brazilian merchants and online stores. A store creates a charge priced in BRL; the buyer pays the equivalent in XRP straight to the merchant's own wallet; Kuaryx watches the ledger and notifies the store by a signed webhook. XRP only: Kuaryx never holds funds, has no payouts/withdrawals, no Pix and no currency conversion. Full human docs (Portuguese): https://kuaryx.com/docs/ ## API basics - Base URL: https://api.kuaryx.com - Auth: header `X-Api-Key: `. Live keys start with `kuaryx_`, test keys with `kuaryx_test_`. Keep keys server-side. - Test mode: charges made with the test key never move XRP, carry no fee, return `"livemode": false`, and can be marked paid with `POST /api/charges/{id}/simulate-payment` (test key only) or the "Simular pagamento" button on the checkout page. Each key only sees charges of its own mode. - Amounts in XRP are in drops (1 XRP = 1,000,000 drops). `amount_brl` is a decimal string. ## Endpoints - `POST /api/charges` — create a charge. Body: `amount_brl` (required), `description`, `external_reference` (your order id), `expires_in_minutes` (1–1440, default 15), `metadata` (object, up to 20 flat keys), `customer_email`, `success_url`, `cancel_url` (http/https). Optional header `Idempotency-Key`: repeating it returns the first charge instead of creating another (409 if it was used in the other mode). Response includes `id`, `status`, `livemode`, `expected_drops`, `xrpl_address`, `destination_tag`, `checkout_url`, `expires_at`. - `GET /api/charges/{id}` — one charge. - `GET /api/charges` — newest first. Query: `limit` (1–500, default 100), `created_before` (ISO datetime; pass the last item's `created_at` for the next page), `status_filter`, `external_reference`. - `GET /api/charges/summary` — sales today and this month (Brasília time). - `POST /api/charges/{id}/simulate-payment` — test key only. ## Checkout Send the buyer to `checkout_url`. After a validated payment it redirects to `success_url` with `?kuaryx_charge_id=` appended (or shows a Kuaryx receipt). `cancel_url` is shown as "Voltar para a loja". Never fulfil an order from the redirect alone: confirm with the webhook or `GET /api/charges/{id}`. ## Statuses `pending`, `underpaid` (partial within deadline), `paid`, `overpaid`, `late_payment` (arrived after deadline; merchant decides), `expired`. Only validated XRP Ledger transactions count, by `delivered_amount`, matched on the charge's destination address and destination tag. ## Webhooks POST JSON to the store's webhook URL on each status change: `{"event", "livemode", "timestamp", "charge": {id, status, livemode, amount_brl, expected_drops, fee_drops, destination_tag, external_reference, metadata, customer_email, created_at, expires_at, paid_at}}`. Events: `charge.paid`, `charge.overpaid`, `charge.underpaid`, `charge.late_payment`, `charge.expired`. Signature: header `X-Kuaryx-Signature: sha256=`. Compare in constant time before parsing JSON. Reply 2xx; failures are retried after 1 min, 5 min, 30 min, 2 h and 12 h, so handle repeats idempotently by `charge.id`. ## Errors 401 invalid key · 403 wrong mode for the action · 404 charge not found (or other mode) · 409 idempotency key used in other mode · 422 validation · 503 price quote unavailable, retry. ## Contact - Integrations: lojistas@kuaryx.com - Site: https://kuaryx.com/