Arguments, results, errors, and access, confirmation, and retry policy for each Checkouts tool in FloPay MCP, from the reviewed API contract.

Checkouts tools

Generated from the FloPay MCP contract version 1, revision 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.

CheckoutAnalytics_get

Checkout performance stats

Returns loads and canonical session-cohort attempt totals, conversion, and money-derived ratios anchored to session creation; transaction tries and approval use attempt-row creation time; headline non-rebill purchase transactions and revenue use financial business time. An automatic upsell is a customer-linked automatic sale preceded at or before its business time, and by strictly less than 24 hours, by a successful standard sale for the same client and resolved customer; each automatic sale is counted once and attributed by its own business time. Refund and chargeback counts and amounts sit beside the gross figures on an issued-period (occurrence) basis: refunds are attributed by their own financial effective date and chargebacks by their own money-movement effective date within the half-open reporting interval, so they can exceed 100% of gross and are never clamped.

Policy	Value
Operation	`GET /v1/checkouts/stats`
Class	`read-only`
Risk	`medium`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`aggregate`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`from`	query	string	Yes	Inclusive reporting-period start as an ISO-8601 instant.
`to`	query	string	Yes	Exclusive reporting-period end as an ISO-8601 instant.

Result

Returns 200 with a JSON body. One coherent checkout performance snapshot.

Field	Type	Required	Description
`attempts`	object	Yes
`attempts.approvalRate`	number or null	No	Approved transaction tries divided by transaction tries from the same attempt-outcome period. Minimum: 0.
`attempts.revenuePerAttempt`	number or null	No	Canonical session-cohort revenue divided by attempted session-cohort checkouts. Minimum: 0.
`attempts.toSalesConversionPercentage`	number or null	No	Conversion percentage: session-cohort canonical sales divided by attempted session-cohort checkouts. Minimum: 0.
`attempts.total`	integer	No	Distinct selected-period session-cohort checkouts with an attempt inside 24 hours. Minimum: 0.
`attempts.transactionTries`	integer	No	Transaction-attempt outcomes attributed by lifecycle transition time for managed rows and creation time for legacy rows. Minimum: 0.
`context`	object	Yes
`context.appliedFilters`	array of object	Yes	Additional filters applied after the authoritative tenant boundary. Empty for merchant calls.
`context.appliedFilters[].field`	string	Yes
`context.appliedFilters[].operator`	string	Yes	Allowed values: `eq`.
`context.appliedFilters[].value`	string	Yes
`context.authoritativeLinks`	array of object	Yes	Relative authenticated Flo API links for verifying authoritative source records.
`context.authoritativeLinks[].href`	string	Yes
`context.authoritativeLinks[].rel`	string	Yes
`context.consistency`	object	Yes	The consistency model and its operator-facing freshness caveat.
`context.consistency.model`	string	Yes	Allowed values: `eventual`.
`context.consistency.note`	string	Yes
`context.currency`	object	Yes	Reporting-currency basis and immutable daily FX snapshots for home/platform totals. Source amounts remain separately segmented.
`context.currency.fx`	object	Yes
`context.currency.fx.applied`	boolean	Yes	Whether this aggregate contains monetary values that were FX-valued.
`context.currency.fx.effectiveDateTimezone`	string	Yes	Allowed values: `UTC`.
`context.currency.fx.method`	string	Yes	Allowed values: `daily-exact-or-prior`.
`context.currency.fx.provisional`	boolean	Yes
`context.currency.fx.snapshots`	array of object	Yes
`context.currency.fx.snapshots[].provisional`	boolean	Yes
`context.currency.fx.snapshots[].valuationDate`	string (date)	Yes
`context.currency.fx.snapshots[].version`	integer	Yes	Minimum: 1.
`context.currency.homeCurrency`	string or null	Yes	Minimum length: 3. Maximum length: 3.
`context.currency.reportingCurrency`	string	Yes	Minimum length: 3. Maximum length: 3.
`context.currency.reportingCurrencyBasis`	string	Yes	Allowed values: `client-home`, `platform-usd`.
`context.dataAsOf`	string (date-time)	Yes	The persisted-data observation boundary for this response.
`context.generatedAt`	string (date-time)	Yes	When the API generated this response.
`context.statusSemantics`	array of object	Yes	Canonical definitions and time bases for statuses and outcomes used in the response.
`context.statusSemantics[].appliesTo`	array of string	Yes
`context.statusSemantics[].code`	string	Yes
`context.statusSemantics[].description`	string	Yes
`context.statusSemantics[].timeBasis`	string	Yes	Allowed values: `created-at`, `financial-effective-at`, `billing-cycle-at`, `attempt-outcome-at`.
`context.tenantScope`	object	Yes	The explicit client-selection mode used by the authenticated backend query.
`context.tenantScope.clientId`	string or null	Yes
`context.tenantScope.kind`	string	Yes	Allowed values: `authenticated-client`, `selected-client`, `all-clients`.
`context.timeRange`	object	Yes	The explicit half-open UTC reporting window applied to the aggregate.
`context.timeRange.bounds`	string	Yes	Allowed values: `[from,to)`.
`context.timeRange.from`	string (date-time)	Yes
`context.timeRange.timezone`	string	Yes	Allowed values: `UTC`.
`context.timeRange.to`	string (date-time)	Yes
`currency`	string	Yes	Minimum length: 3. Maximum length: 3.
`finalAt`	string (date-time)	Yes	The unchanged instant 24 hours after the requested period ends when isFinal becomes true.
`isFinal`	boolean	Yes	True after the existing checkout-attribution finality window closes; it does not guarantee that financial totals are frozen against later-arriving settlements.
`loads`	object	Yes
`loads.revenuePerLoad`	number or null	No	Canonical session-cohort revenue divided by checkout sessions created in this period. Minimum: 0.
`loads.toSalesConversionPercentage`	number or null	No	Conversion percentage: session-cohort canonical sales divided by checkout sessions created in this period. Minimum: 0.
`loads.total`	integer	No	Checkout sessions attributed to this period by session creation time. Minimum: 0.
`period`	object	Yes
`period.from`	string (date-time)	No
`period.to`	string (date-time)	No
`revenue`	object	Yes
`revenue.averageOrderValue`	number or null	No	Canonical session-cohort revenue divided by the canonical session-cohort sale count. Minimum: 0.
`revenue.chargebacks`	object	No	Deprecated compatibility alias for `disputes`. Same values as `revenue.disputes`. Removal is tracked separately.
`revenue.chargebacks.amount`	number	No	FX-valued charged-back amount for this period.
`revenue.chargebacks.percentageOfRevenue`	number or null	No	Charged-back amount divided by gross revenue amount from exact unrounded totals, HALF_UP to two places; null when gross revenue is zero and not clamped above 100%.
`revenue.disputes`	object	No	Disputed amount valued in the same target currency as `revenue.total`, each Dispute money movement valued at its own effective date. Kept gross and separate from `revenue.total`. Network warnings are Pre-Dispute Alerts and are not included.
`revenue.disputes.amount`	number	No	FX-valued disputed amount for this period.
`revenue.disputes.percentageOfRevenue`	number or null	No	Disputed amount divided by gross revenue amount from exact unrounded totals, HALF_UP to two places; null when gross revenue is zero and not clamped above 100%.
`revenue.refunds`	object	No	Refunded amount valued in the same target currency as `revenue.total`, each refund valued at its own financial effective date. Kept gross and separate from `revenue.total`.
`revenue.refunds.amount`	number	No	FX-valued refunded amount for this period.
`revenue.refunds.percentageOfRevenue`	number or null	No	Refunded amount divided by gross revenue amount from exact unrounded totals, HALF_UP to two places; null when gross revenue is zero and not clamped above 100%.
`revenue.total`	number	No	Valued revenue from the period non-rebill transaction-identity sales. Minimum: 0.
`revenue.upsells`	object	No	Revenue from qualifying automatic sales valued in the same reporting currency and through the same per-business-day FX path as `revenue.total`.
`revenue.upsells.amount`	number	No	FX-valued revenue from qualifying automatic sales.
`revenue.upsells.percentageOfRevenue`	number or null	No	Exact unrounded upsell revenue divided by exact unrounded gross checkout revenue, HALF_UP to two places; null when gross revenue is zero.
`sales`	object	Yes
`sales.change`	integer or null	No
`sales.chargebacks`	object	No	Deprecated compatibility alias for `disputes`. Same values as `sales.disputes`. Removal is tracked separately.
`sales.chargebacks.count`	integer	No	Chargeback events in this period. Minimum: 0.
`sales.chargebacks.percentageOfSales`	number or null	No	Chargeback count divided by gross sales count, HALF_UP to two places; null when gross sales count is zero and not clamped above 100%.
`sales.comparisonUnavailableReason`	string or null	No	Allowed values: `insufficient_history`.
`sales.direction`	string or null	No	Allowed values: `up`, `down`, `unchanged`.
`sales.disputes`	object	No	Disputes (actual Stripe and PayPal chargebacks) against checkout sales attributed to this period by their own money-movement effective date (issued-period / occurrence basis), independent of when the disputed sale occurred. Disputes against subscription renewal charges are reported on the rebill figures (subscription stats), not here; a dispute against the first charge of a subscription is a checkout sale and stays here. Each dispute money movement is counted once. Network warnings are Pre-Dispute Alerts and are not included.
`sales.disputes.count`	integer	No	Dispute events in this period. Minimum: 0.
`sales.disputes.percentageOfSales`	number or null	No	Dispute count divided by gross sales count, HALF_UP to two places; null when gross sales count is zero and not clamped above 100%.
`sales.previousFrom`	string (date-time) or null	No	Start of the previous equal-duration financial period when history is covered.
`sales.previousSales`	integer or null	No	Non-rebill purchase transactions attributed to the previous period by financial business time. Minimum: 0.
`sales.previousTo`	string (date-time) or null	No	End of the previous equal-duration financial period when history is covered.
`sales.refunds`	object	No	Refunds against checkout sales attributed to this period by their own financial effective date (issued-period / occurrence basis), independent of when the refunded sale occurred. Refunds against subscription renewal charges are reported on the rebill figures (subscription stats), not here; a refund against the first charge of a subscription (including a trial conversion) is a checkout sale and stays here. Each refund is counted once.
`sales.refunds.count`	integer	No	Refund events in this period. Minimum: 0.
`sales.refunds.percentageOfSales`	number or null	No	Refund count divided by gross sales count, HALF_UP to two places; null when gross sales count is zero and not clamped above 100%.
`sales.total`	integer	No	Non-rebill purchase transactions whose financial business time is in this period. Minimum: 0.
`sales.upsells`	object	No	Successful automatic checkout sales in this period whose resolved customer completed a standard buyer-present checkout for the same client at or before the automatic sale and strictly less than 24 hours earlier. Each automatic sale is counted once.
`sales.upsells.count`	integer	No	Qualifying automatic sales in this period. Minimum: 0.
`sales.upsells.percentageOfSales`	number or null	No	Upsell count divided by gross checkout sales count, HALF_UP to two places; null when gross sales count is zero.
`sourceCurrencySegments`	array of object	Yes	Gross source amounts grouped by uppercase ISO currency. Amounts are summed exactly then rounded once to that source currency minor unit; no counts are repeated here.
`sourceCurrencySegments[].currency`	string	Yes	Minimum length: 3. Maximum length: 3.
`sourceCurrencySegments[].disputeAmount`	number	Yes
`sourceCurrencySegments[].refundAmount`	number	Yes
`sourceCurrencySegments[].salesAmount`	number	Yes
`sourceCurrencySegments[].sessionCohortSalesAmount`	number	Yes
`sourceCurrencySegments[].upsellAmount`	number	Yes

