> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meterlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Corridor Endpoints: Create, Quote, and Pay in USDC

> Reference for POST /corridors, GET /corridors/:id, GET /corridors/:id/quote, and POST /corridors/:id/pay — the full payout lifecycle.

These four endpoints cover the complete payout lifecycle: you create a corridor for a destination currency, wait for KYC approval, request a live FX quote, and then submit a pay request with your beneficiary details. All requests must include a valid `Authorization: Bearer bp_live_…` header. See the [overview](/api-reference/corridor-overview) for base URL, error codes, and the endpoint index.

***

## POST /corridors

Creates a new corridor for your organisation. The corridor starts in `PENDING_KYC` status and cannot be used for quotes or payments until KYC is approved in the Meterlane dashboard.

<ParamField body="destCurrency" type="string" required>
  The destination fiat currency for payouts. Must be one of `BRL`, `MXN`, `NGN`, `KES`, or `ZAR`.
</ParamField>

### Response fields

<ResponseField name="id" type="string">
  Unique corridor ID. Use this as the `:id` path parameter in subsequent requests.
</ResponseField>

<ResponseField name="orgId" type="string">
  The organisation ID that owns this corridor.
</ResponseField>

<ResponseField name="destCurrency" type="string">
  The destination fiat currency code you specified on creation.
</ResponseField>

<ResponseField name="status" type="string">
  Lifecycle status of the corridor. Starts as `PENDING_KYC`; transitions to `ACTIVE` after dashboard KYC approval.
</ResponseField>

### Example

```bash theme={null}
curl -sS -X POST https://corridor.meterlane.app/corridors \
  -H "Authorization: Bearer bp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"destCurrency": "BRL"}'
```

```json theme={null}
{
  "id": "cor_01j9z8k2m4p6q7r3s5t0",
  "orgId": "org_01j8a3b2c4d5e6f7g8h9",
  "destCurrency": "BRL",
  "status": "PENDING_KYC"
}
```

<Note>
  A newly created corridor cannot accept quotes or payments. Navigate to **Dashboard → Corridors** to complete KYC and move the corridor to `ACTIVE` status.
</Note>

***

## GET /corridors/:id

Retrieves the current state of a corridor belonging to your organisation.

<ParamField path="id" type="string" required>
  The corridor ID returned when you called `POST /corridors`.
</ParamField>

### Response fields

<ResponseField name="id" type="string">
  Unique corridor ID.
</ResponseField>

<ResponseField name="orgId" type="string">
  The organisation ID that owns this corridor.
</ResponseField>

<ResponseField name="destCurrency" type="string">
  The destination fiat currency code.
</ResponseField>

<ResponseField name="status" type="string">
  Current lifecycle status: `PENDING_KYC` or `ACTIVE`.
</ResponseField>

### Example

```bash theme={null}
curl -sS https://corridor.meterlane.app/corridors/cor_01j9z8k2m4p6q7r3s5t0 \
  -H "Authorization: Bearer bp_live_…"
```

```json theme={null}
{
  "id": "cor_01j9z8k2m4p6q7r3s5t0",
  "orgId": "org_01j8a3b2c4d5e6f7g8h9",
  "destCurrency": "BRL",
  "status": "ACTIVE"
}
```

***

## GET /corridors/:id/quote

Returns a live FX quote for converting USDC to the corridor's destination currency. The corridor must be `ACTIVE`.

<ParamField path="id" type="string" required>
  The corridor ID.
</ParamField>

<ParamField query="amount" type="string" required>
  The USDC amount to convert, expressed as a positive numeric string (e.g. `"100"`).
</ParamField>

### Response fields

<ResponseField name="quoteId" type="string">
  Opaque identifier for this quote. Pass it to `POST /corridors/:id/pay` to lock in the rate.
</ResponseField>

<ResponseField name="fxRate" type="string">
  Exchange rate from USDC to the destination currency at the time of the quote.
</ResponseField>

<ResponseField name="destAmount" type="string">
  The amount the beneficiary will receive in the destination currency after all fees.
</ResponseField>

<ResponseField name="expiresAt" type="string">
  ISO 8601 timestamp after which the quote is no longer valid.
</ResponseField>

### Example

