Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.relayer.fi/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through a complete off-ramp payout: onboarding a recipient, setting up their virtual account, getting a quote, and executing a payment that settles to their bank.

​
Prerequisites

  • A Relayer API key (see Authentication)
  • Your workspace activated with the Payout module enabled
  • KYB completed for your workspace (handled through the Relayer dashboard — one-time setup)
export RELAYER_API_KEY="rk_client_key_v1_your_key_here"
export RELAYER_BASE_URL="https://testnet.relayer.fi/v1"  # sandbox; use https://api.relayer.fi/v1 for production
Business onboarding (KYB) is completed through the dashboard before you can use the Payout API. Once approved, every endpoint below becomes available.

​
Steps

1

Create a recipient (beneficiary)

Register the person or business you want to pay. This creates a recipient record in Relayer — no fiat-rails call yet.
curl -X POST $RELAYER_BASE_URL/v1/payout/recipients \
  -H "Authorization: ApiKey $RELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Garcia",
    "email": "maria@example.com",
    "ownerType": "individual",
    "address": {
      "street": "Paseo de la Reforma 123",
      "city": "Mexico City",
      "country": "MX",
      "postalCode": "06600"
    }
  }'
2

Invite the recipient to add their bank account

Generate an invite link. The recipient visits this URL to submit their bank details securely. The token is valid for 7 days.
curl -X POST $RELAYER_BASE_URL/v1/payout/recipients/$BENEFICIARY_ID/invite \
  -H "Authorization: ApiKey $RELAYER_API_KEY"
Once the recipient submits their bank details, the account is registered with the regulated fiat rails partner. You can list bank accounts at any time via GET /v1/payout/recipients/{id}/accounts.
If you already have the recipient’s bank details on file, you can skip the invite and call POST /v1/payout/recipients/{id}/accounts directly.
3

Create a withdrawal address (Step 1 of account setup)

Link the recipient’s bank account to a crypto chain. Stablecoins sent to this address trigger the off-ramp transfer. This call is idempotent.
curl -X POST $RELAYER_BASE_URL/v1/payout/accounts/setup/liquidation-address \
  -H "Authorization: ApiKey $RELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryId": "ben_abc123",
    "beneficiaryAccountId": "acc_xyz789",
    "chain": "polygon",
    "currency": "usdc"
  }'
4

Create a virtual account / CLABE (Step 2 of account setup)

Create an MXN SPEI virtual account tied to the withdrawal address. Returns the CLABE your client uses for fiat deposits. This call is idempotent.
curl -X POST $RELAYER_BASE_URL/v1/payout/accounts/setup/virtual-account \
  -H "Authorization: ApiKey $RELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryId": "ben_abc123",
    "beneficiaryAccountId": "acc_xyz789"
  }'
Share the CLABE with your client. When they deposit MXN to this CLABE, the funds settle through the withdrawal address to the recipient’s bank.
5

Get a payment quote

Before executing a settlement, get a quote to confirm the rate and fees.
curl -X POST $RELAYER_BASE_URL/v1/payout/accounts/quote \
  -H "Authorization: ApiKey $RELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryId": "ben_abc123",
    "amount": 1000,
    "currency": "MXN"
  }'
6

Execute the payment

Trigger the settlement. This initiates the off-ramp transfer to the recipient’s bank.
curl -X POST $RELAYER_BASE_URL/v1/payout/accounts/execute \
  -H "Authorization: ApiKey $RELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "qte_ghi789",
    "beneficiaryId": "ben_abc123"
  }'
Payment execution is irreversible once initiated. Confirm the quote details and recipient bank account before calling this endpoint.
Settlement typically completes within 1-2 business days via SPEI.
7

Track the order

Every payment is represented as an order. Track status via the unified orders endpoint:
cURL
curl $RELAYER_BASE_URL/v1/orders/$ORDER_ID \
  -H "Authorization: ApiKey $RELAYER_API_KEY"
To list recent orders for this recipient:
cURL
curl $RELAYER_BASE_URL/v1/payout/recipients/$BENEFICIARY_ID/orders \
  -H "Authorization: ApiKey $RELAYER_API_KEY"
You can also check payment status by reference:
cURL
curl $RELAYER_BASE_URL/v1/payout/accounts/$REFERENCE/status \
  -H "Authorization: ApiKey $RELAYER_API_KEY"

​
On-ramp variant (fiat → stablecoin)

If instead of off-ramp you want to receive stablecoins from a fiat deposit, use the on-ramp endpoints: 
POST /v1/payout/onramp/quote                — Get fiat → stablecoin rate
POST /v1/payout/onramp/deposit-accounts     — Create or get a deposit account (idempotent)
GET  /v1/payout/onramp/deposit-accounts/{id}/events  — Track lifecycle events
The deposit account is a permanent fiat account (e.g. a CLABE in Mexico) tied to a stablecoin wallet. When the client deposits fiat, the stablecoin lands at the wallet.

​
Cancelling an order

An order in awaiting status can be cancelled before settlement: 
POST /v1/orders/{id}/cancel
The call is idempotent — calling it twice on the same awaiting order is safe. Once the order has moved past awaiting, cancellation is no longer possible.

​
Next Steps

Endpoints

Full endpoint reference for accounts, on/off-ramp, recipients, and orders.

API Reference

Interactive schemas and try-it playground.

Glossary

Settlement, on-ramp, off-ramp, and other domain terms.

Error Reference

API error codes and handling patterns.