Merchant API · 1.0.0 · 40 endpoints

REST API v1 reference

Public REST v1 for merchants' backends and the dashboard, with a test mode.

The merchant integration API

Every endpoint here accepts an API key with the scope shown. Base units everywhere, Idempotency-Key on every POST, cursor pagination, and errors as {code, message, request_id, retryable}. Read the guides on idempotency, pagination, rate limits and errors, and start with the quickstart.

Sign-in, passkeys, devices and the other calls the dashboard makes for itself are not part of the integration API. They are listed on the dashboard session API page.

payments

Payment requests (intents) a customer pays, with their state, fundings and fulfilment.

GET/v1/payment-intents

List payment intents, newest first

Auth: Dashboard session · API key
Key scope: payments:read

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
statusqueryPaymentStatus
order_refquerystring
cursorquerystring
limitqueryinteger

Response 200 · object

One page without fundings; fetch an intent for its fundings.

itemsrequired
PaymentIntent[]
next_cursorrequired
string | null

POST/v1/payment-intents

Create a payment intent and get exact payment instructions

Reserves an address for this intent and fixes the amount and the price-term expiry (default 30 minutes, 2 minutes to 24 hours). Give amount in base units or price in fiat, which is converted at the latest rates and rounded up. Replaying the same Idempotency-Key with the same body returns the original intent with 200, even while the platform has paused new payment requests (503 operation_paused); intents already open keep being watched and credited during a pause. Any change to the body under the same key is 409 idempotency_conflict. The address normally comes from a pool reserved in advance. When the pool has none for the network, a live-mode intent is opened as a checkout session at the provider instead: the response carries instructions.state pending until the session's address, or its hosted_url when the provider assigns no address, is known (the call waits a few seconds for it). Poll the intent until state is ready. Test-mode intents always get a synthetic address.

Auth: Dashboard session · API key
Key scope: payments:write

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · PaymentIntentInput

order_refrequired
string
The merchant's order id.
asset_idrequired
string
amount
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
price
object
description
string
What the payment is for, returned as given. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
metadata
object
Up to 4 KB, returned as given. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
expires_in_seconds
integer

Response 200 · PaymentIntent

Replayed from the same Idempotency-Key.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
order_refrequired
string
statusrequired
PaymentStatus
requires_payment: waiting for funds. processing: funding seen at the provider, not yet verified on-chain. partially_funded: verified funds short of the amount due by more than the platform's underpay tolerance. succeeded: verified funds cover the amount due within that tolerance, or the merchant accepted less (funds are available). expired and cancelled are final.
dispositionrequired
"none" | "hold" | "blocked"
Compliance outcome of the matched fundings.
funds_statusrequired
"none" | "pending" | "available" | "held" | "blocked"
fulfilment_statusrequired
"unfulfilled" | "fulfilled"
settlement_statusrequired
"unsettled" | "settled"
asset_idrequired
string
networkrequired
NetworkID
amountrequired
unknown
What the merchant charged.
feerequired
unknown
Our fee, paid by the payer on top of the amount.
amount_duerequired
unknown
Amount plus fee; what the payer is asked to send.
fee_collectedrequired
unknown
The part of the fee taken from verified fundings so far. It comes out first, so a short payment still pays it.
amount_seenrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_receivedrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_overpaidrequired
unknown
Verified funds beyond the amount due.
amount_overpay_heldrequired
unknown
Overpayment beyond the platform's tolerance, held out of the balance to be returned to the payer. Within the tolerance it is credited to the merchant and this is zero.
amount_refundedrequired
unknown
Completed refunds of this payment.
amount_refund_pendingrequired
unknown
Refunds requested but not yet completed; they already count against what can still be refunded.
amount_refundablerequired
unknown
What a refund can still return; verified funds (late ones included) less our fee, the held overpayment and refunds not cancelled or failed.
amount_overpay_returnedrequired
unknown
The part of the held overpayment that completed returns sent back to the payer, network fee included.
overpay_statusrequired
"none" | "held" | "return_in_progress" | "returned" | "expired"
Where the held overpayment stands. held: return it with POST /v1/overpayment-returns before overpay_return_by. return_in_progress: a return awaits approval, review or payment. returned: it reached the payer. expired: the window passed; platform staff return it and the merchant path is closed.
overpay_return_byrequired
ISODate | null
The deadline to return the held overpayment; null when nothing was held.
pricerequired
object | null
descriptionrequired
string
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
metadatarequired
object
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
instructionsrequired
object
What the payer must do, exactly. Most intents pay to an address reserved for them; when none is free, the intent is opened as a checkout session at the provider and the instructions are pending until its address or hosted page is known (the create call waits a few seconds for it).
fundings
PaymentFunding[]
expires_atrequired
ISODate
created_atrequired
ISODate
succeeded_at
ISODate | null
accepted_atrequired
ISODate | null
When the merchant took a short payment as paid.
funds_available_at
ISODate | null
fulfilled_at
ISODate | null
settled_at
ISODate | null
expired_at
ISODate | null
cancelled_at
ISODate | null

Errors: 400 · 403 · 409 · 422 · 429 · 503

GET/v1/checkout-origins

Approved browser origins for embedded checkout widgets

Auth: Dashboard session · API key
Key scope: payments:read

Response 200 · CheckoutOriginList

Approved origins in creation order.

datarequired
CheckoutOrigin[]

Errors: 401 · 403 · 429

POST/v1/checkout-origins

Approve a browser origin for embedded checkout widgets

Normalises origin (scheme://host[:port] with default ports stripped and no path, query or fragment) and adds it to the account's allowlist (up to 50 origins). Live accounts accept public https:// origins only; test-mode accounts also accept http://localhost, http://127.0.0.1 and http://[::1].

Auth: Dashboard session · API key
Key scope: payments:write

Parameters

Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · CheckoutOriginInput

originrequired
string
Origin URL without path, query or fragment.

Response 201 · CheckoutOrigin

Approved origin.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
originrequired
string
Normalized scheme + host + optional non-default port, e.g. https://shop.example.com.
created_atrequired
ISODate

Errors: 400 · 401 · 403 · 409 · 429

DELETE/v1/checkout-origins/{id}

Remove an approved checkout origin

Revokes the origin immediately; active widget tokens bound to it stop working at once.

Auth: Dashboard session · API key
Key scope: payments:write

Parameters

idpathrequiredID

Response 204

Removed.

Errors: 401 · 403 · 404 · 429

POST/v1/payment-intents/{id}/widget-token

Mint a short-lived widget session token for an approved origin

Issues a stateless HMAC-signed wcs_ token bound to the payment intent, account, normalized origin, and ttl_seconds (60 to 900 seconds, default 900). Safe to pass to the browser checkout widget; carries no API key or webhook secret.

Auth: Dashboard session · API key
Key scope: payments:write

Parameters

idpathrequiredID
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · WidgetTokenInput

originrequired
string
Approved origin where the widget will be mounted.
ttl_seconds
integer
Token lifetime in seconds (1 to 15 minutes).

Response 201 · WidgetToken

The short-lived widget token.

tokenrequired
string
Short-lived wcs_ token bound to one intent and origin.
expires_atrequired
ISODate

Errors: 400 · 401 · 403 · 404 · 429

GET/v1/payment-intents/{id}

One payment intent with its fundings

Auth: Dashboard session · API key
Key scope: payments:read

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).