Errors

Status	Description
`401`	Client Basic authentication or OAuth2 bearer authentication is required.

CheckoutLink_create

Create a reusable checkout link

Policy	Value
Operation	`POST /v1/checkout-links`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`avsCheck`	body	boolean	No	Enable AVS (Address Verification) on checkouts opened from this link. Default: `false`.
`avsFields`	body	object or null	No	Per-field AVS exposure. Requires `avsCheck` to be enabled. Fields the gateway requires for the buyer's country are always collected regardless of this selection.
`avsFields.city`	body	boolean	No	Expose the city field.
`avsFields.line1`	body	boolean	No	Expose the street address line 1 field.
`avsFields.line2`	body	boolean	No	Expose the street address line 2 field.
`avsFields.postal`	body	boolean	No	Expose the postal / ZIP code field.
`avsFields.state`	body	boolean	No	Expose the state / province / region field.
`cancelUrl`	body	string (uri) or null	No	Maximum length: 2048.
`captureMethod`	body	string	No	Allowed values: `automatic`, `manual`. Default: `automatic`.
`checkoutMode`	body	string	No	Checkout mode the hosted link opens in. Only `full` is currently supported on a reusable link; other modes are rejected because a fresh anonymous buyer lacks their prerequisites. Allowed values: `auto`, `full`, `confirm`, `setup`. Default: `full`.
`couponCodes`	body	array of string	No	Default: `[]`.
`currency`	body	string	Yes	Minimum length: 3. Maximum length: 3.
`expiresAt`	body	string (date-time) or null	No
`products`	body	array of object	Yes	Minimum items: 1.
`products[].code`	body	string	Yes
`products[].quantity`	body	number	Yes	Minimum: 1.
`products[].variantId`	body	string (uuid)	No
`successUrl`	body	string (uri) or null	No	Maximum length: 2048.
`surface`	body	string	No	Hosted-page surface: `full_detail` renders order summary and merchandising around the embed; `widget_only` renders just the payment embed. The AVS form lives inside the embed in both surfaces. Allowed values: `full_detail`, `widget_only`. Default: `full_detail`.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`avsCheck`	boolean	Yes
`avsFields`	object or null	Yes
`avsFields.city`	boolean	No	Expose the city field.
`avsFields.line1`	boolean	No	Expose the street address line 1 field.
`avsFields.line2`	boolean	No	Expose the street address line 2 field.
`avsFields.postal`	boolean	No	Expose the postal / ZIP code field.
`avsFields.state`	boolean	No	Expose the state / province / region field.
`cancelUrl`	string or null	Yes
`captureMethod`	string	Yes	Allowed values: `automatic`, `manual`.
`checkoutMode`	string	Yes	Allowed values: `auto`, `full`, `confirm`, `setup`.
`clientId`	string	Yes
`couponCodes`	array of string	Yes
`createdAt`	string (date-time)	Yes
`currency`	string	Yes
`expiresAt`	string (date-time) or null	Yes
`isActive`	boolean	Yes
`products`	array of object	Yes
`products[].code`	string	Yes
`products[].quantity`	number	Yes	Minimum: 1.
`products[].variantId`	string (uuid)	No
`publicToken`	string	Yes
`successUrl`	string or null	Yes
`surface`	string	Yes	Allowed values: `full_detail`, `widget_only`.
`updatedAt`	string (date-time)	Yes
`url`	string	Yes
`uuid`	string	Yes

Errors

Status	Description
`400`	The checkout link options are invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`422`	The selected catalog offer is unavailable.

CheckoutLink_findOne

Get a reusable checkout link

