List payments

API contract v1.0.0

On this page

listPayments

GET/v1/payments

Required scopespayments:read

Lists payments for the current merchant and environment, filtered by merchant order ID, status and creation time. Results are ordered by creation time descending, with ties broken by id descending, so the order is stable. It uses cursor pagination; created_gte is inclusive and created_lt is exclusive.

Request headers

Request headers	Required	Format	Description
Authorization	Yes	Bearer <API_KEY>	Server-side key, to be used only on the merchant's server. The merchant and environment are derived from the key. A missing, invalid, revoked or expired key returns 401.

Query parameters

Name	Type	Required	Description
`merchant_order_no`	string	No	Exact match on the merchant order ID, case-sensitive. Constraints: `Format ^[A-Za-z0-9._:-]{1,64}$` Example: `ORDER-DEMO-001`
`status`	string	No	Filter by payment status. `created`: The order has been created and no valid charge attempt has been submitted yet; new attempts are allowed within the validity period `processing`: Submitted and being processed, or the outcome isn't confirmed yet; new attempts aren't allowed `requires_action`: The current attempt needs the payer to complete an action such as authentication; new attempts aren't allowed `failed`: The latest attempt clearly failed; this is not a terminal state, and an explicit retry is possible when the deadline, attempt limit and risk conditions are met `succeeded`: Payment confirmed as successful `canceled`: Cancellation confirmed as safe `expired`: No unresolved attempt, and the order has expired and closed More values may be added in the future. Don't treat a status you don't recognize as success. Example: `requires_action`
`limit`	integer	No	Number of items per page. The default is 20 and the maximum is 100. Constraints: `1–100Default 20`
`cursor`	string	No	The next_cursor from the previous page's response. An opaque string: don't parse it or build one yourself. Send the same filters as for the first page. Constraints: `Length 1–512`
`created_gte`	string(date-time)	No	Lower bound of the creation time (inclusive), as ISO 8601 with a time zone. Example: `2026-09-23T00:00:00Z`
`created_lt`	string(date-time)	No	Upper bound of the creation time (exclusive), as ISO 8601 with a time zone. Example: `2026-09-24T00:00:00Z`

Request example

curl

curl -X GET 'https://api.fluxan.co/v1/payments?limit=20' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>'

Placeholders to replace

<TEST_SERVER_API_KEY>: Test-environment server API key, created on the "API Key" page of the merchant portal

Note

Server API keys must only be used on your own server, so the docs site doesn't offer interactive API testing. Get a test key: API Key page in the merchant portal (opens the merchant portal in a new tab) (Test environment; Requires Owner, Admin or Developer)

Responses

The payment list.

First page (there are more results: continue with next_cursor and the same filters)

