MCPTool reference
Disputes tools
Arguments, results, errors, and access, confirmation, and retry policy for each Disputes tool in FloPay MCP, from the reviewed API contract.
Disputes tools
Generated from the FloPay MCP contract version 1, revision 764b41d5c7205d6df7eeaeac832fafe882247f5526b1d4d6bc6f98e3eaca7784.
Disputes_act
Act on a Dispute
Records a merchant review action against a Stripe or PayPal payment dispute.
| Policy | Value |
|---|---|
| Operation | POST /v1/disputes/{id}/actions |
| Class | mutating |
| Risk | medium |
| Confirmation | required |
| Retry | same-idempotency-key |
| Rate-limit tier | mutation |
| Roles | owner, admin |
| Scopes | mcp:write |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | |
action | body | string | Yes | Allowed values: attach, detach, confirmed_unmatched, ignored_duplicate. |
reason | body | string | Yes | Minimum length: 1. Maximum length: 500. |
transactionId | body | string (uuid) | No |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
actionRequired | boolean | Yes | |
amount | number | Yes | |
createdAt | string (date-time) | Yes | |
currency | string | Yes | |
id | string (uuid) | Yes | |
linkStatus | string | Yes | Allowed values: linked, partially_linked, unmatched, action_required. |
paymentIds | array of string | Yes | |
phase | string | Yes | Allowed values: initial, appeal. |
reason | string | Yes | Allowed values: fraud_or_unauthorized, duplicate, not_received, not_as_described, credit_not_processed, cancelled_recurring, incorrect_amount, paid_by_other_means, processing_error, other. |
responseDueAt | string (date-time) or null | No | |
reviewState | string | Yes | Allowed values: pending, confirmed_unmatched, ignored_duplicate. |
sequence | number | Yes | |
status | string | Yes | Allowed values: open, under_review, won, lost. |
updatedAt | string (date-time) | Yes | |
userId | string (uuid) or null | No |
Errors
| Status | Description |
|---|---|
400 | The path, filter, sort, pagination, or review action input is invalid. |
401 | A valid OAuth client_user bearer token is required. |
403 | The live merchant role or bearer scope does not permit this operation. |
404 | No dispute or payment with this id exists for the authenticated client. |
Disputes_get
Get Dispute
Returns a single Stripe or PayPal payment dispute owned by the authenticated client.
| Policy | Value |
|---|---|
| Operation | GET /v1/disputes/{id} |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
actionRequired | boolean | Yes | |
amount | number | Yes | |
createdAt | string (date-time) | Yes | |
currency | string | Yes | |
id | string (uuid) | Yes | |
linkStatus | string | Yes | Allowed values: linked, partially_linked, unmatched, action_required. |
paymentIds | array of string | Yes | |
phase | string | Yes | Allowed values: initial, appeal. |
reason | string | Yes | Allowed values: fraud_or_unauthorized, duplicate, not_received, not_as_described, credit_not_processed, cancelled_recurring, incorrect_amount, paid_by_other_means, processing_error, other. |
responseDueAt | string (date-time) or null | No | |
reviewState | string | Yes | Allowed values: pending, confirmed_unmatched, ignored_duplicate. |
sequence | number | Yes | |
status | string | Yes | Allowed values: open, under_review, won, lost. |
updatedAt | string (date-time) | Yes | |
userId | string (uuid) or null | No |
Errors
| Status | Description |
|---|---|
400 | The path, filter, sort, pagination, or review action input is invalid. |
401 | A valid OAuth client_user bearer token is required. |
403 | The live merchant role or bearer scope does not permit this operation. |
404 | No dispute with this id exists for the authenticated client. |
Disputes_list
List Disputes
Returns paginated Stripe and PayPal payment disputes (actual chargebacks) for the authenticated client. Network warnings are Pre-Dispute Alerts.
| Policy | Value |
|---|---|
| Operation | GET /v1/disputes |
| Class | read-only |
| Risk | low |
| Confirmation | not-required |
| Retry | safe |
| Rate-limit tier | read |
| Roles | owner, admin, member |
| Scopes | mcp:read |
Arguments
| Argument | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | No | 1-based page number for paginated list endpoints. Default: 1. Minimum: 1. |
limit | query | integer | No | Maximum number of records to return per page. Default: 20. Minimum: 1. Maximum: 100. |
sort | query | string | No | Sort by one allowed field. Use exactly one of sort[asc] or sort[desc]. Allowed fields: amount, createdAt, responseDueAt, status, updatedAt. Default: createdAt DESC. Allowed values: amount, createdAt, responseDueAt, status, updatedAt. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
actionRequired | query | string | No | Whether merchant action is required. Equality filter. Pass without operator for exact match. |
createdAt | query | string (date-time) | No | Dispute creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
currency | query | string | No | ISO-4217 dispute currency. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
linkStatus | query | string | No | Payment-link review status. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: linked, partially_linked, unmatched, action_required. |
phase | query | string | No | Dispute lifecycle phase. 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: initial, appeal. |
reason | query | string | No | Provider-neutral dispute reason. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. Allowed values: fraud_or_unauthorized, duplicate, not_received, not_as_described, credit_not_processed, cancelled_recurring, incorrect_amount, paid_by_other_means, processing_error, other. |
status | query | string | No | Provider-neutral dispute 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: open, under_review, won, lost. |
updatedAt | query | string (date-time) | No | Last material update timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
userUuid | query | string | No | Resolved Flo customer ID. Equality filter. Pass without operator for exact match or pass any of the following operators: [in]. [in] accepts comma-separated values; blank entries return 400. |
uuid | query | string | No | Opaque Flo dispute 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[].actionRequired | boolean | Yes | |
data[].amount | number | Yes | |
data[].createdAt | string (date-time) | Yes | |
data[].currency | string | Yes | |
data[].id | string (uuid) | Yes | |
data[].linkStatus | string | Yes | Allowed values: linked, partially_linked, unmatched, action_required. |
data[].paymentIds | array of string | Yes | |
data[].phase | string | Yes | Allowed values: initial, appeal. |
data[].reason | string | Yes | Allowed values: fraud_or_unauthorized, duplicate, not_received, not_as_described, credit_not_processed, cancelled_recurring, incorrect_amount, paid_by_other_means, processing_error, other. |
data[].responseDueAt | string (date-time) or null | No | |
data[].reviewState | string | Yes | Allowed values: pending, confirmed_unmatched, ignored_duplicate. |
data[].sequence | number | Yes | |
data[].status | string | Yes | Allowed values: open, under_review, won, lost. |
data[].updatedAt | string (date-time) | Yes | |
data[].userId | string (uuid) or null | No | |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The path, filter, sort, pagination, or review action input is invalid. |
401 | A valid OAuth client_user bearer token is required. |
403 | The live merchant role or bearer scope does not permit this operation. |
Disputes_listCandidates
List Dispute match candidates
Returns paginated privacy-safe payment match candidates for a Dispute.
| Policy | Value |
|---|---|
| Operation | GET /v1/disputes/{id}/candidates |
| 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 | |
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: confidence, createdAt, rank. Default: rank ASC. Allowed values: confidence, createdAt, rank. |
relation | query | string | No | This endpoint does not support relation aliases. Supplying relation returns 400. |
confidence | query | number | No | Privacy-safe match confidence. Equality filter. Pass without operator for exact match or pass any of the following operators: [gte] [lte]. |
createdAt | query | string (date-time) | No | Candidate creation timestamp. Equality filter. Pass without operator for exact match or pass any of the following operators: [gt] [gte] [lt] [lte]. |
paymentId | query | string | No | Candidate Flo payment 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. |
rank | query | number | No | Candidate rank. Equality filter. Pass without operator for exact match or pass any of the following operators: [gte] [lte]. |
Result
Returns 200 with a JSON body.
| Field | Type | Required | Description |
|---|---|---|---|
data | array of object | Yes | |
data[].confidence | number | Yes | |
data[].createdAt | string (date-time) | Yes | |
data[].evidence | object | Yes | |
data[].id | string (uuid) | Yes | |
data[].paymentId | string (uuid) | Yes | |
data[].rank | number | Yes | |
limit | number | Yes | |
page | number | Yes | |
pages | number | Yes | |
total | number | Yes |
Errors
| Status | Description |
|---|---|
400 | The path, filter, sort, pagination, or review action input is invalid. |
401 | A valid OAuth client_user bearer token is required. |
403 | The live merchant role or bearer scope does not permit this operation. |
404 | No dispute with this id exists for the authenticated client. |
Authentication tools
Arguments, results, errors, and access, confirmation, and retry policy for each Authentication tool in FloPay MCP, from the reviewed API contract.
Pre-Dispute Alerts tools
Arguments, results, errors, and access, confirmation, and retry policy for each Pre-Dispute Alerts tool in FloPay MCP, from the reviewed API contract.