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

Settings tools

Generated from the FloPay MCP contract version 1, revision cc71a476426ea531d369de5441cde85ab81ab52c9764406e5f09501857d7ed32.

Branding_clear

Clear branding

Clears branding for the active client across SDK embeds, hosted checkout, branding emails, and other white-label services.

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

Arguments

This tool takes no arguments.

Result

Returns 204 with no body.

Errors

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

Branding_get

Read branding

Returns branding for the active client, including hostedCheckoutTheme used for branding emails and other white-label services.

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

Arguments

This tool takes no arguments.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes
`hostedCheckoutTheme`	object	Yes
`hostedCheckoutTheme.appearance`	object	No
`hostedCheckoutTheme.appearance.colorPrimary`	string	No
`hostedCheckoutTheme.appearance.colorText`	string	No
`hostedCheckoutTheme.appearance.container`	object	No
`hostedCheckoutTheme.appearance.container.backgroundColor`	string	No
`hostedCheckoutTheme.appearance.container.borderRadius`	string	No	Minimum length: 1. Maximum length: 255.
`hostedCheckoutTheme.appearance.container.maxWidth`	string	No	Minimum length: 1. Maximum length: 255.
`hostedCheckoutTheme.appearance.container.shadow`	string	No	Minimum length: 1. Maximum length: 1000.
`hostedCheckoutTheme.appearance.footer`	object	No
`hostedCheckoutTheme.appearance.footer.show`	boolean	No
`hostedCheckoutTheme.appearance.footer.text`	string	No	Minimum length: 0. Maximum length: 1000.
`hostedCheckoutTheme.appearance.header`	object	No
`hostedCheckoutTheme.appearance.header.backgroundColor`	string	No
`hostedCheckoutTheme.appearance.header.show`	boolean	No
`hostedCheckoutTheme.appearance.pageBackgroundColor`	string	No
`hostedCheckoutTheme.appearance.pageBackgroundImage`	string	No
`hostedCheckoutTheme.appearance.rules`	object	No
`hostedCheckoutTheme.fontFamily`	string	No	Minimum length: 1. Maximum length: 1000.
`hostedCheckoutTheme.fontUrl`	string	No
`hostedCheckoutTheme.logo`	object	Yes
`hostedCheckoutTheme.logo.alt`	string	No	Minimum length: 0. Maximum length: 255.
`hostedCheckoutTheme.logo.href`	string	No
`hostedCheckoutTheme.logo.size`	number	No	Minimum: 1. Maximum: 512.
`hostedCheckoutTheme.logo.src`	string	Yes
`id`	string (uuid)	Yes
`name`	string	Yes
`sdkEmbedTheme`	object	Yes
`sdkEmbedTheme.appearance`	object	No
`sdkEmbedTheme.appearance.rules`	object	No
`sdkEmbedTheme.appearance.theme`	string	No	Allowed values: `default`, `flat`, `night`, `none`.
`sdkEmbedTheme.appearance.variables`	object	No
`sdkEmbedTheme.appearance.variables.borderRadius`	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.appearance.variables.colorBackground`	string	No
`sdkEmbedTheme.appearance.variables.colorDanger`	string	No
`sdkEmbedTheme.appearance.variables.colorPrimary`	string	No
`sdkEmbedTheme.appearance.variables.colorPrimaryHover`	string	No
`sdkEmbedTheme.appearance.variables.colorText`	string	No
`sdkEmbedTheme.appearance.variables.fontFamily`	string	No	Minimum length: 1. Maximum length: 1000.
`sdkEmbedTheme.appearance.variables.fontSizeBase`	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.appearance.variables.spacingUnit`	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.buttonsStyles`	object	No
`sdkEmbedTheme.buttonsStyles.addressLine1Input`	object	No
`sdkEmbedTheme.buttonsStyles.addressLine2Input`	object	No
`sdkEmbedTheme.buttonsStyles.backButton`	object	No
`sdkEmbedTheme.buttonsStyles.backButtonFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.backButtonIcon`	object	No
`sdkEmbedTheme.buttonsStyles.cardButton`	object	No
`sdkEmbedTheme.buttonsStyles.cardButtonFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.cardFormContainer`	object	No
`sdkEmbedTheme.buttonsStyles.cardInputBackground`	string	No
`sdkEmbedTheme.buttonsStyles.cardInputBorder`	string	No
`sdkEmbedTheme.buttonsStyles.cardInputColor`	string	No
`sdkEmbedTheme.buttonsStyles.cardInputFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.cardInputPlaceholderColor`	string	No
`sdkEmbedTheme.buttonsStyles.cityInput`	object	No
`sdkEmbedTheme.buttonsStyles.countrySelect`	object	No
`sdkEmbedTheme.buttonsStyles.errorBanner`	object	No
`sdkEmbedTheme.buttonsStyles.nameInput`	object	No
`sdkEmbedTheme.buttonsStyles.stateInput`	object	No
`sdkEmbedTheme.buttonsStyles.submitButton`	object	No
`sdkEmbedTheme.buttonsStyles.submitButtonFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.title`	object	No
`sdkEmbedTheme.buttonsStyles.titleFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.vaultCardForm`	object	No
`sdkEmbedTheme.buttonsStyles.zipInput`	object	No
`sdkEmbedTheme.layout`	string	Yes	Allowed values: `default`, `buttons`.
`sdkEmbedTheme.themePreset`	string	Yes	Allowed values: `classic`, `modern-light`, `modern-dark`, `bold-light`, `bold-dark`, `glass-light`, `glass-dark`.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`401`	Client Basic authentication or OAuth2 bearer authentication is required.
`404`	The client has not configured branding.

Branding_upsert

Create or replace branding

Creates or wholly replaces branding for the active client. hostedCheckoutTheme is also used for branding emails and other white-label services.

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

Arguments

Argument	In	Type	Required	Description
`hostedCheckoutTheme`	body	object	Yes
`hostedCheckoutTheme.appearance`	body	object	No
`hostedCheckoutTheme.appearance.colorPrimary`	body	string	No
`hostedCheckoutTheme.appearance.colorText`	body	string	No
`hostedCheckoutTheme.appearance.container`	body	object	No
`hostedCheckoutTheme.appearance.container.backgroundColor`	body	string	No
`hostedCheckoutTheme.appearance.container.borderRadius`	body	string	No	Minimum length: 1. Maximum length: 255.
`hostedCheckoutTheme.appearance.container.maxWidth`	body	string	No	Minimum length: 1. Maximum length: 255.
`hostedCheckoutTheme.appearance.container.shadow`	body	string	No	Minimum length: 1. Maximum length: 1000.
`hostedCheckoutTheme.appearance.footer`	body	object	No
`hostedCheckoutTheme.appearance.footer.show`	body	boolean	No
`hostedCheckoutTheme.appearance.footer.text`	body	string	No	Minimum length: 0. Maximum length: 1000.
`hostedCheckoutTheme.appearance.header`	body	object	No
`hostedCheckoutTheme.appearance.header.backgroundColor`	body	string	No
`hostedCheckoutTheme.appearance.header.show`	body	boolean	No
`hostedCheckoutTheme.appearance.pageBackgroundColor`	body	string	No
`hostedCheckoutTheme.appearance.pageBackgroundImage`	body	string	No
`hostedCheckoutTheme.appearance.rules`	body	object	No
`hostedCheckoutTheme.fontFamily`	body	string	No	Minimum length: 1. Maximum length: 1000.
`hostedCheckoutTheme.fontUrl`	body	string	No
`hostedCheckoutTheme.logo`	body	object	Yes
`hostedCheckoutTheme.logo.alt`	body	string	No	Minimum length: 0. Maximum length: 255.
`hostedCheckoutTheme.logo.href`	body	string	No
`hostedCheckoutTheme.logo.size`	body	number	No	Minimum: 1. Maximum: 512.
`hostedCheckoutTheme.logo.src`	body	string	Yes
`name`	body	string	Yes	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme`	body	object	Yes
`sdkEmbedTheme.appearance`	body	object	No
`sdkEmbedTheme.appearance.rules`	body	object	No
`sdkEmbedTheme.appearance.theme`	body	string	No	Allowed values: `default`, `flat`, `night`, `none`.
`sdkEmbedTheme.appearance.variables`	body	object	No
`sdkEmbedTheme.appearance.variables.borderRadius`	body	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.appearance.variables.colorBackground`	body	string	No
`sdkEmbedTheme.appearance.variables.colorDanger`	body	string	No
`sdkEmbedTheme.appearance.variables.colorPrimary`	body	string	No
`sdkEmbedTheme.appearance.variables.colorPrimaryHover`	body	string	No
`sdkEmbedTheme.appearance.variables.colorText`	body	string	No
`sdkEmbedTheme.appearance.variables.fontFamily`	body	string	No	Minimum length: 1. Maximum length: 1000.
`sdkEmbedTheme.appearance.variables.fontSizeBase`	body	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.appearance.variables.spacingUnit`	body	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.buttonsStyles`	body	object	No
`sdkEmbedTheme.buttonsStyles.addressLine1Input`	body	object	No
`sdkEmbedTheme.buttonsStyles.addressLine2Input`	body	object	No
`sdkEmbedTheme.buttonsStyles.backButton`	body	object	No
`sdkEmbedTheme.buttonsStyles.backButtonFontSize`	body	string	No
`sdkEmbedTheme.buttonsStyles.backButtonIcon`	body	object	No
`sdkEmbedTheme.buttonsStyles.cardButton`	body	object	No
`sdkEmbedTheme.buttonsStyles.cardButtonFontSize`	body	string	No
`sdkEmbedTheme.buttonsStyles.cardFormContainer`	body	object	No
`sdkEmbedTheme.buttonsStyles.cardInputBackground`	body	string	No
`sdkEmbedTheme.buttonsStyles.cardInputBorder`	body	string	No
`sdkEmbedTheme.buttonsStyles.cardInputColor`	body	string	No
`sdkEmbedTheme.buttonsStyles.cardInputFontSize`	body	string	No
`sdkEmbedTheme.buttonsStyles.cardInputPlaceholderColor`	body	string	No
`sdkEmbedTheme.buttonsStyles.cityInput`	body	object	No
`sdkEmbedTheme.buttonsStyles.countrySelect`	body	object	No
`sdkEmbedTheme.buttonsStyles.errorBanner`	body	object	No
`sdkEmbedTheme.buttonsStyles.nameInput`	body	object	No
`sdkEmbedTheme.buttonsStyles.stateInput`	body	object	No
`sdkEmbedTheme.buttonsStyles.submitButton`	body	object	No
`sdkEmbedTheme.buttonsStyles.submitButtonFontSize`	body	string	No
`sdkEmbedTheme.buttonsStyles.title`	body	object	No
`sdkEmbedTheme.buttonsStyles.titleFontSize`	body	string	No
`sdkEmbedTheme.buttonsStyles.vaultCardForm`	body	object	No
`sdkEmbedTheme.buttonsStyles.zipInput`	body	object	No
`sdkEmbedTheme.layout`	body	string	Yes	Allowed values: `default`, `buttons`.
`sdkEmbedTheme.themePreset`	body	string	Yes	Allowed values: `classic`, `modern-light`, `modern-dark`, `bold-light`, `bold-dark`, `glass-light`, `glass-dark`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes
`hostedCheckoutTheme`	object	Yes
`hostedCheckoutTheme.appearance`	object	No
`hostedCheckoutTheme.appearance.colorPrimary`	string	No
`hostedCheckoutTheme.appearance.colorText`	string	No
`hostedCheckoutTheme.appearance.container`	object	No
`hostedCheckoutTheme.appearance.container.backgroundColor`	string	No
`hostedCheckoutTheme.appearance.container.borderRadius`	string	No	Minimum length: 1. Maximum length: 255.
`hostedCheckoutTheme.appearance.container.maxWidth`	string	No	Minimum length: 1. Maximum length: 255.
`hostedCheckoutTheme.appearance.container.shadow`	string	No	Minimum length: 1. Maximum length: 1000.
`hostedCheckoutTheme.appearance.footer`	object	No
`hostedCheckoutTheme.appearance.footer.show`	boolean	No
`hostedCheckoutTheme.appearance.footer.text`	string	No	Minimum length: 0. Maximum length: 1000.
`hostedCheckoutTheme.appearance.header`	object	No
`hostedCheckoutTheme.appearance.header.backgroundColor`	string	No
`hostedCheckoutTheme.appearance.header.show`	boolean	No
`hostedCheckoutTheme.appearance.pageBackgroundColor`	string	No
`hostedCheckoutTheme.appearance.pageBackgroundImage`	string	No
`hostedCheckoutTheme.appearance.rules`	object	No
`hostedCheckoutTheme.fontFamily`	string	No	Minimum length: 1. Maximum length: 1000.
`hostedCheckoutTheme.fontUrl`	string	No
`hostedCheckoutTheme.logo`	object	Yes
`hostedCheckoutTheme.logo.alt`	string	No	Minimum length: 0. Maximum length: 255.
`hostedCheckoutTheme.logo.href`	string	No
`hostedCheckoutTheme.logo.size`	number	No	Minimum: 1. Maximum: 512.
`hostedCheckoutTheme.logo.src`	string	Yes
`id`	string (uuid)	Yes
`name`	string	Yes
`sdkEmbedTheme`	object	Yes
`sdkEmbedTheme.appearance`	object	No
`sdkEmbedTheme.appearance.rules`	object	No
`sdkEmbedTheme.appearance.theme`	string	No	Allowed values: `default`, `flat`, `night`, `none`.
`sdkEmbedTheme.appearance.variables`	object	No
`sdkEmbedTheme.appearance.variables.borderRadius`	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.appearance.variables.colorBackground`	string	No
`sdkEmbedTheme.appearance.variables.colorDanger`	string	No
`sdkEmbedTheme.appearance.variables.colorPrimary`	string	No
`sdkEmbedTheme.appearance.variables.colorPrimaryHover`	string	No
`sdkEmbedTheme.appearance.variables.colorText`	string	No
`sdkEmbedTheme.appearance.variables.fontFamily`	string	No	Minimum length: 1. Maximum length: 1000.
`sdkEmbedTheme.appearance.variables.fontSizeBase`	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.appearance.variables.spacingUnit`	string	No	Minimum length: 1. Maximum length: 255.
`sdkEmbedTheme.buttonsStyles`	object	No
`sdkEmbedTheme.buttonsStyles.addressLine1Input`	object	No
`sdkEmbedTheme.buttonsStyles.addressLine2Input`	object	No
`sdkEmbedTheme.buttonsStyles.backButton`	object	No
`sdkEmbedTheme.buttonsStyles.backButtonFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.backButtonIcon`	object	No
`sdkEmbedTheme.buttonsStyles.cardButton`	object	No
`sdkEmbedTheme.buttonsStyles.cardButtonFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.cardFormContainer`	object	No
`sdkEmbedTheme.buttonsStyles.cardInputBackground`	string	No
`sdkEmbedTheme.buttonsStyles.cardInputBorder`	string	No
`sdkEmbedTheme.buttonsStyles.cardInputColor`	string	No
`sdkEmbedTheme.buttonsStyles.cardInputFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.cardInputPlaceholderColor`	string	No
`sdkEmbedTheme.buttonsStyles.cityInput`	object	No
`sdkEmbedTheme.buttonsStyles.countrySelect`	object	No
`sdkEmbedTheme.buttonsStyles.errorBanner`	object	No
`sdkEmbedTheme.buttonsStyles.nameInput`	object	No
`sdkEmbedTheme.buttonsStyles.stateInput`	object	No
`sdkEmbedTheme.buttonsStyles.submitButton`	object	No
`sdkEmbedTheme.buttonsStyles.submitButtonFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.title`	object	No
`sdkEmbedTheme.buttonsStyles.titleFontSize`	string	No
`sdkEmbedTheme.buttonsStyles.vaultCardForm`	object	No
`sdkEmbedTheme.buttonsStyles.zipInput`	object	No
`sdkEmbedTheme.layout`	string	Yes	Allowed values: `default`, `buttons`.
`sdkEmbedTheme.themePreset`	string	Yes	Allowed values: `classic`, `modern-light`, `modern-dark`, `bold-light`, `bold-dark`, `glass-light`, `glass-dark`.
`updatedAt`	string (date-time)	Yes

Errors

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

ChargebackSettings_createDescriptor

Create Chargeback Descriptor

Deprecated compatibility alias for Pre-Dispute Alert Settings. Use GET /v1/settings/pre-dispute-alerts (PreDisputeAlertSettings_list), GET/PATCH /v1/settings/pre-dispute-alerts/{id} (PreDisputeAlertSettings_get|update), and GET/POST /v1/settings/pre-dispute-alerts/{id}/descriptors (PreDisputeAlertSettings_listDescriptors|enrollDescriptor). Removal is tracked separately; there is no fixed removal date. Enrolls a merchant billing descriptor with the alert network and seeds one local row per requested enrollment. Status updates then keep each enrollment current.

Policy	Value
Operation	`POST /v1/settings/chargebacks/{id}/descriptors`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The chargeback business-account setting id.
`descriptor`	body	string	Yes	Merchant billing descriptor text to enroll with the alert network. Maximum length: 255.
`enrollments`	body	array of string	Yes	Alert networks to enroll the descriptor in. One row is tracked per (descriptor, enrollment). Allowed values: `ethoca`, `rdr`, `cdrn`. Minimum items: 1.
`visaArnCodes`	body	array of string	No	Visa ARN codes to scope the descriptor. Required when the RDR network is enrolled (RDR enrollment is rejected without them); ignored for non-RDR enrollments.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`[].clientChargebackSettingId`	string	Yes	Deprecated compatibility field for the owning setting UUID. Prefer `preDisputeAlertSettingId` on PreDisputeAlertDescriptorDto from `settings/pre-dispute-alerts/{id}/descriptors`. Removal is tracked separately.
`[].createdAt`	string (date-time)	Yes
`[].descriptor`	string	Yes	The merchant billing descriptor text.
`[].enrollment`	string	Yes	The alert network enrolled. Allowed values: `ethoca`, `rdr`, `cdrn`.
`[].externalId`	string or null	Yes	Deprecated compatibility field for the alert-network external id. Prefer Pre-Dispute Alert descriptor enrollments. Removal is tracked separately.
`[].id`	string	Yes	The Flopay descriptor-enrollment UUID.
`[].status`	string	Yes	Normalized enrollment status, kept current by the billing_descriptor.updated webhook. Allowed values: `pending`, `live`, `error`.
`[].updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body 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 such chargeback setting for this client.
`409`	The descriptor is already enrolled, or the setting is not linked to an alert-network account.
`502`	The alert network rejected or did not answer the enrollment request.

