@garuhq/mcp

Create a PIX charge. Returns a QR code for the customer to pay.

Swap the saved card on a recurring series. The new PaymentMethod must belong to the same customerId. Future cycles silent-charge the new card; the in-flight cycle is not retroactively rebound.

Clear the saved card on a recurring series. Future cycles fall back to the email-with-link flow so the customer can re-enter card details or pay via PIX/Boleto.

Per-attempt billing log for a scheduled charge series (SPEC §4.2). One row per logical billing event: cycle 1 interactive charge, every silent-charge attempt, every retry cron retry, every manual mark-paid. Each row carries the canonical Garu failureCode for declines, the gateway raw code for forensics, and a snapshot of the card last4 / brand even after the PaymentMethod is deleted (LGPD survival). Use this to audit why a recurring series fell behind.

List a product

Get one offer by id. Use it to read the current price and whether it is still active.

Create an offer so the same product can be sold at a second price behind its

Update an offer — reprice, rename, or activate/deactivate it. Deactivating is

Delete an offer permanently. Works ONLY while it has never sold — once a

Schedule a future charge for an existing customer. Use list_customers first to find the customerId. type=

List scheduled charges for the authenticated seller, with pagination and filters. Pass status as a single value or an array. Use search to match against the linked customer

Get a scheduled charge by ID, bundled with its event timeline and any linked Garu transactions. The response shape is { charge, events, transactions }. Both charge.amount and transactions[].value are decimal BRL (e.g. 297.50) — never centavos, no conversion needed.

Postpone a scheduled charge to a new due date. Allowed from scheduled / due_today / overdue / paused. Clears any pending dunning so the customer gets a fresh reminder on the new date.

Pause a scheduled charge. No reminders fire while paused. Allowed from scheduled / due_today / overdue. Use resume_scheduled_charge to bring it back.

Resume a paused scheduled charge. Only valid from `paused`.

Manually mark a scheduled charge as paid (e.g. customer paid via bank transfer outside Garu). For one-time: omit cycleNumber, allowed from due_today / overdue. For recurring: pass cycleNumber, allowed from cycle status due_today / overdue / failed; future cycles continue.

Force-bill the current cycle right now instead of waiting for its due date. Runs the same dispatch the daily billing cron would: customer email/notification + outbound webhook + timeline event. Allowed only from a billable status (scheduled / due_today); a recurring series must also have an open cycle (otherwise the gateway returns 400). IDEMPOTENT — NOT a re-charge: if this cycle

Stop future cycles for a recurring scheduled charge. The currently in-flight cycle (if any) remains active until paid, postponed, or marked-paid; only after that resolves does the series flip to recurrence_canceled. Final — use a new series to restart. Recurring-only.

Toggle Stripe-style soft cancel on a recurring series. With enabled=true, the cycle generator stops emitting new cycles after the next paid cycle (the in-flight cycle still bills + can be paid). Reversible by passing enabled=false. Mutually exclusive with recurrence.endsAfter and recurrence.endsOn.

Create a boleto bancario charge. Returns a bank slip line for payment.

List charges for the authenticated seller with pagination and filters.

Get details of a specific charge by its uuid.

Refund a charge fully or partially. Amount is in BRL / reais (e.g. 10.50 for R$10,50).

Cancel an unpaid charge by its uuid.

Create a customer and link to the current seller. Safe to retry: the SDK attaches an

List customers for the authenticated seller with pagination, search, and an optional

Get details of a specific customer by uuid.

Update a customer

Set or clear the per-seller billing email override for a customer. The override is sticky: it takes precedence over the per-seller last-used email and the global customer.email for outbound seller-to-customer emails, and is never auto-overwritten by subsequent payments. Pass null to clear and fall back to the last-used email. Use this when the customer asks for a specific billing address (e.g. financeiro@empresa.com.br) different from the email they used at checkout.

Remove a customer from the current seller. Does not delete the customer globally.

