On-ramp (Buy) APIs

Copy page

Query order details

Code
POST /papi/v1/ramp/connect/order

Request Body

Field	Type	Mandatory	Remarks
externalOrderId	string	Yes	The unique order id from the partner side.
language	string	No	Language code, which determines the multi-language of the content(if any, such as "payment method name") in the response data. If not passed, English is the default. The format is "LanguageCode-RegionCode", RegionCode is optional.

Response Body

Field	Type	Remarks
externalOrderId	string	The unique order id from the partner side.
type	int	1: buy, 2: sell, 3: send*
status	int	Please refer to "Order status"
fiatCurrency	string	fiat currency
cryptoCurrency	string	crypto currency
openUserId	string	OpenUserId represents a Binance user ID that has been securely hashed. This field is provided to merchants to facilitate the identification of whether multiple orders originate from the same user.
fiatAmount	string	fiat amount
cryptoAmount	string	crypto amount
paymentMethod	object	payment method
feeAmount	string	total fee amount
feeCurrency	string	fee currency, fiat currency or crypto
revenueAmount	string	partner revenue amount
revenueCurrency	string	partner revenue currency, fiat currency or crypto
networkFee	string	network fee amount
withdrawWalletAddress	string	withdraw wallet address
withdrawNetwork	string	withdraw network
withdrawMemo	string	withdraw network memo
withdrawTxHash	string	withdraw tx hash
orderDetailLink	string	order detail link
orderTime	timestamp	order time
completionTime	timestamp	completion time
convertInfo	object	Convert information. This field is only present for Convert orders. Refer to ConvertInfo
swapDetailInfoVo.fromCryptoCurrencyContractAddress	string	swap information. The from crypto currency contract address. Basically, it's stable coin and same with cryptoCurrecny field
swapDetailInfoVo.toCryptoCurrencyContractAddress	string	swap information. The to crypto currency contract address. The target token that user want to buy
swapDetailInfoVo.toCryptoCurrencyAmount	string	swap information. The amount of the target token the user purchased.
userData	string	AES-encrypted JSON string (see details below). Disabled by default; contact us to enable

ConvertInfo

Field	Type	Remarks
fromCoin	string	The source cryptocurrency being converted from
fromCoinAmount	string	The amount of source cryptocurrency being converted

userData field

• Type: string

• Remarks: When enabled, userData contains a JSON object (serialized to a string) that is encrypted with AES. The field value is the AES-encrypted ciphertext encoded as a string. This field is disabled by default — please contact us if you need it enabled and for access to the AES key and configuration.

• Decryption reference: follow the AES decryption instructions described in Binance documentation

• JSON structure (plaintext before AES encryption):

Field	Type	Remarks
firstName	string	User's first name
middleName	string	User's middle name (optional)
lastName	string	User's last name
residenceCountry	string	Country code of residence (ISO)
birthday	string	Birthday in YYYY-MM-DD format
country	string	Country code (ISO)
refundAddress	string	Refund crypto address (if any)
refundNetwork	string	Network of refund (e.g., ETH)
refundMemo	string	Refund memo/memo field (if any)

Notes:

• Field names and types above show the expected JSON keys that will be present after decrypting userData.
• The concrete AES parameters (mode, IV, padding) and key delivery method will be provided when the field is enabled; see the decryption reference link above for an example.

Example 1

Request Parameters:

Code
{
  "externalOrderId": "180401941923045",
  "language": "zh-CN"
}

Response:

