Payout Flow Guide - Relayer.fi

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

Create a recipient (beneficiary)

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"
    }
  }'

const response = await fetch(`${RELAYER_BASE_URL}/v1/payout/recipients`, {
  method: "POST",
  headers: {
    "Authorization": `ApiKey ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Maria Garcia",
    email: "maria@example.com",
    ownerType: "individual",
    address: {
      street: "Paseo de la Reforma 123",
      city: "Mexico City",
      country: "MX",
      postalCode: "06600",
    },
  }),
});
const { data } = await response.json();
const beneficiaryId = data.id;

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"

const response = await fetch(
  `${RELAYER_BASE_URL}/v1/payout/recipients/${beneficiaryId}/invite`,
  {
    method: "POST",
    headers: { "Authorization": `ApiKey ${apiKey}` },
  }
);
const { data } = await response.json();
// data.inviteUrl — send this to the recipient
console.log(`Send invite to recipient: ${data.inviteUrl}`);

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.

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"
  }'

const response = await fetch(
  `${RELAYER_BASE_URL}/v1/payout/accounts/setup/liquidation-address`,
  {
    method: "POST",
    headers: {
      "Authorization": `ApiKey ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      beneficiaryId: "ben_abc123",
      beneficiaryAccountId: "acc_xyz789",
      chain: "polygon",
      currency: "usdc",
    }),
  }
);
const { data } = await response.json();
const withdrawalAddress = data.address;

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"
  }'

const response = await fetch(
  `${RELAYER_BASE_URL}/v1/payout/accounts/setup/virtual-account`,
  {
    method: "POST",
    headers: {
      "Authorization": `ApiKey ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      beneficiaryId: "ben_abc123",
      beneficiaryAccountId: "acc_xyz789",
    }),
  }
);
const { data } = await response.json();
console.log(`Client CLABE: ${data.clabe}`);

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.

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"
  }'

const response = await fetch(`${RELAYER_BASE_URL}/v1/payout/accounts/quote`, {
  method: "POST",
  headers: {
    "Authorization": `ApiKey ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    beneficiaryId: "ben_abc123",
    amount: 1000,
    currency: "MXN",
  }),
});
const { data } = await response.json();
// data.rate — exchange rate applied
// data.fees — settlement fees
// data.netAmount — recipient receives this amount
const quoteId = data.quoteId;

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"
  }'

const response = await fetch(`${RELAYER_BASE_URL}/v1/payout/accounts/execute`, {
  method: "POST",
  headers: {
    "Authorization": `ApiKey ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    quoteId: "qte_ghi789",
    beneficiaryId: "ben_abc123",
  }),
});
const { data } = await response.json();
// data.reference — payment reference for tracking
// data.status — "pending" initially
console.log(`Payment initiated: ${data.reference}`);

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.

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.

​Prerequisites

​Steps

​On-ramp variant (fiat → stablecoin)

​Cancelling an order

​Next Steps

Endpoints

API Reference

Glossary

Error Reference

Prerequisites

Steps

On-ramp variant (fiat → stablecoin)

Cancelling an order

Next Steps