Corridor Endpoints: Create, Quote, and Pay in USDC

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

string

required

The destination fiat currency for payouts. Must be one of BRL, MXN, NGN, KES, or ZAR.

Response fields

string

Unique corridor ID. Use this as the :id path parameter in subsequent requests.

string

The organisation ID that owns this corridor.

string

The destination fiat currency code you specified on creation.

string

Lifecycle status of the corridor. Starts as PENDING_KYC; transitions to ACTIVE after dashboard KYC approval.

Example

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

{
  "id": "cor_01j9z8k2m4p6q7r3s5t0",
  "orgId": "org_01j8a3b2c4d5e6f7g8h9",
  "destCurrency": "BRL",
  "status": "PENDING_KYC"
}

A newly created corridor cannot accept quotes or payments. Navigate to Dashboard → Corridors to complete KYC and move the corridor to ACTIVE status.

GET /corridors/:id

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

string

required

The corridor ID returned when you called POST /corridors.

Response fields

string

Unique corridor ID.

string

The organisation ID that owns this corridor.

string

The destination fiat currency code.

string

Current lifecycle status: PENDING_KYC or ACTIVE.

Example

curl -sS https://corridor.meterlane.app/corridors/cor_01j9z8k2m4p6q7r3s5t0 \
  -H "Authorization: Bearer bp_live_…"

{
  "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.

string

required

The corridor ID.

string

required

The USDC amount to convert, expressed as a positive numeric string (e.g. "100").

Response fields

string

Opaque identifier for this quote. Pass it to POST /corridors/:id/pay to lock in the rate.

string

Exchange rate from USDC to the destination currency at the time of the quote.

string

The amount the beneficiary will receive in the destination currency after all fees.

string

ISO 8601 timestamp after which the quote is no longer valid.

Example

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

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

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.

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.

string

required

The corridor ID.

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.

string

required

The quoteId returned by GET /corridors/:id/quote. Must not be expired.

string

required

The USDC wallet address on the source chain that is funding this payment.

string

required

The amount of USDC to send, expressed as a positive numeric string (e.g. "100").

object

required

Bank account details for the recipient.

Show beneficiary fields

string

required

Full legal name of the beneficiary entity or individual.

string

required

Name of the beneficiary’s bank.

string

required

Bank account number. Format requirements vary by country — see the validation table below.

string

required

ISO 3166-1 alpha-2 country code for the beneficiary’s bank (e.g. "BR", "NG").

string

required

Destination currency code. Must match the corridor’s destCurrency (e.g. "BRL").

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

string

Meterlane’s internal payment record ID. Use this to reconcile payments in your system.

string

The payment ID assigned by Circle’s Cross-Platform Network (CPN). Useful for support escalations.

string

Initial status of the payment. Always "PENDING" on a 202 response.

Example

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

{
  "paymentId": "pay_03l1b0m4o6r8s9t5u2v3",
  "cpnPaymentId": "cpn_a1b2c3d4e5f6g7h8i9j0",
  "status": "PENDING"
}

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 to confirm final settlement.

Gateway API

Corridor API

Corridor Endpoints: Create, Quote, and Pay in USDC

POST /corridors

Response fields

Example

GET /corridors/:id

Response fields

Example

GET /corridors/:id/quote

Response fields

Example

POST /corridors/:id/pay

Beneficiary account number validation

Response fields

Example

​POST /corridors

​Response fields

​Example

​GET /corridors/:id

​Response fields

​Example

​GET /corridors/:id/quote

​Response fields

​Example

​POST /corridors/:id/pay

​Beneficiary account number validation

​Response fields

​Example

POST /corridors

Response fields

Example

GET /corridors/:id

Response fields

Example

GET /corridors/:id/quote

Response fields

Example

POST /corridors/:id/pay

Beneficiary account number validation

Response fields

Example