Response 200 · PaymentIntent

The intent.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
order_refrequired
string
statusrequired
PaymentStatus
requires_payment: waiting for funds. processing: funding seen at the provider, not yet verified on-chain. partially_funded: verified funds short of the amount due by more than the platform's underpay tolerance. succeeded: verified funds cover the amount due within that tolerance, or the merchant accepted less (funds are available). expired and cancelled are final.
dispositionrequired
"none" | "hold" | "blocked"
Compliance outcome of the matched fundings.
funds_statusrequired
"none" | "pending" | "available" | "held" | "blocked"
fulfilment_statusrequired
"unfulfilled" | "fulfilled"
settlement_statusrequired
"unsettled" | "settled"
asset_idrequired
string
networkrequired
NetworkID
amountrequired
unknown
What the merchant charged.
feerequired
unknown
Our fee, paid by the payer on top of the amount.
amount_duerequired
unknown
Amount plus fee; what the payer is asked to send.
fee_collectedrequired
unknown
The part of the fee taken from verified fundings so far. It comes out first, so a short payment still pays it.
amount_seenrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_receivedrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_overpaidrequired
unknown
Verified funds beyond the amount due.
amount_overpay_heldrequired
unknown
Overpayment beyond the platform's tolerance, held out of the balance to be returned to the payer. Within the tolerance it is credited to the merchant and this is zero.
amount_refundedrequired
unknown
Completed refunds of this payment.
amount_refund_pendingrequired
unknown
Refunds requested but not yet completed; they already count against what can still be refunded.
amount_refundablerequired
unknown
What a refund can still return; verified funds (late ones included) less our fee, the held overpayment and refunds not cancelled or failed.
amount_overpay_returnedrequired
unknown
The part of the held overpayment that completed returns sent back to the payer, network fee included.
overpay_statusrequired
"none" | "held" | "return_in_progress" | "returned" | "expired"
Where the held overpayment stands. held: return it with POST /v1/overpayment-returns before overpay_return_by. return_in_progress: a return awaits approval, review or payment. returned: it reached the payer. expired: the window passed; platform staff return it and the merchant path is closed.
overpay_return_byrequired
ISODate | null
The deadline to return the held overpayment; null when nothing was held.
pricerequired
object | null
descriptionrequired
string
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
metadatarequired
object
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
instructionsrequired
object
What the payer must do, exactly. Most intents pay to an address reserved for them; when none is free, the intent is opened as a checkout session at the provider and the instructions are pending until its address or hosted page is known (the create call waits a few seconds for it).
fundings
PaymentFunding[]
expires_atrequired
ISODate
created_atrequired
ISODate
succeeded_at
ISODate | null
accepted_atrequired
ISODate | null
When the merchant took a short payment as paid.
funds_available_at
ISODate | null
fulfilled_at
ISODate | null
settled_at
ISODate | null
expired_at
ISODate | null
cancelled_at
ISODate | null

Errors: 404

POST/v1/payment-intents/{id}/fulfil

Record that the order was delivered (succeeded intents only)

Auth: Dashboard session · API key
Key scope: payments:write

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Response 200 · PaymentIntent

The intent.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
order_refrequired
string
statusrequired
PaymentStatus
requires_payment: waiting for funds. processing: funding seen at the provider, not yet verified on-chain. partially_funded: verified funds short of the amount due by more than the platform's underpay tolerance. succeeded: verified funds cover the amount due within that tolerance, or the merchant accepted less (funds are available). expired and cancelled are final.
dispositionrequired
"none" | "hold" | "blocked"
Compliance outcome of the matched fundings.
funds_statusrequired
"none" | "pending" | "available" | "held" | "blocked"
fulfilment_statusrequired
"unfulfilled" | "fulfilled"
settlement_statusrequired
"unsettled" | "settled"
asset_idrequired
string
networkrequired
NetworkID
amountrequired
unknown
What the merchant charged.
feerequired
unknown
Our fee, paid by the payer on top of the amount.
amount_duerequired
unknown
Amount plus fee; what the payer is asked to send.
fee_collectedrequired
unknown
The part of the fee taken from verified fundings so far. It comes out first, so a short payment still pays it.
amount_seenrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_receivedrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_overpaidrequired
unknown
Verified funds beyond the amount due.
amount_overpay_heldrequired
unknown
Overpayment beyond the platform's tolerance, held out of the balance to be returned to the payer. Within the tolerance it is credited to the merchant and this is zero.
amount_refundedrequired
unknown
Completed refunds of this payment.
amount_refund_pendingrequired
unknown
Refunds requested but not yet completed; they already count against what can still be refunded.
amount_refundablerequired
unknown
What a refund can still return; verified funds (late ones included) less our fee, the held overpayment and refunds not cancelled or failed.
amount_overpay_returnedrequired
unknown
The part of the held overpayment that completed returns sent back to the payer, network fee included.
overpay_statusrequired
"none" | "held" | "return_in_progress" | "returned" | "expired"
Where the held overpayment stands. held: return it with POST /v1/overpayment-returns before overpay_return_by. return_in_progress: a return awaits approval, review or payment. returned: it reached the payer. expired: the window passed; platform staff return it and the merchant path is closed.
overpay_return_byrequired
ISODate | null
The deadline to return the held overpayment; null when nothing was held.
pricerequired
object | null
descriptionrequired
string
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
metadatarequired
object
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
instructionsrequired
object
What the payer must do, exactly. Most intents pay to an address reserved for them; when none is free, the intent is opened as a checkout session at the provider and the instructions are pending until its address or hosted page is known (the create call waits a few seconds for it).
fundings
PaymentFunding[]
expires_atrequired
ISODate
created_atrequired
ISODate
succeeded_at
ISODate | null
accepted_atrequired
ISODate | null
When the merchant took a short payment as paid.
funds_available_at
ISODate | null
fulfilled_at
ISODate | null
settled_at
ISODate | null
expired_at
ISODate | null
cancelled_at
ISODate | null

