stable本次发布有变化全部展示
来自 TikTok Shop 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Path: /finance/202605/payments
#§2 Method: [GET]
#§3 Function Description
This API is currently unavailable to SEA markets. Retrieves records of automated payments for a shop based on a specified date range. Use the returned list to verify and reconcile payments with the transactions in the seller's bank account.
§4 Common Parameters
For common parameters, refer to How to call TikTok Shop APIs - Common Parameters
| Properties | Location | Type | Require | Sample | Properties description |
|---|---|---|---|---|---|
| shop_cipher | query | string | Y | GCP_XF90igAAAABh00qsWgtvOiGFNqyubMt3 | Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response. |
| Get by API Get Authorization Shop | |||||
| content-type | header | string | Y | application/json | Allowed type: application/json |
§5 Request Query Parameters
| Properties | Type | Require | Sample | Properties description |
|---|---|---|---|---|
| app_key | string | Y | 38abcd | Every single app will have a unique key. Please use the specific key assigned to your app. |
| create_time_lt | int | N | 1687266376 | Filter payments to show only those that occurred before the specified date and time. Unix timestamp. |
Refer to notes in create_time_ge for more usage information. | ||||
| page_size | int | N | 20 | The number of results to be returned per page. |
| Default: 20 | ||||
| Valid range: [1-100] | ||||
| page_token | string | N | 6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5Oa | An opaque token used to retrieve the next page of a paginated result set. Retrieve this value from the result of the next_page_token from a previous response. It is not needed for the first page. |
| sort_field | string | Y | create_time | The returned results will be sorted by the specified field. Only supports create_time. |
| sort_order | string | N | ASC | The sort order for the sort_field parameter. |
| Default: ASC | ||||
| Possible values: |
- ASC: Ascending order
- DESC: Descending order | create_time_ge |int |N |1687266376 |Filter payments to show only those that occurred on or after the specified date and time. Unix timestamp.
Note:
create_time_ge and create_time_lt together constitute the creation time filter condition.
- If
create_time_geis filled butcreate_time_ltis empty,create_time_ltwill default to the current time. - If
create_time_ltis filled butcreate_time_geis empty,create_time_gewill default to the earliest shop time. | sign |string |Y |5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c |Signature generated by gen algorithm. When you send API requests to TTS, you must sign them so that TTS can identify the senders. | timestamp |int |Y |1623812664 |Unix timestamp GMT (UTC+00:00). This timestamp is used across all API requests. Developers can use this convert to local time. |
§6 Request Sample
Query
https://open-api.tiktokglobalshop.com/finance/202605/payments?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c×tamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY&create_time_lt=1687266376&page_size=20&page_token=6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5Oa&sort_field=create_time&sort_order=ASC&create_time_ge=1687266376
§7 Response Parameters
| Properties | Type | Sample | Properties description |
|---|---|---|---|
| code | int | 0 | The success or failure status code returned in API response. |
| message | string | Success | The success or failure messages returned in API response. Reasons of failure will be described in the message. |
| request_id | string | 202203070749000101890810281E8C70B7 | Request log |
| data | object | Specific return information | |
| ^next_page_token | string | 6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT | An opaque token used to retrieve the next page of a paginated result set. Provide this value in the page_token parameter of your request if the current response does not return all the results. |
| ^payments | []object | The list of payments that meet the query conditions. | |
| ^^create_time | int | 1636105796 | The time when the payment was initiated in TikTok Shop. Unix timestamp. |
| ^^id | string | 3458767051733897992 | The payment ID. |
| ^^status | string | PAID | The payment status, indicating whether payment has been transferred to the seller's bank account. |
| Possible values: |
- PAID: Payment has been transferred to the seller.
- FAILED: Payment transfer failed.
- PROCESSING: Payment is currently being processed. | ^^amount |object | |The final payment amount after currency exchange. | ^^^value |string |100 |The final payment amount. | ^^^currency |string |GBP |The exchange currency code in ISO 4217 format. | ^^settlement_amount |object | |The settlement amount before currency exchange. | ^^^value |string |130 |The settlement amount. | ^^^currency |string |GBP |The original currency code in ISO 4217 format. | ^^payment_amount_before_exchange |object | |The original payment amount before currency exchange. | ^^^value |string |100 |The original payment amount. | ^^^currency |string |GBP |The original currency code in ISO 4217 format. | ^^exchange_rate |string |1.000000 |The exchange rate, displayed with six decimal places. | ^^paid_time |int |1685548800 |The time when the payment was successfully processed. Unix timestamp. | ^^bank_account |string |***********1234 |The seller's bank account number masked, revealing only the last 4 digits for privacy. |
§8 Response Sample
{"code":0,"data":{"next_page_token":"6AsPQsUMvH3RkchNUPPh22NROHkE0D8pmq/N5M1kHYcZmtRyv9aVrNv65W7Q6tFA+7D1ud64MPNz5OaT","payments":[{"create_time":1636105796,"id":"3458767051733897992","status":"PAID","amount":{"value":"100","currency":"GBP"},"settlement_amount":{"value":"130","currency":"GBP"},"payment_amount_before_exchange":{"value":"100","currency":"GBP"},"exchange_rate":"1.000000","paid_time":1685548800,"bank_account":"***********1234"}]},"message":"Success","request_id":"202203070749000101890810281E8C70B7"}
§9 Error Code
For common error codes, refer to How to call TikTok Shop APIs - Common Error Code
| Code | Message |
|---|---|
| 36009003 | Internal error. Please try again. If the issue persists after multiple attempts, please contact platform support. |