# Develop Reference ### 1. Signature Verification #### 1.1 HTTP Header Parameters | Parameter Name | Parameter Type | Required | Description | | -------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | app\_id | string | Y | The key assigned by the system | | timestamp | number | Y | Seconds, difference from the server should not exceed 1h (1714492800) | | sign | string | Y | The signed string generated using the system-assigned secret key, the server will use the same rules to verify the validity of the request | #### 1.3 Request Body Specification Only JSON objects are supported, and all key-value pairs are of type string. #### 1.3 Signing Rules 1. Signing Secret: The secret corresponding to the api\_key 2. Signing Algorithm: HmacSHA1 3. Signing Content: ```txt 1. Concatenate timestamp and the assembled body content 2. The assembled body content structure is: Sort the keys in ascending order, take their values and concatenate, if the content is empty (multiple spaces, tabs are also considered empty, but this should be avoided as much as possible, when there is no data, do not pass this parameter), concatenate a space (If the parameter is a complex structure, such as JSON, it needs to be converted to a JSON string for processing) 3. If there are query parameters in the URL, these parameters will override the same key parameters in the body for signing 4. If the key is "sign", its value will not participate in the signing ``` For example: timestamp is 1694958440 The body content is: {"sign": "xxxxadqw", "ba":"ba\_content", "aa": "aa\_content", "cb": "\t \t (the \t here is a tab)"} The signing content would be: There is a space at the end (ignoring the double quotes) "1704959546aa\_contentba\_content " ### 2. Business Codes `🟡 Response code, not HTTP status code` | Code | Description | Remark | | ---- | ------------------------- | ------------------------------------------------------------------------------ | | 0 | Success | Y | | 419 | 'Api key status abnormal' | | | 420 | Invalid parameters | Missing required parameters (sign, timestamp) in the header or invalid api-key | | 421 | Invalid timestamp | Y | | 422 | Other unknown exceptions | | | 423 | Signature error | | ### 3. API #### 3.1 Client `Initiate in-app purchase flow` #### 3.2 Server **3.2.1 Order** **3.2.1.1 Order Details** * HTTP Request * GET * Query Parameters | Parameter Name | Parameter Type | Required | Description | | -------------- | -------------- | -------- | ----------------------------------------------------------------------------------- | | mer\_order\_id | string | Y | The order ID passed in by the dapp client (the order ID in the client's own system) | * The request body is empty * Response Body | Parameter Name | Parameter Type | Nullable | Content | Description | | -------------- | -------------- | -------- | ---------------------- | ---------------------- | | code | number | N | 0 | 0 - Request successful | | data | object (json) | Y | Order details instance | | * Order Details Instance Description | Parameter Name | Parameter Type | Nullable | Content | Description | | -------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------- | | order\_id | string | N | Platform order ID | | | product\_id | string | N | Product ID | | | mer\_order\_id | string | N | Merchant order ID (the merchant must ensure uniqueness in their own system, the platform does not perform uniqueness validation) | | | product\_name | string | N | Product name | | | status | number | N | Order status, 1 - Success, 2 - Refunded | | | purchase\_time | number | N | Payment time, in milliseconds | | | refund\_time | number | Y | Refund time, valid when status is 2 | | | amount | number | N | Payment amount (micros, actual payment amount \* 10^6) | | | currency | number | N | Currency type (USD, etc.) | | | dapp\_id | number | N | The Dapp ID the order belongs to | | * Example Order Details Instance ```json { "order_id": "664d90293a2de71ad9f0", "mer_order_id": "5", "product_id": "test_product_id_1", "product_name": "test_name", "user_data": "xadauser", "status": 1, "purchase_time": 1715323679516, "refund_time": null, "amount": 0, "currency": "USD", "dapp_id": 384 } ``` #### 3.2.1.2 Order List * HTTP Request * GET * Query Parameters | Parameter Name | Parameter Type | Required | Description | | -------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------- | | start\_time | number | Y | Start time, seconds (order payment time, greater than or equal to this time) | | end\_time | number | Y | End time, seconds (order payment time, less than this time) | | page\_num | number | Y | Pagination parameter, page number | | page\_size | number | Y | Pagination parameter, number of items per page, maximum 1000, over 1000 will be automatically processed as 1000 | | status | number | N | Order status, if not passed, it will query all statuses | | dapp\_id | number | N | Dapp ID, if not passed, it will query orders for all dapps under the organization | * The request body is empty * Response Body | Parameter Name | Parameter Type | Nullable | Content | Description | | -------------- | -------------- | -------- | ------------------- | ---------------------- | | code | number | N | 0 | 0 - Request successful | | data | object (json) | Y | Order data instance | | * Order Data Instance Description | Parameter Name | Parameter Type | Nullable | Content | | -------------- | -------------- | -------- | ------------------------------------- | | count | string | N | Total records for the query condition | | list | array (json) | Y | List of order detail instances | * Example Order Data Instance ```json { "count": 1, "list": [ { "order_id": "664eafe0c1b6ec2ca553", "mer_order_id": "5", "product_id": "test_product_id_1", "product_name": "Test Name", "user_data": "xadauser", "status": 2, "purchase_time": 1715323679516, "refund_time": 1716377660287, "amount": 0, "currency": "USD", "dapp_id": 382 } ] } ```