Errors: 404 · 409

POST/v1/payment-intents/{id}/cancel

Cancel an intent nobody has paid yet

Auth: Dashboard session · API key
Key scope: payments:write

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Response 200 · PaymentIntent

The intent.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
order_refrequired
string
statusrequired
PaymentStatus
requires_payment: waiting for funds. processing: funding seen at the provider, not yet verified on-chain. partially_funded: verified funds short of the amount due by more than the platform's underpay tolerance. succeeded: verified funds cover the amount due within that tolerance, or the merchant accepted less (funds are available). expired and cancelled are final.
dispositionrequired
"none" | "hold" | "blocked"
Compliance outcome of the matched fundings.
funds_statusrequired
"none" | "pending" | "available" | "held" | "blocked"
fulfilment_statusrequired
"unfulfilled" | "fulfilled"
settlement_statusrequired
"unsettled" | "settled"
asset_idrequired
string
networkrequired
NetworkID
amountrequired
unknown
What the merchant charged.
feerequired
unknown
Our fee, paid by the payer on top of the amount.
amount_duerequired
unknown
Amount plus fee; what the payer is asked to send.
fee_collectedrequired
unknown
The part of the fee taken from verified fundings so far. It comes out first, so a short payment still pays it.
amount_seenrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_receivedrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_overpaidrequired
unknown
Verified funds beyond the amount due.
amount_overpay_heldrequired
unknown
Overpayment beyond the platform's tolerance, held out of the balance to be returned to the payer. Within the tolerance it is credited to the merchant and this is zero.
amount_refundedrequired
unknown
Completed refunds of this payment.
amount_refund_pendingrequired
unknown
Refunds requested but not yet completed; they already count against what can still be refunded.
amount_refundablerequired
unknown
What a refund can still return; verified funds (late ones included) less our fee, the held overpayment and refunds not cancelled or failed.
amount_overpay_returnedrequired
unknown
The part of the held overpayment that completed returns sent back to the payer, network fee included.
overpay_statusrequired
"none" | "held" | "return_in_progress" | "returned" | "expired"
Where the held overpayment stands. held: return it with POST /v1/overpayment-returns before overpay_return_by. return_in_progress: a return awaits approval, review or payment. returned: it reached the payer. expired: the window passed; platform staff return it and the merchant path is closed.
overpay_return_byrequired
ISODate | null
The deadline to return the held overpayment; null when nothing was held.
pricerequired
object | null
descriptionrequired
string
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
metadatarequired
object
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
instructionsrequired
object
What the payer must do, exactly. Most intents pay to an address reserved for them; when none is free, the intent is opened as a checkout session at the provider and the instructions are pending until its address or hosted page is known (the create call waits a few seconds for it).
fundings
PaymentFunding[]
expires_atrequired
ISODate
created_atrequired
ISODate
succeeded_at
ISODate | null
accepted_atrequired
ISODate | null
When the merchant took a short payment as paid.
funds_available_at
ISODate | null
fulfilled_at
ISODate | null
settled_at
ISODate | null
expired_at
ISODate | null
cancelled_at
ISODate | null

Errors: 404 · 409

POST/v1/payment-intents/{id}/accept

Take a short payment as paid

For a partially funded (or expired, part-paid) intent with nothing still verifying or held. The merchant keeps what arrived less our fee and the intent succeeds; to give the money back instead, refund it.

Auth: Dashboard session · API key
Key scope: payments:write

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Response 200 · PaymentIntent

The intent, now succeeded.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
order_refrequired
string
statusrequired
PaymentStatus
requires_payment: waiting for funds. processing: funding seen at the provider, not yet verified on-chain. partially_funded: verified funds short of the amount due by more than the platform's underpay tolerance. succeeded: verified funds cover the amount due within that tolerance, or the merchant accepted less (funds are available). expired and cancelled are final.
dispositionrequired
"none" | "hold" | "blocked"
Compliance outcome of the matched fundings.
funds_statusrequired
"none" | "pending" | "available" | "held" | "blocked"
fulfilment_statusrequired
"unfulfilled" | "fulfilled"
settlement_statusrequired
"unsettled" | "settled"
asset_idrequired
string
networkrequired
NetworkID
amountrequired
unknown
What the merchant charged.
feerequired
unknown
Our fee, paid by the payer on top of the amount.
amount_duerequired
unknown
Amount plus fee; what the payer is asked to send.
fee_collectedrequired
unknown
The part of the fee taken from verified fundings so far. It comes out first, so a short payment still pays it.
amount_seenrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_receivedrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
amount_overpaidrequired
unknown
Verified funds beyond the amount due.
amount_overpay_heldrequired
unknown
Overpayment beyond the platform's tolerance, held out of the balance to be returned to the payer. Within the tolerance it is credited to the merchant and this is zero.
amount_refundedrequired
unknown
Completed refunds of this payment.
amount_refund_pendingrequired
unknown
Refunds requested but not yet completed; they already count against what can still be refunded.
amount_refundablerequired
unknown
What a refund can still return; verified funds (late ones included) less our fee, the held overpayment and refunds not cancelled or failed.
amount_overpay_returnedrequired
unknown
The part of the held overpayment that completed returns sent back to the payer, network fee included.
overpay_statusrequired
"none" | "held" | "return_in_progress" | "returned" | "expired"
Where the held overpayment stands. held: return it with POST /v1/overpayment-returns before overpay_return_by. return_in_progress: a return awaits approval, review or payment. returned: it reached the payer. expired: the window passed; platform staff return it and the merchant path is closed.
overpay_return_byrequired
ISODate | null
The deadline to return the held overpayment; null when nothing was held.
pricerequired
object | null
descriptionrequired
string
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
metadatarequired
object
As given when the payment was created. Do not put customer personal data (names, email addresses, phone numbers, postal addresses) in it; it is kept with the payment's financial record and cannot always be erased on request. Use order_ref to link to your own records.
instructionsrequired
object
What the payer must do, exactly. Most intents pay to an address reserved for them; when none is free, the intent is opened as a checkout session at the provider and the instructions are pending until its address or hosted page is known (the create call waits a few seconds for it).
fundings
PaymentFunding[]
expires_atrequired
ISODate
created_atrequired
ISODate
succeeded_at
ISODate | null
accepted_atrequired
ISODate | null
When the merchant took a short payment as paid.
funds_available_at
ISODate | null
fulfilled_at
ISODate | null
settled_at
ISODate | null
expired_at
ISODate | null
cancelled_at
ISODate | null

