Create Payment Invoice
Submission URL: https://openapi.basicex.com/v2/invoices
Request Method: POST
Content-Type:
application/json
Request Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| buyerId | No | string | Merchant-side customer identification number, used to identify the customer ID of the merchant side that paid the invoice |
| orderId | Yes | string | Internal order number on the merchant side, which must be unique within the same merchant, used to associate the payment invoice with the merchant order ID |
| fiat | No | string | BasicEx will convert to the corresponding amount of all cryptocurrencies based on this fiat currency, which can be selected by the customer for payment. If this field is provided, it must be either fiat or currency, not both.ISO 4217 3-digit fiat currency code, supported fiat currencies: CNY/USD/EUR/HKD/INR/IDR/PHP/THB |
| currency | No | string | Cryptocurrency, for example: BCNY (recommended, 1:1 with CNY), USDT, BTC, etc. View currency list. If this parameter is provided, the invoice can only be paid with this cryptocurrency. If this field is provided, it must be either fiat or currency, not both |
| forcedChain | No | string | Force selection of a specified public chain, for example: TRC20, ERC20 View blockchain list. If this parameter is provided, users can only pay on the specified public chain and cannot use the BasicEx wallet for payment |
| amount | Yes | decimal | The amount field, combined with the precision precision field, in integer format. For example, if precision is 2 (amount ÷ 10²), the user pays 2.00, you need to pass 200 |
| precision | Yes | int | Amount precision, recommended precision of 2-6 digits. |
| amountType | Yes | string | Amount type field, indicating whether the amount passed in is a fiat currency or a cryptocurrency amount.coin_amount cryptocurrency amount, money_price fiat currency amount |
| description | Yes | string | Product description field, which will be displayed on the checkout page for product details |
| metadata | No | json | Structured metadata passed in for the merchant's own record, this field will be returned as-is in subsequent responses |
| payerEmail | No | string | Customer email on the merchant's side. If provided, an email will be sent to this address after the invoice payment is successful |
| notificationUrl | Yes | string | The URL for webhook notifications to be sent to the merchant's specified address, must be HTTPS |
| redirectUrl | No | string | After the user successfully pays on the checkout page, they will be redirected to this address. The address must start with https or http |
| buyerIp | No | string | Customer's IP address on the merchant's side |
| sendPaidNotification | No | bool | Whether to send notification data for the paid state. Default is false. If set to true, BasicEx will send a paid status notification after receiving the user's transfer payment and confirming one block on the blockchain.Based on the characteristics of the blockchain, this does not mean that the order is completely valid. BasicEx will send a complete status notification after confirming that the transaction is successful and irreversible. This process may take some time |
| physical | No | bool | Whether it is a physical product, default is false, set to true if it's a physical product |
Response Parameters
BasicEx payment response parameters, specific values depend on business requirements.
After a successful order request, the response code is 0000.
InvoiceObject
Payment invoice response parameters
| Field | Type | Description |
|---|---|---|
| invoiceId | string | Payment invoice order ID |
| merOrderId | string | Internal order number on the merchant side |
| fiat | string | ISO 4217 3-digit fiat currency code |
| currency | string | If the payment invoice order restricts the payment currency or chooses the payment currency, this field is returned |
| currencyInfo | CoinInfo | If the payment invoice order restricts the payment network or chooses the payment network, this field is returned View details |
| forcedChain | string | If the payment invoice order restricts the payment network or chooses the payment network, this field is returned View details |
| fiatAmount | string | The fiat amount of the payment invoice |
| fiatInfo | FiatCurrencyInfo | Fiat currency details View details |
| description | string | Description of the payment invoice order |
| metadata | map | Structured metadata passed in for the merchant's own record, this field will be returned as-is in subsequent responses |
| payerEmail | string | Customer email on the merchant's side |
| merchantCode | string | Merchant code |
| merchantName | string | Merchant name |
| currencies | List | List of supported cryptocurrency information |
| fiatCurrencies | List | List of supported fiat currency information |
| paymentInfo | InvoicePaymentInfo | Payment information View details |
| exchangeRate | InvoiceExchangeRate | Exchange rate information |
| type | int | Payment invoice order type, this order type is read in XOR form. 1. FIAT_CURRENCY_EXCHANGE: Indicates that the payment invoice is created in the form of fiat currency exchange cryptocurrency2. FORCE_SELECTED_CHAIN: Indicates that the payment invoice is created in the form of forcibly selecting a public chain, and the currency and payment public chain cannot be changed later. Only payments on this chain are supported3. FORCE_SELECTED_COIN: Indicates that the payment invoice is created in the form of forcibly selecting a cryptocurrency currency, and the currency cannot be changed later, only this currency is supported for payment |
| status | string | The current status of the payment invoice (created: indicates that the payment invoice is created but not paid, completed: indicates that the payment invoice has been paid and completed, expired: indicates that the payment invoice has expired) |
| invoiceTime | long | Creation time of the payment invoice (13 digits) |
| expirationTime | long | Expiration time of the payment invoice (13 digits) |
| cashierUrl | string | The BasicEx cashier order URL corresponding to the payment invoice, which can be used to pay this unpaid order again to avoid multiple submissions of unpaid orders by users |
CoinInfo
Coin information
| Field | Type | Description |
|---|---|---|
| currency | string | Currency name |
| fullName | string | Full name of the currency |
| coinIcon | string | Currency icon |
| precision | string | Currency precision |
| networkList | string | List of supported blockchain networks for the currency |
CoinChainInfo
Blockchain information
| Field | Type | Description |
|---|---|---|
| network | string | Blockchain network name |
| fullName | string | Blockchain network full name |
| contractAddress | string | Contract address |
FiatCurrencyInfo
Fiat currency information
| Field | Type | Description |
|---|---|---|
| fullName | string | Full name of the fiat currency |
| name | string | Fiat currency name |
| symbol | string | Currency symbol |
| icon | string | Currency icon |
InvoicePaymentInfo
Invoice order information
| Field | Type | Description |
|---|---|---|
| allowPayment | string | Whether payment is allowed. If true, it means that this payment order allows payment. If false, it means that the preconditions are not met, such as no payment amount, no selected currency, no selected public chain, or the receiving address has expired, etc |
| payeeAddress | string | Payee address, the actual address where the user completes the transfer payment |
| network | CoinChainInfo | Network information View details |
| totalAmount | string | The total amount the user needs to pay |
| paidAmount | string | The amount the user has paid |
| payeeAddressExpireTime | int | Payee address expiration time, in milliseconds, the payment or re-acquiring the payee address must be completed before the expiration time |