Documentation · API 1.0.0

Build on Ravelo.

Take crypto payments from your own backend: create payment requests, follow them with signed webhooks, and prepare payouts and refunds that a person approves. Try everything first in test mode, with no real funds.

Quickstart

A test key, a simulated payment and a verified webhook, with copy-paste samples.

REST API

Every endpoint, field and error, generated from the OpenAPI contract.

Webhooks

Signed events for payments, payouts and refunds, retried for 72 hours.

Test mode

A sandbox with its own balances. No real funds, chain or provider.

MCP server

Let an AI assistant read your account and prepare payouts that a person approves.

Base URLs

Surface	URL	Notes
REST API	https://api.ravelopay.app/v1	JSON over HTTPS. Test and live keys use the same address.
MCP server	http://localhost:8081/mcp	Streamable HTTP, stateless, for AI assistants.
Dashboard	https://app.ravelopay.app	Keys, webhooks, team and approvals.

Authentication

Your backend authenticates with an API key in the Authorization header: Authorization: Bearer rvk_.... Create keys under API & apps; a key is shown once, carries only the scopes you give it, and can be rotated with a 24-hour grace period. Test keys start with rvk_test_.

Scheme	Mechanism	Who uses it
sessionCookie	cookie wp_session	Wallet web app session (`HttpOnly`, `SameSite=Lax`). Non-GET requests also send the double-submit CSRF token from the `wp_csrf` cookie in `X-CSRF-Token`.
apiKey	HTTP bearer	Merchant API key `rvk_<prefix>_<secret>`; a test-mode key is `rvk_test_<prefix>_<secret>`. Created per account by an owner, admin or developer after step-up MFA; scoped; rotatable with a 24 h grace period; subject to the per-tenant rate limit (429 with `Retry-After`). Keys cannot call the identity, preferences, team or key-management endpoints (403 `session_required`) and answer 403 `insufficient_scope` outside their scopes.
oauth2	oauth2	OAuth 2.1 authorization code with PKCE (S256) for MCP clients, per the MCP authorization spec 2025-11-25. Tokens are bound to the MCP server (`resource`, RFC 8707) and are not accepted by this REST API. No scope approves money out.

Key scopes

Scope	Lets a key	Endpoints
balances:read	Balances, history, fee quotes and statements.	GET /v1/transactions/export, GET /v1/withdrawals/{id}, GET /v1/statements, GET /v1/statements/export
payments:read	Payment requests, refunds and the event stream.	GET /v1/payment-intents, GET /v1/checkout-origins, GET /v1/payment-intents/{id}, GET /v1/refunds/{id}, GET /v1/overpayment-returns/{id}, GET /v1/events
payments:write	Create, cancel, accept and fulfil payment requests; simulate funding in test mode.	POST /v1/payment-intents, POST /v1/checkout-origins, DELETE /v1/checkout-origins/{id}, POST /v1/payment-intents/{id}/widget-token, POST /v1/payment-intents/{id}/fulfil, POST /v1/payment-intents/{id}/cancel, POST /v1/payment-intents/{id}/accept, POST /v1/sandbox/payment-intents/{id}/simulate-funding
payouts:prepare	Prepare payouts to saved addresses, which wait for approval.	POST /v1/sandbox/address-book, POST /v1/withdrawals
refunds:prepare	Prepare refunds of payments, which wait for approval.	POST /v1/refunds, POST /v1/overpayment-returns
webhooks:manage	Webhook endpoints, deliveries, test events and replays.	GET /v1/webhook-endpoints, POST /v1/webhook-endpoints, PATCH /v1/webhook-endpoints/{id}, POST /v1/webhook-endpoints/{id}/rotate-secret, POST /v1/webhook-endpoints/{id}/end-rotation, POST /v1/webhook-endpoints/{id}/test, GET /v1/webhook-endpoints/{id}/deliveries, POST /v1/events/{id}/replay
addressbook:read	Saved payout addresses.	GET /v1/address-book

No scope can approve money out.

Payouts and refunds a key prepares are created as awaiting_approval with an approval_url. A team member approves them in the dashboard with a passkey or authenticator code. That is the whole safety model, and it is the same for keys and MCP clients.

The approval model

Your server calls POST /v1/withdrawals (a payout) or POST /v1/refunds with an Idempotency-Key.
The API checks limits, balance and the destination (a saved address that has finished its 24-hour cooling-off), reserves the funds, and answers 201 with status: "awaiting_approval" and an approval_url. Nothing has moved.
A team member opens the link, reviews amount, asset, network, full address and fees, and confirms with a passkey.
You follow it to completed with GET /v1/withdrawals/{id} or the payout.* and refund.* webhook events. A request nobody approves within 24 hours is cancelled and its funds return to your balance.

Conventions

Topic	Rule
Amounts	Integer strings in the asset's smallest unit, always with an asset_id such as usdt-tron. Never floats.
Idempotency	An Idempotency-Key on every POST makes a retry safe.
Pagination	Cursors only: pass next_cursor back as cursor.
Errors	{code, message, request_id, retryable} on every failure; switch on code.
Rate limits	One budget per account, reported on every response.
Versioning	Semantic versions, a frozen contract, 12 months' notice for breaking changes.