Errors: 404 · 409

sandbox

Test-mode helpers. They need a `rvk_test_` key or a test-mode session (`X-Test-Mode: true`), and answer `403 test_mode_only` otherwise.

POST/v1/sandbox/payment-intents/{id}/simulate-funding

Simulate a payer sending funds to a test intent

Test-mode keys only (403 test_mode_only otherwise). The sandbox simulator sends a transfer to the intent's address and its signed callback goes through the same intake, verification, crediting and risk pipeline as a real deposit, so the intent moves on its own a moment later. The default is the amount still due in the intent's asset; send asset_id to test a payer who sends the wrong asset (the funds are held in a case, the intent stays unpaid) and amount to test short or over payments.

Auth: Dashboard session · API key
Key scope: payments:write

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · SimulateFundingInput

amount
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
asset_id
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.

Response 201 · SimulatedFunding

The simulated transfer.

payment_intent_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
addressrequired
string
tx_hashrequired
string
callback_statusrequired
integer
What the webhook intake answered the simulated callback (200 when accepted).

Errors: 400 · 401 · 403 · 404 · 429 · 503

POST/v1/sandbox/address-book

Save a payout destination in test mode

Test-mode keys only. The entry is usable at once: no step-up code and no cooling-off, because a sandbox account has no signed-in member to confirm them. Test payouts to it are approved and settled automatically with a simulated result.

Auth: Dashboard session · API key
Key scope: payouts:prepare

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · SandboxAddressRequest

labelrequired
string
networkrequired
NetworkID
addressrequired
string
memo
string

Response 201 · AddressBookEntry

The new entry.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
labelrequired
string
networkrequired
NetworkID
addressrequired
string
memorequired
string | null
Destination tag or memo the network needs (TON), if any.
statusrequired
"cooling_off" | "active"
active_fromrequired
unknown
End of the 24 h cooling-off period.
created_atrequired
ISODate

Errors: 400 · 401 · 403 · 422 · 429

refunds

Refunds of succeeded payments. A key prepares one and a team member approves it.

POST/v1/refunds

Request a refund of a payment

Reserves the amount and 2328's payout fee (no markup) and waits as awaiting_approval until a signed-in owner, admin or finance member approves it at approval_url, someone other than the preparer when two or more members may approve; it lapses at approval_expires_at like a payout (a refund.cancelled event with expired: true, funds released). Platform operations then review every refund before it is sent. Refunds on one intent can never exceed its verified fundings in the intent's asset (late ones included). Nothing refunds automatically. Replaying the same Idempotency-Key with the same body returns the original refund with 200; a changed body under the same key is 409 idempotency_conflict. While the platform has paused refunds, new ones get 503 operation_paused and approved ones wait, funds reserved, until the pause lifts.

Auth: Dashboard session · API key
Key scope: refunds:prepare

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · RefundInput

payment_intent_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
addressrequired
string
Destination on the intent's network; checked by platform operations.
memo
string
reasonrequired
string
Shown to platform operations.
travel_rule
TravelRule
Who receives the funds, for the Travel Rule. Required when the amount is worth Capabilities.travel_rule_threshold_usd_cents or more (422 travel_rule_required otherwise), accepted below it. The originator is the merchant, taken from the account profile. Stored with the payout or refund for compliance; never written to logs. Incomplete data is 400 travel_rule_invalid.

Response 200 · Withdrawal

Replayed from the same Idempotency-Key.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
statusrequired
WithdrawalStatus
asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
network_feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
total_debitrequired
unknown
What left the available balance (amount, fee and a pass-through network fee).
kindrequired
"payout" | "refund" | "overpay_return"
overpay_return sends a payer's held overpayment back; it is drawn from the hold, never from the available balance, and fee is always zero.
payment_intent_idrequired
ID | null
The refunded payment (refunds and overpayment returns).
refund_reasonrequired
string | null
failure_reasonrequired
string | null
address_book_idrequired
ID | null
The saved address a payout goes to; null for refunds.
addressrequired
string
labelrequired
string
tx_hashrequired
string | null
approval_urlrequired
string (uri) | null
approval_expires_atrequired
ISODate | null
When the request stops being approvable; set while awaiting_approval.
prepared_byrequired
TeamPerson | null
The member who prepared it; set while awaiting_approval.
approversrequired
TeamPerson[]
Members who may approve it now (empty once decided). The preparer is left out whenever another member could approve.
expired_atrequired
ISODate | null
Set when the request was cancelled because nobody approved it in time.
sourcerequired
Source
Where the operation was started.
client_namerequired
string | null
created_atrequired
ISODate

Errors: 400 · 404 · 409 · 422 · 423 · 503

GET/v1/refunds/{id}

Refund status

Auth: Dashboard session · API key
Key scope: payments:read

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).

Response 200 · Withdrawal

The refund.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
statusrequired
WithdrawalStatus
asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
network_feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
total_debitrequired
unknown
What left the available balance (amount, fee and a pass-through network fee).
kindrequired
"payout" | "refund" | "overpay_return"
overpay_return sends a payer's held overpayment back; it is drawn from the hold, never from the available balance, and fee is always zero.
payment_intent_idrequired
ID | null
The refunded payment (refunds and overpayment returns).
refund_reasonrequired
string | null
failure_reasonrequired
string | null
address_book_idrequired
ID | null
The saved address a payout goes to; null for refunds.
addressrequired
string
labelrequired
string
tx_hashrequired
string | null
approval_urlrequired
string (uri) | null
approval_expires_atrequired
ISODate | null
When the request stops being approvable; set while awaiting_approval.
prepared_byrequired
TeamPerson | null
The member who prepared it; set while awaiting_approval.
approversrequired
TeamPerson[]
Members who may approve it now (empty once decided). The preparer is left out whenever another member could approve.
expired_atrequired
ISODate | null
Set when the request was cancelled because nobody approved it in time.
sourcerequired
Source
Where the operation was started.
client_namerequired
string | null
created_atrequired
ISODate

Errors: 404

POST/v1/overpayment-returns

Return a held overpayment to the payer