Policy	Value
Operation	`GET /v1/checkout-links/{uuid}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`avsCheck`	boolean	Yes
`avsFields`	object or null	Yes
`avsFields.city`	boolean	No	Expose the city field.
`avsFields.line1`	boolean	No	Expose the street address line 1 field.
`avsFields.line2`	boolean	No	Expose the street address line 2 field.
`avsFields.postal`	boolean	No	Expose the postal / ZIP code field.
`avsFields.state`	boolean	No	Expose the state / province / region field.
`cancelUrl`	string or null	Yes
`captureMethod`	string	Yes	Allowed values: `automatic`, `manual`.
`checkoutMode`	string	Yes	Allowed values: `auto`, `full`, `confirm`, `setup`.
`clientId`	string	Yes
`couponCodes`	array of string	Yes
`createdAt`	string (date-time)	Yes
`currency`	string	Yes
`expiresAt`	string (date-time) or null	Yes
`isActive`	boolean	Yes
`products`	array of object	Yes
`products[].code`	string	Yes
`products[].quantity`	number	Yes	Minimum: 1.
`products[].variantId`	string (uuid)	No
`publicToken`	string	Yes
`successUrl`	string or null	Yes
`surface`	string	Yes	Allowed values: `full_detail`, `widget_only`.
`updatedAt`	string (date-time)	Yes
`url`	string	Yes
`uuid`	string	Yes

Errors

Status	Description
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`404`	No checkout link with the requested id exists for this client.

CheckoutLink_list

List reusable checkout links

Policy	Value
Operation	`GET /v1/checkout-links`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `id`, `createdAt`, `updatedAt`, `expiresAt`, `isActive`, `currency`, `checkoutMode`, `captureMethod`, `surface`, `avsCheck`. Default: `createdAt` DESC. Allowed values: `id`, `createdAt`, `updatedAt`, `expiresAt`, `isActive`, `currency`, `checkoutMode`, `captureMethod`, `surface`, `avsCheck`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`avsCheck`	query	string	No	Whether AVS collection is enabled for the link. Equality filter. Pass without operator for exact match. Allowed values: `true`, `false`.
`cancelUrl`	query	string	No	Buyer cancellation destination URL. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`captureMethod`	query	string	No	Checkout capture method. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `automatic`, `manual`.
`checkoutMode`	query	string	No	Checkout mode stored on the link. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `auto`, `full`, `confirm`, `setup`.
`couponCodes`	query	string	No	Individual coupon codes stored on the link. Pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`createdAt`	query	string (date-time)	No	Checkout link creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`currency`	query	string	No	Uppercase ISO 4217 checkout currency. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`expiresAt`	query	string (date-time)	No	Optional checkout link expiry timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`id`	query	string (uuid)	No	Checkout link id. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`isActive`	query	string	No	Whether the link can currently resolve for buyers. Equality filter. Pass without operator for exact match. Allowed values: `true`, `false`.
`products`	query	string	No	Product code or optional variant id stored on the link. Pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`publicToken`	query	string	No	Opaque public checkout-link token. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`successUrl`	query	string	No	Buyer success destination URL. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`surface`	query	string	No	Hosted checkout presentation surface. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `full_detail`, `widget_only`.
`updatedAt`	query	string (date-time)	No	Checkout link update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].avsCheck`	boolean	Yes
`data[].avsFields`	object or null	Yes
`data[].avsFields.city`	boolean	No	Expose the city field.
`data[].avsFields.line1`	boolean	No	Expose the street address line 1 field.
`data[].avsFields.line2`	boolean	No	Expose the street address line 2 field.
`data[].avsFields.postal`	boolean	No	Expose the postal / ZIP code field.
`data[].avsFields.state`	boolean	No	Expose the state / province / region field.
`data[].cancelUrl`	string or null	Yes
`data[].captureMethod`	string	Yes	Allowed values: `automatic`, `manual`.
`data[].checkoutMode`	string	Yes	Allowed values: `auto`, `full`, `confirm`, `setup`.
`data[].clientId`	string	Yes
`data[].couponCodes`	array of string	Yes
`data[].createdAt`	string (date-time)	Yes
`data[].currency`	string	Yes
`data[].expiresAt`	string (date-time) or null	Yes
`data[].isActive`	boolean	Yes
`data[].products`	array of object	Yes
`data[].products[].code`	string	Yes
`data[].products[].quantity`	number	Yes	Minimum: 1.
`data[].products[].variantId`	string (uuid)	No
`data[].publicToken`	string	Yes
`data[].successUrl`	string or null	Yes
`data[].surface`	string	Yes	Allowed values: `full_detail`, `widget_only`.
`data[].updatedAt`	string (date-time)	Yes
`data[].url`	string	Yes
`data[].uuid`	string	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.

getCheckoutDeclineAnalysis

Analyze checkout payment failures

Returns current DECLINE and ERROR transaction-attempt outcomes for the authenticated merchant in an explicit half-open UTC period, grouped by source currency, canonical Flo decline reason, provider, and result. Managed provider objects are selected by lifecycle transition time; legacy append-only attempts use creation time. PENDING and ACTION_REQUIRED continuations and positive SUCCESS/AUTHORIZED outcomes are excluded.

Policy	Value
Operation	`GET /v1/checkouts/decline-analysis`
Class	`read-only`
Risk	`medium`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`aggregate`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`from`	query	string	Yes	Inclusive reporting-period start as an ISO-8601 instant.
`to`	query	string	Yes	Exclusive reporting-period end as an ISO-8601 instant.

Result

Returns 200 with a JSON body. One tenant-scoped current checkout-failure snapshot.

Field	Type	Required	Description
`affectedCheckoutSessionCount`	integer	Yes	Distinct checkout sessions represented by the selected failure attempts. Minimum: 0.
`context`	object	Yes
`context.appliedFilters`	array of object	Yes	Additional filters applied after the authoritative tenant boundary. Empty for merchant calls.
`context.appliedFilters[].field`	string	Yes
`context.appliedFilters[].operator`	string	Yes	Allowed values: `eq`.
`context.appliedFilters[].value`	string	Yes
`context.authoritativeLinks`	array of object	Yes	Relative authenticated Flo API links for verifying authoritative source records.
`context.authoritativeLinks[].href`	string	Yes
`context.authoritativeLinks[].rel`	string	Yes
`context.consistency`	object	Yes	The consistency model and its operator-facing freshness caveat.
`context.consistency.model`	string	Yes	Allowed values: `eventual`.
`context.consistency.note`	string	Yes
`context.currency`	object	Yes	Reporting-currency basis and immutable daily FX snapshots for home/platform totals. Source amounts remain separately segmented.
`context.currency.fx`	object	Yes
`context.currency.fx.applied`	boolean	Yes	Whether this aggregate contains monetary values that were FX-valued.
`context.currency.fx.effectiveDateTimezone`	string	Yes	Allowed values: `UTC`.
`context.currency.fx.method`	string	Yes	Allowed values: `daily-exact-or-prior`.
`context.currency.fx.provisional`	boolean	Yes
`context.currency.fx.snapshots`	array of object	Yes
`context.currency.fx.snapshots[].provisional`	boolean	Yes
`context.currency.fx.snapshots[].valuationDate`	string (date)	Yes
`context.currency.fx.snapshots[].version`	integer	Yes	Minimum: 1.
`context.currency.homeCurrency`	string or null	Yes	Minimum length: 3. Maximum length: 3.
`context.currency.reportingCurrency`	string	Yes	Minimum length: 3. Maximum length: 3.
`context.currency.reportingCurrencyBasis`	string	Yes	Allowed values: `client-home`, `platform-usd`.
`context.dataAsOf`	string (date-time)	Yes	The persisted-data observation boundary for this response.
`context.generatedAt`	string (date-time)	Yes	When the API generated this response.
`context.statusSemantics`	array of object	Yes	Canonical definitions and time bases for statuses and outcomes used in the response.
`context.statusSemantics[].appliesTo`	array of string	Yes
`context.statusSemantics[].code`	string	Yes
`context.statusSemantics[].description`	string	Yes
`context.statusSemantics[].timeBasis`	string	Yes	Allowed values: `created-at`, `financial-effective-at`, `billing-cycle-at`, `attempt-outcome-at`.
`context.tenantScope`	object	Yes	The explicit client-selection mode used by the authenticated backend query.
`context.tenantScope.clientId`	string or null	Yes
`context.tenantScope.kind`	string	Yes	Allowed values: `authenticated-client`, `selected-client`, `all-clients`.
`context.timeRange`	object	Yes	The explicit half-open UTC reporting window applied to the aggregate.
`context.timeRange.bounds`	string	Yes	Allowed values: `[from,to)`.
`context.timeRange.from`	string (date-time)	Yes
`context.timeRange.timezone`	string	Yes	Allowed values: `UTC`.
`context.timeRange.to`	string (date-time)	Yes
`failureAttemptCount`	integer	Yes	Minimum: 0.
`missingCanonicalReasonAttemptCount`	integer	Yes	Failure attempts with no persisted canonical reason. Distinct from the canonical UNKNOWN_DECLINE_REASON bucket. Minimum: 0.
`sourceCurrencySegments`	array of object	Yes
`sourceCurrencySegments[].affectedCheckoutSessionCount`	integer	Yes	Minimum: 1.
`sourceCurrencySegments[].currency`	string or null	Yes	Minimum length: 3. Maximum length: 3.
`sourceCurrencySegments[].currencyStatus`	string	Yes	Allowed values: `known`, `unavailable`, `mixed`.
`sourceCurrencySegments[].failureAttemptCount`	integer	Yes	Minimum: 1.
`sourceCurrencySegments[].groups`	array of object	Yes
`sourceCurrencySegments[].groups[].affectedCheckoutSessionCount`	integer	Yes	Minimum: 1.
`sourceCurrencySegments[].groups[].attemptCount`	integer	Yes	Minimum: 1.
`sourceCurrencySegments[].groups[].canonicalReason`	string or null	Yes	Allowed values: `INSUFFICIENT_FUNDS`, `DO_NOT_HONOUR`, `TOO_MANY_ATTEMPTS`, `PARTIAL_APPROVAL`, `PAYMENT_GATEWAY_ERROR`, `TECHNICAL_ERROR`, `RETRYABLE_DECLINE`, `UNSUPPORTED_CARD_PURCHASE`, `USER_ERROR`, `CVV_INVALID`, `AVS_FAIL`, `POSTCODE_INVALID`, `3DS_FAIL`, `EXCEEDS_CARD_LIMIT`, `CLIENT_ERROR`, `UNKNOWN_DECLINE_REASON`.
`sourceCurrencySegments[].groups[].provider`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`sourceCurrencySegments[].groups[].result`	string	Yes	Allowed values: `DECLINE`, `ERROR`.

