Create an onramp

curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "customer_id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
    "quote_id": "qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": { "address": "6KhMtrKUhYGqVVgV6fcr1Vr1XnQtZCrDwpXTNZHPiReR", "network": "solana" }
    }
  }'

curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1002" \
  -d '{
    "customer_id": "cus_2mQ9xLp3VnR7tY1wZ4cB6dE8fK",
    "quote_id": "qte_2mQ9xLp3VnR7tY1wZ4cB6dE8fK",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": { "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed", "network": "base" }
    },
    "payer": {
      "type": "momo",
      "currency": "GHS",
      "details": { "bank_code": "0004", "account_number": "0241234567", "account_name": "Kwame Mensah" }
    }
  }'

{
  "status": "success",
  "message": "Onramp payment initiated",
  "payment": {
    "id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
    "status": "pending",
    "state": "initiated",
    "event_id": "evt_2cB6dE8fK2mQ9xLp3VnR7tY1wZ",
    "deposit": {
      "type": "bank_transfer",
      "currency": "NGN",
      "details": {
        "account_name": "Bridge / Ada Obi",
        "account_number": "9912345678",
        "bank_name": "Example Bank"
      },
      "amount": "150000",
      "amount_expected": "150150",
      "processor_fee": "150"
    }
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "quote_expired",
    "message": "Quote qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ has expired",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 400
  }
}

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Wallet network must match the quote network",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 422,
    "errors": [
      { "field": "payment_details.details.network", "message": "Wallet network must match the quote network" }
    ]
  }
}

POST

payments

onramp

curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "customer_id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
    "quote_id": "qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": { "address": "6KhMtrKUhYGqVVgV6fcr1Vr1XnQtZCrDwpXTNZHPiReR", "network": "solana" }
    }
  }'

curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1002" \
  -d '{
    "customer_id": "cus_2mQ9xLp3VnR7tY1wZ4cB6dE8fK",
    "quote_id": "qte_2mQ9xLp3VnR7tY1wZ4cB6dE8fK",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": { "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed", "network": "base" }
    },
    "payer": {
      "type": "momo",
      "currency": "GHS",
      "details": { "bank_code": "0004", "account_number": "0241234567", "account_name": "Kwame Mensah" }
    }
  }'

{
  "status": "success",
  "message": "Onramp payment initiated",
  "payment": {
    "id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
    "status": "pending",
    "state": "initiated",
    "event_id": "evt_2cB6dE8fK2mQ9xLp3VnR7tY1wZ",
    "deposit": {
      "type": "bank_transfer",
      "currency": "NGN",
      "details": {
        "account_name": "Bridge / Ada Obi",
        "account_number": "9912345678",
        "bank_name": "Example Bank"
      },
      "amount": "150000",
      "amount_expected": "150150",
      "processor_fee": "150"
    }
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "quote_expired",
    "message": "Quote qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ has expired",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 400
  }
}

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Wallet network must match the quote network",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 422,
    "errors": [
      { "field": "payment_details.details.network", "message": "Wallet network must match the quote network" }
    ]
  }
}

Requires the Ramps, banks & methods scope (onramp write). See Onramp for a walkthrough. Onramps are always first party: the customer pays for themselves and receives the stablecoin in their own wallet.

Headers

string

default:"2026-10-29-atlas"

required

Your account’s API version.

string

Recommended. A unique value so retries don’t create a second payment.

Body

string

required

The customer. Must match the quote’s customer.

string

required

An unexpired, unused onramp quote.

object

required

The wallet that receives the stablecoin.

Show fields

string

required

Always stablecoin.

string

required

Must match the quote’s target_currency.

string

required

The wallet address. Must be valid for the network.

string

required

Must match the quote’s network.

object

Required for mobile money. The wallet that pays.

Show fields

string

required

momo. Must match the quote’s payment_method.

string

required

The fiat currency, for example GHS. Must match the quote’s source_currency.