Code
{
  "success": true,
  "code": "000000",
  "message": "success",
  "data": {
    "externalOrderId": "180401941923045",
    "type": 1,
    "status": 11,
    "fiatCurrency": "EUR",
    "cryptoCurrency": "USDT",
    "openUserId": "f47ac10b58cc4372a5670e02b2c3d479",
    "fiatAmount": "100",
    "cryptoAmount": "889.35",
    "paymentMethod": {
      "payMethodCode": "BUY_CARD",
      "payMethodSubCode": "card",
      "paymentMethod": "Card (VISA/Mastercard)",
      "p2p": false,
      "withdrawRestriction": 0
    },
    "feeAmount": "1",
    "feeCurrency": "EUR",
    "revenueAmount": "0.3",
    "revenueCurrency": "EUR",
    "networkFee": "0.5",
    "withdrawWalletAddress": "0xbb4CdB98Bd36B01bD1cBaEA52De08d9173bc095c",
    "withdrawNetwork": "ETH",
    "withdrawMemo": "",
    "withdrawTxHash": "0xcb163e2e6322cd6aa7bc4d45306029e846c0c06e9cdee45a06e88801d1231e71",
    "orderDetailLink": "https://www.binance.com/en/my/wallet/exchange/buysell-history?type=buy",
    "orderTime": "1723186761000",
    "completionTime": "1723189981000"
  }
}

Example 2

Request Parameters:

Code
{
  "externalOrderId": "13402681029896",
  "language": "en"
}

Response:

Code
{
  "code": "000000",
  "message": "success",
  "data": {
    "externalOrderId": "13402681029896",
    "type": 1,
    "status": 20,
    "fiatCurrency": "EUR",
    "cryptoCurrency": "USDC",
    "openUserId": "f47ac10b58cc4372a5670e02b2c3d479",
    "fiatAmount": "15",
    "cryptoAmount": "16.78903899",
    "paymentMethod": {
      "payMethodCode": "BUY_WALLET",
      "payMethodSubCode": "Wallet",
      "paymentMethod": "Spot Account",
      "p2p": false,
      "withdrawRestriction": 0
    },
    "feeAmount": "1.001",
    "feeCurrency": "EUR",
    "networkFee": null,
    "withdrawWalletAddress": "3WZVn9cY4x8BBdpPsLEDG7LpthoDov4bUT11FvPCqvAA",
    "withdrawNetwork": "SOL",
    "withdrawMemo": "",
    "withdrawTxHash": null,
    "orderDetailLink": "https://www.binance.com/en/my/wallet/exchange/buysell-history?type=buy",
    "orderTime": 1746788679000,
    "completionTime": 1746788688982,
    "swapDetailInfoVo": {
      "fromCryptoCurrencyContractAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "toCryptoCurrencyContractAddress": "38PgzpJYu2HkiYvV8qePFakB8tuobPdGm2FFEn7Dpump",
      "toCryptoCurrencyAmount": 605.496926
    }
  },
  "success": true
}

Example 3 (Convert Order)

Request Parameters:

Code
{
  "externalOrderId": "830315252102",
  "language": "en"
}

Response:

Code
{
  "code": "000000",
  "message": "success",
  "data": {
    "externalOrderId": "830315252102",
    "type": 1,
    "status": 11,
    "openUserId": "09e03149752da10be5471c0c74f2811a",
    "fiatCurrency": "",
    "cryptoCurrency": "USDT",
    "fiatAmount": "0",
    "cryptoAmount": "1.03",
    "paymentMethod": {
      "payMethodCode": "SPOT",
      "payMethodSubCode": "CUMBERLAND",
      "paymentMethod": null,
      "p2p": false,
      "withdrawRestriction": null
    },
    "feeAmount": "0",
    "feeCurrency": "USDT",
    "networkFee": "0.03000000",
    "withdrawWalletAddress": "0xbb4CdB98Bd36B01bD1cBaEA52De08d9173bc095c",
    "withdrawNetwork": "ETH",
    "withdrawMemo": "",
    "withdrawTxHash": "",
    "orderDetailLink": null,
    "orderTime": 1753344231742,
    "completionTime": null,
    "swapDetailInfoVo": null,
    "convertInfo": {
      "fromCoin": "BNB",
      "fromCoinAmount": 0.00137386
    }
  },
  "success": true
}