ChargebackSettings_getSetting

Get Chargeback Setting

Deprecated compatibility alias for Pre-Dispute Alert Settings. Use GET /v1/settings/pre-dispute-alerts (PreDisputeAlertSettings_list), GET/PATCH /v1/settings/pre-dispute-alerts/{id} (PreDisputeAlertSettings_get|update), and GET/POST /v1/settings/pre-dispute-alerts/{id}/descriptors (PreDisputeAlertSettings_listDescriptors|enrollDescriptor). Removal is tracked separately; there is no fixed removal date. Returns a single alert-network business-account setting owned by the authenticated client.

Policy	Value
Operation	`GET /v1/settings/chargebacks/{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 (uuid)	Yes	The chargeback business-account setting id.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`autoRefundAmount`	number or null	Yes	Cap applied to AUTO-REFUND-CAPPED (Phase 2).
`chargebackAction`	string	Yes	Deprecated compatibility field for the configured response mode. Prefer `responseMode` on Pre-Dispute Alert Settings. Removal is tracked separately. Allowed values: `AUTO-REFUND`, `AUTO-REFUND-CAPPED`, `ALERT`.
`chargebackIoId`	string or null	Yes	Deprecated compatibility field for the alert-network business-account id used to attribute inbound alerts. Prefer Pre-Dispute Alert Settings. Removal is tracked separately.
`clientId`	string	Yes	The owning Flopay client UUID.
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes	Optional free-text note describing this business account. Local display value only.
`id`	string	Yes	The Flopay chargeback-settings UUID.
`name`	string or null	Yes	Human-friendly label for this business account (e.g. "UK Ltd"). Local display value only.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body 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 such chargeback setting for this client.

ChargebackSettings_updateSetting

Update Chargeback Setting

Deprecated compatibility alias for Pre-Dispute Alert Settings. Use GET /v1/settings/pre-dispute-alerts (PreDisputeAlertSettings_list), GET/PATCH /v1/settings/pre-dispute-alerts/{id} (PreDisputeAlertSettings_get|update), and GET/POST /v1/settings/pre-dispute-alerts/{id}/descriptors (PreDisputeAlertSettings_listDescriptors|enrollDescriptor). Removal is tracked separately; there is no fixed removal date. Updates a single alert-network business-account setting owned by the authenticated client. The provider business-account id is server-assigned by Flopay and is not editable here.

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

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The chargeback business-account setting id.
`autoRefundAmount`	body	number	No	Cap applied to AUTO-REFUND-CAPPED (Phase 2). Minimum: 0.
`chargebackAction`	body	string	No	Configured chargeback response mode. Recorded but never acted on in Phase 1 (ALERT mode). Allowed values: `AUTO-REFUND`, `AUTO-REFUND-CAPPED`, `ALERT`.
`description`	body	string or null	No	Optional free-text note describing this business account. Send null to clear. Maximum length: 1000.
`name`	body	string or null	No	Human-friendly label for this business account. Send null to clear. Maximum length: 255.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`autoRefundAmount`	number or null	Yes	Cap applied to AUTO-REFUND-CAPPED (Phase 2).
`chargebackAction`	string	Yes	Deprecated compatibility field for the configured response mode. Prefer `responseMode` on Pre-Dispute Alert Settings. Removal is tracked separately. Allowed values: `AUTO-REFUND`, `AUTO-REFUND-CAPPED`, `ALERT`.
`chargebackIoId`	string or null	Yes	Deprecated compatibility field for the alert-network business-account id used to attribute inbound alerts. Prefer Pre-Dispute Alert Settings. Removal is tracked separately.
`clientId`	string	Yes	The owning Flopay client UUID.
`createdAt`	string (date-time)	Yes
`description`	string or null	Yes	Optional free-text note describing this business account. Local display value only.
`id`	string	Yes	The Flopay chargeback-settings UUID.
`name`	string or null	Yes	Human-friendly label for this business account (e.g. "UK Ltd"). Local display value only.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body 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 such chargeback setting for this client.

ClientUser_create

Adds a team member

Creates a new user from a new email or attaches an existing identity as a member. A password must be omitted when attaching an existing operator. owner is never assignable here. Owner/admin only.

Policy	Value
Operation	`POST /v1/client-users`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`email`	body	string (email)	Yes	The operator email address. Normalised to lowercase. Unique per client_user identity. Maximum length: 300.
`name`	body	string	No	Display name. Required when creating a brand-new identity; ignored when attaching an existing one. Maximum length: 200.
`password`	body	string	No	Plaintext password, hashed server-side (argon2id). Required for a new identity; must be omitted when attaching an existing one. Policy: 12-256 chars, at least three of lowercase/uppercase/number/symbol, not whitespace-only, and must not contain the email local-part. Minimum length: 12. Maximum length: 256.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	When the client_user identity was created.
`email`	string	Yes	The operator email address (always stored and returned lowercase).
`emailVerified`	boolean	Yes	Whether the operator has verified their email address.
`id`	string	Yes	The client_user identifier. Use this value in `/v1/client-users/{id}` routes.
`name`	string	Yes	The operator display name.
`role`	string	Yes	The operator role within this client. Allowed values: `owner`, `admin`, `member`.
`updatedAt`	string (date-time)	Yes	When the client_user identity was last updated.

Errors

Status	Description
`401`	A valid OAuth client_user access token with the `mcp` scope is required.
`403`	The caller is authenticated but their membership role does not permit this action.
`409`	The operator is already a member of this client.

ClientUser_getOne

Get a team member by id

Owner/admin can read any team member; members can read only themselves.

Policy	Value
Operation	`GET /v1/client-users/{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	The client_user id.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	When the client_user identity was created.
`email`	string	Yes	The operator email address (always stored and returned lowercase).
`emailVerified`	boolean	Yes	Whether the operator has verified their email address.
`id`	string	Yes	The client_user identifier. Use this value in `/v1/client-users/{id}` routes.
`name`	string	Yes	The operator display name.
`role`	string	Yes	The operator role within this client. Allowed values: `owner`, `admin`, `member`.
`updatedAt`	string (date-time)	Yes	When the client_user identity was last updated.

Errors

Status	Description
`401`	A valid OAuth client_user access token with the `mcp` scope is required.
`403`	The caller is authenticated but their membership role does not permit this action.

ClientUser_list

List team

Returns the team directory for the active client. Available to any role.

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

Arguments

This tool takes no arguments.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].createdAt`	string (date-time)	Yes	When the client_user identity was created.
`data[].email`	string	Yes	The operator email address (always stored and returned lowercase).
`data[].emailVerified`	boolean	Yes	Whether the operator has verified their email address.
`data[].id`	string	Yes	The client_user identifier. Use this value in `/v1/client-users/{id}` routes.
`data[].name`	string	Yes	The operator display name.
`data[].role`	string	Yes	The operator role within this client. Allowed values: `owner`, `admin`, `member`.
`data[].updatedAt`	string (date-time)	Yes	When the client_user identity was last updated.

Errors

Status	Description
`401`	A valid OAuth client_user access token with the `mcp` scope is required.
`403`	The caller is authenticated but their membership role does not permit this action.

ClientUser_remove

Remove a team member

Removes the team member’s membership. An owner membership cannot be removed (transfer first). Owner/admin may remove other non-owner team members; admins/members may remove themselves. If this was the team member’s last membership, the orphaned identity is deleted too.

Policy	Value
Operation	`DELETE /v1/client-users/{id}`
Class	`mutating`
Risk	`critical`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string	Yes	The client_user id.

Result

Returns 204 with no body. The membership was removed.

Errors

Status	Description
`401`	A valid OAuth client_user access token with the `mcp` scope is required.
`403`	The caller is authenticated but their membership role does not permit this action.

ClientUser_transferOwnership

Transfer ownership of the client

Atomically promotes the target team member to owner and demotes the current owner (the caller) to admin. Caller must be the current owner; the target must already be a member. After transfer, the former owner (now admin) may remove themselves.

Policy	Value
Operation	`POST /v1/client-users/ownership/transfer`
Class	`mutating`
Risk	`critical`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`restricted`
Roles	`owner`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`targetClientUserId`	body	string (uuid)	Yes	The client_user id of the operator who will become the new owner. Must already be a member.

Result

Returns 200 with a JSON body. The new owner.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	When the client_user identity was created.
`email`	string	Yes	The operator email address (always stored and returned lowercase).
`emailVerified`	boolean	Yes	Whether the operator has verified their email address.
`id`	string	Yes	The client_user identifier. Use this value in `/v1/client-users/{id}` routes.
`name`	string	Yes	The operator display name.
`role`	string	Yes	The operator role within this client. Allowed values: `owner`, `admin`, `member`.
`updatedAt`	string (date-time)	Yes	When the client_user identity was last updated.

Errors

Status	Description
`401`	A valid OAuth client_user access token with the `mcp` scope is required.
`403`	The caller is authenticated but their membership role does not permit this action.

ClientUser_update

Update a team member

Updates profile fields (name, email, password) and/or the membership role (member ↔ admin). Owner/admin may update any team member; any role may update themselves but never their own role. Changing an email resets verification state and revokes the team member’s sessions; changing a password also revokes their sessions.

Policy	Value
Operation	`PATCH /v1/client-users/{id}`
Class	`mutating`
Risk	`critical`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string	Yes	The client_user id.
`email`	body	string (email)	No	New email address. Normalised to lowercase; changing it resets email-verification state and revokes renewable sessions. Maximum length: 300.
`name`	body	string	No	New display name. Maximum length: 200.
`password`	body	string	No	New plaintext password, hashed server-side. Same policy as create. Changing a password revokes the operator's active sessions. Minimum length: 12. Maximum length: 256.
`role`	body	string	No	New role. Only `member` or `admin`: `owner` is set exclusively through ownership transfer. Allowed values: `member`, `admin`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes	When the client_user identity was created.
`email`	string	Yes	The operator email address (always stored and returned lowercase).
`emailVerified`	boolean	Yes	Whether the operator has verified their email address.
`id`	string	Yes	The client_user identifier. Use this value in `/v1/client-users/{id}` routes.
`name`	string	Yes	The operator display name.
`role`	string	Yes	The operator role within this client. Allowed values: `owner`, `admin`, `member`.
`updatedAt`	string (date-time)	Yes	When the client_user identity was last updated.

Errors

Status	Description
`401`	A valid OAuth client_user access token with the `mcp` scope is required.
`403`	The caller is authenticated but their membership role does not permit this action.

GatewaySettings_activate

Activate Gateway

Activates a gateway for runtime use. Requires complete credentials including the webhook verification value; the provider connection is re-validated first.

Policy	Value
Operation	`POST /v1/settings/gateways/{id}/activate`
Class	`mutating`
Risk	`critical`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The gateway id.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`cascadeEnabled`	boolean	Yes	Whether this gateway may receive a failover attempt after another of your gateways declines the same payment. When `false`, the gateway can still take a payment's first attempt but never a failover attempt.
`clientId`	string	Yes	The owning client UUID.
`code`	string	Yes	Flopay-owned unique gateway code (webhook account-code hint).
`connectionValidatedAt`	string (date-time) or null	Yes	When the provider last confirmed the stored credentials. Null for unconnected drafts.
`countries`	array of string or null	Yes	ISO 3166-1 alpha-2 countries, or null.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO 4217 currency this gateway serves.
`environment`	string	Yes	Allowed values: `stage`, `production`.
`id`	string	Yes	The gateway UUID.
`name`	string	Yes	Display name.
`priority`	number	Yes	Routing priority (lower ranks first).
`providerAccountId`	string or null	Yes	Canonical provider account identity captured at validation (Stripe acct_…, PayPal REST-app client ID). Null until the connection has been validated.
`providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`publishableKey`	string or null	Yes	Provider public identifier (Stripe publishable key / PayPal client ID).
`secretKeyConfigured`	boolean	Yes	Whether a provider secret credential is stored. The value is write-only.
`sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Existing gateways that omit the field read as `both`. Allowed values: `both`, `on_session`, `off_session`.
`status`	string	Yes	Lifecycle state: draft, active, or inactive. Allowed values: `draft`, `active`, `inactive`.
`stripeMitExemptionApproved`	boolean	Yes	Operations approval for this Stripe account to quote a card-scheme transaction reference that another processor issued, using Stripe's merchant-initiated exemption on off-session charges. Stripe enables that parameter per account. Only Operations may set it.
`trafficSplitPercent`	integer or null	Yes	Relative share of new-card checkouts this gateway takes for its card processor, as a whole number from 0 to 100. When a buyer enters a new card, each card processor is represented by its best-matching gateway for the checkout, and the first attempt is divided between processors in proportion to the shares on those gateways. Shares are relative weights and need not total 100. A gateway with `0`, `null`, or no share takes no weighted traffic: it is used only when no competing gateway has a positive share, or as a failover when cascading is enabled on it. Saved-card, renewal, and direct API charges are not split. `null` when no share is set. Minimum: 0. Maximum: 100.
`updatedAt`	string (date-time)	Yes
`webhookSigningSecretConfigured`	boolean	Yes	Whether a webhook verification value is stored. The value is write-only.
`worldpayCapabilities`	object or null	Yes	Approved Worldpay merchant-code capabilities. `operations` lists `refund`, `capture` and `void` only while that operation has current, complete approval for this gateway environment.
`worldpayCapabilities.approvalReference`	string	Yes	Privacy-safe Operations approval reference. Maximum length: 255.
`worldpayCapabilities.approvedAt`	string (date-time)	Yes
`worldpayCapabilities.cardSchemes`	array of string	Yes	Optional Worldpay card-scheme names. Checkout does not match a card brand against this list; an empty list is allowed.
`worldpayCapabilities.countries`	array of string	Yes	Optional ISO 3166-1 alpha-2 names. Routing uses the gateway countries field for every provider; an empty list is allowed.
`worldpayCapabilities.currencies`	array of string	Yes	Explicit ISO 4217 currency allowlist; empty never means all. Minimum items: 1.
`worldpayCapabilities.expiresAt`	string (date-time)	Yes
`worldpayCapabilities.externalSchemeReferenceApproved`	boolean	No	Operations approval to quote a card-scheme transaction reference issued through another processor, recorded after a Secure Test exercise on this merchant code. Omission keeps it disabled.
`worldpayCapabilities.operations`	array of string	Yes	Allowed values: `purchase`, `authorization`, `capture`, `void`, `refund`, `status`, `order_inquiry`, `order_notifications`, `three_ds`, `stored_credentials`, `zero_value_verification`. Minimum items: 1.
`worldpayCapabilities.orderNotificationsCertified`	boolean	Yes
`worldpayCapabilities.pcivaultBinMetadataCertified`	boolean	Yes
`worldpayCapabilities.pcivaultProxyCertified`	boolean	Yes
`worldpayCapabilities.storedCredentialCustomerInitiatedReason`	string	No	Operations-approved Worldpay reason for buyer-present reuse. Omission keeps customer-initiated reuse disabled. Allowed values: `UNSCHEDULED`.
`worldpayCapabilities.storedCredentialMerchantInitiatedReasons`	array of string	No	Operations-approved merchant-initiated purposes. Omission keeps unattended reuse disabled. Allowed values: `RECURRING`, `UNSCHEDULED`. Minimum items: 1.
`worldpayCapabilities.storedCredentialsCertified`	boolean	Yes
`worldpayCapabilities.threeDsCallbackOrigins`	array of string	No	Exact https origins allowed for Worldpay Flex challenge and return callbacks.
`worldpayCapabilities.threeDsCertified`	boolean	Yes
`worldpayCapabilities.version`	number	Yes	Capability-record schema version. Allowed values: `1`.
`worldpayMerchantCode`	string or null	Yes	Worldpay merchant code, or null for other providers.
`worldpayThreeDsApiIdConfigured`	boolean	Yes	Whether the Worldpay 3DS API ID is stored. The value is write-only.
`worldpayThreeDsHmacKeyConfigured`	boolean	Yes	Whether the Worldpay 3DS HMAC key is stored. The value is write-only.
`worldpayThreeDsOrganizationUnitIdConfigured`	boolean	Yes	Whether the Worldpay 3DS organisation unit ID is stored. The value is write-only.
`worldpayXmlPasswordConfigured`	boolean	Yes	Whether the Worldpay XML machine password is stored. The value is write-only.
`worldpayXmlUsernameConfigured`	boolean	Yes	Whether the Worldpay XML machine username is stored. The value is write-only.

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	Members cannot manage gateway settings.
`404`	No such gateway for this client.
`409`	The gateway configuration is incomplete or duplicates another connection.
`422`	The provider rejected the stored credentials.

GatewaySettings_create

Create Gateway

Creates a gateway draft. A client can connect multiple distinct Stripe and PayPal accounts. When credentials are supplied they are validated with the provider before anything is persisted, and the canonical provider account identity is captured.

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

Arguments

Argument	In	Type	Required	Description
`cascadeEnabled`	body	boolean	No	Whether this gateway may receive a failover attempt after another of your gateways declines the same payment. When `false`, the gateway can still take a payment's first attempt but never a failover attempt. When creating a gateway, omitted values default to `false`. Default: `false`.
`countries`	body	array of string	No	ISO 3166-1 alpha-2 countries this gateway serves. Omit for no country preference. Minimum items: 1.
`currency`	body	string	Yes	ISO 4217 currency this gateway serves.
`environment`	body	string	Yes	Provider environment (stage = Stripe test mode / PayPal sandbox). Immutable once a provider connection has been validated: moving to production requires a new gateway. Allowed values: `stage`, `production`.
`name`	body	string	Yes	Display name for this gateway. Maximum length: 255.
`priority`	body	number	No	Routing priority (lower ranks first). Defaults to 0. Minimum: 0.
`providerType`	body	string	Yes	Payment provider. Immutable once a provider connection has been validated. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`publishableKey`	body	string	No	Provider public identifier: Stripe publishable key (pk_…) or PayPal REST-app client ID. Returned in read responses. Maximum length: 512.
`secretKey`	body	string	No	Provider secret credential: Stripe secret/restricted key (sk_…/rk_…) or PayPal client secret. Write-only: read responses expose configuration metadata, never the value. When supplied, the credentials are validated with the provider before anything is persisted. Maximum length: 512.
`sessionMode`	body	string	No	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Omitted values default to `both`. Allowed values: `both`, `on_session`, `off_session`.
`stripeMitExemptionApproved`	body	boolean	No	Operations approval for this Stripe account to quote a card-scheme transaction reference that another processor issued, using Stripe's merchant-initiated exemption on off-session charges. Stripe enables that parameter per account. Only Operations may set it. Omitted values default to `false` on create and keep the current value on update.
`trafficSplitPercent`	body	integer or null	No	Relative share of new-card checkouts this gateway takes for its card processor, as a whole number from 0 to 100. When a buyer enters a new card, each card processor is represented by its best-matching gateway for the checkout, and the first attempt is divided between processors in proportion to the shares on those gateways. Shares are relative weights and need not total 100. A gateway with `0`, `null`, or no share takes no weighted traffic: it is used only when no competing gateway has a positive share, or as a failover when cascading is enabled on it. Saved-card, renewal, and direct API charges are not split. When creating a gateway, an omitted share is stored as `null`. Minimum: 0. Maximum: 100.
`webhookSigningSecret`	body	string	No	Webhook verification value: Stripe webhook signing secret (whsec_…) or PayPal webhook ID. Write-only. Phase 1 webhook registration is manual in the provider dashboard. Maximum length: 512.
`worldpayCapabilities`	body	object	No
`worldpayCapabilities.approvalReference`	body	string	Yes	Privacy-safe Operations approval reference. Maximum length: 255.
`worldpayCapabilities.approvedAt`	body	string (date-time)	Yes
`worldpayCapabilities.cardSchemes`	body	array of string	Yes	Optional Worldpay card-scheme names. Checkout does not match a card brand against this list; an empty list is allowed.
`worldpayCapabilities.countries`	body	array of string	Yes	Optional ISO 3166-1 alpha-2 names. Routing uses the gateway countries field for every provider; an empty list is allowed.
`worldpayCapabilities.currencies`	body	array of string	Yes	Explicit ISO 4217 currency allowlist; empty never means all. Minimum items: 1.
`worldpayCapabilities.expiresAt`	body	string (date-time)	Yes
`worldpayCapabilities.externalSchemeReferenceApproved`	body	boolean	No	Operations approval to quote a card-scheme transaction reference issued through another processor, recorded after a Secure Test exercise on this merchant code. Omission keeps it disabled.
`worldpayCapabilities.operations`	body	array of string	Yes	Allowed values: `purchase`, `authorization`, `capture`, `void`, `refund`, `status`, `order_inquiry`, `order_notifications`, `three_ds`, `stored_credentials`, `zero_value_verification`. Minimum items: 1.
`worldpayCapabilities.orderNotificationsCertified`	body	boolean	Yes
`worldpayCapabilities.pcivaultBinMetadataCertified`	body	boolean	Yes
`worldpayCapabilities.pcivaultProxyCertified`	body	boolean	Yes
`worldpayCapabilities.storedCredentialCustomerInitiatedReason`	body	string	No	Operations-approved Worldpay reason for buyer-present reuse. Omission keeps customer-initiated reuse disabled. Allowed values: `UNSCHEDULED`.
`worldpayCapabilities.storedCredentialMerchantInitiatedReasons`	body	array of string	No	Operations-approved merchant-initiated purposes. Omission keeps unattended reuse disabled. Allowed values: `RECURRING`, `UNSCHEDULED`. Minimum items: 1.
`worldpayCapabilities.storedCredentialsCertified`	body	boolean	Yes
`worldpayCapabilities.threeDsCallbackOrigins`	body	array of string	No	Exact https origins allowed for Worldpay Flex challenge and return callbacks.
`worldpayCapabilities.threeDsCertified`	body	boolean	Yes
`worldpayCapabilities.version`	body	number	Yes	Capability-record schema version. Allowed values: `1`.
`worldpayMerchantCode`	body	string	No	Worldpay merchant code. This is the only readable Worldpay account value. Maximum length: 255.
`worldpayThreeDsApiId`	body	string	No	Worldpay 3DS Flex API ID. Write-only. Maximum length: 512.
`worldpayThreeDsHmacKey`	body	string	No	Worldpay 3DS Flex HMAC key. Write-only. Maximum length: 512.
`worldpayThreeDsOrganizationUnitId`	body	string	No	Worldpay 3DS Flex organisation unit ID. Write-only. Maximum length: 512.
`worldpayXmlPassword`	body	string	No	Worldpay XML machine password. Write-only. Maximum length: 512.
`worldpayXmlUsername`	body	string	No	Worldpay XML machine username. Write-only. Maximum length: 512.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`cascadeEnabled`	boolean	Yes	Whether this gateway may receive a failover attempt after another of your gateways declines the same payment. When `false`, the gateway can still take a payment's first attempt but never a failover attempt.
`clientId`	string	Yes	The owning client UUID.
`code`	string	Yes	Flopay-owned unique gateway code (webhook account-code hint).
`connectionValidatedAt`	string (date-time) or null	Yes	When the provider last confirmed the stored credentials. Null for unconnected drafts.
`countries`	array of string or null	Yes	ISO 3166-1 alpha-2 countries, or null.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO 4217 currency this gateway serves.
`environment`	string	Yes	Allowed values: `stage`, `production`.
`id`	string	Yes	The gateway UUID.
`name`	string	Yes	Display name.
`priority`	number	Yes	Routing priority (lower ranks first).
`providerAccountId`	string or null	Yes	Canonical provider account identity captured at validation (Stripe acct_…, PayPal REST-app client ID). Null until the connection has been validated.
`providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`publishableKey`	string or null	Yes	Provider public identifier (Stripe publishable key / PayPal client ID).
`secretKeyConfigured`	boolean	Yes	Whether a provider secret credential is stored. The value is write-only.
`sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Existing gateways that omit the field read as `both`. Allowed values: `both`, `on_session`, `off_session`.
`status`	string	Yes	Lifecycle state: draft, active, or inactive. Allowed values: `draft`, `active`, `inactive`.
`stripeMitExemptionApproved`	boolean	Yes	Operations approval for this Stripe account to quote a card-scheme transaction reference that another processor issued, using Stripe's merchant-initiated exemption on off-session charges. Stripe enables that parameter per account. Only Operations may set it.
`trafficSplitPercent`	integer or null	Yes	Relative share of new-card checkouts this gateway takes for its card processor, as a whole number from 0 to 100. When a buyer enters a new card, each card processor is represented by its best-matching gateway for the checkout, and the first attempt is divided between processors in proportion to the shares on those gateways. Shares are relative weights and need not total 100. A gateway with `0`, `null`, or no share takes no weighted traffic: it is used only when no competing gateway has a positive share, or as a failover when cascading is enabled on it. Saved-card, renewal, and direct API charges are not split. `null` when no share is set. Minimum: 0. Maximum: 100.
`updatedAt`	string (date-time)	Yes
`webhookSigningSecretConfigured`	boolean	Yes	Whether a webhook verification value is stored. The value is write-only.
`worldpayCapabilities`	object or null	Yes	Approved Worldpay merchant-code capabilities. `operations` lists `refund`, `capture` and `void` only while that operation has current, complete approval for this gateway environment.
`worldpayCapabilities.approvalReference`	string	Yes	Privacy-safe Operations approval reference. Maximum length: 255.
`worldpayCapabilities.approvedAt`	string (date-time)	Yes
`worldpayCapabilities.cardSchemes`	array of string	Yes	Optional Worldpay card-scheme names. Checkout does not match a card brand against this list; an empty list is allowed.
`worldpayCapabilities.countries`	array of string	Yes	Optional ISO 3166-1 alpha-2 names. Routing uses the gateway countries field for every provider; an empty list is allowed.
`worldpayCapabilities.currencies`	array of string	Yes	Explicit ISO 4217 currency allowlist; empty never means all. Minimum items: 1.
`worldpayCapabilities.expiresAt`	string (date-time)	Yes
`worldpayCapabilities.externalSchemeReferenceApproved`	boolean	No	Operations approval to quote a card-scheme transaction reference issued through another processor, recorded after a Secure Test exercise on this merchant code. Omission keeps it disabled.
`worldpayCapabilities.operations`	array of string	Yes	Allowed values: `purchase`, `authorization`, `capture`, `void`, `refund`, `status`, `order_inquiry`, `order_notifications`, `three_ds`, `stored_credentials`, `zero_value_verification`. Minimum items: 1.
`worldpayCapabilities.orderNotificationsCertified`	boolean	Yes
`worldpayCapabilities.pcivaultBinMetadataCertified`	boolean	Yes
`worldpayCapabilities.pcivaultProxyCertified`	boolean	Yes
`worldpayCapabilities.storedCredentialCustomerInitiatedReason`	string	No	Operations-approved Worldpay reason for buyer-present reuse. Omission keeps customer-initiated reuse disabled. Allowed values: `UNSCHEDULED`.
`worldpayCapabilities.storedCredentialMerchantInitiatedReasons`	array of string	No	Operations-approved merchant-initiated purposes. Omission keeps unattended reuse disabled. Allowed values: `RECURRING`, `UNSCHEDULED`. Minimum items: 1.
`worldpayCapabilities.storedCredentialsCertified`	boolean	Yes
`worldpayCapabilities.threeDsCallbackOrigins`	array of string	No	Exact https origins allowed for Worldpay Flex challenge and return callbacks.
`worldpayCapabilities.threeDsCertified`	boolean	Yes
`worldpayCapabilities.version`	number	Yes	Capability-record schema version. Allowed values: `1`.
`worldpayMerchantCode`	string or null	Yes	Worldpay merchant code, or null for other providers.
`worldpayThreeDsApiIdConfigured`	boolean	Yes	Whether the Worldpay 3DS API ID is stored. The value is write-only.
`worldpayThreeDsHmacKeyConfigured`	boolean	Yes	Whether the Worldpay 3DS HMAC key is stored. The value is write-only.
`worldpayThreeDsOrganizationUnitIdConfigured`	boolean	Yes	Whether the Worldpay 3DS organisation unit ID is stored. The value is write-only.
`worldpayXmlPasswordConfigured`	boolean	Yes	Whether the Worldpay XML machine password is stored. The value is write-only.
`worldpayXmlUsernameConfigured`	boolean	Yes	Whether the Worldpay XML machine username is stored. The value is write-only.

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	Members cannot manage gateway settings.
`409`	The provider account is already connected in this environment.
`422`	The provider rejected the supplied credentials.

GatewaySettings_deactivate

Deactivate Gateway

Deactivates an active gateway. The record is retained and can be reactivated.

Policy	Value
Operation	`POST /v1/settings/gateways/{id}/deactivate`
Class	`mutating`
Risk	`critical`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The gateway id.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`cascadeEnabled`	boolean	Yes	Whether this gateway may receive a failover attempt after another of your gateways declines the same payment. When `false`, the gateway can still take a payment's first attempt but never a failover attempt.
`clientId`	string	Yes	The owning client UUID.
`code`	string	Yes	Flopay-owned unique gateway code (webhook account-code hint).
`connectionValidatedAt`	string (date-time) or null	Yes	When the provider last confirmed the stored credentials. Null for unconnected drafts.
`countries`	array of string or null	Yes	ISO 3166-1 alpha-2 countries, or null.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO 4217 currency this gateway serves.
`environment`	string	Yes	Allowed values: `stage`, `production`.
`id`	string	Yes	The gateway UUID.
`name`	string	Yes	Display name.
`priority`	number	Yes	Routing priority (lower ranks first).
`providerAccountId`	string or null	Yes	Canonical provider account identity captured at validation (Stripe acct_…, PayPal REST-app client ID). Null until the connection has been validated.
`providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`publishableKey`	string or null	Yes	Provider public identifier (Stripe publishable key / PayPal client ID).
`secretKeyConfigured`	boolean	Yes	Whether a provider secret credential is stored. The value is write-only.
`sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Existing gateways that omit the field read as `both`. Allowed values: `both`, `on_session`, `off_session`.
`status`	string	Yes	Lifecycle state: draft, active, or inactive. Allowed values: `draft`, `active`, `inactive`.
`stripeMitExemptionApproved`	boolean	Yes	Operations approval for this Stripe account to quote a card-scheme transaction reference that another processor issued, using Stripe's merchant-initiated exemption on off-session charges. Stripe enables that parameter per account. Only Operations may set it.
`trafficSplitPercent`	integer or null	Yes	Relative share of new-card checkouts this gateway takes for its card processor, as a whole number from 0 to 100. When a buyer enters a new card, each card processor is represented by its best-matching gateway for the checkout, and the first attempt is divided between processors in proportion to the shares on those gateways. Shares are relative weights and need not total 100. A gateway with `0`, `null`, or no share takes no weighted traffic: it is used only when no competing gateway has a positive share, or as a failover when cascading is enabled on it. Saved-card, renewal, and direct API charges are not split. `null` when no share is set. Minimum: 0. Maximum: 100.
`updatedAt`	string (date-time)	Yes
`webhookSigningSecretConfigured`	boolean	Yes	Whether a webhook verification value is stored. The value is write-only.
`worldpayCapabilities`	object or null	Yes	Approved Worldpay merchant-code capabilities. `operations` lists `refund`, `capture` and `void` only while that operation has current, complete approval for this gateway environment.
`worldpayCapabilities.approvalReference`	string	Yes	Privacy-safe Operations approval reference. Maximum length: 255.
`worldpayCapabilities.approvedAt`	string (date-time)	Yes
`worldpayCapabilities.cardSchemes`	array of string	Yes	Optional Worldpay card-scheme names. Checkout does not match a card brand against this list; an empty list is allowed.
`worldpayCapabilities.countries`	array of string	Yes	Optional ISO 3166-1 alpha-2 names. Routing uses the gateway countries field for every provider; an empty list is allowed.
`worldpayCapabilities.currencies`	array of string	Yes	Explicit ISO 4217 currency allowlist; empty never means all. Minimum items: 1.
`worldpayCapabilities.expiresAt`	string (date-time)	Yes
`worldpayCapabilities.externalSchemeReferenceApproved`	boolean	No	Operations approval to quote a card-scheme transaction reference issued through another processor, recorded after a Secure Test exercise on this merchant code. Omission keeps it disabled.
`worldpayCapabilities.operations`	array of string	Yes	Allowed values: `purchase`, `authorization`, `capture`, `void`, `refund`, `status`, `order_inquiry`, `order_notifications`, `three_ds`, `stored_credentials`, `zero_value_verification`. Minimum items: 1.
`worldpayCapabilities.orderNotificationsCertified`	boolean	Yes
`worldpayCapabilities.pcivaultBinMetadataCertified`	boolean	Yes
`worldpayCapabilities.pcivaultProxyCertified`	boolean	Yes
`worldpayCapabilities.storedCredentialCustomerInitiatedReason`	string	No	Operations-approved Worldpay reason for buyer-present reuse. Omission keeps customer-initiated reuse disabled. Allowed values: `UNSCHEDULED`.
`worldpayCapabilities.storedCredentialMerchantInitiatedReasons`	array of string	No	Operations-approved merchant-initiated purposes. Omission keeps unattended reuse disabled. Allowed values: `RECURRING`, `UNSCHEDULED`. Minimum items: 1.
`worldpayCapabilities.storedCredentialsCertified`	boolean	Yes
`worldpayCapabilities.threeDsCallbackOrigins`	array of string	No	Exact https origins allowed for Worldpay Flex challenge and return callbacks.
`worldpayCapabilities.threeDsCertified`	boolean	Yes
`worldpayCapabilities.version`	number	Yes	Capability-record schema version. Allowed values: `1`.
`worldpayMerchantCode`	string or null	Yes	Worldpay merchant code, or null for other providers.
`worldpayThreeDsApiIdConfigured`	boolean	Yes	Whether the Worldpay 3DS API ID is stored. The value is write-only.
`worldpayThreeDsHmacKeyConfigured`	boolean	Yes	Whether the Worldpay 3DS HMAC key is stored. The value is write-only.
`worldpayThreeDsOrganizationUnitIdConfigured`	boolean	Yes	Whether the Worldpay 3DS organisation unit ID is stored. The value is write-only.
`worldpayXmlPasswordConfigured`	boolean	Yes	Whether the Worldpay XML machine password is stored. The value is write-only.
`worldpayXmlUsernameConfigured`	boolean	Yes	Whether the Worldpay XML machine username is stored. The value is write-only.

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	Members cannot manage gateway settings.
`404`	No such gateway for this client.
`409`	Only an active gateway can be deactivated.

GatewaySettings_get

Get Gateway

Returns a single gateway owned by the authenticated client.

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

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The gateway id.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`cascadeEnabled`	boolean	Yes	Whether this gateway may receive a failover attempt after another of your gateways declines the same payment. When `false`, the gateway can still take a payment's first attempt but never a failover attempt.
`clientId`	string	Yes	The owning client UUID.
`code`	string	Yes	Flopay-owned unique gateway code (webhook account-code hint).
`connectionValidatedAt`	string (date-time) or null	Yes	When the provider last confirmed the stored credentials. Null for unconnected drafts.
`countries`	array of string or null	Yes	ISO 3166-1 alpha-2 countries, or null.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO 4217 currency this gateway serves.
`environment`	string	Yes	Allowed values: `stage`, `production`.
`id`	string	Yes	The gateway UUID.
`name`	string	Yes	Display name.
`priority`	number	Yes	Routing priority (lower ranks first).
`providerAccountId`	string or null	Yes	Canonical provider account identity captured at validation (Stripe acct_…, PayPal REST-app client ID). Null until the connection has been validated.
`providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`publishableKey`	string or null	Yes	Provider public identifier (Stripe publishable key / PayPal client ID).
`secretKeyConfigured`	boolean	Yes	Whether a provider secret credential is stored. The value is write-only.
`sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Existing gateways that omit the field read as `both`. Allowed values: `both`, `on_session`, `off_session`.
`status`	string	Yes	Lifecycle state: draft, active, or inactive. Allowed values: `draft`, `active`, `inactive`.
`stripeMitExemptionApproved`	boolean	Yes	Operations approval for this Stripe account to quote a card-scheme transaction reference that another processor issued, using Stripe's merchant-initiated exemption on off-session charges. Stripe enables that parameter per account. Only Operations may set it.
`trafficSplitPercent`	integer or null	Yes	Relative share of new-card checkouts this gateway takes for its card processor, as a whole number from 0 to 100. When a buyer enters a new card, each card processor is represented by its best-matching gateway for the checkout, and the first attempt is divided between processors in proportion to the shares on those gateways. Shares are relative weights and need not total 100. A gateway with `0`, `null`, or no share takes no weighted traffic: it is used only when no competing gateway has a positive share, or as a failover when cascading is enabled on it. Saved-card, renewal, and direct API charges are not split. `null` when no share is set. Minimum: 0. Maximum: 100.
`updatedAt`	string (date-time)	Yes
`webhookSigningSecretConfigured`	boolean	Yes	Whether a webhook verification value is stored. The value is write-only.
`worldpayCapabilities`	object or null	Yes	Approved Worldpay merchant-code capabilities. `operations` lists `refund`, `capture` and `void` only while that operation has current, complete approval for this gateway environment.
`worldpayCapabilities.approvalReference`	string	Yes	Privacy-safe Operations approval reference. Maximum length: 255.
`worldpayCapabilities.approvedAt`	string (date-time)	Yes
`worldpayCapabilities.cardSchemes`	array of string	Yes	Optional Worldpay card-scheme names. Checkout does not match a card brand against this list; an empty list is allowed.
`worldpayCapabilities.countries`	array of string	Yes	Optional ISO 3166-1 alpha-2 names. Routing uses the gateway countries field for every provider; an empty list is allowed.
`worldpayCapabilities.currencies`	array of string	Yes	Explicit ISO 4217 currency allowlist; empty never means all. Minimum items: 1.
`worldpayCapabilities.expiresAt`	string (date-time)	Yes
`worldpayCapabilities.externalSchemeReferenceApproved`	boolean	No	Operations approval to quote a card-scheme transaction reference issued through another processor, recorded after a Secure Test exercise on this merchant code. Omission keeps it disabled.
`worldpayCapabilities.operations`	array of string	Yes	Allowed values: `purchase`, `authorization`, `capture`, `void`, `refund`, `status`, `order_inquiry`, `order_notifications`, `three_ds`, `stored_credentials`, `zero_value_verification`. Minimum items: 1.
`worldpayCapabilities.orderNotificationsCertified`	boolean	Yes
`worldpayCapabilities.pcivaultBinMetadataCertified`	boolean	Yes
`worldpayCapabilities.pcivaultProxyCertified`	boolean	Yes
`worldpayCapabilities.storedCredentialCustomerInitiatedReason`	string	No	Operations-approved Worldpay reason for buyer-present reuse. Omission keeps customer-initiated reuse disabled. Allowed values: `UNSCHEDULED`.
`worldpayCapabilities.storedCredentialMerchantInitiatedReasons`	array of string	No	Operations-approved merchant-initiated purposes. Omission keeps unattended reuse disabled. Allowed values: `RECURRING`, `UNSCHEDULED`. Minimum items: 1.
`worldpayCapabilities.storedCredentialsCertified`	boolean	Yes
`worldpayCapabilities.threeDsCallbackOrigins`	array of string	No	Exact https origins allowed for Worldpay Flex challenge and return callbacks.
`worldpayCapabilities.threeDsCertified`	boolean	Yes
`worldpayCapabilities.version`	number	Yes	Capability-record schema version. Allowed values: `1`.
`worldpayMerchantCode`	string or null	Yes	Worldpay merchant code, or null for other providers.
`worldpayThreeDsApiIdConfigured`	boolean	Yes	Whether the Worldpay 3DS API ID is stored. The value is write-only.
`worldpayThreeDsHmacKeyConfigured`	boolean	Yes	Whether the Worldpay 3DS HMAC key is stored. The value is write-only.
`worldpayThreeDsOrganizationUnitIdConfigured`	boolean	Yes	Whether the Worldpay 3DS organisation unit ID is stored. The value is write-only.
`worldpayXmlPasswordConfigured`	boolean	Yes	Whether the Worldpay XML machine password is stored. The value is write-only.
`worldpayXmlUsernameConfigured`	boolean	Yes	Whether the Worldpay XML machine username is stored. The value is write-only.

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	Members cannot manage gateway settings.
`404`	No such gateway for this client.

GatewaySettings_list

List Gateways

Returns a page of payment gateways owned by the authenticated client (drafts, active, and inactive) in the shared { data, page, limit, pages, total } list envelope, with the shared filter, sort, and paging parameters. Secret credentials and webhook verification values are write-only and surface as configuration flags.

Policy	Value
Operation	`GET /v1/settings/gateways`
Class	`read-only`
Risk	`low`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`read`
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: `id`, `cascadeEnabled`, `code`, `connectionValidatedAt`, `createdAt`, `currency`, `environment`, `isActive`, `name`, `priority`, `providerType`, `sessionMode`, `status`, `trafficSplitPercent`, `updatedAt`. Default: `createdAt` ASC. Allowed values: `id`, `cascadeEnabled`, `code`, `connectionValidatedAt`, `createdAt`, `currency`, `environment`, `isActive`, `name`, `priority`, `providerType`, `sessionMode`, `status`, `trafficSplitPercent`, `updatedAt`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`cascadeEnabled`	query	string	No	Whether the gateway may receive failover attempts after another gateway declines the same payment. Equality filter. Pass without operator for exact match. Allowed values: `true`, `false`.
`code`	query	string	No	Flopay-owned unique gateway code. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]` `[search]`. `[in]` accepts comma-separated values; blank entries return 400. `[search]` is case-insensitive text contains matching.
`connectionValidatedAt`	query	string (date-time)	No	When the provider last confirmed the stored credentials. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`createdAt`	query	string (date-time)	No	Gateway creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`currency`	query	string	No	Uppercase ISO 4217 currency this gateway serves. 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.
`environment`	query	string	No	Provider environment the gateway connects to. 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: `stage`, `production`.
`id`	query	string (uuid)	No	Gateway id. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400.
`isActive`	query	string	No	Whether the gateway is available for runtime routing. Equality filter. Pass without operator for exact match. Allowed values: `true`, `false`.
`name`	query	string	No	Gateway display name. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`priority`	query	number	No	Routing priority (lower ranks first). Equality filter. Pass without operator for exact match or pass any of the following operators: `[gte]` `[lte]`.
`providerAccountId`	query	string	No	Canonical provider account identity captured at credential validation. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]` `[search]`. `[in]` accepts comma-separated values; blank entries return 400. `[search]` is case-insensitive text contains matching.
`sessionMode`	query	string	No	Whether the gateway may serve buyer-present payments, merchant-initiated payments, or both. 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: `both`, `on_session`, `off_session`.
`providerType`	query	string	No	Payment provider backing the gateway. 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	Gateway lifecycle state: draft, active, or inactive. 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: `draft`, `active`, `inactive`.
`trafficSplitPercent`	query	number	No	Relative share of new-card checkouts the gateway takes for its card processor. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`updatedAt`	query	string (date-time)	No	Gateway update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`data`	array of object	Yes
`data[].cascadeEnabled`	boolean	Yes	Whether this gateway may receive a failover attempt after another of your gateways declines the same payment. When `false`, the gateway can still take a payment's first attempt but never a failover attempt.
`data[].clientId`	string	Yes	The owning client UUID.
`data[].code`	string	Yes	Flopay-owned unique gateway code (webhook account-code hint).
`data[].connectionValidatedAt`	string (date-time) or null	Yes	When the provider last confirmed the stored credentials. Null for unconnected drafts.
`data[].countries`	array of string or null	Yes	ISO 3166-1 alpha-2 countries, or null.
`data[].createdAt`	string (date-time)	Yes
`data[].currency`	string	Yes	ISO 4217 currency this gateway serves.
`data[].environment`	string	Yes	Allowed values: `stage`, `production`.
`data[].id`	string	Yes	The gateway UUID.
`data[].name`	string	Yes	Display name.
`data[].priority`	number	Yes	Routing priority (lower ranks first).
`data[].providerAccountId`	string or null	Yes	Canonical provider account identity captured at validation (Stripe acct_…, PayPal REST-app client ID). Null until the connection has been validated.
`data[].providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`data[].publishableKey`	string or null	Yes	Provider public identifier (Stripe publishable key / PayPal client ID).
`data[].secretKeyConfigured`	boolean	Yes	Whether a provider secret credential is stored. The value is write-only.
`data[].sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Existing gateways that omit the field read as `both`. Allowed values: `both`, `on_session`, `off_session`.
`data[].status`	string	Yes	Lifecycle state: draft, active, or inactive. Allowed values: `draft`, `active`, `inactive`.
`data[].stripeMitExemptionApproved`	boolean	Yes	Operations approval for this Stripe account to quote a card-scheme transaction reference that another processor issued, using Stripe's merchant-initiated exemption on off-session charges. Stripe enables that parameter per account. Only Operations may set it.
`data[].trafficSplitPercent`	integer or null	Yes	Relative share of new-card checkouts this gateway takes for its card processor, as a whole number from 0 to 100. When a buyer enters a new card, each card processor is represented by its best-matching gateway for the checkout, and the first attempt is divided between processors in proportion to the shares on those gateways. Shares are relative weights and need not total 100. A gateway with `0`, `null`, or no share takes no weighted traffic: it is used only when no competing gateway has a positive share, or as a failover when cascading is enabled on it. Saved-card, renewal, and direct API charges are not split. `null` when no share is set. Minimum: 0. Maximum: 100.
`data[].updatedAt`	string (date-time)	Yes
`data[].webhookSigningSecretConfigured`	boolean	Yes	Whether a webhook verification value is stored. The value is write-only.
`data[].worldpayCapabilities`	object or null	Yes	Approved Worldpay merchant-code capabilities. `operations` lists `refund`, `capture` and `void` only while that operation has current, complete approval for this gateway environment.
`data[].worldpayCapabilities.approvalReference`	string	Yes	Privacy-safe Operations approval reference. Maximum length: 255.
`data[].worldpayCapabilities.approvedAt`	string (date-time)	Yes
`data[].worldpayCapabilities.cardSchemes`	array of string	Yes	Optional Worldpay card-scheme names. Checkout does not match a card brand against this list; an empty list is allowed.
`data[].worldpayCapabilities.countries`	array of string	Yes	Optional ISO 3166-1 alpha-2 names. Routing uses the gateway countries field for every provider; an empty list is allowed.
`data[].worldpayCapabilities.currencies`	array of string	Yes	Explicit ISO 4217 currency allowlist; empty never means all. Minimum items: 1.
`data[].worldpayCapabilities.expiresAt`	string (date-time)	Yes
`data[].worldpayCapabilities.externalSchemeReferenceApproved`	boolean	No	Operations approval to quote a card-scheme transaction reference issued through another processor, recorded after a Secure Test exercise on this merchant code. Omission keeps it disabled.
`data[].worldpayCapabilities.operations`	array of string	Yes	Allowed values: `purchase`, `authorization`, `capture`, `void`, `refund`, `status`, `order_inquiry`, `order_notifications`, `three_ds`, `stored_credentials`, `zero_value_verification`. Minimum items: 1.
`data[].worldpayCapabilities.orderNotificationsCertified`	boolean	Yes
`data[].worldpayCapabilities.pcivaultBinMetadataCertified`	boolean	Yes
`data[].worldpayCapabilities.pcivaultProxyCertified`	boolean	Yes
`data[].worldpayCapabilities.storedCredentialCustomerInitiatedReason`	string	No	Operations-approved Worldpay reason for buyer-present reuse. Omission keeps customer-initiated reuse disabled. Allowed values: `UNSCHEDULED`.
`data[].worldpayCapabilities.storedCredentialMerchantInitiatedReasons`	array of string	No	Operations-approved merchant-initiated purposes. Omission keeps unattended reuse disabled. Allowed values: `RECURRING`, `UNSCHEDULED`. Minimum items: 1.
`data[].worldpayCapabilities.storedCredentialsCertified`	boolean	Yes
`data[].worldpayCapabilities.threeDsCallbackOrigins`	array of string	No	Exact https origins allowed for Worldpay Flex challenge and return callbacks.
`data[].worldpayCapabilities.threeDsCertified`	boolean	Yes
`data[].worldpayCapabilities.version`	number	Yes	Capability-record schema version. Allowed values: `1`.
`data[].worldpayMerchantCode`	string or null	Yes	Worldpay merchant code, or null for other providers.
`data[].worldpayThreeDsApiIdConfigured`	boolean	Yes	Whether the Worldpay 3DS API ID is stored. The value is write-only.
`data[].worldpayThreeDsHmacKeyConfigured`	boolean	Yes	Whether the Worldpay 3DS HMAC key is stored. The value is write-only.
`data[].worldpayThreeDsOrganizationUnitIdConfigured`	boolean	Yes	Whether the Worldpay 3DS organisation unit ID is stored. The value is write-only.
`data[].worldpayXmlPasswordConfigured`	boolean	Yes	Whether the Worldpay XML machine password is stored. The value is write-only.
`data[].worldpayXmlUsernameConfigured`	boolean	Yes	Whether the Worldpay XML machine username is stored. The value is write-only.
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	Members cannot manage gateway settings.

GatewaySettings_test

Test Gateway Connection

Probes the provider with the stored credentials without mutating the gateway. Returns a sanitized success or error result.

Policy	Value
Operation	`POST /v1/settings/gateways/{id}/test`
Class	`read-only`
Risk	`medium`
Confirmation	`not-required`
Retry	`safe`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`
Scopes	`mcp:read`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The gateway id.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`error`	string or null	Yes	Sanitized, actionable failure summary.
`providerAccountId`	string or null	Yes	Canonical provider account identity the probe observed (not persisted by the probe).
`success`	boolean	Yes	Whether the provider accepted the stored credentials.

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	Members cannot manage gateway settings.
`404`	No such gateway for this client.

