Get Payments

GET

/finance/202605/payments

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.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

create_time_lt

integer format: int64

Filter payments to show only those initiated before the specified date and time. Unix timestamp in seconds. Refer to notes in create_time_ge for more usage information.

page_size

integer format: int64

>= 1 <= 100

The number of results to be returned per page. Default: 20 Valid range: [1-100]

page_token

string

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

required

string

The returned results will be sorted by the specified field. Only supports create_time.

sort_order

string

Allowed values: ASC DESC

The sort order for the sort_field parameter. Default: ASC Possible values:

• ASC: Ascending order
• DESC: Descending order

create_time_ge

integer format: int64

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_ge is filled but create_time_lt is empty, create_time_lt will default to the current time.
• If create_time_lt is filled but create_time_ge is empty, create_time_ge will default to the earliest shop time.

Responses

200

Success

Media typeapplication/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

next_page_token

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. An empty string means there is no next page.

string

payments

The list of payments that meet the query conditions.

Array<object>

object

create_time

The time when the payment was initiated in TikTok Shop, as a Unix timestamp in seconds.

integer format: int64

id

The payment ID.

string

status

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.

string

Allowed values: PAID FAILED PROCESSING

amount

The final payment amount after currency exchange.

object

value

The final payment amount.

string

currency

The exchange currency code in ISO 4217 format.

string

settlement_amount

The settlement amount before currency exchange.

object

value

The settlement amount.

string

currency

The original currency code in ISO 4217 format.

string

payment_amount_before_exchange

The original payment amount before currency exchange.

object

value

The original payment amount.

string

currency

The original currency code in ISO 4217 format.

string

exchange_rate

The exchange rate, displayed with six decimal places.

string

paid_time

The time when payment processing finished in TikTok Shop, as a Unix timestamp in seconds. Returns 0 when no finish time is available.

integer format: int64

bank_account

The seller’s bank account number masked, revealing only the last 4 digits for privacy.

string

Example

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