> ## 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.

# Payout Endpoints

> Accounts (virtual accounts, payments), on-ramp, off-ramp, recipients, and orders reference

Reference for all Payout Kit endpoints. For interactive schemas and try-it functionality, see the [API Reference](/api-reference/introduction).

<Note>
  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.
</Note>

## 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "beneficiaryId": "ben_abc123",
  "beneficiaryAccountId": "acc_xyz789"
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "beneficiaryId": "ben_abc123",
  "amount": 1000,
  "currency": "MXN"
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "quoteId": "qte_jkl012",
  "beneficiaryId": "ben_abc123"
}
```

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

***

### 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{ "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):**

```json theme={null}
{
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "accountType": "checking",
  "bankName": "Bank of America"
}
```

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

### 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](/api-reference/introduction). Payout endpoints are grouped under **Payout: Accounts**, **Payout: On-ramp**, **Payout: Off-ramp**, **Payout: Recipients**, and **Payout: Orders**.