Payout Endpoints - Relayer.fi

Reference for all Payout Kit endpoints. For interactive schemas and try-it functionality, see the API Reference.

Business onboarding (KYB) is completed through the Relayer dashboard before you can call any of these endpoints. Once your workspace is approved, every endpoint below is available.

Payout Accounts

Account setup and payment execution for the cross-currency flow (stablecoin → fiat).

Step 1 — Create Withdrawal Address (Liquidation Address)

Link a recipient’s bank account to a crypto chain for off-ramp. Idempotent — returns the existing address if already configured for this recipient.

POST /v1/payout/accounts/setup/liquidation-address

Request body:

{
  "beneficiaryId": "ben_abc123",
  "beneficiaryAccountId": "acc_xyz789",
  "chain": "polygon",
  "currency": "usdc"
}

Field	Type	Description
`beneficiaryId`	string	Relayer recipient ID
`beneficiaryAccountId`	string	Recipient’s bank account ID
`chain`	string	Blockchain network (e.g., `polygon`, `base`)
`currency`	string	Stablecoin (e.g., `usdc`, `usdt`)

Response:

{
  "success": true,
  "data": {
    "id": "liq_def456",
    "address": "0xWithdrawalAddress",
    "chain": "polygon",
    "currency": "usdc"
  }
}

Step 2 — Create Virtual Account

Create an MXN SPEI virtual account with a CLABE tied to the withdrawal address. Requires a withdrawal address to exist first. Idempotent.

POST /v1/payout/accounts/setup/virtual-account

Request body:

{
  "beneficiaryId": "ben_abc123",
  "beneficiaryAccountId": "acc_xyz789"
}

Response:

{
  "success": true,
  "data": {
    "id": "va_ghi789",
    "clabe": "646180123456789012",
    "currency": "MXN",
    "beneficiaryId": "ben_abc123"
  }
}

The clabe is the SPEI account number your client deposits MXN to.

Get Payment Quote

Get the exchange rate and fees for a payment before executing (MXN → USD).

POST /v1/payout/accounts/quote

Request body:

{
  "beneficiaryId": "ben_abc123",
  "amount": 1000,
  "currency": "MXN"
}

Response:

{
  "success": true,
  "data": {
    "quoteId": "qte_jkl012",
    "amount": 1000,
    "currency": "MXN",
    "rate": 17.25,
    "fees": 2.50,
    "netAmount": 997.50,
    "expiresAt": "2026-03-28T12:10:00.000Z"
  }
}

Execute Payment

Trigger a payment using an accepted quote. Initiates off-ramp settlement.

POST /v1/payout/accounts/execute

Request body:

{
  "quoteId": "qte_jkl012",
  "beneficiaryId": "ben_abc123"
}

Payment execution is irreversible once initiated. Verify quote and recipient details before calling this endpoint.

List Payments

GET /v1/payout/accounts

Returns all payments for the authenticated workspace.

Get Payment Status by Reference

GET /v1/payout/accounts/{reference}/status

On-ramp (Fiat → Stablecoin)

Move fiat from a client deposit into a stablecoin wallet.

Get On-ramp Quote

POST /v1/payout/onramp/quote

Returns the current fiat → stablecoin rate, fees, and net amount.

Create / Get Deposit Account

Create a permanent fiat deposit account (e.g. a CLABE) tied to a stablecoin wallet. Idempotent.

POST /v1/payout/onramp/deposit-accounts

List Deposit Accounts

GET /v1/payout/onramp/deposit-accounts

Get a Deposit Account

GET /v1/payout/onramp/deposit-accounts/{id}

List Lifecycle Events

Track deposit, conversion, and settlement events for a single deposit account.

GET /v1/payout/onramp/deposit-accounts/{id}/events

Off-ramp (Stablecoin → Fiat)

Move stablecoins from a deposit into a recipient’s bank account.

Get Off-ramp Quote

POST /v1/payout/offramp/quote

Returns the current stablecoin → fiat rate, fees, and net amount.

Create / Get Withdrawal Address

Create a permanent crypto withdrawal address linked to a recipient’s bank account. Idempotent.

POST /v1/payout/offramp/withdraw-addresses

Get a Withdrawal Address

GET /v1/payout/offramp/withdraw-addresses/{id}

List Drain History

Stablecoin deposits to the withdrawal address that triggered fiat settlements.

GET /v1/payout/offramp/withdraw-addresses/{id}/drains

Recipients (Beneficiaries)

Recipient and bank account management.

Create Recipient

