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 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.
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, 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, 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. |
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. |
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. |
id | string | Yes | The Flopay invoice UUID. |
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.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.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.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.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.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.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.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, 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, 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[].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[].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[].id | string | Yes | The Flopay invoice UUID. |
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.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.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.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.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.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.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.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, 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, 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_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, 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, 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, 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. |
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. |
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 | |
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.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.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.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.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, 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, 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, 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[].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[].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[].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.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.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.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.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. |
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.