Recharge Integration Process

Recharge business is similar to the mechanism of exchanges, where each user has a fixed sub-contract wallet address for receiving user deposits. This means that each user has a unique identifier and can recharge to the sub-contract address assigned to them. This mechanism is more suitable for handling the recharge needs of individual users, ensuring accurate attribution and management of funds.

1. Recharge Process

The sequence diagram for the recharge process API calls is as follows:

The calling process is as follows:

1. The merchant system calls /user/create (Create User Sub-contract Wallet API) to initiate a request to create a sub-contract wallet for the user. Pay Protocol validates the merchant's request parameters and generates a wallet address for the user on the corresponding blockchain.

2. After the creation is completed, the corresponding sub-contract address for the user's wallet on the blockchain can be obtained by calling /api/mer/user/detail (Get Wallet Details API).

   {
     "code": 200,
     "msg": "success",
     "data": {
       "userId": 1054,
       "createTime": "2024-03-28 11:43:05",
       "userWallet": [
         {
           "walletId": 55875,
           "chainId": 1,
           "walletAddress": "TGJVB5aC6wvG7fgD7uyfYsPbEUKhV4vigC"
         }
       ],
       "userType": 1,
       "uuid": "2313-5f08afe6ca854e4ebf79781f351d0cb7"
     }
   }

3. After the user recharges and transfers to the receiving address, Pay Protocol will generate a corresponding recharge order based on the successful transaction record of the receiving address.

4. After the recharge order is completed, Pay Protocol will return the callback notification parameters through a POST request to the recharge callback URL (as shown in the following figure, please set the recharge callback address in the merchant admin console).

5. Since the recharge order is generated by the Pay Protocol system, not created by the merchant, the merchant can also query the recharge list and the latest recharge record information by calling /recharge/list (Get Recharge Order List API).
6. If the merchant system does not receive the callback notification due to network or other reasons, the merchant can query the recharge and recharge record information by calling /recharge/detail (Get Recharge Order Detail API) (the merchant can also directly call this query interface without relying on the callback notification), or initiate the recharge callback notification by calling /recharge/notify (Initiate Recharge Callback Notification API).

warning

• After the merchant system receives the callback notification, it must verify the notification signature (verify the X-PAY-SIGN parameter in the notification request header) to ensure that the recharge notification is sent by Pay Protocol. For detailed signature verification rules, please refer to Callback Notification Signature Verification.
• After receiving the callback notification and passing the signature verification, please verify whether the parameter values in the notification are consistent with those in the request, and process the subsequent business based on the rechargeStatus parameter.

2. Withdrawal Process

The sequence diagram for the withdrawal process API calls is as follows:

The call process is as follows:

1. The merchant system calls /withdraw/apply (Initiate Withdrawal Application Interface) to initiate a withdrawal request to Pay Protocol. Pay Protocol validates the merchant's request parameters, then generates a withdrawal record and returns it.
2. After generating the withdrawal record, the merchant audits the withdrawal order and transfers the transaction through the management backend.
3. After the transaction is successful, Pay Protocol sends a POST request to notifyUrl (passed in by the merchant during withdrawal), returning the callback notification parameters.
4. If, due to network or other reasons, the merchant system does not receive the callback notification, the merchant can call /withdraw/detail (Query Withdrawal Order Details Interface) to query the transaction and withdrawal information (the merchant can also directly call this query interface, without relying on callback notifications), or call /withdraw/notify (Initiate Withdrawal Callback Notification).

warning

• After the merchant system receives the callback notification, it must verify the signature (verify the X-PAY-SIGN parameter in the notification request header) to ensure that the withdrawal notification is sent by Pay Protocol. Detailed signature verification rules can be found at Callback Notification Signature Verification.
• After receiving the callback notification and passing the signature verification, please be sure to check whether the parameter values in the notification are consistent with those in the request, and handle subsequent business according to the withdrawStatus parameter.