Payments
BlueSuite MCP tools for payments
See connection and authentication and workflow rules before calling these tools.
Related REST API and behavior.
List payments with optional filtering by parent object (invoice/quote), status, and pagination.
| Field | Type / accepted values | Required | Details |
|---|
page | integer | No | Page number (default: 1) |
per_page | integer | No | Results per page (default: 25) minimum: 1. maximum: 100. |
sort_by | "id", "amount", "status", "created_at", "modified_at" | No | Field to sort by. Unknown values fall back to the default sort. |
sort_direction | "asc", "desc" | No | Sort direction |
object_id | integer | No | Filter by parent object ID (invoice or quote ID) |
object_type | "invoice", "quote" | No | Filter by parent object type: 'invoice' or 'quote' |
status | "pending", "completed", "failed", "refunded" | No | Filter by payment status |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
Record money already received against an invoice or quote. For "mark invoice paid", set object_type="invoice", category="payment", settle_remaining=true and omit amount. The server records only the outstanding balance, accounting for existing payments and deposits, and then updates the invoice status. Repeating settlement of an already covered balance creates no payment. For a specific partial payment, supply amount. Omitted method defaults to other. Supply created_at only when the user gives a payment date. This records a manual payment; it does not charge a card.
| Field | Type / accepted values | Required | Details |
|---|
object_id | integer | Yes | Parent object ID (invoice or quote ID) |
object_type | "invoice", "quote" | Yes | Parent object type: 'invoice' or 'quote' |
category | "deposit", "payment" | Yes | Payment category: 'deposit' for deposit payments, 'payment' for regular payments |
amount | number | No | Amount received for a specific payment. Omit when settle_remaining is true. |
settle_remaining | boolean | No | Set true to mark an invoice paid by recording its remaining balance. Only for completed manual invoice payments, without a tip. |
created_at | string | No | When payment was received, as an ISO timestamp. Use the user-provided date in the workspace timezone; omit if unspecified. Format: date-time. |
tip_amount | number | No | Tip amount (default: 0) minimum: 0. |
status | "pending", "completed", "failed", "refunded" | No | Payment status (default: 'completed') |
gateway | "manual", "stripe:connect" | No | Payment gateway (default: 'manual') |
method | "other", "credit_card", "cash", "check", "bank_transfer", "ach" | No | Payment method: 'cash', 'check', 'credit_card', 'bank_transfer', 'ach', or 'other' (default: 'other') |
notes | string | No | Payment notes. Omit when not needed. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Get a single payment by ID
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Payment ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Update an existing payment. Changing amount or status will automatically recalculate the parent object status.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Payment ID |
amount | number | No | Payment amount |
tip_amount | number | No | Tip amount minimum: 0. |
status | "pending", "completed", "failed", "refunded" | No | Payment status |
method | "other", "credit_card", "cash", "check", "bank_transfer", "ach" | No | Payment method |
category | "deposit", "payment" | No | Payment category |
notes | string | No | Payment notes |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Delete a payment. This will automatically recalculate the parent object status (e.g., invoice may revert from "paid" to "partially_paid" or "sent").
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Payment ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
The downloadable tool schemas include the full input and output contracts. Tables describe schema-level required fields; cross-field rules still apply.