curl --request POST \
  --url https://sandbox.elementpay.net/api/v1/partner/orders/quote \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "order_type": "OnRamp",
  "currency": "KES",
  "country": "KE",
  "local_amount": 800,
  "asset": {
    "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bdA02913",
    "currency": "USDC",
    "network": "BASE"
  },
  "customer": {
    "uid": "sandbox-ke-onramp-success-001",
    "type": "user",
    "name": "Successful Jane Customer",
    "country": "KE",
    "phone": "+2541111111111",
    "address": "Nairobi",
    "dob": "02/01/1997",
    "email": "jane@example.com",
    "id_number": "A1234567",
    "id_type": "passport"
  },
  "payment_method": {
    "type": "mobile_money",
    "phone_number": "+2541111111111",
    "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb"
  },
  "wallet_address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe"
}
'

{
  "status": "success",
  "message": "Partner order quote created",
  "data": {
    "quote_id": "yc_receive_580e04c2-a136-5cca-be54-b49fcf80970c",
    "rail": "local_fiat",
    "status": "process",
    "order_type": "OnRamp",
    "route": {
      "family": "ramp_provider",
      "rail": "local_fiat",
      "direction": "payin",
      "mode": "auto",
      "reason": "Auto-routed for KE KES OnRamp."
    },
    "expires_at": "2026-05-16T08:13:40.322Z",
    "amounts": {
      "rate": 131.69,
      "rate_currency": "KES",
      "user_pays": {
        "amount": 800,
        "currency": "KES"
      },
      "user_receives": {
        "amount": 5.94999132,
        "currency": "USDC",
        "network": "BASE"
      },
      "fees": {
        "network_fee_usd": 0,
        "network_fee_local": 0,
        "service_fee_usd": 0.12,
        "service_fee_local": 16,
        "partner_fee_usd": 0,
        "partner_fee_local": 0
      }
    },
    "instructions": {
      "available_after_accept": true,
      "note": "Accept this quote to create the local order and receive final payment instructions."
    },
    "audit": {
      "rail": "local_fiat",
      "provider_quote_id": "580e04c2-a136-5cca-be54-b49fcf80970c",
      "direction": "payin",
      "token_symbol": "BASE_USDC",
      "crypto_currency": "USDC",
      "crypto_network": "BASE"
    }
  }
}

{
  "status": "error",
  "message": "elementpay partner order routing is not enabled yet",
  "data": {
    "route": {
      "family": "native",
      "direction": "payin",
      "mode": "override",
      "reason": "Provider override requested: rail.",
      "rail": "native"
    }
  }
}

{
  "status": "error",
  "message": "Missing requirements for selected route",
  "data": {
    "missing_fields": [
      "wallet_address",
      "recipient or customer",
      "source or payment_method"
    ],
    "route": {
      "family": "ramp_provider",
      "direction": "payin",
      "mode": "auto",
      "reason": "Selected rail for KE KES OnRamp.",
      "rail": "local_fiat"
    }
  }
}

{
  "status": "error",
  "message": "Quote request failed",
  "data": null
}

Partner

Create a partner order quote

Create a binding quote for a fiat ↔ crypto order. Flow: create a quote → show the returned amounts and payment instructions to the user → accept the quote_id with POST /partner/orders/{quote_id}/accept. Discovery before quote: - GET /partner/catalog or GET /partner/payment-methods → rails for the corridor. - GET /partner/catalog?order_type=OnRamp|OffRamp → providers[].id for momo/bank. - GET /partner/order-requirements → exact field names (network_id required for momo/bank). - GET /partner/banks → bank institution UUIDs where applicable. Payment method by rail: - mobile_money: payment_method.type=mobile_money, payment_method.phone_number (E.164), and payment_method.network_id (UUID from catalog providers[].id). - bank: payment_method.type=bank, account_number, account_name, and payment_method.network_id (from GET /partner/banks or catalog). OnRamp response includes payment_instructions — show these to the user before accept. provider is optional. When omitted, ElementPay auto-routes by corridor. Quote id formats: yc_receive_<id> (OnRamp), yc_send_<id> (OffRamp). The quote expires at data.expires_at.

POST

partner

orders

quote

curl --request POST \
  --url https://sandbox.elementpay.net/api/v1/partner/orders/quote \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "order_type": "OnRamp",
  "currency": "KES",
  "country": "KE",
  "local_amount": 800,
  "asset": {
    "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bdA02913",
    "currency": "USDC",
    "network": "BASE"
  },
  "customer": {
    "uid": "sandbox-ke-onramp-success-001",
    "type": "user",
    "name": "Successful Jane Customer",
    "country": "KE",
    "phone": "+2541111111111",
    "address": "Nairobi",
    "dob": "02/01/1997",
    "email": "jane@example.com",
    "id_number": "A1234567",
    "id_type": "passport"
  },
  "payment_method": {
    "type": "mobile_money",
    "phone_number": "+2541111111111",
    "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb"
  },
  "wallet_address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe"
}
'

{
  "status": "success",
  "message": "Partner order quote created",
  "data": {
    "quote_id": "yc_receive_580e04c2-a136-5cca-be54-b49fcf80970c",
    "rail": "local_fiat",
    "status": "process",
    "order_type": "OnRamp",
    "route": {
      "family": "ramp_provider",
      "rail": "local_fiat",
      "direction": "payin",
      "mode": "auto",
      "reason": "Auto-routed for KE KES OnRamp."
    },
    "expires_at": "2026-05-16T08:13:40.322Z",
    "amounts": {
      "rate": 131.69,
      "rate_currency": "KES",
      "user_pays": {
        "amount": 800,
        "currency": "KES"
      },
      "user_receives": {
        "amount": 5.94999132,
        "currency": "USDC",
        "network": "BASE"
      },
      "fees": {
        "network_fee_usd": 0,
        "network_fee_local": 0,
        "service_fee_usd": 0.12,
        "service_fee_local": 16,
        "partner_fee_usd": 0,
        "partner_fee_local": 0
      }
    },
    "instructions": {
      "available_after_accept": true,
      "note": "Accept this quote to create the local order and receive final payment instructions."
    },
    "audit": {
      "rail": "local_fiat",
      "provider_quote_id": "580e04c2-a136-5cca-be54-b49fcf80970c",
      "direction": "payin",
      "token_symbol": "BASE_USDC",
      "crypto_currency": "USDC",
      "crypto_network": "BASE"
    }
  }
}