Errors

Status	Description
`400`	The reporting range is missing or invalid.
`401`	Client Basic or OAuth2 bearer authentication is required.
`403`	The bearer token does not grant the required merchant read scope.
`429`	The merchant aggregate rate limit was exceeded.

Session_createSetup

Create Card Setup Session

Creates a no-charge card setup session for an existing customer linked to the authenticated client.

Policy	Value
Operation	`POST /v1/checkouts/sessions/setup`
Class	`mutating`
Risk	`medium`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`mutation`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`cancelUrl`	body	string or null	No	Default: `null`. Maximum length: 2048.
`successUrl`	body	string or null	No	Default: `null`. Maximum length: 2048.
`userId`	body	string (uuid)	Yes	Flo customer UUID. The customer must already belong to the authenticated client.

Result

Returns 201 with a JSON body. A checkout session was created and requires client-side follow-up.

Field	Type	Required	Description
`autoProcessingAttempted`	boolean	No
`autoProcessingError`	object	No
`autoProcessingError.advice`	string	No	Advice for next action.
`autoProcessingError.fields`	array of object	No
`autoProcessingError.fields[].field`	string	Yes
`autoProcessingError.fields[].message`	string	Yes
`autoProcessingError.gatewayErrorCode`	string	No	Gateway-specific error code.
`autoProcessingError.message`	string	No	Message to display to user.
`autoProcessingError.nextActionRedirectUrl`	string	No	Provider-hosted next-action URL (e.g. Stripe 3DS challenge page) the SDK must render to obtain client authentication. Set together with `type=three_d_secure_required`; without it the SDK cannot present the challenge and the attempt times out.
`autoProcessingError.orderId`	string	No	PayPal Order id (or Subscription id, for subscription checkouts) the SDK should bind its DirectPayPalButton to. Returned alongside `type=paypal_direct_required` so the buyer can re-approve via PayPal without re-creating the intent on the backend.
`autoProcessingError.paymentMethodId`	string	No	Payment method identifier when available.
`autoProcessingError.threeDSecureToken`	string	No	3DS token used for 3DS authentication.
`autoProcessingError.transactionId`	string	No	Transaction ID if available.
`autoProcessingError.type`	string	Yes	Exception type based on action. Allowed values: `3ds_required`, `paypal_redirect_required`, `paypal_direct_required`, `unknown`.
`autoProcessingPending`	object	No
`autoProcessingPending.retryAfterMs`	number	Yes
`autoProcessingPending.sessionId`	string	Yes
`autoProcessingPending.sessionUrl`	string	Yes
`autoProcessingPending.statusUrl`	string	Yes
`autoProcessingPending.type`	string	Yes
`data`	object	Yes
`data.accountData`	object	Yes
`data.accountData.addressLine1`	string or null	Yes	Default: `null`.
`data.accountData.addressLine2`	string or null	Yes	Default: `null`.
`data.accountData.city`	string or null	Yes	Default: `null`.
`data.accountData.country`	string or null	Yes	Default: `null`.
`data.accountData.email`	string or null	Yes
`data.accountData.firstName`	string	Yes
`data.accountData.gender`	string or null	Yes	Default: `null`.
`data.accountData.lastName`	string	Yes
`data.accountData.state`	string or null	Yes	Default: `null`.
`data.accountData.userId`	string or null	Yes
`data.accountData.zip`	string or null	Yes	Default: `null`.
`data.authorizationExpiresAt`	string (date-time) or null	Yes
`data.authorizationVoidReason`	string or null	Yes	Allowed values: `merchant_requested`, `expired`, `provider_canceled`.
`data.avsCheck`	boolean	Yes	Whether AVS was enabled for this session.
`data.buyerIdentified`	boolean	Yes	False when the session has no buyer email yet (an anonymous / Flo-hosted checkout). Lets a reader distinguish "email not collected yet" from an empty email: attach one by re-entering the claim endpoint with a buyer block. Always true for every session created with a buyer.
`data.cancelUrl`	string or null	Yes
`data.captureMethod`	string	Yes	Whether the checkout captures immediately or reserves funds for merchant capture. Allowed values: `automatic`, `manual`.
`data.checkoutLayout`	string or null	Yes	default_layout, buttons_layout, or custom_layout.
`data.checkoutMetadata`	object	No	Immutable non-sensitive client context supplied when the checkout session was created.
`data.checkoutMode`	string	Yes	Allowed values: `auto`, `full`, `confirm`, `setup`.
`data.checkoutType`	string or null	Yes	standard_checkout or embedded_checkout.
`data.clientId`	string or null	Yes	UUID of the Flopay client account that owns this checkout session. Returned so SDKs and the demo portal can keep multi-account sessions in sync with the right client.
`data.coupons`	array of string	Yes
`data.createdAt`	string (date-time)	Yes
`data.dataAttachmentDeferred`	boolean	Yes	True only for an opt-in lightweight session that still requires buyer and catalog data through the claim endpoint.
`data.discountAmount`	number	Yes	Total reduction in major units of the session currency: includes both sale savings and coupon reductions (subtotalAmount - totalAmount).
`data.gateways`	object	Yes
`data.gateways.paypal`	object or null	Yes
`data.gateways.paypal.enabledPaymentMethodCountries`	object	Yes	Per-method buyer-country gate; methods omitted here are country-agnostic.
`data.gateways.paypal.enabledPaymentMethods`	array of string	Yes	Stripe payment method types enabled on the routed gateway account, filtered against the session's mode and with `card` excluded.
`data.gateways.paypal.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateways.paypal.providerObjectType`	string	No	Allowed values: `order`, `setup_token`.
`data.gateways.paypal.publishableKey`	string or null	Yes
`data.gateways.stripe`	object or null	Yes
`data.gateways.stripe.enabledPaymentMethodCountries`	object	Yes	Per-method buyer-country gate; methods omitted here are country-agnostic.
`data.gateways.stripe.enabledPaymentMethods`	array of string	Yes	Stripe payment method types enabled on the routed gateway account, filtered against the session's mode and with `card` excluded.
`data.gateways.stripe.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateways.stripe.providerObjectType`	string	No	Allowed values: `order`, `setup_token`.
`data.gateways.stripe.publishableKey`	string or null	Yes
`data.gateways.worldpayCorporateGateway`	object	No
`data.gateways.worldpayCorporateGateway.enabledPaymentMethodCountries`	object	Yes	Per-method buyer-country gate; methods omitted here are country-agnostic.
`data.gateways.worldpayCorporateGateway.enabledPaymentMethods`	array of string	Yes	Stripe payment method types enabled on the routed gateway account, filtered against the session's mode and with `card` excluded.
`data.gateways.worldpayCorporateGateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data.gateways.worldpayCorporateGateway.providerObjectType`	string	No	Allowed values: `order`, `setup_token`.
`data.gateways.worldpayCorporateGateway.publishableKey`	string or null	Yes
`data.items`	array of object	Yes	Deprecated. Use `products[]` filtered by `type === "item"`. Removal tracked separately.
`data.items[].checkoutSessionId`	string	Yes
`data.items[].currency`	string	Yes
`data.items[].metadata`	object or null	Yes
`data.items[].providerItemDescription`	string or null	No
`data.items[].providerItemId`	string	Yes
`data.items[].providerItemName`	string	Yes
`data.items[].quantity`	number	Yes
`data.items[].totalAmount`	number	Yes
`data.items[].uuid`	string	Yes
`data.nonce`	string	Yes
`data.products`	array of object	Yes
`data.products[].checkoutSessionId`	string	Yes
`data.products[].code`	string	Yes
`data.products[].currency`	string	Yes
`data.products[].description`	string or null	No
`data.products[].metadata`	object or null	Yes
`data.products[].name`	string	Yes
`data.products[].originalAmount`	number or null	No	The original (non-sale) price in major units. Present only when a sale is active, allowing the client to display strikethrough pricing.
`data.products[].overrideAmount`	number or null	No	Set to 0 when the resolved subscription product has a non-zero recurring trial period. Absent when the catalog was not resolved.
`data.products[].productId`	string or null	No	Stable Flopay catalog product UUID.
`data.products[].productPriceId`	string or null	No	Stable Flopay catalog price UUID.
`data.products[].quantity`	number	Yes
`data.products[].rebillAmount`	number or null	No	Go-forward renewal price in major units for a subscription product. When a sale is active and rebillAtSaleAmount is false this is the full (non-sale) amount; when rebillAtSaleAmount is true it stays the sale price. Absent for non-subscription products.
`data.products[].rebillAtSaleAmount`	boolean or null	No	Whether an active sale price is retained for the lifetime of the subscription (true) or applies to the first charge only (false). Absent for non-subscription products.
`data.products[].saleAmount`	number or null	No	Active sale price in major units. Present only when the product has a sale running within its valid date range.
`data.products[].saleEndsAt`	string (date-time) or null	No	End of the sale window (inclusive). Null when the sale has no end constraint.
`data.products[].saleStartsAt`	string (date-time) or null	No	Start of the sale window (inclusive). Null when the sale has no start constraint.
`data.products[].totalAmount`	number	Yes
`data.products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`data.products[].uuid`	string	Yes
`data.products[].variantId`	string or null	No	Selected Flopay catalog variant UUID.
`data.status`	string	Yes	Allowed values: `pending`, `authorized`, `completed`, `voided`.
`data.subscriptions`	array of object	Yes	Deprecated. Use `products[]` filtered by `type === "subscription"`. Removal tracked separately.
`data.subscriptions[].checkoutSessionId`	string	Yes
`data.subscriptions[].currency`	string	Yes
`data.subscriptions[].metadata`	object or null	Yes
`data.subscriptions[].overrideAmount`	number or null	No	Set to 0 when the resolved product has a non-zero recurring trial period. Absent on responses where the catalog was not resolved.
`data.subscriptions[].providerPlanDescription`	string or null	Yes
`data.subscriptions[].providerPlanId`	string	Yes
`data.subscriptions[].providerPlanName`	string or null	Yes
`data.subscriptions[].quantity`	number	Yes
`data.subscriptions[].totalAmount`	number	Yes
`data.subscriptions[].uuid`	string	Yes
`data.subtotalAmount`	number	Yes	Cart subtotal in major units using original (non-sale) catalog prices. When no sale is active this equals the sum of product prices before coupon reductions.
`data.successUrl`	string or null	Yes
`data.tagsData`	object	Yes
`data.tagsData.googleContainerId`	string or null	Yes
`data.tagsData.sessionId`	string or null	Yes
`data.tagsData.testEventCode`	string or null	Yes
`data.totalAmount`	number	Yes	Final cart total in major units (subtotalAmount - discountAmount), clamped at zero.
`data.transactionAttempts`	array of object	Yes
`data.transactionAttempts[].checkoutSessionsUuid`	string	Yes
`data.transactionAttempts[].createdAt`	string (date-time)	Yes
`data.transactionAttempts[].declineReason`	string or null	Yes	Allowed values: `INSUFFICIENT_FUNDS`, `DO_NOT_HONOUR`, `TOO_MANY_ATTEMPTS`, `PARTIAL_APPROVAL`, `PAYMENT_GATEWAY_ERROR`, `TECHNICAL_ERROR`, `RETRYABLE_DECLINE`, `UNSUPPORTED_CARD_PURCHASE`, `USER_ERROR`, `CVV_INVALID`, `AVS_FAIL`, `POSTCODE_INVALID`, `3DS_FAIL`, `EXCEEDS_CARD_LIMIT`, `CLIENT_ERROR`, `UNKNOWN_DECLINE_REASON`.
`data.transactionAttempts[].gateway`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.transactionAttempts[].nextActionRedirectUrl`	string or null	Yes	Provider-hosted next-action URL (e.g. Stripe 3DS challenge page). Populated together with `result=ACTION_REQUIRED`; the SDK loads this URL in an iframe / popup to let the buyer complete the challenge.
`data.transactionAttempts[].providerIntentId`	string or null	Yes	Provider PaymentIntent id (e.g. Stripe `pi_*`) the attempt is bound to. Surfaced so the SDK can correlate a 3DS challenge to its originating intent and so `/3ds/complete` has the id without re-parsing the client secret.
`data.transactionAttempts[].result`	string	Yes	Allowed values: `PENDING`, `AUTHORIZED`, `SUCCESS`, `DECLINE`, `ERROR`, `ACTION_REQUIRED`.
`data.transactionAttempts[].uuid`	string	Yes
`data.uuid`	string	Yes
`vault`	object	No	Embedded vault capture credentials for a pending card-capable session, independent of the reported SDK version. The explicit `POST /v1/checkouts/sessions/{id}/vault/capture` endpoint remains available for idempotent recovery and retry.
`vault.expectedOrigin`	string	No	Exact hosted-form origin the SDK targets and accepts for vault postMessages.
`vault.html`	string	No	PCIVault hosted-form HTML the SDK injects into the buyer flow. Already wrapped in the Flo bundle (event listeners, postMessage handshake).
`vault.messageToken`	string	No	Per-session token authenticating messages exchanged with the hosted vault form.
`vault.secret`	string	No	PCIVault submit secret used in the form POST.
`vault.url`	string	No	PCIVault submit URL the hosted form POSTs to.

