Skip to main content
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.
​
destCurrency
string
required
The destination fiat currency for payouts. Must be one of BRL, MXN, NGN, KES, or ZAR.

​
Response fields

​
id
string
Unique corridor ID. Use this as the :id path parameter in subsequent requests.
​
orgId
string
The organisation ID that owns this corridor.
​
destCurrency
string
The destination fiat currency code you specified on creation.
​
status
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.
​
id
string
required
The corridor ID returned when you called POST /corridors.

​
Response fields

​
id
string
Unique corridor ID.
​
orgId
string
The organisation ID that owns this corridor.
​
destCurrency
string
The destination fiat currency code.
​
status
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.
​
id
string
required
The corridor ID.
​
amount
string
required
The USDC amount to convert, expressed as a positive numeric string (e.g. "100").

​
Response fields

​
quoteId
string
Opaque identifier for this quote. Pass it to POST /corridors/:id/pay to lock in the rate.
​
fxRate
string
Exchange rate from USDC to the destination currency at the time of the quote.
​
destAmount
string
The amount the beneficiary will receive in the destination currency after all fees.
​
expiresAt
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.
​
id
string
required
The corridor ID.
​
Idempotency-Key
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.
​
quoteId
string
required
The quoteId returned by GET /corridors/:id/quote. Must not be expired.
​
fromAddress
string
required
The USDC wallet address on the source chain that is funding this payment.
​
amountUSDC
string
required
The amount of USDC to send, expressed as a positive numeric string (e.g. "100").
​
beneficiary
object
required
Bank account details for the recipient.

​
Beneficiary account number validation

CountryCodeRule
NigeriaNGExactly 10 digits (NUBAN format)
KenyaKE8–14 digits
South AfricaZA7–11 digits
BrazilBRNo enforced digit length
MexicoMXNo enforced digit length

​
Response fields

​
paymentId
string
Meterlane’s internal payment record ID. Use this to reconcile payments in your system.
​
cpnPaymentId
string
The payment ID assigned by Circle’s Cross-Platform Network (CPN). Useful for support escalations.
​
status
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.