Introduction
Rook is a cross-border payout platform for banks and fintechs. It lets you pay beneficiaries in markets where you have no licence, presence, or correspondent bank, through one REST API. Rook finds the best path across licensed local partners, returns one all-in rate, and coordinates every step of the payment. Value moves between partners in USD₮, so a payout settles in minutes instead of days.
Key benefits
- One integration, many corridors. Each new market Rook opens is available to you without new contracts or code.
- Best path on every payment. Rook prices every available route in parallel, direct or through USD₮, and picks the best amount for you.
- No custody. Rook never holds your funds or wallet keys. Your client pays a licensed partner directly and the beneficiary is paid by a licensed partner directly.
- One rate. You get a single
clientRate with Rook's fee inside it. Providers, base rates and markups never appear in the public API.
- Full audit trail. Every order keeps a timeline of each status change, when it happened and what triggered it.
How Rook works
A payment in Rook is a corridor: a chain of one or two legs, each served by a licensed partner.
- One leg. A single partner converts and pays out, for example USD₮ to COP.
- Two legs. An origin partner converts your fiat to USD₮ and sends it on-chain to a destination partner, which pays the beneficiary in local currency. For example USD to USD₮ in the United States, then USD₮ to MXN over SPEI.
When you ask for a quote, Rook builds every corridor that can serve the pair, prices all of them at once, and keeps the one that gives the beneficiary the most (or costs you the least, if you fix the amount received). If one partner is slow or down, that corridor is dropped and the others still answer.
Architecture
| Component | What it does for you |
| Public API | The REST API you integrate with: authentication, beneficiaries, quotes, orders and notifications. |
| Routing engine | Builds and prices corridors, applies the rate you see, and records each quote. |
| Order engine | Turns a quote into an order, instructs each partner leg by leg, and moves the order through its states. |
| Partner connectors | Talk to each licensed partner in its own protocol (REST, FIX, webhooks) and translate its statuses into Rook's. |
| Event receiver | Receives signed partner events, discards duplicates, and feeds them to the order engine. |
Security
- All traffic is HTTPS only. Every request carries a signed bearer token that expires after 24 hours.
- Each request is scoped to one organization, and you can only reach organizations you are a member of.
- Partner credentials are encrypted at rest with AES-256-GCM. Partner events are accepted only with a valid signature.
Compliance
Every institution passes KYB with Rook before going live, and Rook uses it for every provider your corridors need, so you send each document once. Each of your end clients, the sender of the payment, also passes KYB before its first payment; beneficiaries do not. Every order carries the sender and beneficiary details each corridor requires. See Onboarding for the full list.
Onboarding
Before your institution can send payments through Rook, it goes through a one-time onboarding with Rook and the payment providers that run each corridor. Rook coordinates the whole process: you send each document once, and Rook uses it for every provider.
After your institution is approved, each of your end clients goes through its own KYB before its first payment.
You keep the relationship with your clients. Rook provides the technology infrastructure.
Overview
| Step | What it is | When | Approved by |
| 1. Institution KYB | Corporate documents, policies and identity of directors and UBOs | 1 working day after onboarding starts | Rook |
| 2. Provider pack | Pre-filled forms and supporting documents for the payment providers | Before go-live | Payment providers, through Rook |
| 3. End-client KYB | KYB of each of your clients | Before that client's first payment | Payment provider, in 2 to 3 working days |
| 4. Payment data | Sender and beneficiary details on every order | On every order | Validated automatically |
Step 1: Institution KYB
Send these documents on the working day after onboarding starts. If a document has a different name in your country, its local equivalent is accepted.
- Certificate of incorporation: or equivalent.
- Register of shareholders: or equivalent. If a shareholder is a company, add an ownership chart signed by an authorized person.
- Register of directors: or equivalent.
- Compliance policies: your AML/CFT policy and any other compliance policies in force.
- Licenses: every regulatory or business license your institution holds.
- Directors and UBOs: full legal name, residential address and ID check (passport or national ID) for each one, through the KYB link Rook sends you.
Step 2: Provider pack
Two working days after onboarding starts, Rook sends you a set of forms already pre-filled with your Step 1 information. Complete, sign and return them before the agreed submission date.
- Due diligence form: complete it and sign it with the company seal.
- AML questionnaire: complete it, sign it with the company seal and attach every policy it cites.
- Sanctions certification letter: signed by a director.
- Provider service agreement: signed electronically. The provider's bank requires it. It is not a commercial agreement.
- Onboarding questionnaire: add your money services details and the details of each director and UBO.
Documents your institution provides
- Board resolution: approval to start a payment services relationship with the providers.
- Proof of business address: a document that shows your institution's address.
- Proof of residential address: for each director and UBO.
- Bank statements: last 3 months. Required if your institution provides money services or is less than 1 year old.
- Verification selfie: for each UBO, through the provider's portal. Required only if your institution or the UBO is in one of the countries below.
Countries that require a verification selfieBahamas, Bolivia, China, Colombia, Costa Rica, Dominican Republic, Ecuador, Fiji, Guatemala, Honduras, Hong Kong, India, Jamaica, Monaco, Nigeria, Panama, Peru, Philippines, Saudi Arabia, Trinidad and Tobago, Turkey and Vietnam. Mexico is not on the list.
Step 3: End-client KYB
Before the first payment for each of your clients, send that client's KYB to Rook. The provider approves it within 2 to 3 working days. The end client is the sender of the payment. The beneficiary does not need KYB.
Business end client
- Company details: legal name, registration number, address and business activity.
- Corporate documents: certificate of incorporation and registers of shareholders and directors.
- Proof of business address and onboarding questionnaire: same as in Step 2.
- AML/CFT policy: only if the client provides money services.
- Directors and UBOs: name, date of birth, ID and proof of residential address for each one. Bank statements and selfies follow the same conditions as in Step 2.
Individual end client
- Identity: full name, date of birth, nationality and government ID.
- Contact and address: residential address with proof of address, email and phone.
- Tax ID: RFC, NIT or the local equivalent.
Step 4: Payment data
Every order carries the sender and beneficiary details that the provider requires for that corridor (Travel Rule). Rook shares the exact list of fields for each corridor before your first payment.
- Account in the end client's name: requires that client's KYB to be approved (Step 3).
- Payment in the provider's name: in some corridors the payment is sent in the provider's name, not the end client's. Rook tells you which ones when your corridors are set up.
Before you start
The payment providers in Rook's network do not serve certain industries and jurisdictions. Review these points with your compliance team before sending documents.
- Allowed use: B2B payments for the purchase of goods and remittance payments, with no high-risk activity.
- Excluded industries: include weapons and defense, gambling, cannabis, adult content, crypto mixers, consumer lending, real estate, political bodies and non-profits. Rook shares the full list on request.
- Excluded jurisdictions: businesses, UBOs and individuals from, among others, Venezuela, Cuba, Nicaragua, El Salvador, Russia, Iran and North Korea are not accepted. Rook shares the full list on request.
First steps
While compliance onboarding runs, your engineers integrate against the sandbox.
- Get sandbox access. Create your user with
POST /v1/auth/sign-up/email on https://api.sandbox.rooklabs.co, using your work email, and send that email to your Rook contact. Rook creates your organization and adds you to it. Each colleague signs up the same way and Rook adds them too.
- Generate your client. Download
/openapi.json and generate a typed client in your language with any OpenAPI generator (for example openapi-generator, oapi-codegen or openapi-typescript). Every endpoint, field and error in these docs is in that file.
- Sign in and keep your token. Call
POST /v1/auth/sign-in/email, keep the token, and send it as Authorization: Bearer on every request. It lasts 24 hours. There are no keys to register. See Authentication.
- Run the sandbox checklist. Work through the checklist below against the sandbox. Its partners are simulated, so no real money moves. Send your Rook contact the order ids when you are done.
- Sandbox testing session. We'll then arrange a session to run transactions end to end exactly as they will in production, including prefunding with real USD₮.
Sandbox checklist
Each case lists the call and what you should see. In the sandbox, Rook confirms your test funding for you, so orders move past AWAITING_FIAT without a real transfer.
| Case | Call | Expected |
| Sign in | POST /v1/auth/sign-in/email, then GET /v1/organizations | A token, and your organization in the list. |
| Register a beneficiary | POST /v1/beneficiaries (a Mexican CLABE) | 201 with an id. |
| Quote by amount sent | POST /v1/rates/quote with side: SEND | 200 with quoteId and expiresAt 60 s ahead. |
| Quote by amount received | POST /v1/rates/quote with side: RECEIVE | receiveAmount equals the amount you sent. |
| Reject bad amounts | Quote with 7 decimals, then with an amount outside the corridor limits | INVALID_AMOUNT, then AMOUNT_OUT_OF_BOUNDS. |
| Reject an unknown pair | Quote a pair Rook does not route | ROUTE_NOT_SUPPORTED. |
| Create an order | POST /v1/orders | 201, AWAITING_FIAT and paymentInstructions. |
| Retry the same order | POST /v1/orders again with the same quoteId | QUOTE_ALREADY_USED, and still only one order in GET /v1/orders. |
| Use an expired quote | Wait more than 60 s, then POST /v1/orders | QUOTE_EXPIRED. |
| Follow to paid out | Receive order.status_changed webhooks, or poll GET /v1/orders/:id, after Rook confirms funding | PAID_OUT and a full timeline. |
| Let an order expire | Create an order and do not fund it for 15 minutes | EXPIRED. |
Going live
After the testing session Rook enables your organization in production, shares the production base URL, and turns on the corridors you agreed. Your code does not change between environments; only the base URL and your credentials do.
Quote management
A quote is Rook's price for sending a given amount from one currency to another. You ask for one with POST /v1/rates/quote; Rook prices every corridor that serves the pair and returns the best one.
SEND and RECEIVE
| side | You fix | Rook optimizes | Rounding |
SEND (default) | What you pay (sendAmount) | Maximizes what the beneficiary receives | receiveAmount rounded down |
RECEIVE | What the beneficiary gets (receiveAmount) | Minimizes what you pay | sendAmount rounded up |
Fiat amounts round to 2 decimals and USD₮ to 6. When two corridors give the same amount, Rook prefers the one with fewer legs.
Anatomy of a quote
| Field | Meaning |
quoteId | The id you confirm into an order. |
sendAmount / receiveAmount | What you pay and what the beneficiary gets, as decimal strings. |
clientRate | Units of to per one unit of from, all fees included. For display; the amounts are what count. |
expiresAt | When the quote can no longer be confirmed. 60 seconds after it is issued. |
indicative | Always true. See below. |
legs | How many partners the payment crosses: 1 or 2. |
Indicative vs executed rate
Every quote is indicative. It reflects partner prices at the moment you asked, and it is what you show your client. When the order executes, each partner's actual rate is recorded on the order next to the quoted one. Any difference between the two is borne by you. Keep the time between quote and funding short to keep that difference small.
Amount limits
Each corridor has a minimum and maximum amount, checked in the currency of each leg. If no corridor can take your amount, the quote fails with AMOUNT_OUT_OF_BOUNDS. amount accepts at most 6 decimals, and no more than the currency allows (2 for most fiat); anything else fails with INVALID_AMOUNT.
Integration checklist
- Send amounts as strings, never as numbers.
- Pass
toCountry for currencies used in more than one country (USD, EUR). For EUR, any SEPA country (DE, FR, ES, IT, NL…) routes to SEPA payouts.
- Re-quote rather than reuse a quote close to
expiresAt.
- Treat
NO_LIQUIDITY_AVAILABLE as temporary and retry after a few seconds.
Order flow
An order is a confirmed quote assigned to a beneficiary. End to end, a payout takes three calls from you, one payment from your client, and a status you follow to the end.
Step by step
- Register the beneficiary with
POST /v1/beneficiaries. Once per recipient. Rook registers the account with every destination partner in that country.
- Get a quote with
POST /v1/rates/quote. Free of side effects; quote as often as you like.
- Create the order with
POST /v1/orders, passing the quoteId and beneficiaryId. The order starts in AWAITING_FIAT and carries paymentInstructions.
- Your client pays the exact
amount to the instructions, with the reference when there is one, before paymentInstructions.expiresAt (15 minutes). The money goes to the origin partner, not to Rook.
- Follow the order with
GET /v1/orders/:id until it reaches PAID_OUT or a failure state.
What Rook does in between
Once the origin partner confirms the funds, Rook executes each leg in order: the origin partner converts to USD₮ and delivers it on-chain to the destination partner, which pays the beneficiary over the local rail. Each partner event moves the order forward and is added to its timeline. In a one-leg corridor the same partner converts and pays out, so the order can go straight from FIAT_RECEIVED to PAID_OUT.
Example
POST /v1/orders
{ "quoteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"beneficiaryId": "84ecbd88-c083-49d6-a780-ef7da4b15e64" }
201 Created
{ "orderId": "b7a1c2e4-1f0d-4e55-9a7b-6a2e9c1d0f33",
"status": "AWAITING_FIAT",
"from": "USD", "to": "MXN",
"sendAmount": "1000.00", "receiveAmount": "18412.37", "clientRate": "18.41237",
"paymentInstructions": {
"bankName": "Example Bank N.A.", "accountNumber": "210987654321",
"routingNumber": "101019644", "holder": "Your organization (virtual account)",
"reference": "ROOK-B7A1C2E4", "amount": "1000.00", "currency": "USD",
"expiresAt": "2026-10-22T14:19:40.000Z" } }
NotePayment instructions come in two shapes. Fiat funding returns bank fields (bankName, accountNumber, and clabe, iban, routingNumber or swiftCode as the rail needs). USD₮ funding returns chain (for example POLYGON) and chainAddress, the partner's deposit address. An order funded in USD₮ always carries both; if the partner cannot supply an address, POST /v1/orders fails with COLLECTION_UNAVAILABLE instead of creating the order.
Order states
Every order moves through a fixed set of states. Rook rejects any transition outside the ones below, so the status you read is always one of these.
Happy path
CONFIRMED → AWAITING_FIAT → FIAT_RECEIVED → USDT_SENT → USDT_RECEIVED → PAID_OUT
All states
| State | Meaning | Can move to |
| CONFIRMED | Quote accepted into an order. | AWAITING_FIAT, CANCELLED |
| AWAITING_FIAT | Waiting for your client's payment. | FIAT_RECEIVED, EXPIRED, CANCELLED |
| FIAT_RECEIVED | The origin partner has the funds. | USDT_SENT, PAID_OUT, CANCELLED, EXCEPTION |
| USDT_SENT | USD₮ sent on-chain to the destination partner. | USDT_RECEIVED, PAID_OUT, EXCEPTION |
| USDT_RECEIVED | The destination partner has the USD₮. | PAID_OUT, PAYOUT_FAILED, EXCEPTION |
| PAID_OUT | The beneficiary was paid. | RETURNED |
| PAYOUT_FAILED | The local rail rejected the payout. | REFUNDED, EXCEPTION |
| EXCEPTION | Needs Rook operations to resolve. | PAID_OUT, CANCELLED |
| CANCELLED | Stopped before payout. | REFUNDED |
| EXPIRED | No funds arrived in time. | Final |
| REFUNDED | Funds returned to the payer. | Final |
| RETURNED | The beneficiary's bank sent a completed payout back. | Final |
Watch forPAID_OUT is not always the last word. A beneficiary bank can return a payout days later, which moves the order to RETURNED. Keep reconciling paid orders.
Timeline
GET /v1/orders/:id returns a timeline: one entry per transition with previousStatus, newStatus, createdAt and source. source is API (your call), WEBHOOK (a partner event), WORKER (Rook's own processing) or ADMIN (Rook operations).
Beneficiaries
A beneficiary is a bank account you pay to. You register it once and reuse its id on every order to that recipient. Beneficiaries belong to your organization and are never visible to other Rook clients.
Registration with partners
When you create or change a beneficiary, Rook registers it in the background with every active destination partner that serves its country. GET /v1/beneficiaries/:id shows the registration status with each partner: ACTIVE, PENDING or REJECTED. Changing bank details registers the account again.
Bank details by country
| Country | accountNumber | Other fields |
| Mexico (MXN) | 18-digit CLABE | extraDetails.rfc |
| Colombia (COP) | Bank account number | accountType, extraDetails.identificationType and identificationNumber (NIT, CC) |
| United States (USD) | Account number | routingNumber (ABA), swiftCode for wires, address in extraDetails |
| Eurozone (EUR) | IBAN | swiftCode (BIC), tax id in extraDetails |
If you omit currency, Rook uses the country's currency. accountType is checking (default) or savings. An order whose beneficiary does not match the quote's destination currency or country fails with INVALID_BENEFICIARY_DESTINATION.
How funds move
Rook orchestrates payments but never sits in the money flow. There is no Rook balance to top up and no Rook account that holds client money.
The three money legs
- Funding. Your client pays the origin partner in fiat (or sends USD₮), using the instructions on the order.
- Settlement between partners. The origin partner converts to USD₮ and transfers it on-chain, wallet to wallet, to the destination partner.
- Payout. The destination partner pays the beneficiary on the local rail, under its own licence.
Your accounts with partners
Where a partner needs an account in your name (for example a US virtual account that receives your USD, and the wallets it settles from), Rook opens it during onboarding from your KYB. Those accounts belong to your organization at the partner; Rook only instructs them.
Funding in USD₮
Send USD₮ from a wallet you control to paymentInstructions.chainAddress on the order, on the network in paymentInstructions.chain (for example POLYGON). USD₮ sent on any other network is lost. Send the exact amount before expiresAt. Some partners give one order its own address and others use a fixed deposit address that serves many orders, so always read the address from the order and never reuse one from an earlier payment.
Supported corridors
These are the markets Rook routes today. Which ones are open for you depends on your onboarding; a pair that is not open returns ROUTE_NOT_SUPPORTED.
Payout destinations
| Country | Currency | Rails |
| Mexico | MXN | SPEI |
| Colombia | COP | ACH |
| United States | USD | ACH, Wire, RTP |
| Eurozone | EUR | SEPA |
| Ecuador | USD | Local ACH |
| Venezuela | VES | Local bank transfer |
Funding sources
| Source | How you fund |
| USD | ACH to your US virtual account |
| MXN | SPEI |
| USD₮ | On-chain transfer to the order's address |
Ask your Rook contact to open a corridor that is not listed.
Supported chains
Value moves between partners in USD₮ on these chains. The corridor decides the chain for each order, and the order's payment instructions name it when you fund in USD₮.
- Ethereum
- Polygon
- Solana
- Tron
Watch forUSD₮ sent on a different chain than the one on the order does not reach the partner. Always match chain.
Pricing and fees
Rook's fee is a markup on the destination, expressed in basis points and already inside the clientRate and amounts you are quoted. There is no separate fee line, no invoice per payment, and no deduction in flight.
- The markup depends on the destination currency and, where it applies, the destination country. Your agreement can set a specific markup for your organization.
- Rook picks the best corridor using partner prices before its markup, so the markup never changes which path your payment takes.
- Partner fees are part of the corridor price and are also inside the amounts you see.
- Rook settles its own revenue with its partners once a day. It never touches your payment to collect it.
To earn on your side, add your own margin on top of Rook's quote when you show it to your client.
Integration guidance
You integrate with Rook through a REST API that speaks JSON over HTTPS. All endpoints are versioned under /v1.
Environments
| Environment | Base URL |
| Sandbox | https://api.sandbox.rooklabs.co/v1 |
| Production | Shared with you at go-live |
OpenAPI and generated clients
The complete OpenAPI 3 description is at /openapi.json. Generate a typed client in Go, TypeScript, Python, Java or C# with any OpenAPI generator. Interactive references: /docs and /redoc.
Conventions
- Money and rates are decimal strings (
"1000.00"), never JSON numbers. Parse them with a decimal library.
- Ids are UUID v4. Timestamps are ISO 8601 in UTC.
- Currencies are ISO 4217 codes (plus
USDT); countries are ISO 3166-1 alpha-2.
- Unknown fields in a request body are rejected with
400.
What you build
- A token manager that signs in and refreshes before the 24-hour expiry.
- Beneficiary sync from your system to Rook.
- Quote and order creation, showing your client the payment instructions.
- A status follower that receives webhooks (or polls open orders) and updates your ledger.
For a narrative walkthrough of a payout, see the technical overview.
Authentication
Rook uses bearer tokens. Sign in with the credentials of your API user to get a token, then send it on every request.
POST /v1/auth/sign-in/email
{ "email": "api@yourbank.com", "password": "••••••••" }
200 OK
{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": { "id": "…", "email": "api@yourbank.com", "name": "API user" } }
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
- Tokens are valid for 24 hours. Sign in again before they expire; an expired token returns
401.
- Use a dedicated API user per integration, not a person's account.
GET /v1/auth/session returns the user behind the current token.
Organizations
Everything in Rook belongs to an organization: beneficiaries, quotes and orders. Your user can be a member of more than one, for example separate legal entities or business lines.
GET /v1/organizations lists the organizations your user belongs to.
- Send
x-organization-id: <uuid> to say which organization a call is for. If your user belongs to a single organization you can omit it.
- Asking for an organization you are not a member of returns
403. Rook never assigns an organization to you on its own.
x-organization-id: 51e0dbd1-5e9f-4a84-ad83-e747e60f269c
Idempotency and retries
Connections drop and requests time out. Rook's API is designed so that retrying is safe when you follow these rules.
By call
| Call | Retry safety |
POST /v1/rates/quote | Safe. No side effects; each call returns a new quote. |
POST /v1/orders | Safe. A quote turns into exactly one order. A retry with the same quoteId returns QUOTE_ALREADY_USED instead of creating a second order; find the first with GET /v1/orders. |
POST /v1/beneficiaries | Not idempotent. Before retrying, list beneficiaries and check whether the first call created it. |
GET calls | Always safe. |
Backoff
Retry 429, 502, 503 and network errors with exponential backoff (for example 1 s, 2 s, 4 s, capped at 30 s). Do not retry other 4xx responses unchanged; they will fail the same way.
On Rook's side
Rook applies the same discipline toward partners: each leg is executed under its own idempotency key and never sent twice, and duplicate partner events are recorded once and ignored after that.
Errors
Errors use standard HTTP status codes and one JSON shape. Branch on code when present; message is for humans and may change.
{ "statusCode": 400,
"error": "Bad Request",
"message": "Amount is outside the corridor limits",
"code": "AMOUNT_OUT_OF_BOUNDS",
"timestamp": "2026-10-22T14:03:11.000Z",
"path": "/v1/rates/quote" }
Error codes
| code | Status | What to do |
ROUTE_NOT_SUPPORTED | 422 | No corridor for this pair or country. Ask Rook to open it. |
NO_LIQUIDITY_AVAILABLE | 422 | Corridors exist but none priced. Retry in a few seconds. |
AMOUNT_OUT_OF_BOUNDS | 400 | Outside corridor limits. Resize or split the payment. |
INVALID_AMOUNT | 400 | Too many decimals for the currency. |
QUOTE_EXPIRED | 422 | Request a new quote. |
QUOTE_ALREADY_USED | 422 | The quote already became an order. Find it with GET /v1/orders. |
INVALID_BENEFICIARY_DESTINATION | 400 | The beneficiary's currency or country does not match the quote. |
COLLECTION_UNAVAILABLE | 503 | The partner could not supply a USD₮ deposit address. No order was created and the quote is still usable: retry POST /v1/orders, or request a new quote. |
ORDER_NOT_FOUND | 404 | No such order in your organization. |
Status codes
| Status | Meaning |
| 400 | Validation failed. message lists each problem. |
| 401 | Missing or expired token. |
| 403 | Not a member of the organization, or the resource belongs to another organization. |
| 404 | Not found in your organization. |
| 422 | Valid request that cannot be fulfilled now (see codes above). |
| 429 | Too many requests. Back off and retry. |
| 5xx | Rook-side problem. Retry with backoff and contact Rook with the x-request-id. |
Rate limits and tracing
Rate limits
The API accepts up to 1,000 requests per minute per client. Above that it returns 429. Orders move in minutes, so polling each open order every 15 to 30 seconds is plenty.
Request ids
Every response carries an x-request-id header. Send your own x-request-id and Rook uses it, so the same id appears in your logs and Rook's. Include it whenever you contact Rook about a call.
Webhooks
Instead of polling every open order, register one HTTPS endpoint and Rook POSTs an order.status_changed event each time one of your orders changes state. Polling GET /v1/orders/:id keeps working; use it to reconcile.
Set up your endpoint
PUT /v1/webhooks/endpoint with your url. The response carries the signing secret (whsec_…) once: store it, Rook never shows it again.
POST /v1/webhooks/test sends a signed webhook.test event right away and returns what your server answered.
- Follow deliveries with
GET /v1/webhooks/deliveries and send one again with POST /v1/webhooks/deliveries/:id/resend.
The URL must be https and resolve to a public address; private, loopback and link-local addresses are rejected. To rotate the secret, call PUT again with "regenerateSecret": true: the old one stops working at once.
The event
POST /your/webhook/path
content-type: application/json
rook-event-id: 0b6f3c3e-2f7d-4a51-9a63-3f0d1c9b2a10
rook-event-type: order.status_changed
rook-signature: t=1792500000,v1=5f1c…
{ "eventId": "0b6f3c3e-2f7d-4a51-9a63-3f0d1c9b2a10",
"type": "order.status_changed",
"occurredAt": "2026-10-27T15:04:05.000Z",
"data": {
"orderId": "8d2f6a90-1c3b-4e5f-a7d8-9b0c1d2e3f40",
"previousStatus": "AWAITING_FIAT",
"status": "FIAT_RECEIVED",
"from": "USDT", "to": "COP",
"sendAmount": "1000", "receiveAmount": "3998500",
"paymentInstructions": { "chain": "TRON", "chainAddress": "T…", "reference": "ROOK-8D2F6A90",
"amount": "1000", "currency": "USDT", "expiresAt": "2026-10-27T15:19:40.000Z" } } }
failureReason is added when the new status is EXPIRED, CANCELLED, EXCEPTION, PAYOUT_FAILED, RETURNED or REFUNDED. Every transition produces one event, including CONFIRMED and AWAITING_FIAT when the order is created.
Verify the signature
rook-signature is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "{t}.{raw body}" keyed with your whole secret. Verify against the raw bytes you received, before parsing the JSON, and reject timestamps older than five minutes.
// Node.js (Express): app.post('/rook/webhooks', express.raw({ type: 'application/json' }), handler)
const crypto = require('crypto');
function verifyRookSignature(secret, rawBody, header, toleranceSeconds = 300) {
const parts = Object.fromEntries(
String(header || '').split(',').map((p) => p.trim().split('=')),
);
const t = Number(parts.t);
if (!Number.isInteger(t) || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(t + '.' + rawBody)
.digest('hex');
const a = Buffer.from(expected, 'hex');
const b = Buffer.from(parts.v1, 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
function handler(req, res) {
const raw = req.body.toString('utf8');
if (!verifyRookSignature(process.env.ROOK_WEBHOOK_SECRET, raw, req.get('rook-signature'))) {
return res.status(400).end();
}
const event = JSON.parse(raw);
// Deduplicate on event.eventId, then update your ledger.
res.status(204).end();
}
# Python
import hashlib, hmac, time
def verify_rook_signature(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
parts = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
Delivery and retries
- Answer with any
2xx within 10 seconds. Anything else, a timeout or a connection error is retried with exponential backoff (1, 2, 4, 8 … minutes, capped at 4 hours) for up to 24 hours, then the delivery is marked FAILED.
- Delivery is at least once and events can arrive out of order. Deduplicate on
eventId (also in the rook-event-id header; a resend keeps it) and order by occurredAt, or read GET /v1/orders/:id when in doubt.
- Rook does not follow redirects. Acknowledge fast and do the work asynchronously.
Auth
POST/v1/auth/sign-in/email
Exchange email and password for a bearer token valid for 24 hours.
| Field | Type | Notes |
email | string | Required. |
password | string | Required. |
Returns { token, user }.
GET/v1/auth/session
The user profile and roles behind the current token.
Organizations
GET/v1/organizations
Lists the organizations the authenticated user belongs to. Use an id from here as x-organization-id.
Beneficiaries
POST/v1/beneficiaries
Register a recipient bank account. Returns 201 with the beneficiary.
| Field | Type | Notes |
name | string | Required. Account holder. |
countryId | string | Required. ISO alpha-2. |
bankName | string | Required. |
accountNumber | string | Required. CLABE, IBAN or account number by country. |
currency | string | Optional. Defaults to the country's currency. |
accountType | string | checking (default) or savings. |
routingNumber | string | US ABA routing number. |
swiftCode | string | SWIFT/BIC. |
extraDetails | object | Country-specific fields such as tax ids and address. |
{ "currency": "COP", "name": "Textiles Medellín S.A.S.", "countryId": "CO",
"bankName": "Bancolombia", "accountNumber": "9007712345", "accountType": "savings",
"extraDetails": { "identificationType": "NIT", "identificationNumber": "900123456-1" } }
GET/v1/beneficiaries
Lists your organization's beneficiaries.
GET/v1/beneficiaries/:id
One beneficiary with its registration status at each partner.
PATCH/v1/beneficiaries/:id
Update any of the fields above. Changing bank details registers the account with partners again.
DELETE/v1/beneficiaries/:id
Remove a beneficiary.
Quotes
POST/v1/rates/quote
Price a payment across every available corridor and return the best one.
| Field | Type | Notes |
from | string | Required. Currency you pay, e.g. USD, MXN, USDT. |
to | string | Required. Currency the beneficiary receives. |
amount | decimal string | Required. At most 6 decimals and no more than the currency allows. |
side | string | SEND (default) or RECEIVE. |
toCountry | string | ISO alpha-2 of the beneficiary's country. Recommended for USD and EUR; for EUR, any SEPA country (DE, FR, ES, IT, NL…). |
200 OK
{ "quoteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"from": "USD", "to": "MXN", "side": "SEND",
"sendAmount": "1000.00", "receiveAmount": "18412.37", "clientRate": "18.41237",
"expiresAt": "2026-10-22T14:05:12.000Z", "indicative": true, "legs": 2 }
Errors: ROUTE_NOT_SUPPORTED, NO_LIQUIDITY_AVAILABLE, AMOUNT_OUT_OF_BOUNDS, INVALID_AMOUNT.
Orders
POST/v1/orders
Confirm a quote into an order for a beneficiary. Returns 201 with the order in AWAITING_FIAT and its paymentInstructions.
| Field | Type | Notes |
quoteId | uuid | Required. Unexpired and unused, from your organization. |
beneficiaryId | uuid | Required. From your organization, matching the quote's destination. |
Errors: QUOTE_EXPIRED, QUOTE_ALREADY_USED (422); INVALID_BENEFICIARY_DESTINATION (400); COLLECTION_UNAVAILABLE (503) when a USD₮-funded order gets no deposit address; 404 if the quote or beneficiary does not exist; 403 if it belongs to another organization.
GET/v1/orders
Lists your organization's orders. Filters: status, fromCurrency, toCurrency.
GET/v1/orders/:id
The order with its current status, payment instructions and timeline.
Order object
| Field | Notes |
orderId | uuid |
status | See Order states. |
from, to | Currencies. |
sendAmount, receiveAmount, clientRate | As quoted. |
paymentInstructions | Bank or chain instructions, reference, amount, currency, expiresAt. |
timeline | On GET /v1/orders/:id only. |
createdAt, updatedAt | ISO 8601. |
Notifications
A feed of events for the authenticated user, such as order status changes.
GET/v1/notifications
Lists notifications, newest first.
POST/v1/notifications/:id/read
Marks one as read.
DELETE/v1/notifications/:id
Dismisses one.
Webhooks
Your organization's endpoint for order.status_changed events. See Webhooks for the event and its signature.
PUT/v1/webhooks/endpoint
Creates or updates the endpoint. Returns it with secret only when it is created or regenerated.
| Field | Type | Notes |
url | string | Required. https, public address, up to 2,048 characters. |
enabled | boolean | Optional. false pauses deliveries; events are not queued while paused. |
regenerateSecret | boolean | Optional. Issues a new secret and invalidates the old one. |
Errors: INVALID_WEBHOOK_URL (400).
GET/v1/webhooks/endpoint
{ "endpoint": { id, url, enabled, createdAt, updatedAt } }, or { "endpoint": null }. Never includes the secret.
POST/v1/webhooks/test
Sends a webhook.test event now and returns the delivery. 404 without an endpoint; WEBHOOK_ENDPOINT_DISABLED (400) if it is paused.
GET/v1/webhooks/deliveries
Delivery log, newest first. Filters: status (PENDING, DELIVERED, FAILED), orderId, page, limit. Each delivery has id, eventId, eventType, orderId, status, attempts, lastStatusCode, lastError, nextAttemptAt, deliveredAt, createdAt and the payload sent.
POST/v1/webhooks/deliveries/:id/resend
Sends that delivery's event again, with the same eventId, as a new delivery, and returns it.
Data types
| Type | Format | Example |
| Decimal | String, dot separator, no thousands separator | "18412.37" |
| Id | UUID v4 | "3fa85f64-5717-4562-b3fc-2c963f66afa6" |
| Timestamp | ISO 8601, UTC | "2026-10-22T14:05:12.000Z" |
| Currency | ISO 4217, plus USDT | "MXN" |
| Country | ISO 3166-1 alpha-2 | "CO" |
| Side | Enum | "SEND", "RECEIVE" |
| Chain | Enum | "ETHEREUM", "POLYGON", "SOLANA", "TRON" |