Payments

The Payments API exposes a read-only list of a venue's paid and refunded payments. It uses the same OAuth token as the rest of the Third Party API (see Authentication) — any token authorized for the venue you query works here, with no extra setup.

Read-only

This endpoint never creates, modifies or deletes payments. It is a reporting / reconciliation feed.

GET /api/v1/payments

Retrieves a list of PAID and REFUNDED payments for a venue, filtered by date and paginated.

Activation lifecycle

The first time a venue is queried, Playtomic builds a one-time historical snapshot of its payments before data becomes available.

First call returns 202 Accepted

While the snapshot is being built, the API responds with 202 Accepted and a Retry-After header (in seconds). The body looks like:

{ "status": "PROCESSING", "tenant_id": "<tenant-id>", "activated_at": "2026-05-04T10:14:50Z" }

Wait and retry (we recommend exponential backoff). Once the snapshot is ready, calls return 200 OK. For most venues this takes a few minutes; large venues take longer.

Parameters

Parameter	Type	Required	Description
`tenant_id`	String	Yes	ID of the venue/club whose payments you want to retrieve.
`start_service_date`	Date (UTC)	No	Filter by service date (when the service takes place). Format: `YYYY-MM-DDTHH:MM:SSZ`. Cannot be combined with payment-date filters.
`end_service_date`	Date (UTC)	No	Upper bound of the service-date filter.
`start_payment_date`	Date (UTC)	No	Filter by payment date (when the money moved). Cannot be combined with service-date filters.
`end_payment_date`	Date (UTC)	No	Upper bound of the payment-date filter.
`cursor_id`	String	No	Cursor marking where to continue. Use the `next_cursor_id` from the previous response. Omit on the first request.
`limit`	Int	No	Max results to return. Default `100`, max `100` (values above are clamped).

Date filters

You may filter by one date axis only — either service date or payment date, never both in the same request.
The maximum range in a single request is 13 months.
If you provide no date filter, the API defaults to the last 13 months.
All timestamps are UTC.

Pagination

This endpoint uses cursor-based pagination, the platform standard.

Make the first request with no cursor_id.
Each response carries next_cursor_id and has_more.
To fetch the next page, send the next_cursor_id value back as the cursor_id parameter.
When has_more is false (and next_cursor_id is null), you have retrieved everything.

Cursor pagination does not compute total counts — it is more efficient for large exports and stays consistent even while data changes.

Response (200)

A cursor-paginated object wrapping the results:

Field	Type	Description
`data`	List[Payment]	The payments for this page. See Payment Model.
`has_more`	Boolean	`true` if more results are available via `next_cursor_id`.
`next_cursor_id`	String	Cursor to retrieve the next page. `null` on the last page.
`last_modified`	Date (UTC)	When a response is served from cache, the timestamp the cached data was generated (see Conventions → Cached Data). Payment lists are read live, so this is currently always `null`.

Models

Payment Model

Most fields are grouped into nested objects. Any field may be null when not applicable to that payment. A whole nested object is null (not an empty object) when none of its fields apply — e.g. payment_info is omitted entirely for a record that carries no payment-level data, so always null-check a group before reading its fields.

Field	Type	Description
`club_payment_id`	String	Unique ID of this payment record.
`payment_id`	String	ID of the original payment (when applicable).
`refund_id`	String	ID of the refund (present on refunded records).
`company_info`	Object	Billing company details.
`user_info`	Object	The payer.
`product_info`	Object	What was paid for.
`payment_info`	Object	Amounts, taxes and status.
`customer_invoice_info`	Object	Customer invoice reference, if invoiced.
`payout_info`	Object	The payout that settled this payment, if settled.

CompanyInfo Model

Field	Type	Description
`name`	String	Corporate / billing name of the venue entity.
`tax_id`	String	Tax identifier of the venue entity.

UserInfo Model

Field	Type	Description
`user_id`	String	ID of the payer.
`user_name`	String	Name of the payer.

ProductInfo Model

Field	Type	Description
`sport_id`	String	Sport associated with the product, if any.
`product_sku`	String	SKU of the product.
`origin`	String	Where the payment originated (e.g. `APP`, `MANAGER`). Mirrors `payment_info.payment_source`.
`service_date`	Date (UTC)	When the paid-for service takes place.
`tax_rate`	Double	Applied tax (VAT) rate.
`price`	String [Money]	List price. Format: `amount currency_code`, e.g. `23.00 EUR`.
`custom_price`	String [Money]	Custom price, if overridden.
`category_name`	String	Product category name.
`applied_discount`	String [Money]	Discount applied, if any.
`campaign_id`	String	ID of the discount campaign, if any.
`campaign_name`	String	Name of the discount campaign, if any.
`store_product_info`	Object	Store-sale details, for store products.