string

required

The network code, for example 0004 for MTN.

string

required

The mobile money number, 10 to 12 digits.

string

required

The name the wallet is registered to.

Response

202 Accepted

string

success

string

Onramp payment initiated

object

Show fields

string

Payment ID, starting with pay_.

string

pending

string

The current state, usually initiated.

string

The first event’s ID.

string

Sometimes included. Useful for support.

object

Where the customer pays.

Show fields

string

bank_transfer or momo.

string

The fiat currency, for example NGN or GHS.

object

Bank transfer: account_name, account_number, bank_name. Mobile money: phone_number, network, next_step, instruction.

string

The quoted amount.

string

The exact amount the customer must send, including any fees.

string

Processing fee, if any.

string

VAT on the fee, if any.

string

Sometimes included. Extra instructions.

Errors

Status	Code	Why
`422`	`validation_failed`	A field is wrong. See the common messages.
`400`	`quote_expired`	The quote has expired.
`409`	`quote_locked`	The quote has already been used.
`404`	`quote_not_found`	No such quote.
`404`	`customer_not_found`	No such customer.
`409`	`customer_banned`	The customer is banned.
`403`	`pair_not_enabled`	The pair is turned off.
`409`	`idempotency_conflict`	Same key still running, or used with a different body.
`422`	`payment_processing_failed`	Our partner couldn’t create the payment.
`503`	`route_temporarily_unavailable`	The route is temporarily down.
`504`	`request_timeout`	A partner took too long. Retry with the same `Idempotency-Key`.

curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001" \
  -d '{
    "customer_id": "cus_4hT9pL2mQx8VnR3tY7wZ1cB5dE",
    "quote_id": "qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": { "address": "6KhMtrKUhYGqVVgV6fcr1Vr1XnQtZCrDwpXTNZHPiReR", "network": "solana" }
    }
  }'

curl -X POST https://sandbox.core.linkio.world/api/payments/onramp \
  -H "X-BRIDGE-API-Key: $BRIDGE_API_KEY" \
  -H "API-Version: 2026-10-29-atlas" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1002" \
  -d '{
    "customer_id": "cus_2mQ9xLp3VnR7tY1wZ4cB6dE8fK",
    "quote_id": "qte_2mQ9xLp3VnR7tY1wZ4cB6dE8fK",
    "payment_details": {
      "type": "stablecoin",
      "currency": "USDC",
      "details": { "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed", "network": "base" }
    },
    "payer": {
      "type": "momo",
      "currency": "GHS",
      "details": { "bank_code": "0004", "account_number": "0241234567", "account_name": "Kwame Mensah" }
    }
  }'

{
  "status": "success",
  "message": "Onramp payment initiated",
  "payment": {
    "id": "pay_8fK2mQ9xLp3VnR7tY1wZ4cB6dE",
    "status": "pending",
    "state": "initiated",
    "event_id": "evt_2cB6dE8fK2mQ9xLp3VnR7tY1wZ",
    "deposit": {
      "type": "bank_transfer",
      "currency": "NGN",
      "details": {
        "account_name": "Bridge / Ada Obi",
        "account_number": "9912345678",
        "bank_name": "Example Bank"
      },
      "amount": "150000",
      "amount_expected": "150150",
      "processor_fee": "150"
    }
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "quote_expired",
    "message": "Quote qte_9xLp3VnR7tY1wZ4cB6dE8fK2mQ has expired",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 400
  }
}

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "Wallet network must match the quote network",
    "request_id": "req_3VnR7tY1wZ4cB6dE8fK2mQ9xLp",
    "status": 422,
    "errors": [
      { "field": "payment_details.details.network", "message": "Wallet network must match the quote network" }
    ]
  }
}

Last modified on October 29, 2026

Overview

Customers

Quotes

Payments

Lookups

Headers

Body

Response

Errors

​Headers

​Body

​Response

​Errors

Headers

Body

Response

Errors