Skip to main content

On-ramp APIs — Typical Flow

On-ramp APIs allow partners to offer a Binance-powered hosted fiat-to-crypto purchase flow. A user can start from the partner application, get redirected to the Binance-hosted checkout, complete payment through supported payment methods, and receive the purchased crypto at the configured destination.

When to use On-ramp APIs​

Use On-ramp APIs when your application wants to help users acquire crypto through a hosted Binance-powered purchase flow.

Core Integration APIs used by this flow​

On-ramp APIs use the shared Core Integration APIs for discovery, quote, order creation, order query, and webhook handling:

  • Get Supported Trading Pairs
  • Get Supported Crypto Networks
  • Get Payment Method List
  • Get Estimated Quote
  • Create Order Link
  • Query Order Details
  • Order Status Webhook

Overview​

This document describes the standard cryptocurrency purchase flow using Binance Pay Onchain's on-ramp service. The sequence diagram below illustrates the interaction between partner systems and Binance Pay Onchain APIs throughout the purchase process.

Flow Steps​

1. Initialize​

  • Partner frontend renders the buy interface for users
  • Backend provides necessary configuration and settings (when applicable)

2. Query Options​

  • Fetch supported blockchain networks for crypto delivery
  • Retrieve available trading pairs
  • Get supported payment methods
  • Return data to the frontend
    • You can be done in parallel. Depending on your UI/UX design, you may choose to call these APIs in different sequences.

3. Get Quote​

  • Request real-time price quote for the selected trading pair, payment method and amount
  • Display quote information to the user

4. Create PreOrder​

  • Submit pre-order request to Binance Pay Onchain with user's selection
  • Receive a redirect URL for payment processing

5. Payment​

  • Redirect user to Binance
  • User completes the purchase using their preferred payment method
  • Binance processes the transaction

6. Confirmation​

  • Receive webhook notifications for order status updates
  • Query order details to confirm final transaction status
  • Update user interface with purchase results and crypto delivery details

buy-flow.png

The examples below use Create Order Link. Replace sample values with your own order ID, destination wallet address, redirect URLs, asset, network, and enabled payment methods.

Example 1 — Fixed fiat amount on-ramp​

Use this pattern when the user chooses how much fiat to spend and receives the quoted crypto amount.

{
  "externalOrderId": "ramp-20260709-001",
  "fiatCurrency": "EUR",
  "cryptoCurrency": "USDT",
  "amountType": 1,
  "requestedAmount": "100",
  "payMethodCode": "BUY_CARD",
  "payMethodSubCode": "card",
  "network": "BSC",
  "address": "0xbb4CdB9CBd3AB01bD10BaEBF2De08d9173bc095c",
  "redirectUrl": "https://partner.example.com/ramp/success",
  "failRedirectUrl": "https://partner.example.com/ramp/failure",
  "clientType": "web",
  "customization": {
    "AUTO_REDIRECTION": true,
  },
}

Example 2 — Fixed crypto amount on-ramp​

Use this pattern when the user chooses the crypto amount they want to receive. The required fiat amount is determined by quote and checkout.

{
  "externalOrderId": "ramp-20260709-002",
  "fiatCurrency": "EUR",
  "cryptoCurrency": "USDT",
  "amountType": 2,
  "requestedAmount": "50",
  "payMethodCode": "BUY_CARD",
  "payMethodSubCode": "card",
  "network": "BSC",
  "address": "0xbb4CdB9CBd3AB01bD10BaEBF2De08d9173bc095c",
  "redirectUrl": "https://partner.example.com/ramp/success",
  "failRedirectUrl": "https://partner.example.com/ramp/failure",
  "customization": {
    "LOCK_ORDER_ATTRIBUTES": [6],
    "AUTO_REDIRECTION": true,
  },
}

Example 3 — Let Binance-hosted checkout show available payment methods​

Use this pattern when the partner does not want to preselect a payment method. Binance can show available payment options based on the user, market, fiat currency, asset, amount, and enabled configuration.

{
  "externalOrderId": "ramp-20260709-003",
  "fiatCurrency": "EUR",
  "cryptoCurrency": "USDT",
  "amountType": 1,
  "requestedAmount": "100",
  "network": "BSC",
  "address": "0xbb4CdB9CBd3AB01bD10BaEBF2De08d9173bc095c",
  "redirectUrl": "https://partner.example.com/ramp/success",
  "failRedirectUrl": "https://partner.example.com/ramp/failure",
  "customization": {
    "AUTO_REDIRECTION": true,
  },
}

Example 4 — P2P payment method selected​

Use this pattern when the partner wants to route the user to a P2P-supported on-ramp method where available and enabled.

{
  "externalOrderId": "ramp-20260709-004",
  "fiatCurrency": "EUR",
  "cryptoCurrency": "USDT",
  "amountType": 1,
  "requestedAmount": "100",
  "payMethodCode": "BUY_P2P",
  "payMethodSubCode": "BANK",
  "network": "BSC",
  "address": "0xbb4CdB9CBd3AB01bD10BaEBF2De08d9173bc095c",
  "redirectUrl": "https://partner.example.com/ramp/success",
  "failRedirectUrl": "https://partner.example.com/ramp/failure",
  "customization": {
    "P2P_EXPRESS": true,
    "AUTO_REDIRECTION": true,
  },
}

Example 5 — Locked checkout attributes​

Use this pattern when the partner needs the user to complete the checkout using the order attributes defined by the partner. This is useful when the partner must keep selected order details fixed after creating the order link.

{
  "externalOrderId": "ramp-20260709-005",
  "fiatCurrency": "EUR",
  "cryptoCurrency": "USDT",
  "amountType": 2,
  "requestedAmount": "100",
  "payMethodCode": "BUY_CARD",
  "payMethodSubCode": "card",
  "network": "BSC",
  "address": "0xbb4CdB9CBd3AB01bD10BaEBF2De08d9173bc095c",
  "redirectUrl": "https://partner.example.com/ramp/success",
  "failRedirectUrl": "https://partner.example.com/ramp/failure",
  "customization": {
    "LOCK_ORDER_ATTRIBUTES": [6],
    "AUTO_REDIRECTION": true,
  },
}

Mix and match customization​

The payloads above are examples of common partner patterns. Partners can combine available request fields and approved customization keys to match their checkout requirements.

Partner needFields or customization to consider
User spends a fixed fiat amountamountType: 1, requestedAmount, fiatCurrency
User receives a fixed crypto amountamountType: 2, requestedAmount, cryptoCurrency, optionally LOCK_ORDER_ATTRIBUTES
Partner wants to preselect payment methodpayMethodCode, payMethodSubCode
Partner wants Binance to show available choicesOmit payMethodCode and payMethodSubCode where supported
Partner wants to keep selected order details fixedLOCK_ORDER_ATTRIBUTES, if approved and enabled

Important: The payloads above show request patterns using existing fields. Actual supported assets, networks, payment methods, and customization keys depend on partner enablement and should be confirmed with Binance before production use.

Depending on partner eligibility and product setup, On-ramp APIs may be used together with customized checkout behavior, Smart Convert Top-Up, Buy Any Token / Swap, supported asset configuration, supported network configuration, and payment method configuration.