MCPTool reference
Transactions tools
Arguments, results, errors, and access, confirmation, and retry policy for each Transactions tool in FloPay MCP, from the reviewed API contract.
Transactions tools
Generated from the FloPay MCP contract version 1, revision cc71a476426ea531d369de5441cde85ab81ab52c9764406e5f09501857d7ed32.
CreatePayment_create
Create Payment
Creates a one-off payment for active products in the authenticated client's catalog. Pricing and discounts are calculated server-side before eligible saved payment routes are attempted in deterministic order. Subscription products must use POST /v1/subscriptions.
| Policy | Value |
|---|---|
| Operation | POST /v1/payments |
| Class | mutating |
| Risk | critical |
| Confirmation | required |
| Retry | manual-reconciliation |
| Rate-limit tier | restricted |
| Roles | owner, admin, member |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
couponCodes | body | array of string | No | Coupon codes to apply. Defaults to an empty array. Default: []. Maximum items: 5. |
currency | body | string | Yes | Three-letter currency code, normalized to uppercase. Minimum length: 3. Maximum length: 3. |
products | body | array of object | Yes | One or more one-off tenant catalog products to charge. Minimum items: 1. |
products[].code | body | string | No | Tenant catalog product code. Supply exactly one of code or uuid. Minimum length: 1. Maximum length: 255. |
products[].quantity | body | number | Yes | Number of units to charge. Minimum: 1. |
products[].uuid | body | string (uuid) | No | Flo base-product UUID. Supply exactly one of code or uuid; variant UUIDs are not accepted. |
userId | body | string (uuid) | Yes | Flo user UUID linked to the authenticated client. |
Result
Returns 201 with a JSON body. The succeeded purchase transaction is durable.
| Field | Type | Required | Description |
|---|---|---|---|
data | object | Yes | The durable one-off payment, including its pollable Flo payment UUID. |
data.amount | number | Yes | |
data.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
data.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
data.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data.checkoutSessionId | string or null | No | Originating checkout session UUID. |
data.createdAt | string (date-time) | Yes | Record creation timestamp. |
data.currency | string | Yes | |
data.description | string or null | Yes | |
data.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
data.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
data.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
data.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
data.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
data.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data.gateway.environment | string | Yes | Allowed values: stage, production. |
data.gateway.id | string | Yes | Gateway UUID. |
data.gateway.name | string | Yes | Human-readable name of the gateway account. |
data.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data.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.gatewayChargeId | string or null | No | Original gateway charge identifier. |
data.gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
data.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
data.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
data.id | string | Yes | |
data.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
data.occurredAt | string (date-time) | Yes | |
data.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
data.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
data.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
data.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
data.status | string | Yes | |
data.subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
data.subscription.amount | number or null | Yes | The stored single-unit amount. |
data.subscription.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
data.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data.subscription.createdAt | string (date-time) | Yes | When the row was created. |
data.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
data.subscription.gateway.id | string | Yes | Gateway UUID. |
data.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
data.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data.subscription.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.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data.subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
data.subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data.subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
data.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
data.subscription.meteredItems[].name | string | Yes | |
data.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
data.subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
data.subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
data.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data.subscription.planDescription | string or null | Yes | The stored plan description when available. |
data.subscription.planId | string | Yes | The stored plan identifier. |
data.subscription.planName | string | Yes | The stored plan name. |
data.subscription.quantity | number | Yes | The subscribed quantity. |
data.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data.subscription.total | number or null | Yes | The stored total amount. |
data.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data.subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
data.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
data.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
data.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
data.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
data.userEmail | string or null | No | Customer email when the user relation is loaded. |
data.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data.userUuid | string or null | No | Linked Flopay user UUID. |
Errors
| Status | Description |
|---|---|
400 | The request body is malformed or the Idempotency-Key header is missing or blank. |
401 | Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use client.uuid as the username and a current client-scoped API token as the password; for bearer, send a valid OAuth2 access token with a current client membership. |
404 | The user does not exist or is not linked to the authenticated client. |
409 | The Idempotency-Key was already used with a different normalized request. |
422 | The tenant catalog selection, coupons, currency, pricing, or total is ineligible, or the user has no eligible payment route. A no-route response has an empty attempts array. |
424 | Every chargeable candidate failed definitively. Attempts are ordered and sanitized. |
Invoice_exportInvoices
Export invoices
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/invoices/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, paidAt, total, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId. Default: createdAt DESC. Allowed values: createdAt, paidAt, total, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: gateway, transaction. Unknown aliases return 400. |
billingReason | query | string | No | Provider-reported billing reason (e.g. subscription_create, manual). 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 | Invoice creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
paidAt | query | string (date-time) | No | Invoice paid timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
state | query | string | No | Invoice state. 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: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
total | query | number | No | Invoice total amount. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
transactionType | query | string | No | Provider-reported transaction type recorded on the invoice. 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. |
updatedAt | query | string (date-time) | No | Invoice update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
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 invoice 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. |
429 | Export capacity exhausted. Retry-After is set to 60 seconds. |
503 | Exports disabled or export storage unavailable. |
Invoice_findOne
Get Invoice
Returns a single invoice for the authenticated client.
| Policy | Value |
|---|---|
| Operation | GET /v1/invoices/{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 | |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: gateway, transaction. Unknown aliases return 400. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
billingReason | string or null | No | Provider-reported billing reason. |
buyerBusinessDetails | object or null | No | The buyer's business details at this merchant as they stood when Flo created the invoice: customerType (business or individual), legalName, address (street1, street2, city, region, postalCode, ISO 3166-1 alpha-2 country) and taxId (type, normalised value). A later change to the buyer's details reaches only the next invoice. null when the buyer had none, and for invoices issued by a payment provider. |
createdAt | string (date-time) | Yes | When the invoice was created. |
currency | string or null | No | |
gateway | object or null | No | Owning gateway (non-secret fields). Present when the gateway relation is loaded. |
gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
gateway.environment | string | Yes | Allowed values: stage, production. |
gateway.id | string | Yes | Gateway UUID. |
gateway.name | string | Yes | Human-readable name of the gateway account. |
gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
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. |
gatewayInvoiceId | string or null | No | The invoice identifier in the billing provider (e.g. Stripe in_…). Null only briefly while a one-time purchase invoice is being minted at the gateway. |
gatewayType | string | Yes | The billing provider that produced this invoice. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
hostedInvoiceUrl | string or null | No | The invoice's hosted page: no sign-in, behind an unguessable token. For invoices FloPay issues itself it shows both parties' identity, each line, the total and the tax note. Provider invoices carry the provider's page. null when the invoice has none. |
id | string | Yes | The Flopay invoice UUID. |
invoiceNumber | string or null | No | The invoice number. FloPay numbers the invoices it issues itself per merchant as <prefix><sequence> (the merchant's prefix, default INV-, and a sequence zero-padded to 6 digits, e.g. INV-000001); a number is never reused or changed. Provider invoices keep the provider's number. null when the invoice has none. |
invoicePdfUrl | string or null | No | The invoice's PDF, a sibling of hostedInvoiceUrl with the same content and the same access rule. null when the invoice has none. |
paidAt | string (date-time) or null | No | When the invoice was paid by the provider. |
state | string | Yes | The current invoice state. Allowed values: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
total | number or null | No | |
transaction | object | No | Linked Flopay transaction (non-secret fields incl. metadata). Present only when the transaction relation is loaded and a transaction settled this invoice. |
transaction.amount | number | Yes | |
transaction.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
transaction.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
transaction.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
transaction.checkoutSessionId | string or null | No | Originating checkout session UUID. |
transaction.createdAt | string (date-time) | Yes | Record creation timestamp. |
transaction.currency | string | Yes | |
transaction.description | string or null | Yes | |
transaction.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
transaction.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
transaction.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
transaction.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
transaction.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
transaction.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
transaction.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
transaction.gateway.environment | string | Yes | Allowed values: stage, production. |
transaction.gateway.id | string | Yes | Gateway UUID. |
transaction.gateway.name | string | Yes | Human-readable name of the gateway account. |
transaction.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
transaction.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
transaction.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. |
transaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
transaction.gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
transaction.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
transaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
transaction.id | string | Yes | |
transaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
transaction.occurredAt | string (date-time) | Yes | |
transaction.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
transaction.status | string | Yes | |
transaction.subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
transaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
transaction.subscription.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
transaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
transaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
transaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
transaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
transaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
transaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
transaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
transaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
transaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
transaction.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
transaction.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
transaction.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
transaction.subscription.gateway.id | string | Yes | Gateway UUID. |
transaction.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
transaction.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
transaction.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
transaction.subscription.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. |
transaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
transaction.subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
transaction.subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
transaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
transaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
transaction.subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
transaction.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
transaction.subscription.meteredItems[].name | string | Yes | |
transaction.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
transaction.subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
transaction.subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
transaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
transaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
transaction.subscription.planId | string | Yes | The stored plan identifier. |
transaction.subscription.planName | string | Yes | The stored plan name. |
transaction.subscription.quantity | number | Yes | The subscribed quantity. |
transaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
transaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
transaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
transaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
transaction.subscription.total | number or null | Yes | The stored total amount. |
transaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
transaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
transaction.subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
transaction.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
transaction.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
transaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
transaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
transaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
transaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
transaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
transaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
transaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
transaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
transaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
transaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
transaction.userUuid | string or null | No | Linked Flopay user UUID. |
transactionType | string or null | No | Provider-reported transaction type. |
transactionUuid | string or null | No | Linked Flopay transaction UUID. |
updatedAt | string (date-time) | Yes | When the invoice was last updated. |
userFirstName | string or null | No | Customer first name when the user relation is loaded. |
userLastName | string or null | No | Customer last name when the user relation is loaded. |
userUuid | string or null | No | Linked Flopay user UUID. |
Errors
| Status | Description |
|---|---|
400 | The supplied path or list query 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. |
404 | No invoice with the requested id exists for this client. |
Invoice_list
List Invoices
Returns paginated invoices for the authenticated client (locally persisted from provider webhooks). Supports page, limit, sort[asc|desc], the relation aliases gateway and transaction, and whitelisted filters for uuid, state, billingReason, transactionType, total, paidAt, createdAt, and updatedAt.
| Policy | Value |
|---|---|
| Operation | GET /v1/invoices |
| 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, paidAt, total, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId. Default: createdAt DESC. Allowed values: createdAt, paidAt, total, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: gateway, transaction. Unknown aliases return 400. |
billingReason | query | string | No | Provider-reported billing reason (e.g. subscription_create, manual). 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 | Invoice creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
paidAt | query | string (date-time) | No | Invoice paid timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
state | query | string | No | Invoice state. 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: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
total | query | number | No | Invoice total amount. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
transactionType | query | string | No | Provider-reported transaction type recorded on the invoice. 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. |
updatedAt | query | string (date-time) | No | Invoice update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
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 invoice 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[].billingReason | string or null | No | Provider-reported billing reason. |
data[].buyerBusinessDetails | object or null | No | The buyer's business details at this merchant as they stood when Flo created the invoice: customerType (business or individual), legalName, address (street1, street2, city, region, postalCode, ISO 3166-1 alpha-2 country) and taxId (type, normalised value). A later change to the buyer's details reaches only the next invoice. null when the buyer had none, and for invoices issued by a payment provider. |
data[].createdAt | string (date-time) | Yes | When the invoice was created. |
data[].currency | string or null | No | |
data[].gateway | object or null | No | Owning gateway (non-secret fields). Present when the gateway relation is loaded. |
data[].gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].gateway.environment | string | Yes | Allowed values: stage, production. |
data[].gateway.id | string | Yes | Gateway UUID. |
data[].gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].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[].gatewayInvoiceId | string or null | No | The invoice identifier in the billing provider (e.g. Stripe in_…). Null only briefly while a one-time purchase invoice is being minted at the gateway. |
data[].gatewayType | string | Yes | The billing provider that produced this invoice. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].hostedInvoiceUrl | string or null | No | The invoice's hosted page: no sign-in, behind an unguessable token. For invoices FloPay issues itself it shows both parties' identity, each line, the total and the tax note. Provider invoices carry the provider's page. null when the invoice has none. |
data[].id | string | Yes | The Flopay invoice UUID. |
data[].invoiceNumber | string or null | No | The invoice number. FloPay numbers the invoices it issues itself per merchant as <prefix><sequence> (the merchant's prefix, default INV-, and a sequence zero-padded to 6 digits, e.g. INV-000001); a number is never reused or changed. Provider invoices keep the provider's number. null when the invoice has none. |
data[].invoicePdfUrl | string or null | No | The invoice's PDF, a sibling of hostedInvoiceUrl with the same content and the same access rule. null when the invoice has none. |
data[].paidAt | string (date-time) or null | No | When the invoice was paid by the provider. |
data[].state | string | Yes | The current invoice state. Allowed values: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
data[].total | number or null | No | |
data[].transaction | object | No | Linked Flopay transaction (non-secret fields incl. metadata). Present only when the transaction relation is loaded and a transaction settled this invoice. |
data[].transaction.amount | number | Yes | |
data[].transaction.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
data[].transaction.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
data[].transaction.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].transaction.checkoutSessionId | string or null | No | Originating checkout session UUID. |
data[].transaction.createdAt | string (date-time) | Yes | Record creation timestamp. |
data[].transaction.currency | string | Yes | |
data[].transaction.description | string or null | Yes | |
data[].transaction.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
data[].transaction.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
data[].transaction.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
data[].transaction.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
data[].transaction.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
data[].transaction.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].transaction.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].transaction.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].transaction.gateway.id | string | Yes | Gateway UUID. |
data[].transaction.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].transaction.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].transaction.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].transaction.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[].transaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
data[].transaction.gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
data[].transaction.gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
data[].transaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
data[].transaction.id | string | Yes | |
data[].transaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
data[].transaction.occurredAt | string (date-time) | Yes | |
data[].transaction.refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
data[].transaction.refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
data[].transaction.refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
data[].transaction.refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
data[].transaction.status | string | Yes | |
data[].transaction.subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
data[].transaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
data[].transaction.subscription.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
data[].transaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].transaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].transaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].transaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].transaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].transaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
data[].transaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].transaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].transaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].transaction.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].transaction.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].transaction.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].transaction.subscription.gateway.id | string | Yes | Gateway UUID. |
data[].transaction.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].transaction.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].transaction.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].transaction.subscription.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[].transaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].transaction.subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
data[].transaction.subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].transaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].transaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].transaction.subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
data[].transaction.subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
data[].transaction.subscription.meteredItems[].name | string | Yes | |
data[].transaction.subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
data[].transaction.subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
data[].transaction.subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
data[].transaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].transaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
data[].transaction.subscription.planId | string | Yes | The stored plan identifier. |
data[].transaction.subscription.planName | string | Yes | The stored plan name. |
data[].transaction.subscription.quantity | number | Yes | The subscribed quantity. |
data[].transaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].transaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].transaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data[].transaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].transaction.subscription.total | number or null | Yes | The stored total amount. |
data[].transaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].transaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].transaction.subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
data[].transaction.subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
data[].transaction.subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
data[].transaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].transaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].transaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].transaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].transaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data[].transaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
data[].transaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
data[].transaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
data[].transaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].transaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].transaction.userUuid | string or null | No | Linked Flopay user UUID. |
data[].transactionType | string or null | No | Provider-reported transaction type. |
data[].transactionUuid | string or null | No | Linked Flopay transaction UUID. |
data[].updatedAt | string (date-time) | Yes | When the invoice was last updated. |
data[].userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].userUuid | string or null | No | Linked Flopay user UUID. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The supplied path or list query 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. |
Invoice_stats
Invoice Stats
Aggregated invoice stats for the authenticated client: total record count plus due/paid totals per currency. Accepts the same whitelisted filters as List Invoices, plus optional from/to ISO datetimes that band the query on created_at.
| Policy | Value |
|---|---|
| Operation | GET /v1/invoices/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 |
|---|---|---|---|---|
to | query | string | No | Inclusive upper bound on created_at (ISO datetime). |
from | query | string | No | Inclusive lower bound on created_at (ISO datetime). |
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, paidAt, total, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId. Default: createdAt DESC. Allowed values: createdAt, paidAt, total, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, transaction.id, transaction.amount, transaction.currency, transaction.status, transaction.description, transaction.createdAt, transaction.userUuid, transaction.checkoutSessionId, transaction.subscriptionUuid, transaction.gatewayTransactionId, transaction.gatewayPaymentIntentId. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: gateway, transaction. Unknown aliases return 400. |
billingReason | query | string | No | Provider-reported billing reason (e.g. subscription_create, manual). 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 | Invoice creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
paidAt | query | string (date-time) | No | Invoice paid timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
state | query | string | No | Invoice state. 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: open, pending, processing, pastDue, paid, closed, failed, voided, unknown. |
total | query | number | No | Invoice total amount. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
transactionType | query | string | No | Provider-reported transaction type recorded on the invoice. 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. |
updatedAt | query | string (date-time) | No | Invoice update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
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 invoice 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 |
|---|---|---|---|
amountDue | object | Yes | Sum of due (unpaid) invoice totals, keyed by ISO-4217 currency. |
amountPaid | object | Yes | Sum of paid invoice totals, keyed by ISO-4217 currency. |
from | string (date-time) or null | No | Inclusive lower bound on created_at, or null. |
records | number | Yes | Total records matching the filters within the time band. |
to | string (date-time) or null | No | Inclusive upper bound on created_at, or null. |
Errors
| Status | Description |
|---|---|
400 | The supplied path or list query 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. |
Payments_cancelAuthorization
Cancel Payment Authorization
Releases an active manual-capture card authorization without capturing funds.
| Policy | Value |
|---|---|
| Operation | PUT /v1/payments/{id}/cancel |
| Class | mutating |
| Risk | critical |
| Confirmation | required |
| Retry | manual-reconciliation |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | Yes | Flopay-issued payment transaction UUID. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | |
authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
checkoutSessionId | string or null | No | Originating checkout session UUID. |
createdAt | string (date-time) | Yes | Record creation timestamp. |
currency | string | Yes | |
description | string or null | Yes | |
effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
gateway.environment | string | Yes | Allowed values: stage, production. |
gateway.id | string | Yes | Gateway UUID. |
gateway.name | string | Yes | Human-readable name of the gateway account. |
gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
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. |
gatewayChargeId | string or null | No | Original gateway charge identifier. |
gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
gatewayTransactionId | string or null | No | Gateway transaction identifier. |
id | string | Yes | |
metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
occurredAt | string (date-time) | Yes | |
refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
status | string | Yes | |
subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
subscription.amount | number or null | Yes | The stored single-unit amount. |
subscription.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
subscription.createdAt | string (date-time) | Yes | When the row was created. |
subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
subscription.gateway.id | string | Yes | Gateway UUID. |
subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
subscription.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. |
subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
subscription.meteredItems[].name | string | Yes | |
subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
subscription.planDescription | string or null | Yes | The stored plan description when available. |
subscription.planId | string | Yes | The stored plan identifier. |
subscription.planName | string | Yes | The stored plan name. |
subscription.quantity | number | Yes | The subscribed quantity. |
subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
subscription.total | number or null | Yes | The stored total amount. |
subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
userEmail | string or null | No | Customer email when the user relation is loaded. |
userFirstName | string or null | No | Customer first name when the user relation is loaded. |
userLastName | string or null | No | Customer last name when the user relation is loaded. |
userUuid | string or null | No | Linked Flopay user UUID. |
Errors
| Status | Description |
|---|---|
400 | The payment id is not a UUID, or the Idempotency-Key header is missing or blank. |
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 | OAuth bearer callers must have a current merchant owner or admin membership. Members and revoked memberships are rejected; authenticated client Basic API-key callers remain authorized. |
404 | No payment with the requested id exists for this merchant. |
409 | The payment is not eligible for the requested authorization operation; the authorization has expired; another authorization operation is in progress; the Idempotency-Key was already used for a different request; the payment provider rejected the operation; or the payment reached a conflicting terminal state. |
502 | The originating gateway could not cancel the authorization. |
Payments_captureAuthorization
Capture Payment Authorization
Captures the full amount of an active manual-capture card authorization. Partial and multiple captures are not supported.
| Policy | Value |
|---|---|
| Operation | PUT /v1/payments/{id}/capture |
| Class | mutating |
| Risk | critical |
| Confirmation | required |
| Retry | manual-reconciliation |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | Yes | Flopay-issued payment transaction UUID. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | |
authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
checkoutSessionId | string or null | No | Originating checkout session UUID. |
createdAt | string (date-time) | Yes | Record creation timestamp. |
currency | string | Yes | |
description | string or null | Yes | |
effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
gateway.environment | string | Yes | Allowed values: stage, production. |
gateway.id | string | Yes | Gateway UUID. |
gateway.name | string | Yes | Human-readable name of the gateway account. |
gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
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. |
gatewayChargeId | string or null | No | Original gateway charge identifier. |
gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
gatewayTransactionId | string or null | No | Gateway transaction identifier. |
id | string | Yes | |
metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
occurredAt | string (date-time) | Yes | |
refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
status | string | Yes | |
subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
subscription.amount | number or null | Yes | The stored single-unit amount. |
subscription.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
subscription.createdAt | string (date-time) | Yes | When the row was created. |
subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
subscription.gateway.id | string | Yes | Gateway UUID. |
subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
subscription.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. |
subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
subscription.meteredItems[].name | string | Yes | |
subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
subscription.planDescription | string or null | Yes | The stored plan description when available. |
subscription.planId | string | Yes | The stored plan identifier. |
subscription.planName | string | Yes | The stored plan name. |
subscription.quantity | number | Yes | The subscribed quantity. |
subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
subscription.total | number or null | Yes | The stored total amount. |
subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
userEmail | string or null | No | Customer email when the user relation is loaded. |
userFirstName | string or null | No | Customer first name when the user relation is loaded. |
userLastName | string or null | No | Customer last name when the user relation is loaded. |
userUuid | string or null | No | Linked Flopay user UUID. |
Errors
| Status | Description |
|---|---|
400 | The payment id is not a UUID, or the Idempotency-Key header is missing or blank. |
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 | OAuth bearer callers must have a current merchant owner or admin membership. Members and revoked memberships are rejected; authenticated client Basic API-key callers remain authorized. |
404 | No payment with the requested id exists for this merchant. |
409 | The payment is not eligible for the requested authorization operation; the authorization has expired; another authorization operation is in progress; the Idempotency-Key was already used for a different request; the payment provider rejected the operation; or the payment reached a conflicting terminal state. |
502 | The originating gateway could not capture the authorization. |
Payments_exportPayments
Export Payments
Streams a point-in-time CSV or JSON export for the authenticated merchant. Requires an OAuth client_user owner/admin token; members and client Basic auth are rejected.
| Policy | Value |
|---|---|
| Operation | POST /v1/payments/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: amount, createdAt, floFeeUsd, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, subscription.uuid, subscription.gatewayType, subscription.gatewaySubscriptionId, subscription.planId, subscription.planName, subscription.quantity, subscription.rebillCount, subscription.currency, subscription.amount, subscription.total, subscription.state, subscription.startDate, subscription.endDate, subscription.canceledAt, subscription.createdAt, subscription.updatedAt. Default: createdAt DESC. Allowed values: amount, createdAt, floFeeUsd, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, subscription.uuid, subscription.gatewayType, subscription.gatewaySubscriptionId, subscription.planId, subscription.planName, subscription.quantity, subscription.rebillCount, subscription.currency, subscription.amount, subscription.total, subscription.state, subscription.startDate, subscription.endDate, subscription.canceledAt, subscription.createdAt, subscription.updatedAt. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: gateway, subscription. Unknown aliases return 400. |
amount | query | number | No | Payment amount. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | Payment 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. |
description | query | string | No | Payment description. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
email | query | string | No | Email address of the user linked to the payment. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
floFeeUsd | query | number | No | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
id | query | string | No | Payment identifier. 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. |
occurredAt | query | string (date-time) | No | Payment occurrence timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
provider | query | string | No | Payment provider. 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. |
status | query | string | No | Canonical payment lifecycle state. 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, processing, succeeded, failed, refunded, partially_refunded, refund_failed, voided, reversed, unknown. |
type | query | string | No | Financial event type. 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: purchase, refund, chargeback, dispute. |
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. |
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. Versioned length-prefixed export stream.
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. |
429 | Export capacity exhausted. Retry-After is set to 60 seconds. |
503 | Exports disabled or export storage unavailable. |
Payments_findOne
Get Payment
Returns a single payment (Flopay transaction row) for the authenticated client. The id is the Flopay-issued transaction UUID; provider-side ids are not accepted.
| Policy | Value |
|---|---|
| Operation | GET /v1/payments/{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 | |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: gateway, subscription. Unknown aliases return 400. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | |
authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
checkoutSessionId | string or null | No | Originating checkout session UUID. |
createdAt | string (date-time) | Yes | Record creation timestamp. |
currency | string | Yes | |
description | string or null | Yes | |
effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
gateway.environment | string | Yes | Allowed values: stage, production. |
gateway.id | string | Yes | Gateway UUID. |
gateway.name | string | Yes | Human-readable name of the gateway account. |
gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
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. |
gatewayChargeId | string or null | No | Original gateway charge identifier. |
gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
gatewayTransactionId | string or null | No | Gateway transaction identifier. |
id | string | Yes | |
metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
occurredAt | string (date-time) | Yes | |
refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
status | string | Yes | |
subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
subscription.amount | number or null | Yes | The stored single-unit amount. |
subscription.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
subscription.createdAt | string (date-time) | Yes | When the row was created. |
subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
subscription.gateway.id | string | Yes | Gateway UUID. |
subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
subscription.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. |
subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
subscription.meteredItems[].name | string | Yes | |
subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
subscription.planDescription | string or null | Yes | The stored plan description when available. |
subscription.planId | string | Yes | The stored plan identifier. |
subscription.planName | string | Yes | The stored plan name. |
subscription.quantity | number | Yes | The subscribed quantity. |
subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
subscription.total | number or null | Yes | The stored total amount. |
subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
userEmail | string or null | No | Customer email when the user relation is loaded. |
userFirstName | string or null | No | Customer first name when the user relation is loaded. |
userLastName | string or null | No | Customer last name when the user relation is loaded. |
userUuid | string or null | No | Linked Flopay user UUID. |
Errors
| Status | Description |
|---|---|
400 | The sort, filter, or pagination query parameters 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 | No payment with the requested id exists for this client. |
Payments_list
List Payments
Returns paginated payments for the authenticated client from the locally persisted transaction table. Supports page, limit, sort[asc|desc], the relation aliases gateway and subscription, and whitelisted filters for id, amount, floFeeUsd, currency, description, email, occurredAt, provider, status, and userUuid. floFeeUsd is the nullable Flo platform fee in USD; unavailable values sort last. The email filter matches the email of the user linked to each payment. Invalid list parameters return 400.
| Policy | Value |
|---|---|
| Operation | GET /v1/payments |
| 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: amount, createdAt, floFeeUsd, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, subscription.uuid, subscription.gatewayType, subscription.gatewaySubscriptionId, subscription.planId, subscription.planName, subscription.quantity, subscription.rebillCount, subscription.currency, subscription.amount, subscription.total, subscription.state, subscription.startDate, subscription.endDate, subscription.canceledAt, subscription.createdAt, subscription.updatedAt. Default: createdAt DESC. Allowed values: amount, createdAt, floFeeUsd, updatedAt, gateway.id, gateway.code, gateway.name, gateway.providerType, gateway.environment, gateway.currency, gateway.sessionMode, subscription.uuid, subscription.gatewayType, subscription.gatewaySubscriptionId, subscription.planId, subscription.planName, subscription.quantity, subscription.rebillCount, subscription.currency, subscription.amount, subscription.total, subscription.state, subscription.startDate, subscription.endDate, subscription.canceledAt, subscription.createdAt, subscription.updatedAt. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: gateway, subscription. Unknown aliases return 400. |
amount | query | number | No | Payment amount. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | Payment 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. |
description | query | string | No | Payment description. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
email | query | string | No | Email address of the user linked to the payment. Equality filter. Pass without operator for exact match or pass any of the following operators: [search]. [search] is case-insensitive text contains matching. |
floFeeUsd | query | number | No | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
id | query | string | No | Payment identifier. 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. |
occurredAt | query | string (date-time) | No | Payment occurrence timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
provider | query | string | No | Payment provider. 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. |
status | query | string | No | Canonical payment lifecycle state. 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, processing, succeeded, failed, refunded, partially_refunded, refund_failed, voided, reversed, unknown. |
type | query | string | No | Financial event type. 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: purchase, refund, chargeback, dispute. |
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. |
Result
Returns 200 with a JSON body. A paginated list of locally persisted payments for the requested client.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].amount | number | Yes | |
data[].authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
data[].authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
data[].checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].checkoutSessionId | string or null | No | Originating checkout session UUID. |
data[].createdAt | string (date-time) | Yes | Record creation timestamp. |
data[].currency | string | Yes | |
data[].description | string or null | Yes | |
data[].effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
data[].financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
data[].floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
data[].floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
data[].gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
data[].gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].gateway.environment | string | Yes | Allowed values: stage, production. |
data[].gateway.id | string | Yes | Gateway UUID. |
data[].gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].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[].gatewayChargeId | string or null | No | Original gateway charge identifier. |
data[].gatewayPaymentIntentId | string or null | No | Opaque provider payment-object identifier, such as a Stripe PaymentIntent or PayPal Order/subscription id. The legacy field name is preserved for compatibility. |
data[].gatewayRefundId | string or null | No | Provider refund-object identifier on a refund transaction, such as a Stripe re_… id. Null on anything that is not a refund, and never a bank-trace reference. |
data[].gatewayTransactionId | string or null | No | Gateway transaction identifier. |
data[].id | string | Yes | |
data[].metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
data[].occurredAt | string (date-time) | Yes | |
data[].refundTraceReference | object or null | No | Provider-neutral bank-trace reference. Present on refund transactions (with a truthful availability status) and null on every other transaction type. |
data[].refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
data[].refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
data[].refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
data[].status | string | Yes | |
data[].subscription | object | No | Linked subscription (non-secret fields incl. metadata). Present only when the subscription relation is loaded and the payment is tied to a subscription. |
data[].subscription.amount | number or null | Yes | The stored single-unit amount. |
data[].subscription.buyerBusinessDetails | object or null | No | The buyer's current business details at this merchant (customerType, legalName, address, taxId), or null when the buyer has none. Returned by the single-subscription read; omitted from lists. |
data[].subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].subscription.createdAt | string (date-time) | Yes | When the row was created. |
data[].subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].subscription.gateway.id | string | Yes | Gateway UUID. |
data[].subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].subscription.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[].subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].subscription.gatewaySubscriptionId | string | Yes | The subscription identifier stored from the billing gateway. Flo-owned subscriptions hold no gateway-side subscription object, so this is a synthesized flo_<uuid> identifier that exists in the response only: it is not stored, and cannot be looked up at the gateway. |
data[].subscription.gatewayType | string | Yes | The payment gateway that processes charges for the subscription. This describes the payment rails only: it does NOT say who owns the billing schedule. A Flo-owned subscription still reports the gateway its charges run through; read ownership to tell the two apart. Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].subscription.meteredItems | array of object | Yes | The plan's metered items as snapshotted when this Flo-owned subscription started, with the effective unit price: a per-subscription override wins over the snapshot price. Later plan price changes do not alter it. Always empty for a provider-owned subscription. |
data[].subscription.meteredItems[].itemId | string (uuid) | Yes | The metered item: the catalogue price attached to the plan. |
data[].subscription.meteredItems[].name | string | Yes | |
data[].subscription.meteredItems[].unitPrice | string | Yes | Effective unit price as an exact decimal string (up to 6 places) in the subscription currency. |
data[].subscription.ownership | string | Yes | Who owns the billing schedule. provider means the gateway holds the subscription object and drives renewals; flo means Flopay holds the schedule and drives renewals itself, charging through the gateway named by gatewayType. Allowed values: flo, provider. |
data[].subscription.pauseState | string or null | Yes | Distinguishes a pause that is in effect ('active') from one recorded to start at a future date ('scheduled'). Null when no pause is recorded. Allowed values: scheduled, active. |
data[].subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].subscription.planDescription | string or null | Yes | The stored plan description when available. |
data[].subscription.planId | string | Yes | The stored plan identifier. |
data[].subscription.planName | string | Yes | The stored plan name. |
data[].subscription.quantity | number | Yes | The subscribed quantity. |
data[].subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data[].subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].subscription.total | number or null | Yes | The stored total amount. |
data[].subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].subscription.usagePeriod | object or null | Yes | The open usage period of a Flo-owned subscription. Plans of a month or less: the billing cycle already paid for, from the last charge to the next charge date. Longer plans: the current month, anchored like the renewal date. null once the subscription has ended, before it has started, and for a provider-owned subscription. |
data[].subscription.usagePeriod.end | string (date-time) | Yes | End of the open usage period (exclusive). |
data[].subscription.usagePeriod.start | string (date-time) | Yes | Start of the open usage period (inclusive). |
data[].subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data[].subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
data[].type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
data[].userEmail | string or null | No | Customer email when the user relation is loaded. |
data[].userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].userUuid | string or null | No | Linked Flopay user UUID. |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The sort, filter, or pagination query parameters 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. |
Payments_refund
Refund Payment
Issues a full or partial refund against the payment’s originating gateway through the shared refund issuance path. Omit amount and currency to refund the full remaining refundable balance; supply both for a partial refund. The payment and every prior refund are scoped to the authenticated merchant.
| Policy | Value |
|---|---|
| Operation | POST /v1/payments/{id}/refund |
| Class | mutating |
| Risk | critical |
| Confirmation | required |
| Retry | manual-reconciliation |
| Rate-limit tier | restricted |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | Yes | Flopay-issued payment transaction UUID. |
amount | body | number | No | Partial refund amount in major currency units. Omit both amount and currency to refund the full remaining amount. Minimum: 1. Maximum: 99999999.99. |
currency | body | string | No | ISO-4217 currency for a partial refund. Must be supplied together with amount. Minimum length: 3. Maximum length: 3. |
reason | body | string | No | Optional merchant-supplied audit reason. Maximum length: 255. |
Result
Returns 201 with a JSON body. The persisted refund and canonical resulting payment status. Completed refunds transition the payment to partially_refunded or refunded; terminal provider failures use refund_failed, while an asynchronous pending refund preserves the prior payment status.
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Issued refund amount in major currency units. |
createdAt | string (date-time) | Yes | Timestamp when the refund transaction was persisted. |
currency | string | Yes | ISO-4217 refund currency. |
gatewayRefundId | string or null | No | Originating gateway refund identifier. |
id | string (uuid) | Yes | Flopay refund transaction UUID. |
paymentId | string (uuid) | Yes | The refunded Flopay payment transaction UUID. |
reason | string or null | No | Trimmed merchant-supplied audit reason. |
refundStatus | string | Yes | Canonical state of this refund transaction. Allowed values: pending, processing, refunded, failed, voided. |
refundTraceReference | object or null | Yes | Provider-neutral bank-trace reference for this refund. Always present on a refund response; gatewayRefundId remains the provider refund-object identifier and is never the trace value. |
refundTraceReference.status | string | Yes | Availability of the reference. Allowed values: unknown, absent, pending, unavailable, available. |
refundTraceReference.type | string or null | Yes | Which reference scheme the provider reported. A scheme Flo does not recognise is reported as other rather than assumed to be an ARN. Allowed values: acquirer_reference_number, system_trace_audit_number, retrieval_reference_number, other. |
refundTraceReference.value | string or null | Yes | The bank-trace reference, preserved verbatim including any leading zeroes. Populated only when status is available. |
status | string | Yes | Canonical resulting state of the parent payment. A pending provider refund leaves the prior payment state unchanged. Allowed values: succeeded, partially_refunded, refunded, refund_failed. |
Errors
| Status | Description |
|---|---|
400 | The idempotency key or refund body is invalid; amount and currency were not supplied together; the amount exceeds the remaining balance or has invalid precision; or the currency does not match the payment. |
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 | OAuth bearer callers must have a current merchant owner or admin membership. Members and revoked memberships are rejected; authenticated client Basic API-key callers remain authorized. |
404 | No payment with the requested id exists for this merchant. |
409 | The payment is in a non-refundable state, is disputed/reversed, was already fully refunded, or the idempotency key was reused for a different request. |
502 | The originating gateway could not issue the refund. The payment is marked refund_failed for audit and retry visibility. If the stored charge is absent from that gateway account, the response includes a stable code, the Flo gateway UUID, retry safety, and provider-neutral recovery guidance. |
Subscriptions tools
Arguments, results, errors, and access, confirmation, and retry policy for each Subscriptions tool in FloPay MCP, from the reviewed API contract.
Users tools
Arguments, results, errors, and access, confirmation, and retry policy for each Users tool in FloPay MCP, from the reviewed API contract.