Errors

Status	Description
`400`	The request body, session id, or resolved product provider credentials were invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`404`	The requested customer is unknown or is not linked to the authenticated client, or no active card gateway is available.
`424`	Throws in cases where Billing service cannot get data from billing provider.

Session_exportSessions

Export checkout-sessions

Exports the resource-owned list as a point-in-time framed stream. Reuses this endpoint's list query filters and sort. current_page preserves page/limit; all_matching ignores page/limit while preserving filters and sort. Client routes require an OAuth client_user owner/admin token; admin routes require a single valid clientId selector; partner routes require an authenticated partner seat and are scoped to that partner. Ordinary members, client Basic auth, and cross-tenant requests are rejected.

Policy	Value
Operation	`POST /v1/checkouts/sessions/exports`
Class	`read-only`
Risk	`medium`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`aggregate`
Roles	`owner`, `admin`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `createdAt`, `status`, `updatedAt`, `products.id`, `products.productId`, `products.code`, `products.name`, `products.description`, `products.type`, `products.currency`, `products.totalAmount`, `products.quantity`, `products.createdAt`, `products.updatedAt`, `transactionAttempts.id`, `transactionAttempts.gateway`, `transactionAttempts.result`, `transactionAttempts.declineReason`, `transactionAttempts.gatewayPaymentIntentId`, `transactionAttempts.createdAt`, `user.id`, `user.email`, `user.firstName`, `user.lastName`, `user.createdAt`, `user.updatedAt`, `utmMetadata.id`, `utmMetadata.utmMedium`, `utmMetadata.utmCampaign`, `utmMetadata.utmSource`, `utmMetadata.utmTerm`, `utmMetadata.funnelDomain`, `utmMetadata.funnelUrl`, `utmMetadata.sourceOriginKey`, `utmMetadata.splitTestVariable`, `utmMetadata.funnelVersion`, `utmMetadata.createdAt`, `utmMetadata.updatedAt`. Default: `createdAt` DESC. Allowed values: `createdAt`, `status`, `updatedAt`, `products.id`, `products.productId`, `products.code`, `products.name`, `products.description`, `products.type`, `products.currency`, `products.totalAmount`, `products.quantity`, `products.createdAt`, `products.updatedAt`, `transactionAttempts.id`, `transactionAttempts.gateway`, `transactionAttempts.result`, `transactionAttempts.declineReason`, `transactionAttempts.gatewayPaymentIntentId`, `transactionAttempts.createdAt`, `user.id`, `user.email`, `user.firstName`, `user.lastName`, `user.createdAt`, `user.updatedAt`, `utmMetadata.id`, `utmMetadata.utmMedium`, `utmMetadata.utmCampaign`, `utmMetadata.utmSource`, `utmMetadata.utmTerm`, `utmMetadata.funnelDomain`, `utmMetadata.funnelUrl`, `utmMetadata.sourceOriginKey`, `utmMetadata.splitTestVariable`, `utmMetadata.funnelVersion`, `utmMetadata.createdAt`, `utmMetadata.updatedAt`.
`relation`	query	string	No	Comma-separated relation aliases to include. Allowed aliases: `client`, `products`, `transactionAttempts`, `user`, `utmMetadata`. Unknown aliases return 400.
`checkoutMode`	query	string	No	Checkout mode. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `auto`, `full`, `confirm`, `setup`.
`createdAt`	query	string (date-time)	No	Session creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`gateway`	query	string	No	Billing provider recorded on the session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`id`	query	string	No	Alias for `uuid`: matches the Flopay checkout-session UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`status`	query	string	No	Session status. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `pending`, `authorized`, `completed`, `voided`.
`updatedAt`	query	string (date-time)	No	Session update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`userEmail`	query	string	No	Email recorded on the session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`userId`	query	string	No	Client-managed user identifier recorded on the session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`userUuid`	query	string	No	Linked Flopay user UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`uuid`	query	string	No	Flopay checkout-session UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`fields`	body	array of string	No	Stable export field keys in output order.
`format`	body	string	Yes	Allowed values: `csv`, `json`.
`scope`	body	string	Yes	Allowed values: `current_page`, `all_matching`.

