MCPTool reference
Pre-Dispute Alerts tools
Arguments, results, errors, and access, confirmation, and retry policy for each Pre-Dispute Alerts tool in FloPay MCP, from the reviewed API contract.
Pre-Dispute Alerts tools
Generated from the FloPay MCP contract version 1, revision 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.
Chargeback_exportAlerts
Export chargeback-alerts
Deprecated compatibility alias for Pre-Dispute Alerts. Use GET /v1/pre-dispute-alerts (PreDisputeAlerts_list), GET /v1/pre-dispute-alerts/{id} (PreDisputeAlerts_get), and POST /v1/pre-dispute-alerts/exports (PreDisputeAlerts_export). Removal is tracked separately; there is no fixed removal date.
| Policy | Value |
|---|---|
| Operation | POST /v1/chargebacks/alerts/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, updatedAt, linkedTransaction.id, linkedTransaction.amount, linkedTransaction.currency, linkedTransaction.status, linkedTransaction.description, linkedTransaction.createdAt, linkedTransaction.userUuid, linkedTransaction.checkoutSessionId, linkedTransaction.subscriptionUuid, linkedTransaction.gatewayTransactionId, linkedTransaction.gatewayPaymentIntentId. Default: createdAt DESC. Allowed values: createdAt, updatedAt, linkedTransaction.id, linkedTransaction.amount, linkedTransaction.currency, linkedTransaction.status, linkedTransaction.description, linkedTransaction.createdAt, linkedTransaction.userUuid, linkedTransaction.checkoutSessionId, linkedTransaction.subscriptionUuid, linkedTransaction.gatewayTransactionId, linkedTransaction.gatewayPaymentIntentId. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: linkedTransaction. Unknown aliases return 400. |
alertService | query | string | No | The chargeback-alert network (ethoca, paypal, cdrn, rdr). 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: ethoca, paypal, cdrn, rdr. |
chargebackAlertId | query | string | No | Deprecated compatibility filter for the alert-network provider alert id (e.g. ALRT-…). Prefer GET /v1/pre-dispute-alerts. 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 | Alert creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | ISO-4217 currency code of the disputed amount. 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. |
linkedTransactionId | query | string | No | The linked Flopay transaction UUID (set when the alert was matched). 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. |
matchMethod | query | string | No | How the alert was linked to a transaction (exact, fuzzy). 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: exact, fuzzy. |
status | query | string | No | Internal alert status (pending, linked, action_required, …). 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, linked, unlinked, refunded, refund_failed, action_required, ignored. |
updatedAt | query | string (date-time) | No | Alert 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 | The Flopay customer (user) UUID the alert is attributed to, when linked. 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 chargeback-alert 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. |
Chargeback_findOne
Get Chargeback Alert
Deprecated compatibility alias for Pre-Dispute Alerts. Use GET /v1/pre-dispute-alerts (PreDisputeAlerts_list), GET /v1/pre-dispute-alerts/{id} (PreDisputeAlerts_get), and POST /v1/pre-dispute-alerts/exports (PreDisputeAlerts_export). Removal is tracked separately; there is no fixed removal date. Returns a single alert-network alert for the authenticated client.
| Policy | Value |
|---|---|
| Operation | GET /v1/chargebacks/alerts/{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: linkedTransaction. Unknown aliases return 400. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
alertService | string or null | No | Allowed values: ethoca, paypal, cdrn, rdr. |
alertStatus | string or null | No | Deprecated compatibility field for the mirrored alert-network display status. |
alertTimestamp | string (date-time) or null | No | When the alert network raised the alert. |
amount | number or null | No | |
arn | string or null | No | Acquirer reference number. |
authCode | string or null | No | |
cardBin | string or null | No | |
cardLast4 | string or null | No | |
chargebackAlertId | string | Yes | Deprecated compatibility field for the alert-network provider alert id (e.g. ALRT-…). Prefer GET /v1/pre-dispute-alerts. Removal is tracked separately. |
chargebackExternalId | string or null | No | Deprecated compatibility field for the alert-network external id. Prefer GET /v1/pre-dispute-alerts. Removal is tracked separately. |
createdAt | string (date-time) | Yes | |
currency | string or null | No | |
id | string | Yes | The Flopay chargeback-alert UUID. Deprecated compatibility identity; prefer Pre-Dispute Alert id. |
linkedTransaction | object or null | No | Matched payment. Present only when the linkedTransaction relation is requested. |
linkedTransaction.amount | number | Yes | |
linkedTransaction.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
linkedTransaction.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
linkedTransaction.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
linkedTransaction.checkoutSessionId | string or null | No | Originating checkout session UUID. |
linkedTransaction.createdAt | string (date-time) | Yes | Record creation timestamp. |
linkedTransaction.currency | string | Yes | |
linkedTransaction.description | string or null | Yes | |
linkedTransaction.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
linkedTransaction.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
linkedTransaction.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
linkedTransaction.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
linkedTransaction.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
linkedTransaction.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
linkedTransaction.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
linkedTransaction.gateway.environment | string | Yes | Allowed values: stage, production. |
linkedTransaction.gateway.id | string | Yes | Gateway UUID. |
linkedTransaction.gateway.name | string | Yes | Human-readable name of the gateway account. |
linkedTransaction.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
linkedTransaction.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
linkedTransaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
linkedTransaction.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. |
linkedTransaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
linkedTransaction.id | string | Yes | |
linkedTransaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
linkedTransaction.occurredAt | string (date-time) | Yes | |
linkedTransaction.status | string | Yes | |
linkedTransaction.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. |
linkedTransaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
linkedTransaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
linkedTransaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
linkedTransaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
linkedTransaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
linkedTransaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
linkedTransaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
linkedTransaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
linkedTransaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
linkedTransaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
linkedTransaction.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
linkedTransaction.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
linkedTransaction.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
linkedTransaction.subscription.gateway.id | string | Yes | Gateway UUID. |
linkedTransaction.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
linkedTransaction.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
linkedTransaction.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
linkedTransaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
linkedTransaction.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. |
linkedTransaction.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. |
linkedTransaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
linkedTransaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
linkedTransaction.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. |
linkedTransaction.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. |
linkedTransaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
linkedTransaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
linkedTransaction.subscription.planId | string | Yes | The stored plan identifier. |
linkedTransaction.subscription.planName | string | Yes | The stored plan name. |
linkedTransaction.subscription.quantity | number | Yes | The subscribed quantity. |
linkedTransaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
linkedTransaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
linkedTransaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
linkedTransaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
linkedTransaction.subscription.total | number or null | Yes | The stored total amount. |
linkedTransaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
linkedTransaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
linkedTransaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
linkedTransaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
linkedTransaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
linkedTransaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
linkedTransaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
linkedTransaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
linkedTransaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
linkedTransaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
linkedTransaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
linkedTransaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
linkedTransaction.userUuid | string or null | No | Linked Flopay user UUID. |
linkedTransactionId | string (uuid) or null | No | The linked Flopay transaction UUID, when matched. |
matchConfidence | number or null | No | 0..1 link-confidence score (audit only). |
matchMethod | string or null | No | Allowed values: exact, fuzzy. |
merchantDescriptor | string or null | No | |
status | string | Yes | Internal alert status. Allowed values: pending, linked, unlinked, refunded, refund_failed, action_required, ignored. |
transactionIds | array of string or null | No | |
updatedAt | string (date-time) | Yes | |
userUuid | string (uuid) or null | No | The Flopay customer (user) UUID this alert is attributed to, when linked. |
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 chargeback alert with the requested id exists for this client. |
Chargeback_list
List Chargeback Alerts
Deprecated compatibility alias for Pre-Dispute Alerts. Use GET /v1/pre-dispute-alerts (PreDisputeAlerts_list), GET /v1/pre-dispute-alerts/{id} (PreDisputeAlerts_get), and POST /v1/pre-dispute-alerts/exports (PreDisputeAlerts_export). Removal is tracked separately; there is no fixed removal date. Returns paginated alert-network alerts for the authenticated client. Supports page, limit, sort[asc|desc], the relation alias linkedTransaction, and whitelisted filters for uuid, status, alertService, currency, matchMethod, chargebackAlertId, createdAt, and updatedAt.
| Policy | Value |
|---|---|
| Operation | GET /v1/chargebacks/alerts |
| 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, updatedAt, linkedTransaction.id, linkedTransaction.amount, linkedTransaction.currency, linkedTransaction.status, linkedTransaction.description, linkedTransaction.createdAt, linkedTransaction.userUuid, linkedTransaction.checkoutSessionId, linkedTransaction.subscriptionUuid, linkedTransaction.gatewayTransactionId, linkedTransaction.gatewayPaymentIntentId. Default: createdAt DESC. Allowed values: createdAt, updatedAt, linkedTransaction.id, linkedTransaction.amount, linkedTransaction.currency, linkedTransaction.status, linkedTransaction.description, linkedTransaction.createdAt, linkedTransaction.userUuid, linkedTransaction.checkoutSessionId, linkedTransaction.subscriptionUuid, linkedTransaction.gatewayTransactionId, linkedTransaction.gatewayPaymentIntentId. |
relation | query | string | No | Comma-separated relation aliases to include. Allowed aliases: linkedTransaction. Unknown aliases return 400. |
alertService | query | string | No | The chargeback-alert network (ethoca, paypal, cdrn, rdr). 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: ethoca, paypal, cdrn, rdr. |
chargebackAlertId | query | string | No | Deprecated compatibility filter for the alert-network provider alert id (e.g. ALRT-…). Prefer GET /v1/pre-dispute-alerts. 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 | Alert creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | ISO-4217 currency code of the disputed amount. 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. |
linkedTransactionId | query | string | No | The linked Flopay transaction UUID (set when the alert was matched). 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. |
matchMethod | query | string | No | How the alert was linked to a transaction (exact, fuzzy). 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: exact, fuzzy. |
status | query | string | No | Internal alert status (pending, linked, action_required, …). 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, linked, unlinked, refunded, refund_failed, action_required, ignored. |
updatedAt | query | string (date-time) | No | Alert 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 | The Flopay customer (user) UUID the alert is attributed to, when linked. 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 chargeback-alert 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[].alertService | string or null | No | Allowed values: ethoca, paypal, cdrn, rdr. |
data[].alertStatus | string or null | No | Deprecated compatibility field for the mirrored alert-network display status. |
data[].alertTimestamp | string (date-time) or null | No | When the alert network raised the alert. |
data[].amount | number or null | No | |
data[].arn | string or null | No | Acquirer reference number. |
data[].authCode | string or null | No | |
data[].cardBin | string or null | No | |
data[].cardLast4 | string or null | No | |
data[].chargebackAlertId | string | Yes | Deprecated compatibility field for the alert-network provider alert id (e.g. ALRT-…). Prefer GET /v1/pre-dispute-alerts. Removal is tracked separately. |
data[].chargebackExternalId | string or null | No | Deprecated compatibility field for the alert-network external id. Prefer GET /v1/pre-dispute-alerts. Removal is tracked separately. |
data[].createdAt | string (date-time) | Yes | |
data[].currency | string or null | No | |
data[].id | string | Yes | The Flopay chargeback-alert UUID. Deprecated compatibility identity; prefer Pre-Dispute Alert id. |
data[].linkedTransaction | object or null | No | Matched payment. Present only when the linkedTransaction relation is requested. |
data[].linkedTransaction.amount | number | Yes | |
data[].linkedTransaction.authorizationExpiresAt | string (date-time) or null | No | Deadline for capturing an active authorization. |
data[].linkedTransaction.authorizationVoidReason | string or null | No | Why an uncaptured authorization was voided. Allowed values: merchant_requested, expired, provider_canceled. |
data[].linkedTransaction.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].linkedTransaction.checkoutSessionId | string or null | No | Originating checkout session UUID. |
data[].linkedTransaction.createdAt | string (date-time) | Yes | Record creation timestamp. |
data[].linkedTransaction.currency | string | Yes | |
data[].linkedTransaction.description | string or null | Yes | |
data[].linkedTransaction.effectiveFloFeeUsd | number or null | Yes | Effective Flo platform fee in USD after adjustments. Null until the legacy base fee has been finalized. |
data[].linkedTransaction.financialEffectiveAt | string (date-time) or null | No | Authoritative provider money-movement timestamp, when available. |
data[].linkedTransaction.floFeeAdjustmentUsd | number | Yes | Net append-only adjustment to the finalized Flo platform fee, in USD. |
data[].linkedTransaction.floFeeUsd | number or null | Yes | Flo's platform fee for this transaction, always in USD: distinct from the shopper amount and currency. |
data[].linkedTransaction.gateway | object | No | Owning gateway (non-secret fields). Present only when the gateway relation is loaded. |
data[].linkedTransaction.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].linkedTransaction.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].linkedTransaction.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].linkedTransaction.gateway.id | string | Yes | Gateway UUID. |
data[].linkedTransaction.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].linkedTransaction.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].linkedTransaction.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].linkedTransaction.gatewayChargeId | string or null | No | Original gateway charge identifier. |
data[].linkedTransaction.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[].linkedTransaction.gatewayTransactionId | string or null | No | Gateway transaction identifier. |
data[].linkedTransaction.id | string | Yes | |
data[].linkedTransaction.metadata | object or null | Yes | Arbitrary metadata captured with the transaction. |
data[].linkedTransaction.occurredAt | string (date-time) | Yes | |
data[].linkedTransaction.status | string | Yes | |
data[].linkedTransaction.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[].linkedTransaction.subscription.amount | number or null | Yes | The stored single-unit amount. |
data[].linkedTransaction.subscription.cancelAt | string (date-time) or null | Yes | When the subscription is scheduled to cancel. |
data[].linkedTransaction.subscription.canceledAt | string (date-time) or null | Yes | When the subscription was canceled. |
data[].linkedTransaction.subscription.checkoutMetadata | object | No | Immutable non-sensitive client context inherited from the originating checkout. |
data[].linkedTransaction.subscription.checkoutSessionId | string or null | Yes | The originating checkout session UUID when available. |
data[].linkedTransaction.subscription.clientId | string or null | Yes | The authenticated client UUID associated with the subscription row. |
data[].linkedTransaction.subscription.createdAt | string (date-time) | Yes | When the row was created. |
data[].linkedTransaction.subscription.currency | string or null | Yes | The ISO 4217 currency code recorded for the subscription. |
data[].linkedTransaction.subscription.endDate | string (date-time) or null | Yes | When the current subscription term ends. |
data[].linkedTransaction.subscription.gateway | object or null | No | Owning gateway (non-secret fields). Present only when the gateway relation is requested. |
data[].linkedTransaction.subscription.gateway.code | string | Yes | Gateway account identifier (e.g. the Stripe connected account acct_…). |
data[].linkedTransaction.subscription.gateway.currency | string | Yes | 3-letter ISO default currency code (e.g. "USD") used by this gateway account. |
data[].linkedTransaction.subscription.gateway.environment | string | Yes | Allowed values: stage, production. |
data[].linkedTransaction.subscription.gateway.id | string | Yes | Gateway UUID. |
data[].linkedTransaction.subscription.gateway.name | string | Yes | Human-readable name of the gateway account. |
data[].linkedTransaction.subscription.gateway.providerType | string | Yes | Allowed values: stripe, paypal, worldpay_corporate_gateway. |
data[].linkedTransaction.subscription.gateway.publishableKey | string | No | Public API key used by frontend clients to identify the gateway account. Not a secret. |
data[].linkedTransaction.subscription.gatewayId | string or null | Yes | The gateway configuration UUID used for this subscription when available. |
data[].linkedTransaction.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[].linkedTransaction.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[].linkedTransaction.subscription.gatewayUserId | string or null | Yes | The billing gateway customer identifier when one is known. |
data[].linkedTransaction.subscription.metadata | object or null | Yes | Arbitrary metadata captured with the subscription row. |
data[].linkedTransaction.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[].linkedTransaction.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[].linkedTransaction.subscription.pausedAt | string (date-time) or null | Yes | When the subscription was paused. |
data[].linkedTransaction.subscription.planDescription | string or null | Yes | The stored plan description when available. |
data[].linkedTransaction.subscription.planId | string | Yes | The stored plan identifier. |
data[].linkedTransaction.subscription.planName | string | Yes | The stored plan name. |
data[].linkedTransaction.subscription.quantity | number | Yes | The subscribed quantity. |
data[].linkedTransaction.subscription.rebillCount | integer (int32) | Yes | The number of successful renewal charges recorded for the subscription. Minimum: 0. |
data[].linkedTransaction.subscription.resumeAt | string (date-time) or null | Yes | When the subscription will resume. |
data[].linkedTransaction.subscription.startDate | string (date-time) or null | Yes | When the subscription started. |
data[].linkedTransaction.subscription.state | string | Yes | The current subscription state stored in Flopay. Allowed values: active, canceled, expired, failed, future, paused, past_due. |
data[].linkedTransaction.subscription.total | number or null | Yes | The stored total amount. |
data[].linkedTransaction.subscription.trialEnd | string (date-time) or null | Yes | When the trial ends. |
data[].linkedTransaction.subscription.updatedAt | string (date-time) | Yes | When the row was last updated. |
data[].linkedTransaction.subscription.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].linkedTransaction.subscription.userGatewayId | string or null | Yes | The linked internal user gateway row UUID when available. |
data[].linkedTransaction.subscription.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].linkedTransaction.subscription.userUuid | string or null | Yes | The Flopay user UUID associated with the subscription. |
data[].linkedTransaction.subscription.uuid | string | Yes | Internal Flopay subscription UUID. |
data[].linkedTransaction.subscriptionUuid | string or null | No | Linked Flopay subscription UUID. |
data[].linkedTransaction.type | string | Yes | Financial event classification. Allowed values: purchase, refund, chargeback, dispute. |
data[].linkedTransaction.userEmail | string or null | No | Customer email when the user relation is loaded. |
data[].linkedTransaction.userFirstName | string or null | No | Customer first name when the user relation is loaded. |
data[].linkedTransaction.userLastName | string or null | No | Customer last name when the user relation is loaded. |
data[].linkedTransaction.userUuid | string or null | No | Linked Flopay user UUID. |
data[].linkedTransactionId | string (uuid) or null | No | The linked Flopay transaction UUID, when matched. |
data[].matchConfidence | number or null | No | 0..1 link-confidence score (audit only). |
data[].matchMethod | string or null | No | Allowed values: exact, fuzzy. |
data[].merchantDescriptor | string or null | No | |
data[].status | string | Yes | Internal alert status. Allowed values: pending, linked, unlinked, refunded, refund_failed, action_required, ignored. |
data[].transactionIds | array of string or null | No | |
data[].updatedAt | string (date-time) | Yes | |
data[].userUuid | string (uuid) or null | No | The Flopay customer (user) UUID this alert is attributed to, when linked. |
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. |
PreDisputeAlerts_export
Export pre-dispute-alerts
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/pre-dispute-alerts/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, responseDueAt, status, updatedAt. Default: createdAt DESC. Allowed values: amount, createdAt, responseDueAt, status, updatedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
actionRequired | query | string | No | Whether merchant action is required. Equality filter. Pass without operator for exact match. |
createdAt | query | string (date-time) | No | Alert creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | ISO-4217 alert 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. |
linkStatus | query | string | No | Payment-link status. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: linked, unmatched, action_required. |
reason | query | string | No | Provider-neutral alert reason. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: fraud_or_unauthorized, duplicate, not_received, not_as_described, credit_not_processed, cancelled_recurring, incorrect_amount, paid_by_other_means, processing_error, other. |
sourceFamily | query | string | No | Origin family without vendor identity: alert_network (Ethoca/RDR/CDRN-style warnings) or payment_provider (eligible Stripe inquiries and early fraud warnings). 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: alert_network, payment_provider. |
status | query | string | No | Provider-neutral Pre-Dispute Alert status. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: needs_response, under_review, closed, prevented, unknown. |
updatedAt | query | string (date-time) | No | Last material 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 | Resolved Flo customer ID, when linked. 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 | Opaque Flo Pre-Dispute Alert ID. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
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. |
PreDisputeAlerts_get
Get Pre-Dispute Alert
Returns a single Pre-Dispute Alert owned by the authenticated client.
| Policy | Value |
|---|---|
| Operation | GET /v1/pre-dispute-alerts/{id} |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
acquirerReferenceNumber | string or null | No | |
actionRequired | boolean | Yes | True when the merchant should act; unknown alert states fail safe to true. |
alertAt | string (date-time) or null | No | When the alert network or provider raised the alert. |
amount | number or null | No | |
authorizationCode | string or null | No | |
cardLast4 | string or null | No | |
createdAt | string (date-time) | Yes | |
currency | string or null | No | ISO-4217 currency code. |
id | string (uuid) | Yes | Opaque Flo Pre-Dispute Alert ID, stable for the whole alert lifecycle. |
linkStatus | string | Yes | Allowed values: linked, unmatched, action_required. |
merchantDescriptor | string or null | No | |
paymentIds | array of string | Yes | Flo payment IDs linked to this alert; empty while unlinked. |
reason | string or null | No | Allowed values: fraud_or_unauthorized, duplicate, not_received, not_as_described, credit_not_processed, cancelled_recurring, incorrect_amount, paid_by_other_means, processing_error, other. |
responseDueAt | string (date-time) or null | No | |
sequence | number | Yes | Monotonic per-alert sequence; discard reads that do not advance it. Minimum: 1. |
sourceFamily | string | Yes | Origin family without vendor identity. Allowed values: alert_network, payment_provider. |
status | string | Yes | Allowed values: needs_response, under_review, closed, prevented, unknown. |
updatedAt | string (date-time) | Yes | |
userUuid | string (uuid) or null | No | Resolved Flo customer ID, when linked. |
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 Pre-Dispute Alert with the requested id exists for this client. |
PreDisputeAlerts_list
List Pre-Dispute Alerts
Returns paginated Pre-Dispute Alerts for the authenticated client. Covers alert-network warnings and eligible payment-provider early warnings. Actual Stripe and PayPal chargebacks are Disputes, not Pre-Dispute Alerts.
| Policy | Value |
|---|---|
| Operation | GET /v1/pre-dispute-alerts |
| 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, responseDueAt, status, updatedAt. Default: createdAt DESC. Allowed values: amount, createdAt, responseDueAt, status, updatedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
actionRequired | query | string | No | Whether merchant action is required. Equality filter. Pass without operator for exact match. |
createdAt | query | string (date-time) | No | Alert creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | ISO-4217 alert 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. |
linkStatus | query | string | No | Payment-link status. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: linked, unmatched, action_required. |
reason | query | string | No | Provider-neutral alert reason. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: fraud_or_unauthorized, duplicate, not_received, not_as_described, credit_not_processed, cancelled_recurring, incorrect_amount, paid_by_other_means, processing_error, other. |
sourceFamily | query | string | No | Origin family without vendor identity: alert_network (Ethoca/RDR/CDRN-style warnings) or payment_provider (eligible Stripe inquiries and early fraud warnings). 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: alert_network, payment_provider. |
status | query | string | No | Provider-neutral Pre-Dispute Alert status. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: needs_response, under_review, closed, prevented, unknown. |
updatedAt | query | string (date-time) | No | Last material 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 | Resolved Flo customer ID, when linked. 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 | Opaque Flo Pre-Dispute Alert ID. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].acquirerReferenceNumber | string or null | No | |
data[].actionRequired | boolean | Yes | True when the merchant should act; unknown alert states fail safe to true. |
data[].alertAt | string (date-time) or null | No | When the alert network or provider raised the alert. |
data[].amount | number or null | No | |
data[].authorizationCode | string or null | No | |
data[].cardLast4 | string or null | No | |
data[].createdAt | string (date-time) | Yes | |
data[].currency | string or null | No | ISO-4217 currency code. |
data[].id | string (uuid) | Yes | Opaque Flo Pre-Dispute Alert ID, stable for the whole alert lifecycle. |
data[].linkStatus | string | Yes | Allowed values: linked, unmatched, action_required. |
data[].merchantDescriptor | string or null | No | |
data[].paymentIds | array of string | Yes | Flo payment IDs linked to this alert; empty while unlinked. |
data[].reason | string or null | No | Allowed values: fraud_or_unauthorized, duplicate, not_received, not_as_described, credit_not_processed, cancelled_recurring, incorrect_amount, paid_by_other_means, processing_error, other. |
data[].responseDueAt | string (date-time) or null | No | |
data[].sequence | number | Yes | Monotonic per-alert sequence; discard reads that do not advance it. Minimum: 1. |
data[].sourceFamily | string | Yes | Origin family without vendor identity. Allowed values: alert_network, payment_provider. |
data[].status | string | Yes | Allowed values: needs_response, under_review, closed, prevented, unknown. |
data[].updatedAt | string (date-time) | Yes | |
data[].userUuid | string (uuid) or null | No | Resolved Flo customer ID, when linked. |
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. |
Disputes tools
Arguments, results, errors, and access, confirmation, and retry policy for each Disputes tool in FloPay MCP, from the reviewed API contract.
Checkouts tools
Arguments, results, errors, and access, confirmation, and retry policy for each Checkouts tool in FloPay MCP, from the reviewed API contract.