{
  "data": [
    {
      "id": "pay_demo_001",
      "merchant_order_no": "ORDER-DEMO-001",
      "environment": "test",
      "amount": 10000,
      "currency": "USD",
      "status": "succeeded",
      "resolution_status": "known",
      "captured_amount": 10000,
      "refunded_amount": 0,
      "refund_returned_amount": 0,
      "refund_reserved_amount": 0,
      "refund_status": "none",
      "authentication_status": "authenticated",
      "reconciliation_status": "pending",
      "upstream_receipt_status": "not_received",
      "latest_attempt_id": "pat_demo_001",
      "attempt_count": 1,
      "version": 4,
      "next_action": null,
      "failure": null,
      "description": "Example order",
      "customer_reference": "CUSTOMER-DEMO-001",
      "metadata": {
        "business_order_type": "one_time_purchase"
      },
      "card": {
        "brand": "visa",
        "last4": "1234"
      },
      "created_at": "2026-09-23T09:00:00Z",
      "succeeded_at": "2026-09-23T09:04:30Z",
      "expires_at": "2026-09-23T09:30:00Z"
    },
    {
      "id": "pay_demo_002",
      "merchant_order_no": "ORDER-DEMO-002",
      "environment": "test",
      "amount": 10000,
      "currency": "USD",
      "status": "succeeded",
      "resolution_status": "known",
      "captured_amount": 10000,
      "refunded_amount": 0,
      "refund_returned_amount": 0,
      "refund_reserved_amount": 0,
      "refund_status": "none",
      "authentication_status": "not_required",
      "reconciliation_status": "pending",
      "upstream_receipt_status": "not_received",
      "latest_attempt_id": "pat_demo_002",
      "attempt_count": 1,
      "version": 3,
      "next_action": null,
      "failure": null,
      "description": "Example order",
      "customer_reference": "CUSTOMER-DEMO-002",
      "metadata": {
        "business_order_type": "one_time_purchase"
      },
      "card": {
        "brand": "visa",
        "last4": "1234"
      },
      "created_at": "2026-09-23T08:58:00Z",
      "succeeded_at": "2026-09-23T08:58:06Z",
      "expires_at": "2026-09-23T09:28:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_demo_opaque_001",
  "request_id": "req_demo_029"
}

Response fields

Paginated list: data is an array of objects. When has_more is true, use next_cursor to fetch the next page. See the object section for field descriptions.

Name	Type	Required	Description
`data`	array<Payment>	Required
`id`	string	Required	Platform payment ID. Example: `pay_demo_001`
`merchant_order_no`	string	Required	Merchant order ID, case-sensitive as sent. Example: `ORDER-DEMO-001`
`environment`	string	Required	Environment: test is the test environment and live is the live environment. Test and live objects are isolated from each other. `test` `live` More values may be added in the future. Don't treat a status you don't recognize as success. Example: `test`
`amount`	integer(int64)	Required	Order amount, in the smallest currency unit. It can't be changed after the first submission to the provider. Constraints: `≥ 1` Example: `10000`
`currency`	string	Required	Uppercase three-letter currency code. Constraints: `Format ^[A-Z]{3}$` Example: `USD`
`status`	string	Required	Payment status. Clients must not treat an unknown status as success. created: the order has been created and no valid charge attempt has been submitted yet; new attempts are allowed within the validity period processing: submitted and being processed, or the outcome isn't confirmed yet; new attempts aren't allowed requires_action: the current attempt needs the payer to complete an action such as authentication; new attempts aren't allowed failed: the latest attempt clearly failed; this is not a terminal state, and an explicit retry is possible when the deadline, attempt limit and risk conditions are met succeeded: payment confirmed as successful canceled: cancellation confirmed as safe expired: no unresolved attempt, and the order has expired and closed `created`: The order has been created and no valid charge attempt has been submitted yet; new attempts are allowed within the validity period `processing`: Submitted and being processed, or the outcome isn't confirmed yet; new attempts aren't allowed `requires_action`: The current attempt needs the payer to complete an action such as authentication; new attempts aren't allowed `failed`: The latest attempt clearly failed; this is not a terminal state, and an explicit retry is possible when the deadline, attempt limit and risk conditions are met `succeeded`: Payment confirmed as successful `canceled`: Cancellation confirmed as safe `expired`: No unresolved attempt, and the order has expired and closed More values may be added in the future. Don't treat a status you don't recognize as success. Example: `requires_action`
`resolution_status`	string	Required	Outcome confirmation. known: outcome confirmed needs_query: outcome unknown; the platform is running a status query against the provider using the original identifiers manual_review: past the automatic query window and handed over to manual follow-up; never marked as failed automatically `known`: Outcome confirmed `needs_query`: Outcome unknown; the platform is running a status query against the provider using the original identifiers `manual_review`: Past the automatic query window and handed over to manual follow-up; never marked as failed automatically More values may be added in the future. Don't treat a status you don't recognize as success. Example: `known`
`captured_amount`	integer(int64)	Required	The amount confirmed as captured; equal to amount on success. Constraints: `≥ 0` Example: `0`
`refunded_amount`	integer(int64)	Required	The confirmed effective refunded principal: the total of successful refunds minus confirmed refund returns. It excludes refunds that are still processing and platform exception refunds. Constraints: `≥ 0` Example: `0`
`refund_returned_amount`	integer(int64)	Required	The cumulative refund principal confirmed as returned. Constraints: `≥ 0` Example: `0`
`refund_reserved_amount`	integer(int64)	Required	Principal reserved for refunds that are under review or processing. Constraints: `≥ 0` Example: `0`
`refund_status`	string	Required	Refund summary status, derived from refunded_amount (the effective refunded principal): none, partial, full. `none` `partial` `full` More values may be added in the future. Don't treat a status you don't recognize as success. Example: `none`
`authentication_status`	stringNullable	Required	The 3DS authentication status of the current attempt, taken from the authentication session status: not_required, pending, challenge, authenticated, failed, abandoned, expired. Tolerate new values. Successful authentication (authenticated) doesn't mean the charge succeeded, so don't use it to decide the payment outcome. It's null when there is no attempt yet or the attempt hasn't entered authentication. Example: `challenge`
`reconciliation_status`	ReconciliationStatus	Required	The progress of the platform's funds processing, for reconciliation reference only. It doesn't indicate whether the payment succeeded or when you'll be paid out. `pending` `matched` `difference` `resolved` More values may be added in the future. Don't treat a status you don't recognize as success.
`upstream_receipt_status`	UpstreamReceiptStatus	Required	The progress of the platform's funds processing, for reconciliation reference only. It doesn't indicate whether the payment succeeded or when you'll be paid out. `not_received` `partially_received` `received` `reversed` More values may be added in the future. Don't treat a status you don't recognize as success.
`latest_attempt_id`	stringNullable	Required	ID of the latest payment attempt; null if no attempt has been submitted yet. Example: `pat_demo_001`
`attempt_count`	integer(int32)	Required	The number of attempts started. The default maximum is 3. Constraints: `≥ 0` Example: `1`
`version`	integer(int64)	Required	Object version, which increases with every effective business change. Compare versions to discard older events, and don't order events by status name. Constraints: `≥ 1` Example: `2`
`next_action`	NextActionNullable	Required	The action the payer must complete when status=requires_action; null in all other cases.
`failure`	PaymentFailureNullable	Required	The reason when the attempt that latest_attempt_id points to has clearly failed; otherwise null.
`description`	string	No	Order summary. Constraints: `Max length 256` Example: `Example order`
`customer_reference`	string	No	Merchant-side customer reference. Constraints: `Max length 128` Example: `CUSTOMER-DEMO-001`
`metadata`	object	No	Custom key-value pairs set by the merchant: up to 20 keys. A key can be up to 40 characters, and a value is a string of up to 200 characters. Don't put sensitive data such as card numbers in it. The platform checks for such data and rejects the request. Constraints: `Up to 20 keysMax value length 200` Example: `{"business_order_type":"one_time_purchase"}`
`card`	CardSummaryNullable	Required	Masked details of the card used in the latest attempt; null when there are no card details yet.
`created_at`	string(date-time)	Required	Creation time. Example: `2026-09-23T09:00:00Z`
`succeeded_at`	string(date-time)Nullable	Required	The time the payment was confirmed as successful; null if it hasn't succeeded. Example: `null`
`expires_at`	string(date-time)	Required	The deadline for starting a new attempt, fixed at creation (by default 30 minutes after creation; the platform can adjust it to between 5 and 120 minutes, so go by this field). Expiry only closes the entry point for new attempts. It doesn't invalidate a payment that was already submitted. Example: `2026-09-23T09:30:00Z`
`has_more`	boolean	Required	Whether there is a next page. Example: `false`
`next_cursor`	stringNullable	Required	The cursor for the next page; null when there is no next page. Example: `null`
`request_id`	string	Required	Unique identifier of this request. Example: `req_demo_001`

Possible error codes

HTTP	Error code	When it occurs	How to handle
400	invalid_request	`Idempotency-Key` is missing; the order ID contains invalid characters; `payment_method_data` and `payment_method_id` are submitted together; `confirm=false` carries card details; `confirm=true` has no `return_url`; a checkout session request sends both groups of identity parameters, or neither; a `browser_info` / `billing_details` field the provider requires is missing; the cursor, time format or `limit` is invalid	Fix the request according to `error.field` and resubmit it; don't charge again automatically
401	unauthenticatedCommon	No `Authorization` header was sent; the key was copied incompletely; the old key expired after a rotation; the key was revoked	Check your credentials: on the API Key page in the merchant portal, verify the key's status and environment
403	forbiddenCommon	Creating a refund with a read-only key; calling `getEvent` without the read scope for the event's business area; if the request's source IP isn't on the key's allowlist, the more specific `ip_not_allowed` is returned	Use a key that has the required scope; don't work around the restriction
429	rate_limitedCommon	A rate limit per merchant and per key; switching keys doesn't get around the merchant's overall limit	Wait for `Retry-After` seconds, then retry with the original idempotency key
500	internal_errorCommon	—	Retry with the original idempotency key, or query by merchant order ID / refund ID; never charge again with a new key
502 / 503	upstream_unavailableCommon	A provider or platform dependency failed, and the platform can't confirm whether this request took effect	Same as above

Notes

You can filter by merchant_order_no (exact match, case-sensitive), status, and created_gte (inclusive) / created_lt (exclusive).
Results are ordered by created_at descending, with ties broken by id descending. When you page through results, send the same filters as for the first page. See Pagination.

Error codes and HTTP status

Was this page helpful?