Create a recipient record. Stored in Relayer — no fiat-rails call at creation.

POST /v1/payout/recipients

Request body:

{
  "name": "Maria Garcia",
  "email": "maria@example.com",
  "ownerType": "individual",
  "address": {
    "street": "Paseo de la Reforma 123",
    "city": "Mexico City",
    "country": "MX",
    "postalCode": "06600"
  }
}

Field	Type	Description
`name`	string	Recipient display name
`email`	string	Contact email
`ownerType`	`"individual"` \| `"business"`	Entity type
`address`	object	Physical address

List Recipients

GET /v1/payout/recipients

List Recipients with Bank Accounts

Returns recipients with their linked bank accounts embedded — single query, no N+1.

GET /v1/payout/recipients/with-accounts

Update Recipient

Update the name and/or email of a recipient. At least one field is required.

PATCH /v1/payout/recipients/{id}

Update Recipient Status

Archive or restore a recipient. Archived recipients cannot receive payouts.

PATCH /v1/payout/recipients/{id}/status

Request body:

{ "status": "archived" }

Valid values: active, archived.

Get Invite Link

GET /v1/payout/recipients/{id}/invite

Generate Invite Link

Create a new invite token (valid 7 days). Replaces any existing invite.

POST /v1/payout/recipients/{id}/invite

Add Bank Account

Register a bank account with the fiat rails partner and link it to the recipient. One recipient can have multiple accounts.

POST /v1/payout/recipients/{id}/accounts

Request body (US ACH example):

{
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "accountType": "checking",
  "bankName": "Bank of America"
}

account_number, clabe, and iban are immutable once set. Use PATCH /payout/recipients/{id}/accounts/{accountId} to update other fields.

Update Bank Account

PATCH /v1/payout/recipients/{id}/accounts/{accountId}

Editable fields: routing_number, checking_or_savings, address. Immutable fields: account_number, clabe, iban.

List Bank Accounts

GET /v1/payout/recipients/{id}/accounts

Recent Orders for a Recipient

GET /v1/payout/recipients/{id}/orders

Orders

Every transfer is represented as an order. The orders endpoints are unified across all rails — list, get, and cancel are the same regardless of direction.

List Orders

GET /v1/orders

Get Order

GET /v1/orders/{id}

Cancel an Awaiting Order

Idempotent. Only valid while the order is still in awaiting status.

POST /v1/orders/{id}/cancel

Full API Reference

All endpoints include interactive schemas and a try-it playground in the API Reference. Payout endpoints are grouped under Payout: Accounts, Payout: On-ramp, Payout: Off-ramp, Payout: Recipients, and Payout: Orders.

​Payout Accounts

​Step 1 — Create Withdrawal Address (Liquidation Address)

​Step 2 — Create Virtual Account

​Get Payment Quote

​Execute Payment

​List Payments

​Get Payment Status by Reference

​On-ramp (Fiat → Stablecoin)

​Get On-ramp Quote

​Create / Get Deposit Account

​List Deposit Accounts

​Get a Deposit Account

​List Lifecycle Events

​Off-ramp (Stablecoin → Fiat)

​Get Off-ramp Quote

​Create / Get Withdrawal Address

​Get a Withdrawal Address

​List Drain History

​Recipients (Beneficiaries)

​Create Recipient

​List Recipients

​List Recipients with Bank Accounts

​Update Recipient

​Update Recipient Status

​Get Invite Link

​Generate Invite Link

​Add Bank Account

​Update Bank Account

​List Bank Accounts

​Recent Orders for a Recipient

​Orders

​List Orders

​Get Order

​Cancel an Awaiting Order

​Full API Reference

Payout Accounts

Step 1 — Create Withdrawal Address (Liquidation Address)

Step 2 — Create Virtual Account

Get Payment Quote

Execute Payment

List Payments

Get Payment Status by Reference

On-ramp (Fiat → Stablecoin)

Get On-ramp Quote

Create / Get Deposit Account

List Deposit Accounts

Get a Deposit Account

List Lifecycle Events

Off-ramp (Stablecoin → Fiat)

Get Off-ramp Quote

Create / Get Withdrawal Address

Get a Withdrawal Address

List Drain History

Recipients (Beneficiaries)

Create Recipient

List Recipients

List Recipients with Bank Accounts

Update Recipient

Update Recipient Status

Get Invite Link

Generate Invite Link

Add Bank Account

Update Bank Account

List Bank Accounts

Recent Orders for a Recipient

Orders

List Orders

Get Order

Cancel an Awaiting Order

Full API Reference