# PayBox Open API ### PayBox Open API Documentation #### Introduction PayBox is a Web3 multi-chain asset aggregation payment system. By leveraging SwapBox's cross-chain exchange capability, merchants only need to select the asset they want to receive, while users can choose various on-chain assets they own for payment. Merchants do not need to worry about exchange slippage and rates. We hope this product will help more international internet products and game projects provide easy and fast access to blockchain asset payment capabilities. #### Integration Process 1. Web page to invoke PayBox payment page 2. Callback notification 3. Query interface 4. Demo #### 1. Integration Process **1.1. Requirements** * Register a Nabox ID account * Test environment registration: * Production environment registration: * Provide a callback URL for transaction notification * Create a PayBox cashier and payment QR code **1.2. Glossary** * **Business System:** The application system integrating with PayBox * **PayBox:** The PayBox cross-chain payment collection system * **Merchant:** The payment recipient entity registered in PayBox * **User:** The user of the business system * **Payment Chain:** The blockchain network where the user initiates the transaction * **Payment Asset:** The asset transferred by the user on the payment chain * **Collection Chain:** The blockchain network where the merchant receives the user's payment asset converted to USDT * **Collection Address:** The blockchain address used by the merchant when registering Nabox ID **1.3. Business Flow** 1. The business system creates a payment order number 2. Invoke the PayBox payment page, passing in the order number, payment amount, payment chain, etc. 3. The user completes the transaction on the PayBox payment page 4. PayBox completes the cross-chain asset exchange 5. PayBox notifies the business system of the completed transaction through the provided notification URL 6. The business system can query the transaction order information through the query interface **1.4. Sequence Diagram**
#### 2. Web Page to Invoke PayBox Payment Page * Testnet URL: * Mainnet URL: **Page Parameters:** \[Specify the required page parameters here] #### 3. Callback Notification When the transaction on the payment chain is confirmed and the asset is received on the collection chain, PayBox will call the merchant-provided callback URL to notify the transaction status. The callback URL needs to be provided in advance to PayBox for configuration. PayBox will sign the request parameters, and the business system should verify the signature to ensure reliability. * **Request Method:** POST * **Request Content-Type:** Application/json * **Request Parameters:** **TxState:** **Request Parameter Example:** ```json { "outerOrderNo": "A10001231023154807", "orderNo": "A10001230925165043", "fromTxHash": "dec04090fff51057dceb8f2d00da7f85bfbb78b303c97e54c808ed51a56014ad", "fromAmount": { "symbol": "NVT", "amount": "63.20416992", "cent": "6320416992", "decimal": 8 }, "fromAddress": "TNVTdTSPRgJo5kUEBRvqKWuLZYfNNksNsSTjt", "fromChain": "NERVE", "toAmount": { "symbol": "USDTN", "amount": "0.198", "cent": "198000000000000000", "decimal": 18 }, "payeeFee": { "symbol": "USDTN", "amount": "0.00786913", "cent": "7869133898641243", "decimal": 18 }, "toTxHash": "b9a6930b893f3f6f990e3c62700603e622e5f3adee48a2120bfefbf73e2b1f48", "toAddress": "TNVTdTSPTW9oftjhqLxZ7j9zq9W9cF8SqXqsd", "fromTimestamp": 1695631846, "toTimestamp": 1695631887, "txState": "Confirm", "sign": "304402206f32214fed292b82e49bb73ce204e4a739fa2fca68e5b6f9f4ee0df3b1619b89022055c0d19e7f8e95a24d8c3a4043ae50dbc925c97f22df86893614a0b0faa51a99", "sendTime": 1699004550 } ``` **Response:** SUCCESS/FAIL The callback notification will be triggered when the payment chain transaction is confirmed and when the asset is received at the collection address. Payment chain transaction confirmation will only be notified once, regardless of success. The collection address receipt notification will be retried if a response of SUCCESS is not received, or if the call fails. If all retry attempts fail, no further notifications will be sent. **Notification Time Series:** \[Specify the notification retry sequence here] **Signature Verification Method:** `ECKey.verify(key, sign, pubKey)` * **ECKey:** Implementation of the ECDSA algorithm (Elliptic Curve Digital Signature Algorithm) * **key:** The signed content, obtained by concatenating the `outerOrderNo` and `sendTime` parameters in the callback request. * **sign:** The signature value in the callback request's `sign` parameter * **pubKey:** The public key for signature verification * Testnet Public Key: `02a6b09b370bf0588e67547f1a5c375cf2d78c5af89a0ced775365ffecb517d8df` * Mainnet Public Key: `02b4bcc1ecbe8785fba3d592fea4dc74e9071fa7399a72cd43993046682c877261` **ECDSA Algorithm Java Package:** ```xml org.bitcoinj bitcoinj-core 0.16.1 ``` or ```xml network.nerve nerve-sdk4j 1.2.5 ``` **Example Code:** ```java public void handleOrderNotify( @RequestBody OuterOrderNotifyDto req, HttpServletResponse res, HttpServletRequest request ) throws IOException { log.info("req:{}", req); // Public key for signature verification byte[] pubKey = HexUtil.decode("02a6b09b370bf0588e67547f1a5c375cf2d78c5af89a0ced775365ffecb517d8df"); // Signature string: concatenation of business system order number and send time timestamp (in seconds) String key = req.getOuterOrderNo() + req.getSendTime(); byte[] keyByte = key.getBytes(StandardCharsets.UTF_8); byte[] sign = HexUtil.decode(req.getSign()); try { // Use the ECDSA algorithm to verify the signature boolean verify = ECKey.verify(keyByte, sign, pubKey); log.info("sign verify:{}", verify); if (verify) { log.info("Order completed"); // Obtain the order object for business processing } res.getWriter().write(verify ? "SUCCESS" : "FAIL"); } catch (Throwable e) { res.getWriter().write("FAIL"); } res.getWriter().flush(); res.getWriter().close(); } ``` #### 4. Query APIs **4.1. Get Supported Chains** * **Method:** GET * **Path:** `/chains` * **Parameters:** None * **Response Data:** * **chain** (string): Chain name * **logo** (string): Chain logo URL * **Response Example:** ```json { "code": 0, "msg": "Success", "data": [ { "chain": "Ethereum", "logo": "https://files.nabox.io/icon/Ethereum.png" }, { "chain": "BSC", "logo": "https://files.nabox.io/icon/BSC.png" }, { "chain": "Polygon", "logo": "https://files.nabox.io/icon/Polygon.png" }, { "chain": "TRON", "logo": "https://files.nabox.io/icon/tron.png" }, { "chain": "NULS", "logo": "https://files.nabox.io/icon/Nuls.png" }, { "chain": "NERVE", "logo": "https://files.nabox.io/icon/NERVE.png" } ] } ``` **4.2. Get Supported Assets of a Chain** * **Method:** GET * **Path:** `/{chain}/assets` * **Parameters:** * **chain** (string): Chain name from the previous API * **Response Data:** * **assetId** (string): Asset ID * **symbol** (string): Asset symbol * **logo** (string): Asset logo URL * **Response Example:** ```json { "code": 0, "msg": "Success", "data": [ { "assetId": "93043", "symbol": "NULS", "logo": "https://files.nabox.io/icon/NULS.png" }, { "assetId": "93051", "symbol": "NNERVENABOXTOMOON", "logo": "https://files.nabox.io/icon/NULL.png" }, { "assetId": "93093", "symbol": "NABOX", "logo": "https://files.nabox.io/icon/NULL.png" } ] } ``` **4.3. Calculate Exchange Price** * **Method:** GET * **Path:** `/asset/price` * **Parameters:** * **chain** (string): Payment chain name * **assetId** (string): Payment asset ID * **quantity** (integer, optional): Amount of USDT to receive, default is 1 if not specified * **Request URL Example:** ``` %URL%/asset/price?chain=NERVE&assetId=93059&quantity=10 ``` * **Response Data:** * **fromPayAmount** (Coin): Required payment asset amount * **fee** (Coin): Fee amount * **Coin Type:** ```json { "symbol": "NVT", // Asset symbol "amount": "68.57450743", // Asset amount "cent": "6857450743", // Amount in smallest unit "decimal": 8 // Decimal places } ``` * **Response Example:** ```json { "code": 0, "msg": "Success", "data": { "fromPayAmount": { "symbol": "NVT", "amount": "68.57450743", "cent": "6857450743", "decimal": 8 }, "fee": { "symbol": "NVT", "amount": "0", "cent": "0", "decimal": 8 } } } ``` **4.4. Query Order Information by Business Order Number** * **Method:** GET * **Path:** `/order/{address}/{outerOrderNo}` * **Parameters:** * **address** (string): Payment address * **outerOrderNo** (string): Business system order number, provided when initiating the payment page * **Request URL Example:** ``` %URL%/order/TNVTdTSPLtaRJ6SXKgoTfrE4qfDsK6YpuzRWy/A10001231023154807 ``` * **Response Data:** Data字段返回值： | Parameter Name | Type | Can be Null | Interpretation | | -------------- | ------- | ----------- | --------------------------------- | | ourderOrderNo | string | No | Business system order number | | orderNo | string | No | PayBox Order Number | | fromTxHash | string | Yes | Payment chain transaction Hash | | fromAmount | Coin | No | Payment chain payment assets | | fromAddress | string | No | Payment chain payment address | | fromChain | string | No | Payment chain name | | toAmount | Coin | No | Amount received | | payeeFee | Coin | No | Payee Fee | | toTxHash | string | Yes | Transaction Hash | | toAddress | string | No | Payment receiver address | | fromTimestamp | int | Yes | Payment time (timestamp, seconds) | | toTimestamp | int | Yes | Arrival time (timestamp, seconds) | | txState | TxState | No | Transaction status | TxState: | Enumeration Values | Interpretation | | ------------------ | --------------------------------------- | | Unsent | Unpaid | | Panding | Payment chain confirming | | SourceConfirm | Payment chain transaction confirmed | | Confirm | Have been sent to the receiving address | | Fail | Transaction failed | * **Response Example:** ```json { "code": 0, "msg": "Success", "data": { "outerOrderNo": "A10001231023154807", "orderNo": "A10001231023154809", "fromTxHash": "9296a59f7100d26a8429d7c22a7c2254066f50cfb31123240fa9255c072e63e3", "fromAmount": { "symbol": "NVT", "amount": "1.26981127", "cent": "126981127", "decimal": 8 }, "fromAddress": "TNVTdTSPRgJo5kUEBRvqKWuLZYfNNksNsSTjt", "fromChain": "NERVE", "toAmount": { "symbol": "USDTN", "amount": "0.01954", "cent": "19540000000000000", "decimal": 18 }, "payeeFee": null, "toTxHash": "31f40f450ca47364746113da074930a881a09c590782c650a9e15bc8c9d97069", "toAddress": "TNVTdTSPLtaRJ6SXKgoTfrE4qfDsK6YpuzRWy", "fromTimestamp": 1698047291, "toTimestamp": 1698047320, "txState": "Confirm" } } ``` #### 5. Download Demo * **Java Demo:** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://nabox.gitbook.io/nabox/paybox-open-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.