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 cc71a476426ea531d369de5441cde85ab81ab52c9764406e5f09501857d7ed32.

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_deactivate

Deactivate a reusable checkout link

Policy	Value
Operation	`DELETE /v1/checkout-links/{uuid}`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes

Result

Returns 204 with no body.

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_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.

CheckoutLink_update

Update a reusable checkout link

Policy	Value
Operation	`PATCH /v1/checkout-links/{uuid}`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`uuid`	path	string	Yes
`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	No	Minimum length: 3. Maximum length: 3.
`expiresAt`	body	string (date-time) or null	No
`isActive`	body	boolean	No
`products`	body	array of object	No	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 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.

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_create

Create Checkout Session

Creates and persists a checkout session. Full/Confirm and unnegotiated Auto requests preserve their existing 201 Created / 204 No Content behavior. Auto requests that advertise async-auto-checkout-v1 return 202 Accepted with the session and an autoProcessingPending.statusUrl; payment processing continues asynchronously and clients poll that status URL for the terminal outcome. Full-mode clients may opt into a lightweight shell with deferDataAttachment=true, then attach buyer/catalog data through PATCH /v1/checkouts/sessions/{id}/claim before payment or vault operations. Authentication is optional: a browser or SDK create sends no credentials. A merchant server that creates sessions for its buyers may authenticate with client Basic authentication (client.uuid and an API token) or an OAuth2 bearer token for the body's clientId, and then pass buyerIpAddress so the per-IP session-creation limit counts each buyer instead of the server. Credentials that do not verify, or that belong to another client, are ignored and the create is handled as unauthenticated (no 401/403).

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

Arguments

This tool takes no arguments.

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.code`	string	No	Stable provider-neutral machine code. `stored_payment_method_unsupported` means the selected saved method cannot be used for this payment and another method must be chosen. Allowed values: `stored_payment_method_unsupported`.
`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.settlementStatus`	string	No	Present only when the session's first payment was accepted by the provider and is still settling (bank debit). A plain fulfilment-lock wait carries no key at all. Allowed values: `pending`, `settled`, `failed`.
`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.advertisedPaymentMethods`	array of object	No	Setup sessions only. The payment methods this setup session can save, each with the gateway data a client needs to render it, snapshotted when the session was created. Derived from the same eligibility policy as checkout; non-reusable methods are omitted. Absent on purchase sessions and on setup sessions created before the field existed.
`data.advertisedPaymentMethods[].environment`	string	Yes	Environment of the selected gateway account. Allowed values: `stage`, `production`.
`data.advertisedPaymentMethods[].family`	string	Yes	Rendering group: `card`, `wallet`, `paypal` or `apm`. Allowed values: `card`, `wallet`, `paypal`, `apm`.
`data.advertisedPaymentMethods[].gatewayId`	string	Yes	The gateway account Flopay selected for this method. Chosen by Flopay, not by the merchant.
`data.advertisedPaymentMethods[].paymentMethodType`	string	Yes	Provider payment method type to render: `card`, a Stripe `PaymentMethod.type` such as `apple_pay` or `sepa_debit`, or `paypal_vaulted` for PayPal.
`data.advertisedPaymentMethods[].providerType`	string	Yes	Provider of the selected gateway account. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.advertisedPaymentMethods[].publishableKey`	string or null	Yes	Publishable key or client id of the selected gateway account, for the provider SDK.
`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.currency`	string	No	Setup sessions only. The session currency as a three-letter upper-case ISO 4217 code: the currency resolved for the customer when the session was created (the `currency` of the create request, else their most recent successful purchase), else the currency of the card gateway the setup selected. A client passes it to a provider SDK that needs one to render an advertised method. Absent when neither is known, and on purchase sessions, whose currency is on each product.
`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.futureUse`	string	No	Every read, purchase and setup. The usage applied to every reusable intent of this session, the same name and values as `futureUse` on the setup create request: exactly the `setup_future_usage` of its PaymentIntents and the `usage` of its SetupIntents. Future use is platform policy, so it is `off_session`. A method listed in `futureUseUnsupported` is the exception: its intent carries no future-use parameter. A client declares this value on its Elements and never guesses one. Allowed values: `on_session`, `off_session`.
`data.futureUseUnsupported`	array of object	No	Every method enabled or advertised on this session that is not set up for reuse: its intent carries no future-use parameter, so a client declares no usage for it. `apple_pay` and `google_pay` are listed together or not at all. Absent when there are none.
`data.futureUseUnsupported[].paymentMethodType`	string	Yes	The method left unsaved: a Stripe `PaymentMethod.type` such as `affirm`, or a wallet label such as `apple_pay`.
`data.futureUseUnsupported[].reason`	string	Yes	Why the method is not set up for reuse, as an open snake_case string. Known values: `not_reusable` (the platform does not set the method up for reuse: the provider documents it as single-use, such as `affirm`, or its reuse depends on the account and Flopay has no per-account source for it, as for `klarna` and `alipay`), `account_not_enabled` (the routed gateway explicitly opted out of reusing the method: today PayPal on a Stripe gateway whose `paypal_capabilities` sets `vaulting: false`) and `paired_wallet_not_reusable` (the partner of an Apple Pay / Google Pay wallet that cannot be reused; the two wallets are always listed together). Clients must accept values not listed here.
`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[].buyerFeedback`	object	No	Present only when Flo stopped this attempt itself, before any gateway work, because the checkout made too many payment attempts in a short time (`buyerFeedback.code=attempt_limited`). Nothing was charged; show `buyerFeedback.message` and let the buyer try again later. Absent on every other attempt.
`data.transactionAttempts[].buyerFeedback.code`	string	Yes	`attempt_limited`: the checkout made too many payment attempts in a short time, so this attempt was stopped before any gateway work and nothing was charged. Allowed values: `attempt_limited`.
`data.transactionAttempts[].buyerFeedback.message`	string	Yes	Wording to show the buyer.
`data.transactionAttempts[].buyerFeedback.recoverable`	boolean	Yes	`true` when the buyer can try the payment again later in the same checkout.
`data.transactionAttempts[].checkoutSessionsUuid`	string	Yes
`data.transactionAttempts[].code`	string	No	Stable provider-neutral terminal outcome code when one is available. Allowed values: `stored_payment_method_unsupported`.
`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. When production verification is enforced the block carries only a `verification` descriptor (no `html`, `url` or `secret`): mount the hosted card form, which runs the check before any capture is issued.
`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 checkout session request could not be created.
`409`	The supplied `Idempotency-Key` was already used for a different request body. The original operation is preserved; resubmit with a fresh key to run a new checkout.
`422`	The checkout session references catalog entries (products or coupons) that are unknown, deleted, or not applicable. The response body contains an `issues` array with one entry per validation failure, plus a `declineReason` / `gatewayDeclineReason` pair that lets dashboards classify the rejection alongside payment-time declines. Product-side issues land on `CLIENT_ERROR` / `flo_invalid_product_code`; coupon-only failures land on `USER_ERROR` / `flo_invalid_coupon_code`. Mixed product+coupon failures inherit the product-side decline metadata.
`424`	Throws in cases where Billing service cannot get data from billing provider.

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.
`country`	body	string or null	No	Optional ISO 3166-1 alpha-2 country used independently for setup gateway routing. When omitted, Flo may fill it from this customer's billed-address history with this merchant. Default: `null`.
`currency`	body	string or null	No	Optional three-letter intended transaction currency used independently for setup routing. When omitted, Flo may fill it from this customer's most recent successful purchase with this merchant. Default: `null`.
`futureUse`	body	string or null	No	Deprecated and ignored: it has no effect. The value is still accepted, so existing requests keep working, and the session read reports the applied usage as `futureUse`. Allowed values: `on_session`, `off_session`. Default: `null`.
`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.code`	string	No	Stable provider-neutral machine code. `stored_payment_method_unsupported` means the selected saved method cannot be used for this payment and another method must be chosen. Allowed values: `stored_payment_method_unsupported`.
`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.settlementStatus`	string	No	Present only when the session's first payment was accepted by the provider and is still settling (bank debit). A plain fulfilment-lock wait carries no key at all. Allowed values: `pending`, `settled`, `failed`.
`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.advertisedPaymentMethods`	array of object	No	Setup sessions only. The payment methods this setup session can save, each with the gateway data a client needs to render it, snapshotted when the session was created. Derived from the same eligibility policy as checkout; non-reusable methods are omitted. Absent on purchase sessions and on setup sessions created before the field existed.
`data.advertisedPaymentMethods[].environment`	string	Yes	Environment of the selected gateway account. Allowed values: `stage`, `production`.
`data.advertisedPaymentMethods[].family`	string	Yes	Rendering group: `card`, `wallet`, `paypal` or `apm`. Allowed values: `card`, `wallet`, `paypal`, `apm`.
`data.advertisedPaymentMethods[].gatewayId`	string	Yes	The gateway account Flopay selected for this method. Chosen by Flopay, not by the merchant.
`data.advertisedPaymentMethods[].paymentMethodType`	string	Yes	Provider payment method type to render: `card`, a Stripe `PaymentMethod.type` such as `apple_pay` or `sepa_debit`, or `paypal_vaulted` for PayPal.
`data.advertisedPaymentMethods[].providerType`	string	Yes	Provider of the selected gateway account. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data.advertisedPaymentMethods[].publishableKey`	string or null	Yes	Publishable key or client id of the selected gateway account, for the provider SDK.
`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.currency`	string	No	Setup sessions only. The session currency as a three-letter upper-case ISO 4217 code: the currency resolved for the customer when the session was created (the `currency` of the create request, else their most recent successful purchase), else the currency of the card gateway the setup selected. A client passes it to a provider SDK that needs one to render an advertised method. Absent when neither is known, and on purchase sessions, whose currency is on each product.
`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.futureUse`	string	No	Every read, purchase and setup. The usage applied to every reusable intent of this session, the same name and values as `futureUse` on the setup create request: exactly the `setup_future_usage` of its PaymentIntents and the `usage` of its SetupIntents. Future use is platform policy, so it is `off_session`. A method listed in `futureUseUnsupported` is the exception: its intent carries no future-use parameter. A client declares this value on its Elements and never guesses one. Allowed values: `on_session`, `off_session`.
`data.futureUseUnsupported`	array of object	No	Every method enabled or advertised on this session that is not set up for reuse: its intent carries no future-use parameter, so a client declares no usage for it. `apple_pay` and `google_pay` are listed together or not at all. Absent when there are none.
`data.futureUseUnsupported[].paymentMethodType`	string	Yes	The method left unsaved: a Stripe `PaymentMethod.type` such as `affirm`, or a wallet label such as `apple_pay`.
`data.futureUseUnsupported[].reason`	string	Yes	Why the method is not set up for reuse, as an open snake_case string. Known values: `not_reusable` (the platform does not set the method up for reuse: the provider documents it as single-use, such as `affirm`, or its reuse depends on the account and Flopay has no per-account source for it, as for `klarna` and `alipay`), `account_not_enabled` (the routed gateway explicitly opted out of reusing the method: today PayPal on a Stripe gateway whose `paypal_capabilities` sets `vaulting: false`) and `paired_wallet_not_reusable` (the partner of an Apple Pay / Google Pay wallet that cannot be reused; the two wallets are always listed together). Clients must accept values not listed here.
`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[].buyerFeedback`	object	No	Present only when Flo stopped this attempt itself, before any gateway work, because the checkout made too many payment attempts in a short time (`buyerFeedback.code=attempt_limited`). Nothing was charged; show `buyerFeedback.message` and let the buyer try again later. Absent on every other attempt.
`data.transactionAttempts[].buyerFeedback.code`	string	Yes	`attempt_limited`: the checkout made too many payment attempts in a short time, so this attempt was stopped before any gateway work and nothing was charged. Allowed values: `attempt_limited`.
`data.transactionAttempts[].buyerFeedback.message`	string	Yes	Wording to show the buyer.
`data.transactionAttempts[].buyerFeedback.recoverable`	boolean	Yes	`true` when the buyer can try the payment again later in the same checkout.
`data.transactionAttempts[].checkoutSessionsUuid`	string	Yes
`data.transactionAttempts[].code`	string	No	Stable provider-neutral terminal outcome code when one is available. Allowed values: `stored_payment_method_unsupported`.
`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. When production verification is enforced the block carries only a `verification` descriptor (no `html`, `url` or `secret`): mount the hosted card form, which runs the check before any capture is issued.
`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[].gatewayAccount.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`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.displayLabel`	string or null	No	Safe, human-readable label for non-card methods: the wallet or APM name (for example `Apple Pay`), or `PayPal` with a masked account email. Never contains tokens or full account identifiers. Null for cards, which keep `brand` and `lastFour`. Additive.
`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.floCardId`	string	No	Gateway-agnostic Flo card UUID. Omitted for saved methods created before Flo card identity.
`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.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data[].transactionAttempts[].paymentMethod.gateways`	array of object	No	Gateway accounts with a binding to this Flo card. Omitted for saved methods created before Flo card identity.
`data[].transactionAttempts[].paymentMethod.gateways[].code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data[].transactionAttempts[].paymentMethod.gateways[].currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data[].transactionAttempts[].paymentMethod.gateways[].environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].transactionAttempts[].paymentMethod.gateways[].id`	string	Yes	Gateway UUID.
`data[].transactionAttempts[].paymentMethod.gateways[].name`	string	Yes	Human-readable name of the gateway account.
`data[].transactionAttempts[].paymentMethod.gateways[].providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].transactionAttempts[].paymentMethod.gateways[].publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data[].transactionAttempts[].paymentMethod.gateways[].sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data[].transactionAttempts[].paymentMethod.id`	string	Yes	Flopay payment method UUID.
`data[].transactionAttempts[].paymentMethod.isPreferred`	boolean	No	Whether this Flo card is the customer preference. Omitted for legacy saved methods.
`data[].transactionAttempts[].paymentMethod.lastFour`	string or null	No	Last four digits of the card. Null for non-card types.
`data[].transactionAttempts[].paymentMethod.methodType`	string	No	Method type identifier, the same identifier the setup flow uses: `card`, `paypal`, or a wallet / APM type such as `apple_pay`, `google_pay`, `sepa_debit` or `us_bank_account`. Additive. Allowed values: `card`, `paypal`, `apple_pay`, `google_pay`, `sepa_debit`, `us_bank_account`.
`data[].transactionAttempts[].paymentMethod.payerEmail`	string or null	No	Payer email for PayPal, kept unchanged for compatibility (`displayLabel` carries the masked form). Null for cards, wallets and APMs.
`data[].transactionAttempts[].paymentMethod.status`	string	Yes	Payment method lifecycle status. Every method type uses the same values: `pending` until verified, `active` when usable, `deleted` for a deletion tombstone. Allowed values: `pending`, `active`, `deleted`.
`data[].transactionAttempts[].paymentMethod.type`	string	Yes	Stored payment method type: `card`, `paypal`, or the type of a saved wallet or APM (for example `apple_pay` or `sepa_debit`). Always the same value as `methodType`. Allowed values: `card`, `paypal`, `apple_pay`, `google_pay`, `sepa_debit`, `us_bank_account`.
`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.
`gatewayAccount.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`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.displayLabel`	string or null	No	Safe, human-readable label for non-card methods: the wallet or APM name (for example `Apple Pay`), or `PayPal` with a masked account email. Never contains tokens or full account identifiers. Null for cards, which keep `brand` and `lastFour`. Additive.
`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.floCardId`	string	No	Gateway-agnostic Flo card UUID. Omitted for saved methods created before Flo card identity.
`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.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`paymentMethod.gateways`	array of object	No	Gateway accounts with a binding to this Flo card. Omitted for saved methods created before Flo card identity.
`paymentMethod.gateways[].code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`paymentMethod.gateways[].currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`paymentMethod.gateways[].environment`	string	Yes	Allowed values: `stage`, `production`.
`paymentMethod.gateways[].id`	string	Yes	Gateway UUID.
`paymentMethod.gateways[].name`	string	Yes	Human-readable name of the gateway account.
`paymentMethod.gateways[].providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`paymentMethod.gateways[].publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`paymentMethod.gateways[].sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`paymentMethod.id`	string	Yes	Flopay payment method UUID.
`paymentMethod.isPreferred`	boolean	No	Whether this Flo card is the customer preference. Omitted for legacy saved methods.
`paymentMethod.lastFour`	string or null	No	Last four digits of the card. Null for non-card types.
`paymentMethod.methodType`	string	No	Method type identifier, the same identifier the setup flow uses: `card`, `paypal`, or a wallet / APM type such as `apple_pay`, `google_pay`, `sepa_debit` or `us_bank_account`. Additive. Allowed values: `card`, `paypal`, `apple_pay`, `google_pay`, `sepa_debit`, `us_bank_account`.
`paymentMethod.payerEmail`	string or null	No	Payer email for PayPal, kept unchanged for compatibility (`displayLabel` carries the masked form). Null for cards, wallets and APMs.
`paymentMethod.status`	string	Yes	Payment method lifecycle status. Every method type uses the same values: `pending` until verified, `active` when usable, `deleted` for a deletion tombstone. Allowed values: `pending`, `active`, `deleted`.
`paymentMethod.type`	string	Yes	Stored payment method type: `card`, `paypal`, or the type of a saved wallet or APM (for example `apple_pay` or `sepa_debit`). Always the same value as `methodType`. Allowed values: `card`, `paypal`, `apple_pay`, `google_pay`, `sepa_debit`, `us_bank_account`.
`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[].gatewayAccount.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`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.displayLabel`	string or null	No	Safe, human-readable label for non-card methods: the wallet or APM name (for example `Apple Pay`), or `PayPal` with a masked account email. Never contains tokens or full account identifiers. Null for cards, which keep `brand` and `lastFour`. Additive.
`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.floCardId`	string	No	Gateway-agnostic Flo card UUID. Omitted for saved methods created before Flo card identity.
`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.gateway.sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data[].paymentMethod.gateways`	array of object	No	Gateway accounts with a binding to this Flo card. Omitted for saved methods created before Flo card identity.
`data[].paymentMethod.gateways[].code`	string	Yes	Gateway account identifier (e.g. the Stripe connected account `acct_…`).
`data[].paymentMethod.gateways[].currency`	string	Yes	3-letter ISO default currency code (e.g. "USD") used by this gateway account.
`data[].paymentMethod.gateways[].environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].paymentMethod.gateways[].id`	string	Yes	Gateway UUID.
`data[].paymentMethod.gateways[].name`	string	Yes	Human-readable name of the gateway account.
`data[].paymentMethod.gateways[].providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].paymentMethod.gateways[].publishableKey`	string	No	Public API key used by frontend clients to identify the gateway account. Not a secret.
`data[].paymentMethod.gateways[].sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Allowed values: `both`, `on_session`, `off_session`.
`data[].paymentMethod.id`	string	Yes	Flopay payment method UUID.
`data[].paymentMethod.isPreferred`	boolean	No	Whether this Flo card is the customer preference. Omitted for legacy saved methods.
`data[].paymentMethod.lastFour`	string or null	No	Last four digits of the card. Null for non-card types.
`data[].paymentMethod.methodType`	string	No	Method type identifier, the same identifier the setup flow uses: `card`, `paypal`, or a wallet / APM type such as `apple_pay`, `google_pay`, `sepa_debit` or `us_bank_account`. Additive. Allowed values: `card`, `paypal`, `apple_pay`, `google_pay`, `sepa_debit`, `us_bank_account`.
`data[].paymentMethod.payerEmail`	string or null	No	Payer email for PayPal, kept unchanged for compatibility (`displayLabel` carries the masked form). Null for cards, wallets and APMs.
`data[].paymentMethod.status`	string	Yes	Payment method lifecycle status. Every method type uses the same values: `pending` until verified, `active` when usable, `deleted` for a deletion tombstone. Allowed values: `pending`, `active`, `deleted`.
`data[].paymentMethod.type`	string	Yes	Stored payment method type: `card`, `paypal`, or the type of a saved wallet or APM (for example `apple_pay` or `sepa_debit`). Always the same value as `methodType`. Allowed values: `card`, `paypal`, `apple_pay`, `google_pay`, `sepa_debit`, `us_bank_account`.
`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_deactivate

CheckoutLink_findOne

CheckoutLink_list

CheckoutLink_update

getCheckoutDeclineAnalysis

Session_create

Session_createSetup

Session_exportSessions

Session_list

TransactionAttempts_findOne

TransactionAttempts_list

On this page

Checkouts tools

Checkouts toolsCopy Anchor Link

CheckoutAnalytics_getCopy Anchor Link

CheckoutLink_createCopy Anchor Link

CheckoutLink_deactivateCopy Anchor Link

CheckoutLink_findOneCopy Anchor Link

CheckoutLink_listCopy Anchor Link

CheckoutLink_updateCopy Anchor Link

getCheckoutDeclineAnalysisCopy Anchor Link

Session_createCopy Anchor Link

Session_createSetupCopy Anchor Link

Session_exportSessionsCopy Anchor Link

Session_listCopy Anchor Link

TransactionAttempts_findOneCopy Anchor Link

TransactionAttempts_listCopy Anchor Link

On this page

Checkouts tools

CheckoutAnalytics_get

CheckoutLink_create

CheckoutLink_deactivate

CheckoutLink_findOne

CheckoutLink_list

CheckoutLink_update

getCheckoutDeclineAnalysis

Session_create

Session_createSetup

Session_exportSessions

Session_list

TransactionAttempts_findOne

TransactionAttempts_list