Payment Tools
A project sells through one or more payment providers, each connected in test or live mode.
A project sells through one or more payment providers, each connected in test or live mode. These tools read which providers a project has, switch them on and off, push the plan catalogue to a provider and read recent payments.
Tools
activate_payment_methodActivate Payment MethodDESTRUCTIVEdeactivate_payment_methodDeactivate Payment MethodDESTRUCTIVEdelete_payment_methodDelete Payment MethodREADget_payment_methodGet Payment MethodREADlist_payment_methodsList Payment MethodsREADlist_recent_paymentsRecent PaymentsDESTRUCTIVEsync_payment_method_plansSync Payment Method Plansactivate_payment_method
DESTRUCTIVEOffer a configured payment method to buyers again and re-queue its plan sync. Refuses a Stripe method whose Connect onboarding never finished.
The creator's on-switch for a gateway. Activating offers the method at checkout again and re-queues
the plan sync for its gateway, so its catalogue is current by the time the first buyer arrives.
Idempotent: a method that is already on is a no-op and emits nothing. When the switch flips,
project.payment_method.updated emits once with
changes.active.
Stripe needs its Connect handshake first
A Stripe method whose Connect onboarding never finished is refused with
VALIDATION_FAILED. Switching it on early would offer buyers a gateway that
fails at checkout; onboarding can only be completed from the dashboard, the
one place the Connect handshake can run.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. Sending the same arguments twice changes nothing the second time.
Arguments
project_id*stringUUID of the project the method belongs to.
payment_method_id*stringUUID of the payment method to switch on.
What it returns
{ "data": { "id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63", "provider": "paypal", "mode": "live", "active": true, "created_at": "2026-05-18T10:05:00+00:00" }}How it fails
VALIDATION_FAILEDa Stripe method whose Connect onboarding is incomplete.
RESOURCE_NOT_FOUNDunknown project_id or payment_method_id, a method of another project, or a project outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-payment-method:update.
deactivate_payment_method
DESTRUCTIVEStop offering a payment method to new buyers. Subscriptions already sold through it keep renewing.
The creator's off-switch for a gateway, and the safe way to retire one: new buyers stop seeing it at
checkout, while every subscription already sold through it keeps renewing with its gateway. The plan
sync for the gateway is re-queued. Idempotent: a method that is already off is a no-op and emits
nothing; when the switch flips,
project.payment_method.updated emits once with
changes.active.
Deactivate before you delete
Deactivating keeps the row and its history and can be undone with
activate_payment_method.
delete_payment_method removes the
gateway from the project. Prefer this one unless the creator asks for removal.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. Sending the same arguments twice changes nothing the second time.
Arguments
project_id*stringUUID of the project the method belongs to.
payment_method_id*stringUUID of the payment method to switch off.
What it returns
{ "data": { "id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63", "provider": "paypal", "mode": "live", "active": false, "created_at": "2026-05-18T10:05:00+00:00" }}How it fails
VALIDATION_FAILEDthe switch was refused for the method's current state.
RESOURCE_NOT_FOUNDunknown project_id or payment_method_id, a method of another project, or a project outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-payment-method:update.
delete_payment_method
DESTRUCTIVERemove a payment method from a project. Destructive — buyers lose that way to pay at once; the row is soft-deleted so history survives.
Take a gateway off a project. The row is soft-deleted rather than destroyed: subscriptions sold through it keep their gateway for refunds and history, and configuring the same provider in the same mode again later revives the row instead of creating a duplicate. What changes immediately is the checkout — buyers lose that way to pay.
Emits project.payment_method.deleted with a
credential-free snapshot. Idempotent: an already-deleted id surfaces as RESOURCE_NOT_FOUND,
exactly as an unknown or out-of-scope id does.
Destructive — confirm with a human first
Confirm the exact payment_method_id with the creator before calling. If the
intent is "stop offering it for now",
deactivate_payment_method does that
reversibly.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. Sending the same arguments twice changes nothing the second time.
Arguments
project_id*stringUUID of the project the method belongs to.
payment_method_id*stringUUID of the payment method to remove.
What it returns
{ "data": { "payment_method_id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63", "deleted": true }}How it fails
VALIDATION_FAILEDthe removal was refused for the method's current state.
RESOURCE_NOT_FOUNDunknown or already-deleted payment_method_id, a method of another project, or a project outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-payment-method:delete.
One configured payment method of a project by UUID — provider, mode and switch only, never a credential.
Read one payment gateway back before switching it, syncing it or removing it. The row is the one
list_payment_methods returns: id, provider, connector,
mode, active and created_at, and nothing else. provider is a gateway slug or a
connector:provider key for a currency a connector brings (telegram:stars), and connector
names that connector or is null.
Deliberately thin
Provider secrets, webhook signing secrets and Stripe Connect account ids live in an encrypted column and are never surfaced through MCP or REST, whatever ability the token carries. The dashboard is the only place a creator sees them.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project the method belongs to.
payment_method_id*stringUUID of the payment method to fetch.
What it returns
{ "data": { "id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63", "provider": "stripe", "connector": null, "mode": "live", "active": true, "created_at": "2026-05-18T10:05:00+00:00" }}mode is test or live and decides which set of credentials the gateway uses; the same
provider can be configured once in each.
How it fails
RESOURCE_NOT_FOUNDunknown project_id or payment_method_id, a method of another project, or a project outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-payment-method:view.
List configured payment methods for one project. Credentials and provider secrets are never returned.
List configured payment methods for one project. Safe to call for agents deciding whether a plan can charge against a given provider.
Provider secrets — API keys, webhook secrets, Stripe Connect account IDs — are always stripped before the response returns.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project whose payment methods to list.
active_onlybooleanoptionalWhen true, omits deactivated payment methods.
What it returns
{ "data": [ { "id": "8b0c4a15-e792-4360-95d8-1f47c0b3e926", "provider": "stripe", "connector": null, "mode": "live", "active": true, "created_at": "2026-03-01T00:00:00Z" } ], "meta": { "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "total": 2 }}How it fails
TOKEN_MISSING_ABILITYtoken lacks project-payment-method:view-any.
RESOURCE_NOT_FOUNDproject_id names a project the token cannot see: unknown, another team's, or outside the token's scope:project: allow-list. A project with no payment methods returns an empty list, not an error.
List the most recent subscription payments for one project with optional status filter. Reverse-chronological, no raw webhook payloads.
Return the most recent subscription payment rows for a project, reverse-chronological by occurred_at. Rows carry provider references (external_payment_id, external_event_id) but omit raw webhook payloads. Useful for quick revenue inspection and failure triage.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Annotations
It reads and never changes anything.
Arguments
project_id*stringUUID of the project whose payments to list.
statusstringoptionalPayment status filter. One of: successful, failed, pending, refunded
successfulfailedpendingrefundedlimitintegeroptionalMaximum payments to return (1..200, default 50).
1max200What it returns
{ "data": [ { "id": "8b0c4a15-e792-4360-95d8-1f47c0b3e926", "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4", "method_id": "8b0c4a15-e792-4360-95d8-1f47c0b3e926", "currency_id": "8f27a0d4-63be-4915-8c07-1a5d9e34b628", "status": "successful", "amount": "29.00", "transaction_fee": 87, "calculated_fee": "0.87", "external_payment_id": "pi_...", "external_event_id": "evt_...", "billing_reason": "subscription_cycle", "occurred_at": "2026-05-18T10:05:00Z" } ], "meta": { "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "total": 50, "limit": 50 }}How it fails
TOKEN_MISSING_ABILITYtoken lacks project-subscription:view-any.
RESOURCE_NOT_FOUNDproject_id names a project the token cannot see: unknown, another team's, or outside the token's scope:project: allow-list.
VALIDATION_FAILEDstatus is not one of the payment statuses; the error context lists the supported values.
sync_payment_method_plans
DESTRUCTIVEQueue a push of the project's plans into a payment gateway's catalogue. Answers sync_queued; the work runs in the background.
Some gateways keep their own catalogue — Stripe products and prices, PayPal, Razorpay and CoinPayments plans — and a subscription can only be sold through them once the plan exists there. Subscriby pushes the catalogue after every plan write and every method switch; this tool queues that push by hand, for the times a gateway was reconfigured or a sync failed and the creator wants it re-run now.
The answer is sync_queued, not a result: the work runs in the background and each plan reports
through the plan-sync webhook events as it lands. Idempotent in the sense that it can be repeated
safely — queuing twice pushes the same catalogue twice, which changes nothing.
Not every gateway has a catalogue
Telegram Stars, access codes and the redirect gateways (Paystack, CeyPay,
Skrill) take the price at checkout and keep no plan objects, so a sync for
them is refused with VALIDATION_FAILED rather than queued as a no-op.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
A client that honours annotations asks a person before running it. Sending the same arguments twice changes nothing the second time. It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
project_id*stringUUID of the project the method belongs to.
payment_method_id*stringUUID of the payment method whose gateway catalogue to refresh.
What it returns
{ "data": { "payment_method_id": "a15d70c8-3e46-4b92-b70f-58c9d2140e63", "status": "sync_queued" }}How it fails
VALIDATION_FAILEDthe gateway keeps no catalogue (connector currencies, access codes, the redirect gateways).
RESOURCE_NOT_FOUNDunknown project_id or payment_method_id, a method of another project, or a project outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-payment-method:update.
How is this guide?
Observability Tools
Where to look when something did not happen: webhook endpoints and their deliveries, the activity log of every mutation, and the status of a job another tool queued.
Plan Tools
Plans are what a project sells, and every plan has a kind that decides its shape: a subscription that renews on a cycle, a pass that sells dated windows, or a series that sells a slate of windows at once.