Sends the whole overpayment held on a payment (amount_overpay_held less what was already returned) back to the payer, less 2328's network fee and with no fee of ours, before overpay_return_by. The return follows the refund path: the destination must be the payer's own sending address or a saved address past its cooling-off, it waits as awaiting_approval for a team member, and once approved it is submitted without a staff review unless screening, limits or the account's market flag it, in which case platform operations review it first. It is drawn from the hold, never from the available balance, and it is the only way the hold can leave. After overpay_return_by the merchant path is closed (409 overpay_window_closed) and platform staff return the funds. Replaying the same Idempotency-Key with the same body returns the original with 200.

Auth: Dashboard session · API key
Key scope: refunds:prepare

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · OverpayReturnInput

payment_intent_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
addressrequired
string
The payer's address on the intent's network: the one that funded the payment, or a saved address past its cooling-off.
memo
string
travel_rule
TravelRule
Who receives the funds, for the Travel Rule. Required when the amount is worth Capabilities.travel_rule_threshold_usd_cents or more (422 travel_rule_required otherwise), accepted below it. The originator is the merchant, taken from the account profile. Stored with the payout or refund for compliance; never written to logs. Incomplete data is 400 travel_rule_invalid.

Response 200 · Withdrawal

Replayed from the same Idempotency-Key.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
statusrequired
WithdrawalStatus
asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
network_feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
total_debitrequired
unknown
What left the available balance (amount, fee and a pass-through network fee).
kindrequired
"payout" | "refund" | "overpay_return"
overpay_return sends a payer's held overpayment back; it is drawn from the hold, never from the available balance, and fee is always zero.
payment_intent_idrequired
ID | null
The refunded payment (refunds and overpayment returns).
refund_reasonrequired
string | null
failure_reasonrequired
string | null
address_book_idrequired
ID | null
The saved address a payout goes to; null for refunds.
addressrequired
string
labelrequired
string
tx_hashrequired
string | null
approval_urlrequired
string (uri) | null
approval_expires_atrequired
ISODate | null
When the request stops being approvable; set while awaiting_approval.
prepared_byrequired
TeamPerson | null
The member who prepared it; set while awaiting_approval.
approversrequired
TeamPerson[]
Members who may approve it now (empty once decided). The preparer is left out whenever another member could approve.
expired_atrequired
ISODate | null
Set when the request was cancelled because nobody approved it in time.
sourcerequired
Source
Where the operation was started.
client_namerequired
string | null
created_atrequired
ISODate

Errors: 400 · 404 · 409 · 422 · 423 · 503

GET/v1/overpayment-returns/{id}

Overpayment return status

Auth: Dashboard session · API key
Key scope: payments:read

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).

Response 200 · Withdrawal

The return.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
statusrequired
WithdrawalStatus
asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
network_feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
total_debitrequired
unknown
What left the available balance (amount, fee and a pass-through network fee).
kindrequired
"payout" | "refund" | "overpay_return"
overpay_return sends a payer's held overpayment back; it is drawn from the hold, never from the available balance, and fee is always zero.
payment_intent_idrequired
ID | null
The refunded payment (refunds and overpayment returns).
refund_reasonrequired
string | null
failure_reasonrequired
string | null
address_book_idrequired
ID | null
The saved address a payout goes to; null for refunds.
addressrequired
string
labelrequired
string
tx_hashrequired
string | null
approval_urlrequired
string (uri) | null
approval_expires_atrequired
ISODate | null
When the request stops being approvable; set while awaiting_approval.
prepared_byrequired
TeamPerson | null
The member who prepared it; set while awaiting_approval.
approversrequired
TeamPerson[]
Members who may approve it now (empty once decided). The preparer is left out whenever another member could approve.
expired_atrequired
ISODate | null
Set when the request was cancelled because nobody approved it in time.
sourcerequired
Source
Where the operation was started.
client_namerequired
string | null
created_atrequired
ISODate

Errors: 404

account

GET/v1/me

Account and limits remaining

Auth: Dashboard session · API key

Response 200 · Me

The authenticated account.

account_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
account_namerequired
string
The merchant's display name.
rolerequired
unknown
The caller's role; for an API key, the role of the member who created it.
emailrequired
string (email)
usernamerequired
string
localerequired
string
BCP-47 tag, e.g. en, pt-BR, ar. Default en.
display_currencyrequired
unknown
Currency balances are shown in. Default USD.
time_zonerequired
string | null
IANA zone dates are shown in, e.g. Europe/Lisbon; null follows the browser. Timestamps in the API are always UTC.
mfarequired
object
withdrawals_frozen_untilrequired
ISODate | null
Present while a security freeze is active (48 h after password/MFA/email change).
notifications_seen_atrequired
ISODate | null
When this member last marked the notification bell read (POST /v1/me/notifications/seen); null until they first do. Items newer than this are unread.
limitsrequired
object
The active limits of the account (the platform default unless an admin set an override; UTC day and month windows) with the usage reserved so far.
created_atrequired
ISODate
accountsrequired
object[]
The accounts the signed-in person can work in, for the account switcher. Empty for an API key.
account_choice_requiredrequired
boolean
True while the person has several accounts and has never picked one; the dashboard asks which to open. Becomes false once they do (POST /v1/session/account).

Errors: 401 · 429 · 500

GET/v1/capabilities

What this caller can do on this account

The assets that take payments, payouts and refunds, each with its minimum, our fee and 2328's own fee (charged on top), plus the account's limits and current usage, any security freeze on money out, and the operations the caller's role or key scopes allow. An operation an asset does not support is null. Any member or API key may call it.

Auth: Dashboard session · API key

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).

Response 200 · Capabilities

The capabilities.

account_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
callerrequired
object
operationsrequired
object
payouts_frozen_untilrequired
ISODate | null
Payouts and refunds are refused until then, whatever operations says.
limitsrequired
object
travel_rule_threshold_usd_centsrequired
integer
Payouts and refunds whose amount is worth this much or more must carry travel_rule.
network_fee_moderequired
"pass_through" | "absorbed"
assetsrequired
AssetCapability[]
event_typesrequired
EventType[]
eligibility
MarketEligibility
What the merchant's registered market allows right now. In a restricted market new payments are refused (market_not_eligible), while payouts, refunds and overpayment returns of the merchant's own funds are accepted and go to Ravelo staff review before anything is sent. The market is the country staff confirmed, else the one declared at sign-up; it is never taken from an IP address.

Errors: 401

ledger

GET/v1/balances

Available, pending and held per asset

Auth: Dashboard session · API key

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).

Response 200 · object

One row per asset the account has ever held.

Errors: 401 · 429 · 500

GET/v1/transactions

Transaction history

