Payments

List payments

Retrieve a paginated list of payments with powerful filtering options. Payments represent individual transactions including one-time purchases, subscription payments, and refunds. Results are sorted by creation date (newest first) by default.

Authorization

Public key
x-fngs-public-key<token>

In: header

Query Parameters

term?string

Search term to filter results. Matches against order/payment number, user email, or transaction ID. Omit the leading '#' the dashboard shows on numbers - it is not part of the stored value and matches nothing.

ids?array<>

Array of UUIDs to filter by specific records.

number?string

Filter by exact order/payment number, as returned in 'number' (e.g., L8VQK3N2M7KpQ9nR). Matched verbatim: omit the leading '#' the dashboard shows, or the filter returns no rows.

Match^#?([0-9A-Za-z]{12,32}|[0-9]+)(-[0-9]+)?$
userId?string

Filter by the user's UUID who made the order/payment.

Formatuuid
subscriptionId?string

Deprecated. Use 'subscriptionNumber' instead. Filter by subscription number, as returned in 'subscription.id', to find all related orders/payments. Omit the leading '#' the dashboard shows.

subscriptionNumber?string

Filter by subscription number, as returned in 'subscription.id', to find all related orders/payments. Omit the leading '#' the dashboard shows.

Match^#?([0-9A-Za-z]{12,32}|[0-9]+)(-[0-9]+)?$
checkoutIds?unknown

Filter by checkout (checkoutElement) UUID(s). Pass a single checkoutId or multiple checkoutIds — returns orders/payments that originated from any of them. Single value: ?checkoutIds=. Multiple: ?checkoutIds=&checkoutIds=.

Formatarray (preprocessed)
customFields?string

Filter by custom field values. Pass a JSON object of fieldId/value pairs, e.g. {"playerName":"john_doe"}. Matches records that have a cart item whose custom fields contain all of the provided pairs (exact match). The JSON must be URL-encoded in the query string.

statuses?array<>

Filter by status values. Available options:

  • PENDING: Being processed
  • PAID: Completed successfully
  • FAILED: Payment failed
  • UNPAID: Not yet attempted
  • CANCELLED: Was cancelled
  • REFUNDED: Fully refunded
  • PARTIALLY_REFUNDED: Partially refunded
  • EXPIRED: Expired before completion
types?array<>

Filter by payment types. Available options:

  • one_time: Single purchase payment
  • subscription_initial: First payment of a subscription
  • subscription_update: Subscription plan change payment
  • subscription_interval: Recurring subscription payment
  • subscription_extra: Additional subscription charge
  • claim_free: Free product claim
valueFrom?|

Minimum value in smallest currency unit (e.g., cents). Filter for amounts greater than or equal to this value.

Formatdouble
Range-1.7976931348623157e+308 <= value <= 1.7976931348623157e+308
valueTo?|

Maximum value in smallest currency unit (e.g., cents). Filter for amounts less than or equal to this value.

Formatdouble
Range-1.7976931348623157e+308 <= value <= 1.7976931348623157e+308
currency?string

Filter by ISO 4217 currency code (e.g., USD, EUR, GBP).

