Overview

The iBitPay OpenAPI lets your system collect fiat from customers (pay-ins) and pay fiat to recipients (payouts). The platform settles with you in USDT at the applicable rate.

Getting set up

1. Activation: contact the platform to open a merchant account and enable the OpenAPI.
2. Get your API base URL and keys: in the merchant console, open Developers → API & callbacks to view the API base URL, your public key and private key (security verification and your fund password are required). Don't publish the base URL or the keys — see the security checklist.
3. IP whitelist: add the outbound IP of every server that calls the API. Requests from other IPs are rejected (40005).
4. Callback URLs: set a pay-in callback URL and a payout callback URL (must be https). You can also set one per order.
5. Integration testing: ask the platform to route your account to test traders first, run small orders through creation, callbacks and queries, then open it to your customers.

API base URL

The API base URL is shown in the merchant console under Developers → API & callbacks, on the same page as your keys. The full URL of each endpoint is the base URL followed by the path in these docs, e.g. base URL + /api/open/order/createBuyOrder.

Conventions

• Requests: always POST with Content-Type: application/json. Business parameters are encrypted first and placed in the request body — see Request format & encryption.

• Responses: the HTTP status is always 200. Check code in the body:

  { "code": 0, "message": "success", "data": { } }

  code 0 means success; other values are listed in Error codes. message is in English. Responses are not encrypted.

• Field names: response fields are camelCase (e.g. merchantOrderNo); request field names are case-insensitive.

• Amounts: fiat amounts must be greater than 0 with at most two decimal places. Numbers in responses are rounded to at most two decimals (rates included). Use a decimal type for money and never compare floating-point values directly.

• Times: yyyy-MM-dd HH:mm:ss, UTC+8, without a time zone suffix.

• Empty values: text fields without a value are returned as "", not null.

• Merchant order number: generate and store a unique merchantOrderNo for every order. Queries, reconciliation and callback checks all rely on it. The same number cannot be used twice (40007), which also prevents duplicate payouts when you retry after a timeout.

• Rate limits: the platform blocks IPs that send too many requests in a short time. Stay below about 10 requests per second, don't poll queries aggressively, and rely on callbacks for completion.

Pay-in flow

1. Call Create pay-in order, get the checkout URL and send the customer there.
2. The customer pays to the account shown on the checkout page.
3. Once the platform confirms the money, the order becomes Released (6) and the platform calls your pay-in callback URL.
4. On the callback, first verify the state and amount with Get order, then credit your customer and reply success.
5. The platform receives success and the order becomes Success (3). The USDT was credited to your balance when the order was released.

For your own checkout page, see Create pay-in order (own checkout).

Payout flow

1. (Optional) Call List payout methods to see which recipient details each currency needs.
2. Call Create payout order. The platform converts the amount at the payout rate, then deducts and freezes the USDT from your balance.
3. When the payout succeeds (4) or is refused (5), the platform calls your payout callback URL. Refused payouts are refunded.
4. Verify with Get order before updating your own records.

Endpoints

Area	Endpoint	Path
Pay-in	Create pay-in order (hosted checkout)	/api/open/order/createBuyOrder
Pay-in	Create pay-in order (own checkout)	/api/open/order/createBuyOrder2
Pay-in	Mark as paid	/api/open/order/complete2
Pay-in	Cancel order	/api/open/order/cancel2
Pay-in	Get pay-in rate	/api/open/order/getBuyRate
Payout	Create payout order	/api/open/order/createSellOrder
Payout	Get payout rate	/api/open/order/getSellRate
Payout	List payout methods	/api/open/order/getPaymentMethods
Query	Get order	/api/open/order/getDetail
Query	Get balance	/api/open/order/getBalance
Query	List balance flows	/api/open/order/getFlows
Query	List blacklist	/api/open/blocked/user/list