Sell a product as a carnê: one product paid with N monthly bank slips (boleto parcelado). This is SELLER-FINANCED credit, not a card instalment — nobody guarantees a boleto, so if the buyer stops paying at parcela 4 the seller keeps four parcelas and loses the rest. Only the FIRST boleto is registered now; the rest are emitted month by month, and the sale activates when parcela 1 compensates. The product must have carnê enabled. Use list_products for the productId and list_customers for the customerId. Idempotent: the SDK attaches a key automatically, so a retry cannot register a second real boleto.

List carnês for the authenticated seller, newest first. dueFrom/dueTo filter on the FIRST parcela

Retrieve one carnê with every parcela: due date, status, barcode line and boleto PDF. Note totalCollected (what actually cleared) against totalScheduled (what the carnê bills) — they differ once a bank adds multa or mora, so totalCollected can legitimately exceed totalScheduled.

Issue a segunda via (replacement boleto) for one parcela, once the current slip has expired. Garu refuses while the old barcode is still live: a boleto stays payable at any bank until its due date plus five days, and two live barcodes for one parcela is how a buyer pays it twice. Allowed once per parcela per day.

Move ONE parcela to a later date. Its siblings keep their dates — this postpones a payment, it does not restructure the carnê. A slip already emitted stays payable on its original date until it expires.

Record a parcela as paid, for when the buyer paid the slip but the webhook never arrived. Garu asks the provider to confirm the charge really compensated before recording it, because this settles the transaction and pays affiliate and co-producer commissions. A provider outage refuses the action rather than trusting the assertion.

Cancel the carnê. Emission and reminders stop and open slips are cancelled at the provider. Money already collected is NOT returned — use request_plan_refund for that. A cancelled carnê is never revived by a late payment; money arriving afterwards opens a refund request instead.

Ask for a carnê to be refunded. Garu does NOT move this money: a boleto cannot be reversed and the funds already settled to the seller, so the return is a bank transfer only they can make. This records the request and notifies the seller team. The carnê KEEPS RUNNING while the request is pending — future parcelas still emit. Transfer the money, then close it with confirm_refund_request. Safe to retry: the SDK attaches an idempotency key automatically, and the gateway already refuses a second pending request for the same carnê.

Return the steps and dashboard URLs an agent needs to integrate an application with Garu:

List refunds Garu has been asked to make. Garu does NOT move this money: a boleto cannot be reversed and Celcoin exposes no Pix devolução, so the funds already settled to the seller and the return is a bank transfer only they can make. Covers carnê and Pix/boleto charges alike. Filter status=

Retrieve one refund request. Exactly one of installmentPlanId or chargeId is set, depending on whether the refund is for a carnê or for a single Pix/boleto charge.

Record that the seller HAS ALREADY returned the money. Call this only after the transfer actually happened — Garu never observes it and takes the seller

Decline a refund request. The carnê is untouched and keeps running exactly as it was; the fact that a refund was asked for is deliberately not erased. Idempotent.

List products for the authenticated seller with pagination and search.

Get details of a specific product by UUID.

Get the per-product portal customization (business name, logo, primary color,

Create a product for the authenticated seller. Returns the created product,

Update an existing product (partial PATCH — only the fields you provide are

Create or merge the per-product portal customization. Both this tool and

Remove the per-product portal customization. The product falls back to the

List webhook events for the authenticated seller. Filter by delivery status (pending, success, failed), by Garu event type (e.g.

Fetch one webhook event by uuid. Returns the full payload, the embedded endpoint snapshot, the most recent response status/body, and the retry schedule. Use this to drill into why a delivery is failing.

Re-deliver a webhook event by uuid. Resets it to

Re-deliver a webhook event by uuid, audit-trail preserving. Inserts a fresh event (new uuid) that points back at the source via manualResendOf, then dispatches that clone — the original row is left untouched, so its prior response status/body stays on the record. Works on any status (success, failed, pending). Returns the clone event; the returned uuid is the new event