```bash theme={null}
curl -sS \
  "https://corridor.meterlane.app/corridors/cor_01j9z8k2m4p6q7r3s5t0/quote?amount=100" \
  -H "Authorization: Bearer bp_live_…"
```

```json theme={null}
{
  "quoteId": "qte_02k0a9l3n5q7r8s4t1u2",
  "fxRate": "5.12",
  "destAmount": "510.87",
  "expiresAt": "2025-01-15T14:32:00Z"
}
```

<Warning>
  Quotes expire quickly — do not cache or reuse a `quoteId`. Fetch a fresh quote immediately before every pay request. Submitting an expired `quoteId` will result in an error from the upstream Circle API.
</Warning>

***

## POST /corridors/:id/pay

Initiates a USDC payout to a beneficiary's bank account. The corridor must be `ACTIVE`. This endpoint accepts the request and returns `202 Accepted`; settlement is confirmed asynchronously via webhook.

<ParamField path="id" type="string" required>
  The corridor ID.
</ParamField>

<ParamField header="Idempotency-Key" type="string" required>
  A unique string (e.g. a UUID) that identifies this pay attempt. Reusing the same key lets you safely retry without creating a duplicate payment.
</ParamField>

<ParamField body="quoteId" type="string" required>
  The `quoteId` returned by `GET /corridors/:id/quote`. Must not be expired.
</ParamField>

<ParamField body="fromAddress" type="string" required>
  The USDC wallet address on the source chain that is funding this payment.
</ParamField>

<ParamField body="amountUSDC" type="string" required>
  The amount of USDC to send, expressed as a positive numeric string (e.g. `"100"`).
</ParamField>

<ParamField body="beneficiary" type="object" required>
  Bank account details for the recipient.

  <Expandable title="beneficiary fields">
    <ParamField body="name" type="string" required>
      Full legal name of the beneficiary entity or individual.
    </ParamField>

    <ParamField body="bankName" type="string" required>
      Name of the beneficiary's bank.
    </ParamField>

    <ParamField body="accountNumber" type="string" required>
      Bank account number. Format requirements vary by country — see the validation table below.
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code for the beneficiary's bank (e.g. `"BR"`, `"NG"`).
    </ParamField>

    <ParamField body="currency" type="string" required>
      Destination currency code. Must match the corridor's `destCurrency` (e.g. `"BRL"`).
    </ParamField>
  </Expandable>
</ParamField>

### Beneficiary account number validation

| Country      | Code | Rule                             |
| ------------ | ---- | -------------------------------- |
| Nigeria      | `NG` | Exactly 10 digits (NUBAN format) |
| Kenya        | `KE` | 8–14 digits                      |
| South Africa | `ZA` | 7–11 digits                      |
| Brazil       | `BR` | No enforced digit length         |
| Mexico       | `MX` | No enforced digit length         |

### Response fields

<ResponseField name="paymentId" type="string">
  Meterlane's internal payment record ID. Use this to reconcile payments in your system.
</ResponseField>

<ResponseField name="cpnPaymentId" type="string">
  The payment ID assigned by Circle's Cross-Platform Network (CPN). Useful for support escalations.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status of the payment. Always `"PENDING"` on a `202` response.
</ResponseField>

### Example

```bash theme={null}
curl -sS -X POST \
  https://corridor.meterlane.app/corridors/cor_01j9z8k2m4p6q7r3s5t0/pay \
  -H "Authorization: Bearer bp_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a3f8c2d1-4e57-4b9a-b0e2-1c6d9f3a7e12" \
  -d '{
    "quoteId": "qte_02k0a9l3n5q7r8s4t1u2",
    "fromAddress": "0xYourWalletAddress",
    "amountUSDC": "100",
    "beneficiary": {
      "name": "Acme Ltda",
      "bankName": "Banco do Brasil",
      "accountNumber": "123456789",
      "country": "BR",
      "currency": "BRL"
    }
  }'
```

```json theme={null}
{
  "paymentId": "pay_03l1b0m4o6r8s9t5u2v3",
  "cpnPaymentId": "cpn_a1b2c3d4e5f6g7h8i9j0",
  "status": "PENDING"
}
```

<Warning>
  A `202 Accepted` response means Meterlane has queued your payment — it does not mean the funds have settled. Listen for `payments.payment_completed` on your [webhook endpoint](/api-reference/corridor-webhooks) to confirm final settlement.
</Warning>