GatewaySettings_update

Update Gateway

Updates Flopay-owned gateway settings. Omitted credential fields keep their stored values; a credential-bearing update validates the complete resulting credential set with the provider before persisting: on failure the stored configuration is preserved. Provider and environment are editable only while the gateway is an unconnected draft.

Policy	Value
Operation	`PATCH /v1/settings/gateways/{id}`
Class	`mutating`
Risk	`critical`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The gateway id.
`cascadeEnabled`	body	boolean	No	Whether this gateway may receive a failover attempt after another of your gateways declines the same payment. When `false`, the gateway can still take a payment's first attempt but never a failover attempt. Omit this field to preserve the current value.
`countries`	body	array of string	No	ISO 3166-1 alpha-2 countries this gateway serves. Omit for no country preference. Minimum items: 1.
`currency`	body	string	No	ISO 4217 currency this gateway serves.
`environment`	body	string	No	Provider environment (stage = Stripe test mode / PayPal sandbox). Immutable once a provider connection has been validated: moving to production requires a new gateway. Allowed values: `stage`, `production`.
`name`	body	string	No	Display name for this gateway. Maximum length: 255.
`priority`	body	number	No	Routing priority (lower ranks first). Defaults to 0. Minimum: 0.
`providerType`	body	string	No	Payment provider. Immutable once a provider connection has been validated. Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`publishableKey`	body	string	No	Provider public identifier: Stripe publishable key (pk_…) or PayPal REST-app client ID. Returned in read responses. Maximum length: 512.
`secretKey`	body	string	No	Provider secret credential: Stripe secret/restricted key (sk_…/rk_…) or PayPal client secret. Write-only: read responses expose configuration metadata, never the value. When supplied, the credentials are validated with the provider before anything is persisted. Maximum length: 512.
`sessionMode`	body	string	No	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Omitted values default to `both`. Allowed values: `both`, `on_session`, `off_session`.
`stripeMitExemptionApproved`	body	boolean	No	Operations approval for this Stripe account to quote a card-scheme transaction reference that another processor issued, using Stripe's merchant-initiated exemption on off-session charges. Stripe enables that parameter per account. Only Operations may set it. Omitted values default to `false` on create and keep the current value on update.
`trafficSplitPercent`	body	integer or null	No	Relative share of new-card checkouts this gateway takes for its card processor, as a whole number from 0 to 100. When a buyer enters a new card, each card processor is represented by its best-matching gateway for the checkout, and the first attempt is divided between processors in proportion to the shares on those gateways. Shares are relative weights and need not total 100. A gateway with `0`, `null`, or no share takes no weighted traffic: it is used only when no competing gateway has a positive share, or as a failover when cascading is enabled on it. Saved-card, renewal, and direct API charges are not split. Omit this field to keep the current value; send `null` to clear it. Minimum: 0. Maximum: 100.
`webhookSigningSecret`	body	string	No	Webhook verification value: Stripe webhook signing secret (whsec_…) or PayPal webhook ID. Write-only. Phase 1 webhook registration is manual in the provider dashboard. Maximum length: 512.
`worldpayCapabilities`	body	object	No
`worldpayCapabilities.approvalReference`	body	string	Yes	Privacy-safe Operations approval reference. Maximum length: 255.
`worldpayCapabilities.approvedAt`	body	string (date-time)	Yes
`worldpayCapabilities.cardSchemes`	body	array of string	Yes	Optional Worldpay card-scheme names. Checkout does not match a card brand against this list; an empty list is allowed.
`worldpayCapabilities.countries`	body	array of string	Yes	Optional ISO 3166-1 alpha-2 names. Routing uses the gateway countries field for every provider; an empty list is allowed.
`worldpayCapabilities.currencies`	body	array of string	Yes	Explicit ISO 4217 currency allowlist; empty never means all. Minimum items: 1.
`worldpayCapabilities.expiresAt`	body	string (date-time)	Yes
`worldpayCapabilities.externalSchemeReferenceApproved`	body	boolean	No	Operations approval to quote a card-scheme transaction reference issued through another processor, recorded after a Secure Test exercise on this merchant code. Omission keeps it disabled.
`worldpayCapabilities.operations`	body	array of string	Yes	Allowed values: `purchase`, `authorization`, `capture`, `void`, `refund`, `status`, `order_inquiry`, `order_notifications`, `three_ds`, `stored_credentials`, `zero_value_verification`. Minimum items: 1.
`worldpayCapabilities.orderNotificationsCertified`	body	boolean	Yes
`worldpayCapabilities.pcivaultBinMetadataCertified`	body	boolean	Yes
`worldpayCapabilities.pcivaultProxyCertified`	body	boolean	Yes
`worldpayCapabilities.storedCredentialCustomerInitiatedReason`	body	string	No	Operations-approved Worldpay reason for buyer-present reuse. Omission keeps customer-initiated reuse disabled. Allowed values: `UNSCHEDULED`.
`worldpayCapabilities.storedCredentialMerchantInitiatedReasons`	body	array of string	No	Operations-approved merchant-initiated purposes. Omission keeps unattended reuse disabled. Allowed values: `RECURRING`, `UNSCHEDULED`. Minimum items: 1.
`worldpayCapabilities.storedCredentialsCertified`	body	boolean	Yes
`worldpayCapabilities.threeDsCallbackOrigins`	body	array of string	No	Exact https origins allowed for Worldpay Flex challenge and return callbacks.
`worldpayCapabilities.threeDsCertified`	body	boolean	Yes
`worldpayCapabilities.version`	body	number	Yes	Capability-record schema version. Allowed values: `1`.
`worldpayMerchantCode`	body	string	No	Worldpay merchant code. This is the only readable Worldpay account value. Maximum length: 255.
`worldpayThreeDsApiId`	body	string	No	Worldpay 3DS Flex API ID. Write-only. Maximum length: 512.
`worldpayThreeDsHmacKey`	body	string	No	Worldpay 3DS Flex HMAC key. Write-only. Maximum length: 512.
`worldpayThreeDsOrganizationUnitId`	body	string	No	Worldpay 3DS Flex organisation unit ID. Write-only. Maximum length: 512.
`worldpayXmlPassword`	body	string	No	Worldpay XML machine password. Write-only. Maximum length: 512.
`worldpayXmlUsername`	body	string	No	Worldpay XML machine username. Write-only. Maximum length: 512.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`cascadeEnabled`	boolean	Yes	Whether this gateway may receive a failover attempt after another of your gateways declines the same payment. When `false`, the gateway can still take a payment's first attempt but never a failover attempt.
`clientId`	string	Yes	The owning client UUID.
`code`	string	Yes	Flopay-owned unique gateway code (webhook account-code hint).
`connectionValidatedAt`	string (date-time) or null	Yes	When the provider last confirmed the stored credentials. Null for unconnected drafts.
`countries`	array of string or null	Yes	ISO 3166-1 alpha-2 countries, or null.
`createdAt`	string (date-time)	Yes
`currency`	string	Yes	ISO 4217 currency this gateway serves.
`environment`	string	Yes	Allowed values: `stage`, `production`.
`id`	string	Yes	The gateway UUID.
`name`	string	Yes	Display name.
`priority`	number	Yes	Routing priority (lower ranks first).
`providerAccountId`	string or null	Yes	Canonical provider account identity captured at validation (Stripe acct_…, PayPal REST-app client ID). Null until the connection has been validated.
`providerType`	string	Yes	Allowed values: `stripe`, `paypal`, `worldpay_corporate_gateway`.
`publishableKey`	string or null	Yes	Provider public identifier (Stripe publishable key / PayPal client ID).
`secretKeyConfigured`	boolean	Yes	Whether a provider secret credential is stored. The value is write-only.
`sessionMode`	string	Yes	Whether this gateway may serve buyer-present payments (`on_session`), merchant-initiated payments (`off_session`), or both. Existing gateways that omit the field read as `both`. Allowed values: `both`, `on_session`, `off_session`.
`status`	string	Yes	Lifecycle state: draft, active, or inactive. Allowed values: `draft`, `active`, `inactive`.
`stripeMitExemptionApproved`	boolean	Yes	Operations approval for this Stripe account to quote a card-scheme transaction reference that another processor issued, using Stripe's merchant-initiated exemption on off-session charges. Stripe enables that parameter per account. Only Operations may set it.
`trafficSplitPercent`	integer or null	Yes	Relative share of new-card checkouts this gateway takes for its card processor, as a whole number from 0 to 100. When a buyer enters a new card, each card processor is represented by its best-matching gateway for the checkout, and the first attempt is divided between processors in proportion to the shares on those gateways. Shares are relative weights and need not total 100. A gateway with `0`, `null`, or no share takes no weighted traffic: it is used only when no competing gateway has a positive share, or as a failover when cascading is enabled on it. Saved-card, renewal, and direct API charges are not split. `null` when no share is set. Minimum: 0. Maximum: 100.
`updatedAt`	string (date-time)	Yes
`webhookSigningSecretConfigured`	boolean	Yes	Whether a webhook verification value is stored. The value is write-only.
`worldpayCapabilities`	object or null	Yes	Approved Worldpay merchant-code capabilities. `operations` lists `refund`, `capture` and `void` only while that operation has current, complete approval for this gateway environment.
`worldpayCapabilities.approvalReference`	string	Yes	Privacy-safe Operations approval reference. Maximum length: 255.
`worldpayCapabilities.approvedAt`	string (date-time)	Yes
`worldpayCapabilities.cardSchemes`	array of string	Yes	Optional Worldpay card-scheme names. Checkout does not match a card brand against this list; an empty list is allowed.
`worldpayCapabilities.countries`	array of string	Yes	Optional ISO 3166-1 alpha-2 names. Routing uses the gateway countries field for every provider; an empty list is allowed.
`worldpayCapabilities.currencies`	array of string	Yes	Explicit ISO 4217 currency allowlist; empty never means all. Minimum items: 1.
`worldpayCapabilities.expiresAt`	string (date-time)	Yes
`worldpayCapabilities.externalSchemeReferenceApproved`	boolean	No	Operations approval to quote a card-scheme transaction reference issued through another processor, recorded after a Secure Test exercise on this merchant code. Omission keeps it disabled.
`worldpayCapabilities.operations`	array of string	Yes	Allowed values: `purchase`, `authorization`, `capture`, `void`, `refund`, `status`, `order_inquiry`, `order_notifications`, `three_ds`, `stored_credentials`, `zero_value_verification`. Minimum items: 1.
`worldpayCapabilities.orderNotificationsCertified`	boolean	Yes
`worldpayCapabilities.pcivaultBinMetadataCertified`	boolean	Yes
`worldpayCapabilities.pcivaultProxyCertified`	boolean	Yes
`worldpayCapabilities.storedCredentialCustomerInitiatedReason`	string	No	Operations-approved Worldpay reason for buyer-present reuse. Omission keeps customer-initiated reuse disabled. Allowed values: `UNSCHEDULED`.
`worldpayCapabilities.storedCredentialMerchantInitiatedReasons`	array of string	No	Operations-approved merchant-initiated purposes. Omission keeps unattended reuse disabled. Allowed values: `RECURRING`, `UNSCHEDULED`. Minimum items: 1.
`worldpayCapabilities.storedCredentialsCertified`	boolean	Yes
`worldpayCapabilities.threeDsCallbackOrigins`	array of string	No	Exact https origins allowed for Worldpay Flex challenge and return callbacks.
`worldpayCapabilities.threeDsCertified`	boolean	Yes
`worldpayCapabilities.version`	number	Yes	Capability-record schema version. Allowed values: `1`.
`worldpayMerchantCode`	string or null	Yes	Worldpay merchant code, or null for other providers.
`worldpayThreeDsApiIdConfigured`	boolean	Yes	Whether the Worldpay 3DS API ID is stored. The value is write-only.
`worldpayThreeDsHmacKeyConfigured`	boolean	Yes	Whether the Worldpay 3DS HMAC key is stored. The value is write-only.
`worldpayThreeDsOrganizationUnitIdConfigured`	boolean	Yes	Whether the Worldpay 3DS organisation unit ID is stored. The value is write-only.
`worldpayXmlPasswordConfigured`	boolean	Yes	Whether the Worldpay XML machine password is stored. The value is write-only.
`worldpayXmlUsernameConfigured`	boolean	Yes	Whether the Worldpay XML machine username is stored. The value is write-only.