Result

Returns 200 as application/vnd.flopay.export-stream.v1. Versioned length-prefixed export stream containing started/progress/completed_file/file_chunk/complete frames.

Errors

Status	Description
`400`	Invalid scope, format, field key, query parameter, client selector, row cap, or plaintext byte cap.
`401`	Authentication is missing or invalid.
`403`	The actor is not allowed to export this resource.
`424`	Throws in cases where Billing service cannot get data from billing provider.
`429`	Export capacity exhausted. Retry-After is set to 60 seconds.
`503`	Exports disabled or export storage unavailable.

Session_list

List Checkout Sessions

Returns paginated checkout sessions for the authenticated client. Supports page, limit, sort[asc|desc], whitelisted filters (id, status, gateway, checkoutMode, userId, userUuid, userEmail, createdAt, updatedAt), and the relation aliases products, transactionAttempts, user, client, and utmMetadata.

Policy	Value
Operation	`GET /v1/checkouts/sessions`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `createdAt`, `status`, `updatedAt`, `products.id`, `products.productId`, `products.code`, `products.name`, `products.description`, `products.type`, `products.currency`, `products.totalAmount`, `products.quantity`, `products.createdAt`, `products.updatedAt`, `transactionAttempts.id`, `transactionAttempts.gateway`, `transactionAttempts.result`, `transactionAttempts.declineReason`, `transactionAttempts.gatewayPaymentIntentId`, `transactionAttempts.createdAt`, `user.id`, `user.email`, `user.firstName`, `user.lastName`, `user.createdAt`, `user.updatedAt`, `utmMetadata.id`, `utmMetadata.utmMedium`, `utmMetadata.utmCampaign`, `utmMetadata.utmSource`, `utmMetadata.utmTerm`, `utmMetadata.funnelDomain`, `utmMetadata.funnelUrl`, `utmMetadata.sourceOriginKey`, `utmMetadata.splitTestVariable`, `utmMetadata.funnelVersion`, `utmMetadata.createdAt`, `utmMetadata.updatedAt`. Default: `createdAt` DESC. Allowed values: `createdAt`, `status`, `updatedAt`, `products.id`, `products.productId`, `products.code`, `products.name`, `products.description`, `products.type`, `products.currency`, `products.totalAmount`, `products.quantity`, `products.createdAt`, `products.updatedAt`, `transactionAttempts.id`, `transactionAttempts.gateway`, `transactionAttempts.result`, `transactionAttempts.declineReason`, `transactionAttempts.gatewayPaymentIntentId`, `transactionAttempts.createdAt`, `user.id`, `user.email`, `user.firstName`, `user.lastName`, `user.createdAt`, `user.updatedAt`, `utmMetadata.id`, `utmMetadata.utmMedium`, `utmMetadata.utmCampaign`, `utmMetadata.utmSource`, `utmMetadata.utmTerm`, `utmMetadata.funnelDomain`, `utmMetadata.funnelUrl`, `utmMetadata.sourceOriginKey`, `utmMetadata.splitTestVariable`, `utmMetadata.funnelVersion`, `utmMetadata.createdAt`, `utmMetadata.updatedAt`.
`relation`	query	string	No	Comma-separated relation aliases to include. Allowed aliases: `client`, `products`, `transactionAttempts`, `user`, `utmMetadata`. Unknown aliases return 400.
`checkoutMode`	query	string	No	Checkout mode. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `auto`, `full`, `confirm`, `setup`.
`createdAt`	query	string (date-time)	No	Session creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`gateway`	query	string	No	Billing provider recorded on the session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`id`	query	string	No	Alias for `uuid`: matches the Flopay checkout-session UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`status`	query	string	No	Session status. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `pending`, `authorized`, `completed`, `voided`.
`updatedAt`	query	string (date-time)	No	Session update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`userEmail`	query	string	No	Email recorded on the session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`userId`	query	string	No	Client-managed user identifier recorded on the session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`userUuid`	query	string	No	Linked Flopay user UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`uuid`	query	string	No	Flopay checkout-session UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].authorizationExpiresAt`	string (date-time) or null	No
`data[].authorizationVoidReason`	string or null	No	Allowed values: `merchant_requested`, `expired`, `provider_canceled`.
`data[].cancelUrl`	string or null	No
`data[].captureMethod`	string	Yes	Allowed values: `automatic`, `manual`.
`data[].checkoutMetadata`	object	No	Immutable non-sensitive client context supplied when the checkout session was created.
`data[].checkoutMode`	string	Yes	Allowed values: `auto`, `full`, `confirm`, `setup`.
`data[].checkoutUrl`	string	Yes
`data[].client`	object or null	No	Owning client. Present only when requested with `relation=client`.
`data[].client.createdAt`	string (date-time)	Yes
`data[].client.id`	string	Yes
`data[].client.slug`	string	Yes
`data[].client.updatedAt`	string (date-time)	Yes
`data[].clientId`	string or null	No	Owning client UUID.
`data[].coupons`	array of string	Yes	Coupon codes applied to the session.
`data[].createdAt`	string (date-time)	Yes
`data[].gateway`	string or null	No	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].gatewayId`	string or null	No	Gateway configuration UUID.
`data[].id`	string	Yes
`data[].products`	array of object	No	Line items. Present only when requested with `relation=products`.
`data[].products[].code`	string	Yes
`data[].products[].createdAt`	string (date-time)	Yes
`data[].products[].currency`	string	Yes
`data[].products[].description`	string or null	No
`data[].products[].id`	string	Yes
`data[].products[].metadata`	object or null	No
`data[].products[].name`	string	Yes
`data[].products[].productId`	string or null	No	Linked Flopay product UUID.
`data[].products[].productPriceId`	string or null	No	Stable Flopay catalog price UUID.
`data[].products[].quantity`	number	Yes
`data[].products[].totalAmount`	number	Yes
`data[].products[].type`	string	Yes	Allowed values: `subscription`, `item`.
`data[].products[].updatedAt`	string (date-time)	Yes
`data[].products[].variantId`	string or null	No	Selected Flopay catalog variant UUID.
`data[].status`	string	Yes	Allowed values: `pending`, `authorized`, `completed`, `voided`.
`data[].successUrl`	string or null	No
`data[].transactionAttempts`	array of object	No	Payment attempts. Present only when requested with `relation=transactionAttempts`.
`data[].transactionAttempts[].checkoutSessionsUuid`	string	Yes	Owning checkout-session UUID.
`data[].transactionAttempts[].createdAt`	string (date-time)	Yes
`data[].transactionAttempts[].declineReason`	string or null	No	Allowed values: `INSUFFICIENT_FUNDS`, `DO_NOT_HONOUR`, `TOO_MANY_ATTEMPTS`, `PARTIAL_APPROVAL`, `PAYMENT_GATEWAY_ERROR`, `TECHNICAL_ERROR`, `RETRYABLE_DECLINE`, `UNSUPPORTED_CARD_PURCHASE`, `USER_ERROR`, `CVV_INVALID`, `AVS_FAIL`, `POSTCODE_INVALID`, `3DS_FAIL`, `EXCEEDS_CARD_LIMIT`, `CLIENT_ERROR`, `UNKNOWN_DECLINE_REASON`.
`data[].transactionAttempts[].gateway`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].transactionAttempts[].gatewayAccount`	object or null	No	Gateway account (non-secret fields) this attempt ran on. Present only when requested.
`data[].transactionAttempts[].gatewayAccount.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data[].transactionAttempts[].gatewayAccount.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data[].transactionAttempts[].gatewayAccount.environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].transactionAttempts[].gatewayAccount.id`	string	Yes	Gateway UUID.
`data[].transactionAttempts[].gatewayAccount.name`	string	Yes	Human-readable name of the gateway account.
`data[].transactionAttempts[].gatewayAccount.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].transactionAttempts[].gatewayAccount.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data[].transactionAttempts[].gatewayDeclineReason`	string or null	No	Raw provider decline reason.
`data[].transactionAttempts[].gatewayPaymentIntentId`	string or null	No	Opaque provider payment-object id for this attempt, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility.
`data[].transactionAttempts[].id`	string	Yes
`data[].transactionAttempts[].nextActionRedirectUrl`	string or null	No	Issuer/3DS redirect URL surfaced when an attempt is in ACTION_REQUIRED state. The SDK renders this in a host-level iframe overlay; the outcome is resolved server-side when the challenge redirects to the Stripe `return_url` (`GET /v1/vault/3ds/return`), with `POST /v1/checkouts/sessions/{id}/3ds/complete` available as a sync probe.
`data[].transactionAttempts[].paymentMethod`	object or null	No	Stored payment method (non-secret display fields) this attempt charged. An attempt charges exactly one method. Present only when the `userPaymentMethod` relation is requested.
`data[].transactionAttempts[].paymentMethod.brand`	string or null	No	Card brand as reported by the gateway (free-text, e.g. "visa"). Null for non-card types.
`data[].transactionAttempts[].paymentMethod.createdAt`	string (date-time)	Yes	When the payment method row was created.
`data[].transactionAttempts[].paymentMethod.expiryMonth`	number or null	No	Card expiry month (1-12). Null for non-card types.
`data[].transactionAttempts[].paymentMethod.expiryYear`	number or null	No	Card expiry year (four digits). Null for non-card types.
`data[].transactionAttempts[].paymentMethod.gateway`	object or null	No	Owning gateway (non-secret fields). Present when the `gateway` relation is loaded.
`data[].transactionAttempts[].paymentMethod.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data[].transactionAttempts[].paymentMethod.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data[].transactionAttempts[].paymentMethod.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].transactionAttempts[].paymentMethod.gateway.id`	string	Yes	Gateway UUID.
`data[].transactionAttempts[].paymentMethod.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data[].transactionAttempts[].paymentMethod.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].transactionAttempts[].paymentMethod.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data[].transactionAttempts[].paymentMethod.id`	string	Yes	Flopay payment method UUID.
`data[].transactionAttempts[].paymentMethod.lastFour`	string or null	No	Last four digits of the card. Null for non-card types.
`data[].transactionAttempts[].paymentMethod.payerEmail`	string or null	No	Payer email for wallet types (PayPal). Null for cards.
`data[].transactionAttempts[].paymentMethod.status`	string	Yes	Payment method lifecycle status. Allowed values: `pending`, `active`, `deleted`.
`data[].transactionAttempts[].paymentMethod.type`	string	Yes	Stored payment method type. Allowed values: `card`, `paypal`.
`data[].transactionAttempts[].providerPaymentMethodId`	string or null	No	Provider PaymentMethod id (e.g. Stripe `pm_xxx`) associated with this attempt. Set on vault-driven attempts once the bridge has minted a provider PM from the vault token; absent on legacy attempts.
`data[].transactionAttempts[].result`	string	Yes	Allowed values: `PENDING`, `AUTHORIZED`, `SUCCESS`, `DECLINE`, `ERROR`, `ACTION_REQUIRED`.
`data[].updatedAt`	string (date-time)	Yes
`data[].user`	object or null	No	Linked Flopay user. Present only when requested with `relation=user`.
`data[].user.clientUserId`	string or null	No
`data[].user.createdAt`	string (date-time)	Yes
`data[].user.email`	string	Yes
`data[].user.firstName`	string	Yes
`data[].user.id`	string	Yes
`data[].user.lastName`	string	Yes
`data[].user.updatedAt`	string (date-time)	Yes
`data[].userAddressCity`	string or null	Yes	Buyer city recorded on the checkout session.
`data[].userAddressCountry`	string or null	Yes	Buyer country as an ISO 3166-1 alpha-2 code.
`data[].userAddressState`	string or null	Yes	Buyer state or region recorded on the checkout session.
`data[].userEmail`	string	Yes
`data[].userFirstName`	string	Yes
`data[].userId`	string	Yes	Client-managed user identifier recorded on the session.
`data[].userLastName`	string	Yes
`data[].userUuid`	string or null	No	Linked Flopay user UUID.
`data[].utmMetadata`	array of object	No	Analytics attribution. Present only when requested with `relation=utmMetadata`.
`data[].utmMetadata[].createdAt`	string (date-time)	Yes
`data[].utmMetadata[].funnelDomain`	string or null	No
`data[].utmMetadata[].funnelUrl`	string or null	No
`data[].utmMetadata[].funnelVersion`	string or null	No
`data[].utmMetadata[].id`	string	Yes
`data[].utmMetadata[].sourceOriginKey`	string or null	No
`data[].utmMetadata[].splitTestVariable`	string or null	No
`data[].utmMetadata[].updatedAt`	string (date-time)	Yes
`data[].utmMetadata[].utmCampaign`	string or null	No
`data[].utmMetadata[].utmMedium`	string or null	No
`data[].utmMetadata[].utmSource`	string or null	No
`data[].utmMetadata[].utmTerm`	string or null	No
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The request body, session id, or resolved product provider credentials were invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`424`	Throws in cases where Billing service cannot get data from billing provider.

TransactionAttempts_findOne

Get Transaction Attempt

Returns a single transaction attempt by UUID, scoped to the authenticated client.

Policy	Value
Operation	`GET /v1/checkouts/transaction-attempts/{id}`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`id`	path	string	Yes

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`checkoutSessionsUuid`	string	Yes	Owning checkout-session UUID.
`createdAt`	string (date-time)	Yes
`declineReason`	string or null	No	Allowed values: `INSUFFICIENT_FUNDS`, `DO_NOT_HONOUR`, `TOO_MANY_ATTEMPTS`, `PARTIAL_APPROVAL`, `PAYMENT_GATEWAY_ERROR`, `TECHNICAL_ERROR`, `RETRYABLE_DECLINE`, `UNSUPPORTED_CARD_PURCHASE`, `USER_ERROR`, `CVV_INVALID`, `AVS_FAIL`, `POSTCODE_INVALID`, `3DS_FAIL`, `EXCEEDS_CARD_LIMIT`, `CLIENT_ERROR`, `UNKNOWN_DECLINE_REASON`.
`gateway`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`gatewayAccount`	object or null	No	Gateway account (non-secret fields) this attempt ran on. Present only when requested.
`gatewayAccount.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`gatewayAccount.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`gatewayAccount.environment`	string	Yes	Allowed values: `stage`, `production`.
`gatewayAccount.id`	string	Yes	Gateway UUID.
`gatewayAccount.name`	string	Yes	Human-readable name of the gateway account.
`gatewayAccount.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`gatewayAccount.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`gatewayDeclineReason`	string or null	No	Raw provider decline reason.
`gatewayPaymentIntentId`	string or null	No	Opaque provider payment-object id for this attempt, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility.
`id`	string	Yes
`nextActionRedirectUrl`	string or null	No	Issuer/3DS redirect URL surfaced when an attempt is in ACTION_REQUIRED state. The SDK renders this in a host-level iframe overlay; the outcome is resolved server-side when the challenge redirects to the Stripe `return_url` (`GET /v1/vault/3ds/return`), with `POST /v1/checkouts/sessions/{id}/3ds/complete` available as a sync probe.
`paymentMethod`	object or null	No	Stored payment method (non-secret display fields) this attempt charged. An attempt charges exactly one method. Present only when the `userPaymentMethod` relation is requested.
`paymentMethod.brand`	string or null	No	Card brand as reported by the gateway (free-text, e.g. "visa"). Null for non-card types.
`paymentMethod.createdAt`	string (date-time)	Yes	When the payment method row was created.
`paymentMethod.expiryMonth`	number or null	No	Card expiry month (1-12). Null for non-card types.
`paymentMethod.expiryYear`	number or null	No	Card expiry year (four digits). Null for non-card types.
`paymentMethod.gateway`	object or null	No	Owning gateway (non-secret fields). Present when the `gateway` relation is loaded.
`paymentMethod.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`paymentMethod.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`paymentMethod.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`paymentMethod.gateway.id`	string	Yes	Gateway UUID.
`paymentMethod.gateway.name`	string	Yes	Human-readable name of the gateway account.
`paymentMethod.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`paymentMethod.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`paymentMethod.id`	string	Yes	Flopay payment method UUID.
`paymentMethod.lastFour`	string or null	No	Last four digits of the card. Null for non-card types.
`paymentMethod.payerEmail`	string or null	No	Payer email for wallet types (PayPal). Null for cards.
`paymentMethod.status`	string	Yes	Payment method lifecycle status. Allowed values: `pending`, `active`, `deleted`.
`paymentMethod.type`	string	Yes	Stored payment method type. Allowed values: `card`, `paypal`.
`providerPaymentMethodId`	string or null	No	Provider PaymentMethod id (e.g. Stripe `pm_xxx`) associated with this attempt. Set on vault-driven attempts once the bridge has minted a provider PM from the vault token; absent on legacy attempts.
`result`	string	Yes	Allowed values: `PENDING`, `AUTHORIZED`, `SUCCESS`, `DECLINE`, `ERROR`, `ACTION_REQUIRED`.

