How to Get a Quote and Initiate a USDC Corridor Payout

Before you can send money, you need an active corridor for your target currency. A corridor is a persistent configuration object that ties your organization to a destination currency and its KYC verification. Once the corridor is active, you can request a live quote and submit a payout against it as many times as you need.

Create a corridor

Send a POST /corridors request with the destination currency you want to pay out in. You only need to do this once per currency—reuse the same corridor ID for every subsequent quote and pay.

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

A successful request returns 201 Created with the new corridor object:

{
  "id": "crd_01HZ9K2XJQMV3NYFP8WTBR4E6D",
  "orgId": "org_01HZ9J7YQPNW2MXFK8VTCA3R5S",
  "destCurrency": "BRL",
  "status": "PENDING_KYC",
  "createdAt": "2025-01-15T10:22:34.000Z"
}

The corridor starts in PENDING_KYC status. It transitions to ACTIVE only after your organization completes KYC verification in the Meterlane dashboard under Settings → Corridors. You cannot request quotes or initiate payouts until the corridor is ACTIVE.

Save the id from this response—you will use it in every subsequent call for this currency.

Get a quote

Request a live FX quote by calling GET /corridors/:id/quote with the amount of USDC you want to send. The amount query parameter is denominated in USDC.

curl https://corridor.meterlane.app/corridors/crd_01HZ9K2XJQMV3NYFP8WTBR4E6D/quote?amount=100 \
  -H "Authorization: Bearer bp_live_YOUR_API_KEY"

The response contains everything you need to confirm the payout:

{
  "quoteId": "qt_01HZ9M4KPQXR7NYVWC5TBF2E8A",
  "fxRate": "5.1823",
  "destAmount": "518.23",
  "destCurrency": "BRL",
  "expiresAt": "2025-01-15T10:24:34.000Z"
}

Field	Description
`quoteId`	Opaque ID that locks the quoted rate. Pass this to `/pay`.
`fxRate`	Units of destination currency per 1 USDC at the time of the quote.
`destAmount`	Amount the beneficiary will receive in `destCurrency`, after all fees.
`expiresAt`	ISO 8601 timestamp. The quote expires at this time—request a new one if you miss the window.

The dashboard quote UI shows a full all-in fee breakdown—platform fee plus Circle CPN rail fees—before you commit to a payout. Check it when you want a transparent view of costs without writing code.

Initiate the payout

Submit the payout by calling POST /corridors/:id/pay. You must include an Idempotency-Key header on every pay request. If you retry a failed network call using the same key, the API returns the original cached response instead of creating a duplicate payment.

curl -X POST https://corridor.meterlane.app/corridors/crd_01HZ9K2XJQMV3NYFP8WTBR4E6D/pay \
  -H "Authorization: Bearer bp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payout-2025-01-15-acme-001" \
  -d '{
    "quoteId": "qt_01HZ9M4KPQXR7NYVWC5TBF2E8A",
    "fromAddress": "0xYourWalletAddressHere",
    "amountUSDC": "100",
    "beneficiary": {
      "name": "Acme Fornecedores Ltda",
      "bankName": "Banco do Brasil",
      "accountNumber": "123456789",
      "country": "BR",
      "currency": "BRL"
    }
  }'

A successful request returns 202 Accepted:

{
  "paymentId": "pay_01HZ9N6LPQXV8MYWC4TBF3E9D7",
  "cpnPaymentId": "cpn_7f3a2b1e-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
  "status": "PENDING"
}

The payment starts as PENDING. Circle processes the fiat leg asynchronously. When Circle confirms or fails the transfer, it posts a webhook event to Meterlane, which updates the payment status to SETTLED, FAILED, or COMPLIANCE_HOLD. See Webhooks for how to receive those updates.

The Idempotency-Key header is required. Omitting it returns a 400 MISSING_IDEMPOTENCY_KEY error immediately. Use a unique, stable key per logical payout—such as your internal order ID—so retries are safe.

Beneficiary validation rules

The beneficiary object is validated on every pay request. Fields that are always required: name, bankName, accountNumber, country, and currency. Three countries have additional account-number format rules enforced at the API level.

Country-specific account number rules

Country	ISO-2 code	Rule	Format
Nigeria	`NG`	NUBAN format	Exactly 10 digits
Kenya	`KE`	—	8–14 digits
South Africa	`ZA`	—	7–11 digits
Brazil	`BR`	—	No extra constraint
Mexico	`MX`	—	No extra constraint

Digits are extracted from the accountNumber string before length validation, so hyphens and spaces in the input do not cause false failures. However, it is good practice to send a clean numeric string.

Error reference

Code	HTTP status	Cause
`CORRIDOR_NOT_ACTIVE`	409	The corridor exists but its status is not `ACTIVE`. Complete KYC in the dashboard first.
`INVALID_CURRENCY`	400	The `destCurrency` value is not one of the supported currencies (`BRL`, `MXN`, `NGN`, `KES`, `ZAR`).
`INVALID_AMOUNT`	400	`amountUSDC` (pay) or `amount` (quote) is zero, negative, or not a valid number.
`INVALID_BENEFICIARY`	400	A required beneficiary field is missing or the account number does not meet country-specific length rules.
`MISSING_IDEMPOTENCY_KEY`	400	The `Idempotency-Key` header was not included on `POST /corridors/:id/pay`.
`DUPLICATE_REQUEST`	409	A pay request with this `Idempotency-Key` was already processed. The response contains the original result.

​Beneficiary validation rules

​Error reference

Beneficiary validation rules

Error reference