Errors

Status	Description
`400`	The supplied request body is invalid.
`401`	Client Basic authentication or OAuth2 bearer authentication is required. For Basic, use `client.uuid` as the username and `client.api_key` as the password; for bearer, send a valid OAuth2 access token with the required scope.
`403`	Members cannot manage gateway settings.
`404`	No such gateway for this client.
`409`	The change would repurpose a validated connection or duplicate an existing one.
`422`	The provider rejected the resulting credentials.

PreDisputeAlertSettings_enrollDescriptor

Enroll Pre-Dispute Alert Descriptor

Enrolls a merchant billing descriptor in one alert network and returns that enrollment.

Policy	Value
Operation	`POST /v1/settings/pre-dispute-alerts/{id}/descriptors`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`manual-reconciliation`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Pre-Dispute Alert Setting id.
`descriptor`	body	string	Yes	Merchant billing descriptor text to enroll in one alert network. Maximum length: 255.
`enrollment`	body	string	Yes	The single alert network to enroll this descriptor in. Allowed values: `ethoca`, `rdr`, `cdrn`.
`visaArnCodes`	body	array of string	No	Visa ARN codes to scope the descriptor. Required when the RDR network is enrolled; ignored otherwise.

Result

Returns 201 with a JSON body.

Field	Type	Required	Description
`createdAt`	string (date-time)	Yes
`descriptor`	string	Yes	The merchant billing descriptor text.
`enrollment`	string	Yes	The alert network enrolled. Allowed values: `ethoca`, `rdr`, `cdrn`.
`id`	string	Yes	The Flo descriptor-enrollment UUID.
`preDisputeAlertSettingId`	string	Yes	The owning Pre-Dispute Alert Setting UUID.
`status`	string	Yes	Normalized enrollment status. Allowed values: `pending`, `live`, `error`.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body 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 such Pre-Dispute Alert Setting for this client.
`409`	The descriptor is already enrolled, or the setting is not linked to an alert network account.
`502`	The alert network rejected or did not answer the enrollment request.

