Skip to navigation
TIANKII API - API KeyPayment RequestsGeneral Operations

List payment requests

View as Markdown

List payment requests

Returns a paginated list of payment requests owned by the store resolved from the API key (or the store scoped via x-application-account-id). Payment requests are the umbrella aggregate over payment links, invoices and subscriptions; the type field discriminates them and shapes each record.

Authentication

Send the merchant API key in the x-api-key header (alias x-account-api-key). The key must carry the scope Merchant.payment_link.read. Optionally scope the key to a specific store/account with the x-application-account-id header (alias x-account-id) or the application_account_id / account_id query param.

Query parameters

  • Pagination: page (default 1), per_page (default 10).
  • Date range: start_at / end_at (ISO date-time). They are validated as a pair — if one is present the other is required. Filters by the Created date.
  • Status: Status — numeric payment request status (0 = PENDING, 1 = COMPLETED, 2 = EXPIRED, 3 = ACTIVE, 4 = DEACTIVATED).
  • Type: type — one of PAYMENT_LINK, INVOICE, SUBSCRIPTION.
  • Sorting: sort (Prisma orderBy over allowed fields Status, Created, Archived) or sorter (a JSON string, e.g. {"Created":"desc"}).

Response

A paginated envelope with meta (pagination info), records (array of payment requests shaped by type) and a legacy _metadata block. There is no request body.

Notas: Handler: paymentRequestsService.findMany. Records are shaped by presenter per type (PaymentLinkResponseDto or BillingInvoiceResponseDto); only whitelisted data-blob fields are returned. Response uses createPaginatedResponse (meta + records + legacy _metadata).

Authentication

x-api-keystring
API Key authentication via header

Headers

x-application-account-idstringOptional

Scope the request to a specific store / account instead of the one resolved from the API key. Aliases: the x-account-id header, or the application_account_id / account_id query parameter.

Query parameters

pageintegerOptionalDefaults to 1
Page number to return.
per_pageintegerOptionalDefaults to 10
Number of records per page.
start_atdatetimeOptional

Start of the Created date range (ISO 8601). Must be sent together with end_at — supplying only one is a validation error.

end_atdatetimeOptional

End of the Created date range (ISO 8601). Must be sent together with start_at.

StatusintegerOptional

Filter by payment request status: 0 PENDING, 1 COMPLETED, 2 EXPIRED, 3 ACTIVE, 4 DEACTIVATED.

CustomerIdstringOptional
Return only payment requests issued to this customer.
typeenumOptional
Filter by payment request type.
Allowed values:
sortstringOptional

Sort by one or more fields, comma-separated.

Allowed fields: Status, Created, Archived

Formats: field (ascending by default), +field, -field, field:asc, field:desc (| also works as the separator).

sorterstringOptional

Alternative to sort: a JSON string mapping a field to a direction (asc / desc).

Allowed fields: Status, Archived, Created