Value in

  • "AFN"
  • "ALL"
  • "DZD"
  • "AOA"
  • "ARS"
  • "AMD"
  • "AWG"
  • "AUD"
  • "AZN"
  • "BSD"
  • "BDT"
  • "BBD"
  • "BZD"
  • "BMD"
  • "BOB"
  • "BAM"
  • "BWP"
  • "BRL"
  • "BHD"
  • "GBP"
  • "BND"
  • "BGN"
  • "BIF"
  • "BYN"
  • "KHR"
  • "CAD"
  • "CVE"
  • "KYD"
  • "KWD"
  • "XAF"
  • "XPF"
  • "CLP"
  • "CNY"
  • "COP"
  • "KMF"
  • "CDF"
  • "CRC"
  • "HRK"
  • "CZK"
  • "DKK"
  • "DJF"
  • "DOP"
  • "XCD"
  • "EGP"
  • "ETB"
  • "EUR"
  • "FKP"
  • "FJD"
  • "GMD"
  • "GEL"
  • "GIP"
  • "GTQ"
  • "GNF"
  • "GYD"
  • "HTG"
  • "HNL"
  • "HKD"
  • "HUF"
  • "ISK"
  • "INR"
  • "IDR"
  • "ILS"
  • "JMD"
  • "JPY"
  • "JOD"
  • "KZT"
  • "KES"
  • "KGS"
  • "LAK"
  • "LBP"
  • "LSL"
  • "LRD"
  • "MOP"
  • "MKD"
  • "MGA"
  • "MWK"
  • "MYR"
  • "MVR"
  • "MRO"
  • "MUR"
  • "MXN"
  • "MDL"
  • "MNT"
  • "MAD"
  • "MZN"
  • "MMK"
  • "NAD"
  • "NPR"
  • "ANG"
  • "TWD"
  • "NZD"
  • "NIO"
  • "NGN"
  • "NOK"
  • "OMR"
  • "PKR"
  • "PAB"
  • "PGK"
  • "PYG"
  • "PEN"
  • "PHP"
  • "PLN"
  • "QAR"
  • "RON"
  • "RUB"
  • "RWF"
  • "SHP"
  • "SVC"
  • "WST"
  • "STD"
  • "SAR"
  • "RSD"
  • "SCR"
  • "SLL"
  • "SGD"
  • "SBD"
  • "SOS"
  • "ZAR"
  • "KRW"
  • "LKR"
  • "SRD"
  • "SZL"
  • "SEK"
  • "CHF"
  • "TJS"
  • "TZS"
  • "THB"
  • "TND"
  • "TOP"
  • "TTD"
  • "TRY"
  • "UGX"
  • "UAH"
  • "AED"
  • "UYU"
  • "USD"
  • "UZS"
  • "VUV"
  • "VEF"
  • "VND"
  • "XOF"
  • "YER"
  • "ZMW"
  • "SLE"
  • "XCG"
  • "SSP"
  • "VES"
  • "MRU"
  • "STN"
  • "VED"
country?string

Filter by ISO 3166-1 alpha-2 country code of the buyer (e.g., US, GB, DE).

Value in

  • "AF"
  • "AX"
  • "AL"
  • "DZ"
  • "AD"
  • "AO"
  • "AI"
  • "AQ"
  • "AG"
  • "AR"
  • "AM"
  • "AW"
  • "AU"
  • "AT"
  • "AZ"
  • "BS"
  • "BH"
  • "BD"
  • "BB"
  • "BY"
  • "BE"
  • "BZ"
  • "BJ"
  • "BM"
  • "BT"
  • "BO"
  • "BA"
  • "BW"
  • "BV"
  • "BR"
  • "IO"
  • "VG"
  • "BN"
  • "BG"
  • "BF"
  • "BI"
  • "KH"
  • "CM"
  • "CA"
  • "CV"
  • "BQ"
  • "KY"
  • "CF"
  • "TD"
  • "CL"
  • "CN"
  • "CO"
  • "KM"
  • "CG"
  • "CD"
  • "CK"
  • "CR"
  • "CI"
  • "HR"
  • "CW"
  • "CY"
  • "CZ"
  • "DK"
  • "DJ"
  • "DM"
  • "DO"
  • "EC"
  • "EG"
  • "SV"
  • "GQ"
  • "ER"
  • "EE"
  • "SZ"
  • "ET"
  • "FK"
  • "FO"
  • "FJ"
  • "FI"
  • "FR"
  • "GF"
  • "PF"
  • "TF"
  • "GA"
  • "GM"
  • "GE"
  • "DE"
  • "GH"
  • "GI"
  • "GR"
  • "GL"
  • "GD"
  • "GP"
  • "GU"
  • "GT"
  • "GG"
  • "GN"
  • "GW"
  • "GY"
  • "HT"
  • "HN"
  • "HK"
  • "HU"
  • "IS"
  • "IN"
  • "ID"
  • "IQ"
  • "IE"
  • "IM"
  • "IL"
  • "IT"
  • "JM"
  • "JP"
  • "JE"
  • "JO"
  • "KZ"
  • "KE"
  • "KI"
  • "XK"
  • "KW"
  • "KG"
  • "LA"
  • "LV"
  • "LB"
  • "LS"
  • "LR"
  • "LY"
  • "LI"
  • "LT"
  • "LU"
  • "MO"
  • "MG"
  • "MW"
  • "MY"
  • "MV"
  • "ML"
  • "MT"
  • "MQ"
  • "MR"
  • "MU"
  • "YT"
  • "MX"
  • "MD"
  • "MC"
  • "MN"
  • "ME"
  • "MS"
  • "MA"
  • "MZ"
  • "MM"
  • "NA"
  • "NR"
  • "NP"
  • "NL"
  • "NC"
  • "NZ"
  • "NI"
  • "NE"
  • "NG"
  • "NU"
  • "MK"
  • "NO"
  • "OM"
  • "PK"
  • "PS"
  • "PA"
  • "PG"
  • "PY"
  • "PE"
  • "PH"
  • "PN"
  • "PL"
  • "PT"
  • "PR"
  • "QA"
  • "RE"
  • "RO"
  • "RU"
  • "RW"
  • "WS"
  • "SM"
  • "ST"
  • "SA"
  • "SN"
  • "RS"
  • "SC"
  • "SL"
  • "SG"
  • "SX"
  • "SK"
  • "SI"
  • "SB"
  • "SO"
  • "ZA"
  • "GS"
  • "KR"
  • "SS"
  • "ES"
  • "LK"
  • "BL"
  • "SH"
  • "KN"
  • "LC"
  • "MF"
  • "PM"
  • "VC"
  • "SD"
  • "SR"
  • "SJ"
  • "SE"
  • "CH"
  • "TW"
  • "TJ"
  • "TZ"
  • "TH"
  • "TL"
  • "TG"
  • "TK"
  • "TO"
  • "TT"
  • "TN"
  • "TR"
  • "TM"
  • "TC"
  • "TV"
  • "UG"
  • "UA"
  • "AE"
  • "GB"
  • "US"
  • "UY"
  • "UZ"
  • "VU"
  • "VA"
  • "VE"
  • "VN"
  • "WF"
  • "EH"
  • "YE"
  • "ZM"
  • "ZW"