PreDisputeAlertSettings_get

Get Pre-Dispute Alert Setting

Returns a single Pre-Dispute Alert Setting owned by the authenticated client.

Policy	Value
Operation	`GET /v1/settings/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 (uuid)	Yes	The Pre-Dispute Alert Setting id.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`autoRefundAmount`	number or null	No	Cap applied to AUTO-REFUND-CAPPED.
`clientId`	string	Yes	The owning Flo client UUID.
`createdAt`	string (date-time)	Yes
`description`	string or null	No	Optional free-text note.
`id`	string (uuid)	Yes	The Flo Pre-Dispute Alert Setting UUID.
`name`	string or null	No	Human-friendly label for this setting.
`preDisputeAlertSettingId`	string (uuid)	Yes	Canonical Pre-Dispute Alert Setting ID. Same value as `id`.
`responseMode`	string	Yes	Configured Pre-Dispute Alert response mode. Recorded but never acted on in ALERT mode. Allowed values: `AUTO-REFUND`, `AUTO-REFUND-CAPPED`, `ALERT`.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body 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 such Pre-Dispute Alert Setting for this client.

PreDisputeAlertSettings_list

List Pre-Dispute Alert Settings

Returns paginated Pre-Dispute Alert Settings for the authenticated client. Actual Stripe and PayPal chargebacks are Disputes, not Pre-Dispute Alerts.

Policy	Value
Operation	`GET /v1/settings/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: `createdAt`, `name`, `updatedAt`. Default: `createdAt` DESC. Allowed values: `createdAt`, `name`, `updatedAt`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`createdAt`	query	string (date-time)	No	Setting creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`name`	query	string	No	Local display label for this setting. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`responseMode`	query	string	No	Configured Pre-Dispute Alert response mode. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `AUTO-REFUND`, `AUTO-REFUND-CAPPED`, `ALERT`.
`updatedAt`	query	string (date-time)	No	Setting update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`uuid`	query	string	No	Opaque Flo Pre-Dispute Alert Setting 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[].autoRefundAmount`	number or null	No	Cap applied to AUTO-REFUND-CAPPED.
`data[].clientId`	string	Yes	The owning Flo client UUID.
`data[].createdAt`	string (date-time)	Yes
`data[].description`	string or null	No	Optional free-text note.
`data[].id`	string (uuid)	Yes	The Flo Pre-Dispute Alert Setting UUID.
`data[].name`	string or null	No	Human-friendly label for this setting.
`data[].preDisputeAlertSettingId`	string (uuid)	Yes	Canonical Pre-Dispute Alert Setting ID. Same value as `id`.
`data[].responseMode`	string	Yes	Configured Pre-Dispute Alert response mode. Recorded but never acted on in ALERT mode. Allowed values: `AUTO-REFUND`, `AUTO-REFUND-CAPPED`, `ALERT`.
`data[].updatedAt`	string (date-time)	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied request body 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.

PreDisputeAlertSettings_listDescriptors

List Pre-Dispute Alert Descriptors

Returns paginated billing-descriptor enrollments for one Pre-Dispute Alert Setting.

Policy	Value
Operation	`GET /v1/settings/pre-dispute-alerts/{id}/descriptors`
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 (uuid)	Yes	The Pre-Dispute Alert Setting id.
`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`, `descriptor`, `updatedAt`. Default: `createdAt` DESC. Allowed values: `createdAt`, `descriptor`, `updatedAt`.
`relation`	query	string	No	This endpoint does not support relation aliases. Supplying relation returns 400.
`createdAt`	query	string (date-time)	No	Descriptor enrollment creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`descriptor`	query	string	No	Merchant billing descriptor text. Equality filter. Pass without operator for exact match or pass any of the following operators: `[search]`. `[search]` is case-insensitive text contains matching.
`enrollment`	query	string	No	Alert network enrolled for this descriptor. 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`, `rdr`, `cdrn`.
`status`	query	string	No	Normalized enrollment status. Equality filter. Pass without operator for exact match or pass any of the following operators: `[in]`. `[in]` accepts comma-separated values; blank entries return 400. Allowed values: `pending`, `live`, `error`.
`updatedAt`	query	string (date-time)	No	Descriptor enrollment update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: `[gt]` `[gte]` `[lt]` `[lte]`.
`uuid`	query	string	No	Opaque Flo descriptor-enrollment 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[].createdAt`	string (date-time)	Yes
`data[].descriptor`	string	Yes	The merchant billing descriptor text.
`data[].enrollment`	string	Yes	The alert network enrolled. Allowed values: `ethoca`, `rdr`, `cdrn`.
`data[].id`	string	Yes	The Flo descriptor-enrollment UUID.
`data[].preDisputeAlertSettingId`	string	Yes	The owning Pre-Dispute Alert Setting UUID.
`data[].status`	string	Yes	Normalized enrollment status. Allowed values: `pending`, `live`, `error`.
`data[].updatedAt`	string (date-time)	Yes
`limit`	number	Yes
`page`	number	Yes
`pages`	number	Yes
`total`	number	Yes

Errors

Status	Description
`400`	The supplied request body 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 such Pre-Dispute Alert Setting for this client.

PreDisputeAlertSettings_update

Update Pre-Dispute Alert Setting

Updates a Pre-Dispute Alert Setting owned by the authenticated client.

Policy	Value
Operation	`PATCH /v1/settings/pre-dispute-alerts/{id}`
Class	`mutating`
Risk	`high`
Confirmation	`required`
Retry	`same-idempotency-key`
Rate-limit tier	`restricted`
Roles	`owner`, `admin`, `member`
Scopes	`mcp:write`

Arguments

Argument	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The Pre-Dispute Alert Setting id.
`autoRefundAmount`	body	number	No	Cap applied to AUTO-REFUND-CAPPED. Minimum: 0.
`description`	body	string or null	No	Optional free-text note. Send null to clear. Maximum length: 1000.
`name`	body	string or null	No	Human-friendly label for this setting. Send null to clear. Maximum length: 255.
`responseMode`	body	string	No	Configured Pre-Dispute Alert response mode. Allowed values: `AUTO-REFUND`, `AUTO-REFUND-CAPPED`, `ALERT`.

Result

Returns 200 with a JSON body.

Field	Type	Required	Description
`autoRefundAmount`	number or null	No	Cap applied to AUTO-REFUND-CAPPED.
`clientId`	string	Yes	The owning Flo client UUID.
`createdAt`	string (date-time)	Yes
`description`	string or null	No	Optional free-text note.
`id`	string (uuid)	Yes	The Flo Pre-Dispute Alert Setting UUID.
`name`	string or null	No	Human-friendly label for this setting.
`preDisputeAlertSettingId`	string (uuid)	Yes	Canonical Pre-Dispute Alert Setting ID. Same value as `id`.
`responseMode`	string	Yes	Configured Pre-Dispute Alert response mode. Recorded but never acted on in ALERT mode. Allowed values: `AUTO-REFUND`, `AUTO-REFUND-CAPPED`, `ALERT`.
`updatedAt`	string (date-time)	Yes

Errors

Status	Description
`400`	The supplied request body 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 such Pre-Dispute Alert Setting for this client.

Site navigation

Settings tools

Settings tools

Branding_clear

Branding_get

Branding_upsert

ChargebackSettings_createDescriptor

ChargebackSettings_getSetting

ChargebackSettings_updateSetting

ClientUser_create

ClientUser_getOne

ClientUser_list

ClientUser_remove

ClientUser_transferOwnership

ClientUser_update

GatewaySettings_activate

GatewaySettings_create

GatewaySettings_deactivate

GatewaySettings_get

GatewaySettings_list

GatewaySettings_test

GatewaySettings_update

PreDisputeAlertSettings_enrollDescriptor

PreDisputeAlertSettings_get

PreDisputeAlertSettings_list

PreDisputeAlertSettings_listDescriptors

PreDisputeAlertSettings_update

On this page

Settings tools

Settings toolsCopy Anchor Link

Branding_clearCopy Anchor Link

Branding_getCopy Anchor Link

Branding_upsertCopy Anchor Link

ChargebackSettings_createDescriptorCopy Anchor Link

ChargebackSettings_getSettingCopy Anchor Link

ChargebackSettings_updateSettingCopy Anchor Link

ClientUser_createCopy Anchor Link

ClientUser_getOneCopy Anchor Link

ClientUser_listCopy Anchor Link

ClientUser_removeCopy Anchor Link

ClientUser_transferOwnershipCopy Anchor Link

ClientUser_updateCopy Anchor Link

GatewaySettings_activateCopy Anchor Link

GatewaySettings_createCopy Anchor Link

GatewaySettings_deactivateCopy Anchor Link

GatewaySettings_getCopy Anchor Link

GatewaySettings_listCopy Anchor Link

GatewaySettings_testCopy Anchor Link

GatewaySettings_updateCopy Anchor Link

PreDisputeAlertSettings_enrollDescriptorCopy Anchor Link

PreDisputeAlertSettings_getCopy Anchor Link

PreDisputeAlertSettings_listCopy Anchor Link

PreDisputeAlertSettings_listDescriptorsCopy Anchor Link

PreDisputeAlertSettings_updateCopy Anchor Link

On this page

Settings tools

Branding_clear

Branding_get

Branding_upsert

ChargebackSettings_createDescriptor

ChargebackSettings_getSetting

ChargebackSettings_updateSetting

ClientUser_create

ClientUser_getOne

ClientUser_list

ClientUser_remove

ClientUser_transferOwnership

ClientUser_update

GatewaySettings_activate

GatewaySettings_create

GatewaySettings_deactivate

GatewaySettings_get

GatewaySettings_list

GatewaySettings_test

GatewaySettings_update

PreDisputeAlertSettings_enrollDescriptor

PreDisputeAlertSettings_get

PreDisputeAlertSettings_list

PreDisputeAlertSettings_listDescriptors

PreDisputeAlertSettings_update