StoreProductInfo Model

Field	Type	Description
`item_name`	String	Name of the store item.
`units`	Int	Number of units sold.
`product_code`	String	Store product code.

PaymentInfo Model

Field	Type	Description
`status`	String	`PAID` or `REFUNDED`.
`payment_date`	Date (UTC)	When the money moved.
`payment_source`	String	Where the payment originated (same value as `product_info.origin`).
`total`	String [Money]	Total amount. Format: `amount currency_code`.
`subtotal`	String [Money]	Subtotal before taxes.
`taxes`	String [Money]	Tax amount.
`payment_method_type`	String	Payment method type (e.g. card).
`payment_type`	String	`SINGLE` or `SPLIT`.
`b2b_commission_info`	Object	Playtomic commission on this payment.
`net_transfer_amount`	String [Money]	Amount net of Playtomic commission and its tax.

B2bCommissionInfo Model

Field	Type	Description
`rate`	Decimal	Commission rate applied.
`amount`	String [Money]	Commission amount.
`tax_rate`	Decimal	Tax rate on the commission.
`tax_amount`	String [Money]	Tax on the commission.

CustomerInvoiceInfo Model

Field	Type	Description
`id`	String	Invoice ID.
`sequence_id`	String	Invoice sequence number.
`issue_date`	Date (UTC)	Invoice issue date.
`payer_name`	String	Name on the invoice.
`type`	String	Invoice type.

PayoutInfo Model

Field	Type	Description
`payout_id`	String	ID of the payout that settled this payment.
`payout_code`	String	Human-readable payout code.
`self_invoice_id`	String	Self-invoice reference for the payout.

Errors

Status Code	Error	Description
202	`PROCESSING`	The venue's snapshot is still being built. Retry after the `Retry-After` interval.
400	`MISSING_TENANT_ID`	`tenant_id` was not provided.
400	`INVALID_DATE_RANGE`	The end date is before the start date.
400	`DATE_RANGE_TOO_LARGE`	The requested range exceeds 13 months.
400	`AMBIGUOUS_DATE_FILTER`	Service-date and payment-date filters were combined.
400	`INVALID_CURSOR_ID`	The `cursor_id` is malformed.
401 or 403	-	Missing/expired token, or your token is not authorized for this venue.
429	`RATE_LIMIT_EXCEEDED`	Too many requests (see Conventions → Rate Limiting).

Example

CURL RequestJSON Response

curl --request GET \
  --url "https://thirdparty.playtomic.io/api/v1/payments?tenant_id=tenant-id&start_payment_date=2026-05-01T00:00:00Z&end_payment_date=2026-05-31T23:59:59Z&limit=20" \
  --header "content-type: application/json" \
  --header "Authorization: Bearer <your-secret-token>"

{
    "has_more": true,
    "next_cursor_id": "eyJzZXJ2aWNlX2RhdGUiOiIyMDI2LTA1L...",
    "last_modified": null,
    "data": [
        {
            "club_payment_id": "club-payment-id",
            "payment_id": "payment-id",
            "refund_id": null,
            "company_info": {
                "name": "My Padel Club S.L.",
                "tax_id": "B12345678"
            },
            "user_info": {
                "user_id": "user-id",
                "user_name": "Jane Doe"
            },
            "product_info": {
                "sport_id": "PADEL",
                "product_sku": "COURT_RENTAL",
                "origin": "APP",
                "service_date": "2026-05-04T18:00:00Z",
                "tax_rate": 21.0,
                "price": "24.00 EUR",
                "custom_price": null,
                "category_name": "Court",
                "applied_discount": "0.00 EUR",
                "campaign_id": null,
                "campaign_name": null,
                "store_product_info": null
            },
            "payment_info": {
                "status": "PAID",
                "payment_date": "2026-05-02T09:31:10Z",
                "payment_source": "APP",
                "total": "24.00 EUR",
                "subtotal": "19.83 EUR",
                "taxes": "4.17 EUR",
                "payment_method_type": "CARD",
                "payment_type": "SINGLE",
                "b2b_commission_info": {
                    "rate": 0.05,
                    "amount": "1.20 EUR",
                    "tax_rate": 0.21,
                    "tax_amount": "0.25 EUR"
                },
                "net_transfer_amount": "22.55 EUR"
            },
            "customer_invoice_info": null,
            "payout_info": {
                "payout_id": "payout-id",
                "payout_code": "PO-2026-0042",
                "self_invoice_id": "SI-2026-0042"
            }
        }
    ]
}