orderBy?string

Field to sort results by. Common options: createdAt, orderNumber, value.

Value in

  • "createdAt"
  • "orderNumber"
  • "value"
createdFrom?|

Filter payments created on or after this timestamp. Accepts Unix timestamp in seconds or milliseconds.

Formatint64
Range0 <= value <= 9007199254740991
createdTo?|

Filter payments created on or before this timestamp. Accepts Unix timestamp in seconds or milliseconds.

Formatint64
Range0 <= value <= 9007199254740991
orderDirection?string

Sort direction for results. 'ASC' for ascending (oldest/lowest first), 'DESC' for descending (newest/highest first).

Value in

  • "ASC"
  • "DESC"
skip?|

Number of records to skip for offset-based pagination. Use with 'take' parameter.

Formatdouble
Range0 <= value <= 1.7976931348623157e+308
take?|

Maximum number of records to return (page size). Use with 'skip' parameter for pagination (default: 20, max: 100). A larger value is clamped to 100 and still returns 200 — it is not rejected.

Range1 <= value <= 100
Default20
archived?|

If true, return only archived/deleted records. If false or omitted, return only active records.

withArchived?|

If true, include archived records in results alongside active records.

returnCount?|

If true, include the total count of matching records in the response. Useful for pagination UI.

Response Body

application/json

application/json

GET
/v0/payments/list
curl -X GET "https://example.com/v0/payments/list"
{  "status": "success",  "data": {    "payments": [      {        "object": "payment",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "type": "one_time",        "number": "string",        "status": "PENDING",        "value": 0,        "tax": 0,        "fee": 0,        "currency": "AFN",        "currencyDecimals": null,        "createdAt": 0,        "userId": null,        "user": null,        "orderId": null,        "orderNumber": null,        "order": null,        "subscriptionId": null,        "subscription": null,        "checkoutId": null,        "discount": null,        "invoiceNumber": null,        "invoiceUrl": null,        "charges": null      }    ],    "count": -1.7976931348623157e+308  }}

Get a download URL for an order item POST

Create a time-limited download URL for one digital-download item on a paid order. Requires write access. Use it to re-deliver a file a buyer lost, or to serve the download from your own app or support desk. The buyer does not have to have opened their redeem link first. The item id is the `id` of the entry in `items` on the order's webhook payload. The URL stops working after `expiresIn` seconds — 15 minutes by default, 24 hours at most. Ask for the shortest window your flow can live with: anyone holding the URL can download the file until it expires. For a link a buyer can keep, send them the redeem link from their confirmation email instead. `validTill` is the latest the URL can work, not a promise that it will: a window measured in hours can end earlier. Mint a URL when you are about to hand it over rather than storing one, and mint a fresh one if the buyer comes back later. `mimeType` is the content type recorded when the file was attached, and is null when none was recorded. Errors: 404 when the order does not exist, when the item is not on that order, and when the item has no digital download — a keyed product delivers a license key instead of a file, so it answers 404 here. 400 when the order was never paid, when it has been fully refunded, when every unit of the item has been refunded, and when `expiresIn` is above 86400 — the ceiling is never applied silently. 429 when a workspace asks for more than 60 of these a minute; retry after a minute.

Get payment details GET

Retrieve detailed information about a specific payment by its ID. Returns the full payment object including associated user, order, subscription, charges, and invoice details.