Errors

Status	Description
`400`	The path, relation, filter, sort, or pagination input is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	The bearer token does not grant the required merchant read scope.
`404`	No transaction attempt with this id exists for the authenticated client.

TransactionAttempts_list

List Transaction Attempts

Returns paginated transaction attempts for the authenticated client. Supports page, limit, sort[asc|desc], whitelisted filters, and the relation aliases checkoutSession and gatewayAccount.

Policy	Value
Operation	`GET /v1/checkouts/transaction-attempts`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`page`	query	integer	No	1-based page number for paginated list endpoints. Default: `1`. Minimum: 1.
`limit`	query	integer	No	Maximum number of records to return per page. Default: `20`. Minimum: 1. Maximum: 100.
`sort`	query	string	No	Sort by one allowed field. Use exactly one of `sort[asc]` or `sort[desc]`. Allowed fields: `createdAt`. Default: `createdAt` DESC. Allowed values: `createdAt`.
`relation`	query	string	No	Comma-separated relation aliases to include. Allowed aliases: `checkoutSession`, `gatewayAccount`, `userPaymentMethod`. Unknown aliases return 400.
`checkoutSessionId`	query	string	No	Owning checkout-session UUID (alias for `checkoutSessionsUuid`). Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`checkoutSessionsUuid`	query	string	No	Owning checkout-session UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`createdAt`	query	string (date-time)	No	Attempt creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`declineReason`	query	string	No	Flopay-normalised decline reason. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `INSUFFICIENT_FUNDS`, `DO_NOT_HONOUR`, `TOO_MANY_ATTEMPTS`, `PARTIAL_APPROVAL`, `PAYMENT_GATEWAY_ERROR`, `TECHNICAL_ERROR`, `RETRYABLE_DECLINE`, `UNSUPPORTED_CARD_PURCHASE`, `USER_ERROR`, `CVV_INVALID`, `AVS_FAIL`, `POSTCODE_INVALID`, `3DS_FAIL`, `EXCEEDS_CARD_LIMIT`, `CLIENT_ERROR`, `UNKNOWN_DECLINE_REASON`.
`gateway`	query	string	No	Payment provider used for the attempt. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`gatewayDeclineReason`	query	string	No	Raw provider decline reason string. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`gatewayId`	query	string	No	Gateway account UUID the attempt ran on. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`id`	query	string	No	Alias for `uuid`: matches the attempt UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`providerIntentId`	query	string	No	Provider payment-intent id (e.g. Stripe `pi_*`). Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`result`	query	string	No	Attempt result. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `PENDING`, `AUTHORIZED`, `SUCCESS`, `DECLINE`, `ERROR`, `ACTION_REQUIRED`.
`userEmail`	query	string	No	Email recorded on the owning checkout session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`userId`	query	string	No	Client-managed user identifier on the owning checkout session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`userPaymentMethodId`	query	string	No	User payment-method UUID associated with the attempt. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`userUuid`	query	string	No	Linked Flopay user UUID on the owning checkout session. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`uuid`	query	string	No	Attempt UUID. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].checkoutSessionsUuid`	string	Yes	Owning checkout-session UUID.
`data[].createdAt`	string (date-time)	Yes
`data[].declineReason`	string or null	No	Allowed values: `INSUFFICIENT_FUNDS`, `DO_NOT_HONOUR`, `TOO_MANY_ATTEMPTS`, `PARTIAL_APPROVAL`, `PAYMENT_GATEWAY_ERROR`, `TECHNICAL_ERROR`, `RETRYABLE_DECLINE`, `UNSUPPORTED_CARD_PURCHASE`, `USER_ERROR`, `CVV_INVALID`, `AVS_FAIL`, `POSTCODE_INVALID`, `3DS_FAIL`, `EXCEEDS_CARD_LIMIT`, `CLIENT_ERROR`, `UNKNOWN_DECLINE_REASON`.
`data[].gateway`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].gatewayAccount`	object or null	No	Gateway account (non-secret fields) this attempt ran on. Present only when requested.
`data[].gatewayAccount.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data[].gatewayAccount.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data[].gatewayAccount.environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].gatewayAccount.id`	string	Yes	Gateway UUID.
`data[].gatewayAccount.name`	string	Yes	Human-readable name of the gateway account.
`data[].gatewayAccount.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].gatewayAccount.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data[].gatewayDeclineReason`	string or null	No	Raw provider decline reason.
`data[].gatewayPaymentIntentId`	string or null	No	Opaque provider payment-object id for this attempt, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility.
`data[].id`	string	Yes
`data[].nextActionRedirectUrl`	string or null	No	Issuer/3DS redirect URL surfaced when an attempt is in ACTION_REQUIRED state. The SDK renders this in a host-level iframe overlay; the outcome is resolved server-side when the challenge redirects to the Stripe `return_url` (`GET /v1/vault/3ds/return`), with `POST /v1/checkouts/sessions/{id}/3ds/complete` available as a sync probe.
`data[].paymentMethod`	object or null	No	Stored payment method (non-secret display fields) this attempt charged. An attempt charges exactly one method. Present only when the `userPaymentMethod` relation is requested.
`data[].paymentMethod.brand`	string or null	No	Card brand as reported by the gateway (free-text, e.g. "visa"). Null for non-card types.
`data[].paymentMethod.createdAt`	string (date-time)	Yes	When the payment method row was created.
`data[].paymentMethod.expiryMonth`	number or null	No	Card expiry month (1-12). Null for non-card types.
`data[].paymentMethod.expiryYear`	number or null	No	Card expiry year (four digits). Null for non-card types.
`data[].paymentMethod.gateway`	object or null	No	Owning gateway (non-secret fields). Present when the `gateway` relation is loaded.
`data[].paymentMethod.gateway.code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data[].paymentMethod.gateway.currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data[].paymentMethod.gateway.environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].paymentMethod.gateway.id`	string	Yes	Gateway UUID.
`data[].paymentMethod.gateway.name`	string	Yes	Human-readable name of the gateway account.
`data[].paymentMethod.gateway.providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].paymentMethod.gateway.publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data[].paymentMethod.id`	string	Yes	Flopay payment method UUID.
`data[].paymentMethod.lastFour`	string or null	No	Last four digits of the card. Null for non-card types.
`data[].paymentMethod.payerEmail`	string or null	No	Payer email for wallet types (PayPal). Null for cards.
`data[].paymentMethod.status`	string	Yes	Payment method lifecycle status. Allowed values: `pending`, `active`, `deleted`.
`data[].paymentMethod.type`	string	Yes	Stored payment method type. Allowed values: `card`, `paypal`.
`data[].providerPaymentMethodId`	string or null	No	Provider PaymentMethod id (e.g. Stripe `pm_xxx`) associated with this attempt. Set on vault-driven attempts once the bridge has minted a provider PM from the vault token; absent on legacy attempts.
`data[].result`	string	Yes	Allowed values: `PENDING`, `AUTHORIZED`, `SUCCESS`, `DECLINE`, `ERROR`, `ACTION_REQUIRED`.
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The path, relation, filter, sort, or pagination input is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	The bearer token does not grant the required merchant read scope.

Site navigation

Checkouts tools

Checkouts tools

CheckoutAnalytics_get

CheckoutLink_create

CheckoutLink_findOne

CheckoutLink_list

getCheckoutDeclineAnalysis

Session_createSetup

Session_exportSessions

Session_list

TransactionAttempts_findOne

TransactionAttempts_list

On this page