{
  "status": "error",
  "message": "elementpay partner order routing is not enabled yet",
  "data": {
    "route": {
      "family": "native",
      "direction": "payin",
      "mode": "override",
      "reason": "Provider override requested: rail.",
      "rail": "native"
    }
  }
}

{
  "status": "error",
  "message": "Missing requirements for selected route",
  "data": {
    "missing_fields": [
      "wallet_address",
      "recipient or customer",
      "source or payment_method"
    ],
    "route": {
      "family": "ramp_provider",
      "direction": "payin",
      "mode": "auto",
      "reason": "Selected rail for KE KES OnRamp.",
      "rail": "local_fiat"
    }
  }
}

{
  "status": "error",
  "message": "Quote request failed",
  "data": null
}

Create a binding quote for a fiat ↔ crypto order.

Create quote

POST with corridor, customer, and payment method details.

Show pricing

Display returned amounts and payment instructions to the user (OnRamp).

POST /partner/orders/{quote_id}/accept when the user confirms.

Discovery before quote

GET /partner/catalog or GET /partner/payment-methods → rails for the corridor
GET /partner/catalog?order_type=OnRamp or OffRamp → providers[].id for momo/bank
GET /partner/order-requirements → exact field names (network_id required for momo/bank)
GET /partner/banks → bank institution UUIDs where applicable

Payment method by rail

mobile_money

payment_method.type=mobile_money
payment_method.phone_number (E.164)
payment_method.network_id (UUID from catalog providers[].id)

bank

payment_method.type=bank
account_number, account_name
payment_method.network_id (from GET /partner/banks or catalog)

provider is optional — when omitted, ElementPay auto-routes by corridor.

Quote IDs

OnRamp: yc_receive_<id>
OffRamp: yc_send_<id>

The quote expires at data.expires_at.

Authorizations

X-API-Key

string

header

required

Body

application/json

Generic partner quote request for the quote -> accept -> webhook flow. provider is optional. When omitted, the partner order router selects the route from country, currency, order type, payment method, asset, and amount. New partner integrations should use the canonical asset, customer, and payment_method blocks. For local fiat rail momo/bank, payment_method.network_id is required (catalog or GET /banks). For mobile money MSISDN, use payment_method.phone_number only — do not fall back to customer.phone. Legacy provider-specific blocks (destination, etc.) are still accepted and mapped to the canonical request fields.

order_type

any

required

OnRamp/0 = fiat to crypto. OffRamp/1 = crypto to fiat.

Available options:

OnRamp,

OffRamp,

onramp,

offramp,

0,

1

provider

enum<string> | null

Optional route override. Omit for ElementPay auto-routing. Use elementpay for native on-chain routes; local fiat rail and international bank for ramp providers.

Available options:

local fiat rail,

international bank,

elementpay,

native

token

string | null

Token contract address or route token hint. local fiat rail currently requires Base USDC or Polygon USDT address.

channel_id

string | null

Minimum string length: 1

channel_type

string | null

sequence_id

string | null

currency

string | null

Required string length: 3

country

string | null

Required string length: 2

reason

string

default:other

customer_uid

string | null

customer_type

enum<string>

default:retail

Available options:

retail,

institution

asset

Asset · object | null

Canonical crypto asset block. Use token for contract-address based routes and currency + network for provider currency routes.

subject_type

enum<string> | null

Stable subject type for providers that require pre-approved PSP customer links (for example international bank USD/EUR IBAN payins).

Available options:

user,

organization

subject_id

string | null

Stable subject id used to resolve provider approval/onboarding state.

Maximum string length: 64

crypto_currency

string | null

Provider crypto currency hint, e.g. USDC or USDC_TEST for international bank.

crypto_network

string | null

Provider network hint, e.g. Base or PolygonTestAmoy for international bank.

amount

local_amount

integer | null

Required range: x >= 1

fiat_amount

integer | null

Required range: x >= 1

crypto_amount

Required range: x > 0

customer

Customer · object | null

Provider-neutral customer details. Retail: personal KYC fields (name, dob, id_number, …). Institution (type: institution with top-level customer_type: institution): uid, business_name, business_id (legal registration/tax id of the paying business), and email — no DOB / national ID / personal name. Used to derive provider party details when provider-specific fields are omitted.

payment_method

Payment Method · object | null

Provider-neutral fiat rail. For type: mobile_money use phone_number (MSISDN) and network_id (institution UUID from catalog providers[].id). For type: bank use account_number, account_name, and network_id (UUID from GET /banks or catalog). Do not use top-level legacy fields.

recipient

Recipient · object | null

source

Source · object | null

sender

Sender · object | null

destination

Destination · object | null

wallet_address

string | null

wallet_tag

string | null

refund_address

string | null

sender_address

string | null

refund_to_source_address

boolean

default:false

redirect_url

string | null

Response

Partner order quote created

​Discovery before quote

​Payment method by rail

​Quote IDs

Authorizations

Body

Response

Discovery before quote

Payment method by rail

Quote IDs