Common API

​

1. Account Inquiry

Brief Description:

• Query the balance of the account corresponding to the current business.

URL: The currency is a path parameter, which should be replaced by the currency you want to query, for example, for USD: /usd/account/ledger. Currencies use the international standard code, three-letter uppercase code, refer to: Wikipedia-ISO_4217 /{currency}/account/ledger Parameters: Response Data:

​

2. Asynchronous Notification

Brief Description:

• When the customer’s collection is successful or failed, we will push the order status. If the first notification fails, it will retry every 5 minutes, up to 5 times.

URL: Your provided URL, Please configure it in HaiPay’s backend or pass it in the request parameters. Collection Callback Parameters: | status | Integer | Status (2: Success(Final), 3: Failure(Final), 4: Partial Collection(Final), 5: Excess Collection(Final)). | | payTime | String | Payment success time (present when status=2, 4, 5) (Local time), format: yyyy-MM-dd HH:mm:ss | | errorMsg | String | Payment failure reason (present when status=3) | | originalCurrency | String | Original order currency, may be empty, only present when currency conversion is involved | | originalAmount | String | Original order amount, may be empty, only present when currency conversion is involved | | inBankCode | String | Payment method used by the user, refer to each region’s documentation, may be empty | | bankNo | String | Receiving account, may be empty | | description | String | Payment note, may be empty | | cardNo | String | Payment card number, credit card payments typically display the first six and last four digits, while ApplePay and GooglePay show only the last four digits, which may be blank | | tokenID | String | Payment token, for MIT mode transactions, may be empty | | name | String | User name, may be empty | | email | String | User email, present for MIT mode transactions | | expMonth | String | Payment card expiration month, may be empty | | expYear | String | Payment card expiration year, may be empty | | ip | String | User IP, may be empty | | is3DS | String | Whether 3DS payment is required, true indicates yes, false indicates no, but it only represents whether the bank recommends 3DS payment, not whether 3DS payment was actually used, may be empty | | sign | String | Signature, (Must use the business secret key for the currency for verification) | Payout Callback Parameters: | hash | String | Transaction hash | | sign | String | Signature, (Must use the business secret for the currency for verification) | Collection Link Order Callback Parameters: | status | Integer | Status (2: Success(Final), 3: Failure(Final), 4: Partial Collection(Final), 5: Excess Collection(Final)). | | payTime | String | Payment success time (present when status=2, 4, 5), format: yyyy-MM-dd HH:mm:ss | | errorMsg | String | Payment failure reason (present when status=3) | | originalCurrency | String | Original order currency, may be empty, only present when currency conversion is involved | | originalAmount | String | Original order amount, may be empty, only present when currency conversion is involved | | inBankCode | String | Payment method used by the user, refer to each region’s documentation, may be empty | | bankNo | String | Receiving account, may be empty | | description | String | Payment note, may be empty | | cardNo | String | Last four digits of the payment card number , may be empty | | createTime | String | Order creation time (Local time), format: yyyy-MM-dd HH:mm:ss | | linkNo | String | Collection link number | | linkName | String | Collection link name | | agentId | Long | Agent ID (empty if there’s no agent) | | email | String | Payer’s email (from the collection link page, random email if not filled) | | name | String | Payer’s nickname (from the collection link page) | | subject | String | Note (filled in the collection link page, randomly generated if not filled) | | sign | String | Signature, (Must use the business secret for the currency for verification) | Note: After receiving the callback notification, please return SUCCESS (in uppercase) in the response body without surrounding quotation marks. Otherwise, the notification will continue for 5 more times.

​

3. Statement File Link Retrieval

Description:

• The file format is the same as the one exported from the merchant backend. The data for the day will be generated the next day after 1:00 PM.

URL: /common/document/download Parameters: Response Data:

​

Field Descriptions

​

Collection

• Error: Collection exception
• Not Started: Not started
• Paying: Collecting
• Success: Collection successful
• Failed: Collection failed
• Payment Part Success: Partial collection
• Payment Excess Success: Excess collection

​

Payout

• Submit Error: Submission exception
• Error: Payout exception
• Not Started: Not started
• Pending: Payout in progress
• Success: Payout successful
• Failed: Payout failed

​

Notification Status

• Not Start: Not notified
• Success: Notification successful
• Failed: Notification failed
• Error: Notification exception

​

Settlement Status

• Error: Exception pending confirmation
• Not Start: Not started
• Settling: Settling
• Success: Settlement successful
• Settlement Failed (Reversed): Settlement failed (reversed)

​

4. Payout Order Voucher

URL: /common/voucher Parameters: Response Data:

• The base64 encoded image of the voucher.

​

5. Real-Time Exchange Rate Query

Description:

• Query exchange rates for converting USD to other currencies, only USD settlement payment methods are supported

URL: /common/quote/v1/exchange-rate Parameters: Return data parameter description