Skip to main content

Binance Pay Prime API Requirements Document

Table of Contents​

The purpose of this API document is to enable seamless integration between merchant side and Binance Pay Prime, facilitating efficient transaction processing, data retrieval, and other essential operations. The document details the endpoints, request and response formats, authentication methods, and error handling protocols to ensure a clear and consistent implementation.

General API Convention​

Base URL​

  • Production environment URL (real money)
  • Testing/Sandbox environment URL (test money)

Authorization (flexible)​

Below are two common authorization methods for demonstration purposes. The authorization details can be discussed at a later time.

Token-based authentication:

  • HTTP header: Authorization: Bearer <access_token>

Private-Public-Key signing

  • Account-based authentication

API Response Envelope​

Response envelope:

  • All endpoints return HTTP code with a JSON body

Buy flow​

Check merchant side transaction status API:​

General Buy Flow:​

  1. On Merchant Side, user transfers fiat to Binance's account
  2. The merchant will call our API to execute the quote, providing information about the transaction in step (1) (e.g. transactionId, orderId, etc…)
  3. Binance will verify that we have received the fiat from the user
  4. After confirming fiat funds have been received, Binance releases crypto to the user

Minimum Requirements​

To facilitate point (2), we would require an endpoint that allows us to check the status of the transaction sent by the user. The transaction status should be exhaustive, ideally an enum. Here's an example:

public enum TransactionStatus {
    PENDING(0),
    COMPLETED(0),
    FAILED(0),
}

Refund API (BUY)​

General Refund Flow (BUY):​

  1. On Merchant Side, user transfers fiat to Binance's account
  2. The merchant will call our API to execute the quote, providing information about the transaction in step (1) (e.g. transactionId, etc…)
  3. Binance will verify that we have received the fiat from the user
  4. Binance executes buy transaction based on the given quote
  5. Quote has expired
  6. Binance calls a provided endpoint to refund fiat back to user

Minimum Requirements​

Since fiat funds are already transferred before buy flow was initiated on Binance's side, we need to refund the user in the event we are unable to process the given quote. We would need:

  • An endpoint that allows Binance to refund the user's fiat transfer in step (1) back to the user.
  • An endpoint that allows Binance to check the status of the refund.

Refund API Specification​

Request: Binance will call the merchant's refund endpoint with the following parameter:

FieldTypeMandatoryRemarks
clientOrderIdstringYesThe unique order ID originally provided by the merchant during Execute Quote. This is the sole identifier for the refund — no userId or additional fields are required.

Request Example:

{
  "clientOrderId": "YOUR_UNIQUE_ORDER_ID_001"
}

Response: The merchant should return the refund status:

FieldTypeMandatoryRemarks
refundIdstringYesMerchant-side unique refund identifier
statusstringYesRefund status: PENDING, COMPLETED, FAILED

Response Example:

{
  "success": true,
  "code": "000000",
  "data": {
    "refundId": "refund_abc123",
    "status": "PENDING"
  }
}

Key Design Points:

  • clientOrderId is the only identifier needed to locate the original transaction. The merchant should be able to look up the user and transaction details on their side using this ID alone.
  • The refund endpoint must be idempotent: calling it multiple times with the same clientOrderId should not create duplicate refunds.
  • Binance will subsequently call the refund status check endpoint with the same clientOrderId (or refundId) to poll for refund completion.

Sell flow​

Transfer API​

General Sell Flow:​

  1. Merchant calls Binance API to execute sell quote
  2. Binance will calculate the corresponding fiat amount based on the given quote.
  3. Binance will call Merchant's API to transfer the fiat amount calculated in step (2) to the user's account

Minimum Requirements​

Since Binance will be transferring fiat to the user, we would need:

  • An endpoint to initiate a fiat fund transfer to a user
  • An endpoint that allows Binance to check the status of the refund.

Miscellaneous Requirements​

Get historical transaction list​

For book-keeping purposes, Binance performs T+1 reconciliation. We would require an endpoint that allows us to fetch our past transactions.

Key Information that's required:

  • transactionId / orderId
  • Fiat currency and amount
  • Direction (transfer IN or OUT)
  • CreatedAt Timestamp (when the transaction was initiated)
  • CompletedAt Timestamp (when the transaction finished processing)

General Key Notes:​

  • For each unique transaction, Idempotency must be ensured. (i.e. transactionId, orderId must be unique)