Keyset pagination over the ledger journal ordered by (created_at, id) descending: pages stay stable while new rows arrive. status comes from the owning operation (deposit, withdrawal) where it exists, otherwise completed. symbol selects every chain of a coin (aliases such as TON for GRAM, formerly Toncoin, are accepted); asset_id selects one chain.

Auth: Dashboard session · API key

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
cursorquerystring
Opaque cursor from a previous page's next_cursor.
limitqueryinteger
Page size.
kindqueryTransactionKind
asset_idqueryID
symbolquerystring
Ticker, e.g. USDT; case-insensitive.

Response 200 · TransactionPage

Newest first.

itemsrequired
Transaction[]
next_cursorrequired
string | null

Errors: 400 · 401 · 429 · 500

GET/v1/transactions/export

Export transaction history as CSV

Streams up to 10,000 matching rows newest-first as a spreadsheet-safe CSV attachment with counterparty address-book labels resolved, and records transactions.exported in the audit log in the same transaction.

Auth: Dashboard session · API key
Key scope: balances:read

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
kindqueryTransactionKind
asset_idqueryID
symbolquerystring
Ticker, e.g. USDT; case-insensitive.
fromquerystring
Inclusive lower bound (RFC 3339 timestamp or YYYY-MM-DD date).
toquerystring
Exclusive upper bound (RFC 3339 timestamp or YYYY-MM-DD date).

Response 200

Spreadsheet-safe CSV attachment.

Errors: 400 · 401 · 429 · 500

deposits

POST/v1/deposit-addresses

Get or assign the deposit address for an asset

Returns the account's deposit address for the asset's network, assigning one from the pre-created 2328 pool on first call (FOR UPDATE SKIP LOCKED, never a provider call on the request path). Idempotent per network: every asset of a network shares the address. Errors: 400 unknown_asset, 422 deposits_disabled, 503 address_pool_empty (retryable).

Auth: Dashboard session · API key

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · object

asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.

Response 200 · DepositAddress

The (possibly newly assigned) deposit address.

asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
networkrequired
NetworkID
addressrequired
string
memorequired
string | null
Required tag/comment on networks that use one; otherwise null.
assigned_atrequired
ISODate

Errors: 400 · 401 · 403 · 409 · 422 · 429 · 500 · 503

fees

GET/v1/fees/quote

Fee and network cost for an amount

Resolves the fee rule for the account (global → tier → user → asset and network), applies clamp(amount × bps ÷ 10000 + fixed, min, max) with half-up rounding and returns the rule version to pass back when creating the operation, so a later fee change never alters a quoted operation. Withdrawals add the network fee of the asset's chain, passed through or absorbed per the schedule's network_fee_mode; total_debit is what leaves available. A quote is honoured for expires_at (5 minutes).

Auth: Dashboard session · API key

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
asset_idqueryrequiredID
operationqueryrequired"withdrawal" | "transfer"
amountqueryrequiredBaseUnits

Response 200 · FeeQuote

Quote, valid until `expires_at`.

asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
operationrequired
"withdrawal" | "transfer"
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
feerequired
unknown
Our markup from the fee schedule or the account's contract, after any discount (may be zero).
discount
unknown
What a contract discount took off fee, already deducted; "0" when none applies.
fee_discount_id
ID | null
The discount that applied, to send back when creating the operation; null when none applies.
network_feerequired
unknown
2328's own fee for the payout, loaded from 2328's directions.
network_fee_moderequired
"pass_through" | "absorbed"
total_debitrequired
unknown
amount + fee (+ network_fee when passed through).
fee_rule_version_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
expires_atrequired
ISODate

Errors: 400 · 401 · 422 · 429 · 500

invoices

Monthly fee invoices, read-only.

GET/v1/invoices

Monthly invoices

The account's invoices, newest first. One is issued for each closed month in which fees were charged; it is immutable once issued and its number never repeats or skips. Read-only. Test-mode keys see none.

Auth: Dashboard session · API key

Parameters

cursorquerystring
Opaque cursor from a previous page's next_cursor.
limitqueryinteger
Page size.
monthquerystring
Only the invoice for this month, YYYY-MM.

Response 200 · InvoicePage

Newest first.

itemsrequired
Invoice[]
next_cursorrequired
string | null

Errors: 400 · 401 · 429 · 500

GET/v1/invoices/{id}

One invoice with its lines

Auth: Dashboard session · API key

Parameters

idpathrequiredID

Response 200 · Invoice

The invoice and one line for each operation kind and asset.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
numberrequired
string
Gapless, e.g. INV-000042.
account_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
period_startrequired
string (date)
period_endrequired
string (date)
currencyrequired
"USD"
gross_fee_usd_centsrequired
integer
Fees at list price: net plus discounts.
discount_usd_centsrequired
integer
net_fee_usd_centsrequired
integer
What was charged.
issued_atrequired
ISODate
linesrequired
InvoiceLine[]

Errors: 401 · 404 · 429 · 500

withdrawals

POST/v1/withdrawals

Prepare a payout to a saved address

Reserves the amount, fee and pass-through network fee and the account's limits, then waits as awaiting_approval until a signed-in owner, admin or finance member approves it with step-up MFA at approval_url. When two or more members may approve, it must be someone other than whoever prepared it (an API key or MCP grant counts as the member who created or consented to it); a sole approver may approve their own. The request lapses at approval_expires_at (24 hours by default): it becomes cancelled, the reserved funds return to the available balance and a payout.cancelled event with expired: true is sent. The destination must be an active address-book entry and fee_rule_version_id must match the current quote (409 quote_changed otherwise). Payouts at or above the review threshold, or to a sanctioned address, go to staff review after approval. Replaying the same Idempotency-Key with the same body returns the original payout with 200; a changed body under the same key is 409 idempotency_conflict. Errors: address_not_found, address_cooling_off, network_mismatch, below_minimum, insufficient_balance, travel_rule_required, limit codes (422); travel_rule_invalid (400); security_freeze (423); operation_paused (503, retryable) while the platform has paused payouts. A payout approved during a pause stays submitted with its funds reserved and is sent once the pause lifts.

Auth: Dashboard session · API key
Key scope: payouts:prepare

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.

Request body · CreateWithdrawalRequest

asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
address_book_idrequired
unknown
An active address-book entry on the asset's network.
fee_rule_version_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
fee_discount_id
unknown
The quote's fee_discount_id. When sent, the payout is refused with 409 quote_changed if that discount no longer applies.
travel_rule
TravelRule
Who receives the funds, for the Travel Rule. Required when the amount is worth Capabilities.travel_rule_threshold_usd_cents or more (422 travel_rule_required otherwise), accepted below it. The originator is the merchant, taken from the account profile. Stored with the payout or refund for compliance; never written to logs. Incomplete data is 400 travel_rule_invalid.

Response 201 · Withdrawal

The withdrawal, awaiting approval or already in review.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
statusrequired
WithdrawalStatus
asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
network_feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
total_debitrequired
unknown
What left the available balance (amount, fee and a pass-through network fee).
kindrequired
"payout" | "refund" | "overpay_return"
overpay_return sends a payer's held overpayment back; it is drawn from the hold, never from the available balance, and fee is always zero.
payment_intent_idrequired
ID | null
The refunded payment (refunds and overpayment returns).
refund_reasonrequired
string | null
failure_reasonrequired
string | null
address_book_idrequired
ID | null
The saved address a payout goes to; null for refunds.
addressrequired
string
labelrequired
string
tx_hashrequired
string | null
approval_urlrequired
string (uri) | null
approval_expires_atrequired
ISODate | null
When the request stops being approvable; set while awaiting_approval.
prepared_byrequired
TeamPerson | null
The member who prepared it; set while awaiting_approval.
approversrequired
TeamPerson[]
Members who may approve it now (empty once decided). The preparer is left out whenever another member could approve.
expired_atrequired
ISODate | null
Set when the request was cancelled because nobody approved it in time.
sourcerequired
Source
Where the operation was started.
client_namerequired
string | null
created_atrequired
ISODate

Errors: 400 · 401 · 403 · 409 · 422 · 429 · 500 · 503

GET/v1/withdrawals/{id}

Payout status

Auth: Dashboard session · API key
Key scope: balances:read

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
idpathrequiredID

Response 200 · Withdrawal

The withdrawal.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for objects created with a test-mode key (rvk_test_); they live in the sandbox and never touch real funds.
statusrequired
WithdrawalStatus
asset_idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
amountrequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
network_feerequired
BaseUnits
Non-negative integer amount in the asset's smallest unit, as a decimal string.
total_debitrequired
unknown
What left the available balance (amount, fee and a pass-through network fee).
kindrequired
"payout" | "refund" | "overpay_return"
overpay_return sends a payer's held overpayment back; it is drawn from the hold, never from the available balance, and fee is always zero.
payment_intent_idrequired
ID | null
The refunded payment (refunds and overpayment returns).
refund_reasonrequired
string | null
failure_reasonrequired
string | null
address_book_idrequired
ID | null
The saved address a payout goes to; null for refunds.
addressrequired
string
labelrequired
string
tx_hashrequired
string | null
approval_urlrequired
string (uri) | null
approval_expires_atrequired
ISODate | null
When the request stops being approvable; set while awaiting_approval.
prepared_byrequired
TeamPerson | null
The member who prepared it; set while awaiting_approval.
approversrequired
TeamPerson[]
Members who may approve it now (empty once decided). The preparer is left out whenever another member could approve.
expired_atrequired
ISODate | null
Set when the request was cancelled because nobody approved it in time.
sourcerequired
Source
Where the operation was started.
client_namerequired
string | null
created_atrequired
ISODate

Errors: 401 · 404 · 429 · 500

address book

GET/v1/address-book

Saved payout addresses

Auth: Dashboard session · API key
Key scope: addressbook:read

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).

Response 200 · object

All entries, including those still cooling off.

Errors: 401 · 429 · 500

events

Account events, delivered to webhook endpoints and readable by cursor. Each delivery is a POST of the `Event` JSON with `Ravelo-Event-Id`, `Ravelo-Event-Type` and `Ravelo-Signature: t=<unix>,kid=<key id>,v1=<hex>`, where `v1` is HMAC-SHA256 of `<t>.<body>` under the endpoint secret named by the `kid` just before it. While a secret is being rotated the header carries one `kid`/`v1` pair per secret, newest first (`t=<unix>,kid=whk_new,v1=<hex>,kid=whk_old,v1=<hex>`): accept the delivery when any `v1` matches the secret you hold, and ignore parameters you do not know. Reject timestamps older than five minutes and compare in constant time. Any 2xx within 10 s acknowledges; anything else retries with backoff from 30 s up to 4 h for 72 h. Delivery is at least once, so deduplicate on the event id.

GET/v1/webhook-endpoints

Webhook endpoints

Test-mode endpoints are separate from live ones. A test key lists the test ones; a signed-in person adds livemode=false to see them.

Auth: Dashboard session · API key
Key scope: webhooks:manage

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.

Response 200 · object

Every endpoint of the account, without secrets.

Errors: 403

POST/v1/webhook-endpoints

Add a webhook endpoint

The URL must be public https without credentials; private, loopback and link-local addresses are refused when saved and again on every connection. An empty event_types subscribes to every type. The signing secret is returned only here. Owners, admins and developers may manage endpoints; at most 10 may be active.

Auth: Dashboard session · API key
Key scope: webhooks:manage

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.

Request body · WebhookEndpointInput

urlrequired
string (uri)
description
string
event_types
EventType[]
code
string
TOTP or passkey step-up code; required for signed-in people, ignored for API keys.

Response 201 · CreatedWebhookEndpoint

The endpoint with its secret.

secretrequired
string
whsec_..., shown once. Signs every delivery.

Errors: 400 · 403 · 409 · 422

PATCH/v1/webhook-endpoints/{id}

Change or disable an endpoint

Omitted fields are kept. A disabled endpoint receives nothing, and its pending deliveries fail.

Auth: Dashboard session · API key
Key scope: webhooks:manage

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.

Request body · WebhookEndpointPatch

url
string (uri)
description
string
event_types
EventType[]
status
"active" | "disabled"
code
string
Step-up code for people; not needed when the patch only disables the endpoint.

Response 200 · WebhookEndpoint

The endpoint.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for an endpoint of test mode, which receives only test events.
urlrequired
string (uri)
descriptionrequired
string
event_typesrequired
EventType[]
Empty means every type.
statusrequired
"active" | "disabled"
key_idrequired
string
Names the secret that signs deliveries; it is the kid in Ravelo-Signature.
previous_key_id
string | null
Set only while a rotation overlap lasts.
previous_secret_expires_at
ISODate | null
When the previous secret stops signing.
created_atrequired
ISODate
updated_atrequired
ISODate

Errors: 400 · 403 · 404 · 409 · 422

POST/v1/webhook-endpoints/{id}/rotate-secret

