Basics

Copy page

Binance Connect Prime API Requirements Document

Table of Contents

• General API Convention
  • Base URL
  • Authorization (flexible)
  • API Response Envelope
• Buy flow
  • Check merchant side transaction status API
    • General Buy Flow
    • Minimum Requirements
  • Refund API (BUY)
    • General Refund Flow (BUY)
    • Minimum Requirements
• Sell flow
  • Transfer API
    • General Sell Flow
    • Minimum Requirements
• Miscellaneous Requirements
  • Get historical transaction list
  • General Key Notes

---

The purpose of this API document is to enable seamless integration between merchant side and Binance Connect 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:

Code
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:

Field	Type	Mandatory	Remarks
clientOrderId	string	Yes	The 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:

Code
{
  "clientOrderId": "YOUR_UNIQUE_ORDER_ID_001"
}

Response: The merchant should return the refund status:

Field	Type	Mandatory	Remarks
refundId	string	Yes	Merchant-side unique refund identifier
status	string	Yes	Refund status: PENDING, COMPLETED, FAILED

Response Example:

Code
{
  "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)