PayBox Open API

PayBox is a Web3 multi-chain asset aggregation payment system.

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: https://beta.id.nabox.io

  • Production environment registration: https://id.nabox.io

• 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: https://dev.web.paybox.id.nabox.io/pay

• Mainnet URL: https://paybox.id.nabox.io/pay

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:

{
    "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:

<!-- https://mvnrepository.com/artifact/org.bitcoinj/bitcoinj-core -->
<dependency>
    <groupId>org.bitcoinj</groupId>
    <artifactId>bitcoinj-core</artifactId>
    <version>0.16.1</version>
</dependency>

or

<!-- https://mvnrepository.com/artifact/network.nerve/nerve-sdk4j -->
<dependency>
    <groupId>network.nerve</groupId>
    <artifactId>nerve-sdk4j</artifactId>
    <version>1.2.5</version>
</dependency>

Example Code:

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:

{
    "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:

{
    "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:

    {
        "symbol": "NVT",           // Asset symbol
        "amount": "68.57450743",   // Asset amount
        "cent": "6857450743",      // Amount in smallest unit
        "decimal": 8               // Decimal places
    }

• Response Example:

{
    "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:

{
    "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: https://oit.oss-cn-hangzhou.aliyuncs.com/paybox-demo.tgz