Rotate the signing secret

Issues a new secret, returned only here, with a new key_id. The previous secret keeps signing next to it for overlap_seconds (default 86400, at most 604800; 0 retires it at once), so every delivery in that time carries a signature for each and a receiver holding either one verifies. When the overlap ends the old secret stops signing on its own, or call end-rotation to end it early. Rotating again inside an overlap retires the older secret immediately. Signed-in people confirm with a step-up code; every rotation is audited.

Auth: Dashboard session · API key
Key scope: webhooks:manage

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.

Request body · WebhookSecretRotation

overlap_seconds
integer
How long the old secret keeps signing next to the new one.
code
string
TOTP or passkey step-up code; required for signed-in people, ignored for API keys.

Response 200 · CreatedWebhookEndpoint

The endpoint with its new secret.

secretrequired
string
whsec_..., shown once. Signs every delivery.

Errors: 400 · 403 · 404 · 422

POST/v1/webhook-endpoints/{id}/end-rotation

End a rotation overlap early

Stops the previous secret signing now. With no overlap in progress it changes nothing. Audited when it ends one.

Auth: Dashboard session · API key
Key scope: webhooks:manage

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.

Response 200 · WebhookEndpoint

The endpoint.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
livemoderequired
boolean
False for an endpoint of test mode, which receives only test events.
urlrequired
string (uri)
descriptionrequired
string
event_typesrequired
EventType[]
Empty means every type.
statusrequired
"active" | "disabled"
key_idrequired
string
Names the secret that signs deliveries; it is the kid in Ravelo-Signature.
previous_key_id
string | null
Set only while a rotation overlap lasts.
previous_secret_expires_at
ISODate | null
When the previous secret stops signing.
created_atrequired
ISODate
updated_atrequired
ISODate

Errors: 403 · 404

POST/v1/webhook-endpoints/{id}/test

Send a test event

Emits a webhook.test event delivered to this endpoint only.

Auth: Dashboard session · API key
Key scope: webhooks:manage

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.

Response 202 · Event

The test event, queued for delivery.

idrequired
ID
Resource identifier. UUIDv7 for user-owned rows; catalogue ids are slugs like usdt-tron.
typerequired
EventType
livemoderequired
boolean
False for events of test mode. A test event is only ever delivered to a test-mode endpoint, a live event only to a live one; the same flag is in data.
created_atrequired
ISODate
datarequired
object
A snapshot of the subject when the event happened (payment intent, payout or refund).

Errors: 404 · 409

GET/v1/webhook-endpoints/{id}/deliveries

Deliveries to an endpoint, newest first

The newest 50 unless limit says otherwise. When older deliveries remain, the X-Next-Cursor response header holds an opaque cursor: send it back as cursor for the next page. The header is absent on the last page.

Auth: Dashboard session · API key
Key scope: webhooks:manage

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.
limitqueryinteger
Page size, 1-100 (default 50).
cursorquerystring
The X-Next-Cursor of the previous page.

Response 200 · object

Newest first.

Errors: 400 · 404

POST/v1/events/{id}/replay

Deliver an event again

Queues the event again for every active endpoint subscribed to its type, including ones that already received it.

Auth: Dashboard session · API key
Key scope: webhooks:manage

Parameters

idpathrequiredID
X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
Idempotency-Keyheaderrequiredstring
Client-generated unique key (UUID recommended) that makes the POST safe to retry.
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.

Response 202 · object

How many deliveries were queued.

deliveriesrequired
integer

Errors: 404

GET/v1/events

Account event stream by cursor

The same events webhooks deliver, oldest first, for clients that poll. Keep next_cursor and pass it back to receive only newer events; it is returned even when the page is empty, so a caught-up client keeps polling with it. Events appear once every transaction that started before them has finished, so a late commit is never skipped. API keys without balances:read do not see payout.* events.

Auth: Dashboard session · API key
Key scope: payments:read

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
cursorquerystring
Opaque cursor from a previous page's next_cursor.
limitqueryinteger
Page size.
livemodequeryboolean
false makes a signed-in person act on the linked test-mode account. A key acts in the mode of its prefix; a live key sending false, or a test key sending true, gets invalid_mode.
typequeryEventType
Only events of this type.
orderquery"asc" | "desc"
desc walks from the newest event back, for browsing a log. Pollers keep the default: a late commit can land above a page already read newest first.

Response 200 · EventPage

Oldest first from the cursor, or newest first with `order=desc`.

itemsrequired
Event[]
next_cursorrequired
string | null

Errors: 400 · 401 · 429

statements

GET/v1/statements

Statement of the available balance

Opening balance, credits, debits and closing balance per asset over [from, to) in UTC days, at most 366 days. Funds count once they clear and leave when a payout or refund reserves them.

Auth: Dashboard session · API key
Key scope: balances:read

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
fromqueryrequiredstring (date)
toqueryrequiredstring (date)

Response 200 · Statement

The statement.

fromrequired
string (date)
torequired
string (date)
Exclusive.
assetsrequired
object[]

Errors: 400

GET/v1/statements/export

Export statement of the available balance as CSV

Streams per-asset summaries and available-balance movements over [from, to) (RFC 3339 timestamps or YYYY-MM-DD dates, at most 366 days) as a spreadsheet-safe CSV attachment and records statement.exported in the audit log.

Auth: Dashboard session · API key
Key scope: balances:read

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
fromqueryrequiredstring
toqueryrequiredstring

Response 200

Spreadsheet-safe CSV attachment.

Errors: 400 · 401 · 429 · 500

portfolio

GET/v1/portfolio/history

Valuation history of the account in USD cents

Hourly snapshots taken after each price snapshot, down-sampled per range (hourly for 24h/7d, 4-hourly for 30d, daily for 90d/1y). A new account has no points until the next hourly run. With symbol, the value of that coin summed across its chains (per-asset snapshots) instead of the whole portfolio; the shape is the same.

Auth: Dashboard session · API key

Parameters

X-Test-Modeheaderboolean
When true, a cookie-session request acts on the linked sandbox account (503 test_mode_unavailable when sandbox is disabled). Live API keys cannot switch modes (400 invalid_mode).
rangequeryHistoryRange
symbolquerystring
Ticker such as USDT (aliases like TON for GRAM, formerly Toncoin, accepted). Omit for the whole portfolio.

Response 200 · PortfolioHistory

Oldest first.

rangerequired
HistoryRange
pointsrequired
PortfolioPoint[]

Errors: 400 · 401 · 429 · 500