For agents
Every page here is also plain markdown, and two MCP servers expose the docs and the API, so an agent reads and acts without scraping HTML. Build with AI connects both in your tool.
Machine-readable files
Section titled “Machine-readable files”https://docs.avvio.xyz/llms.txt index of everything, with linkshttps://docs.avvio.xyz/llms-full.txt every guide, samples in all languageshttps://docs.avvio.xyz/partner-payouts.openapi.yaml the payouts contracthttps://docs.avvio.xyz/partner-checkout.openapi.yaml the checkout contractllms.txt?query=webhooks returns only the index entries that match. Append
.md to any page URL (https://docs.avvio.xyz/webhooks.md) for its markdown,
or request the page with Accept: text/markdown. Every page also has a
Copy page menu by its title.
The skill
Section titled “The skill”https://docs.avvio.xyz/skill.md is a standing brief for an agent: where the
docs are, how to authenticate, and the four mistakes that cost money. Skill
installers find it through /.well-known/agent-skills/index.json and
/.well-known/skills/index.json.
Docs MCP server
Section titled “Docs MCP server”https://docs.avvio.xyz/mcp serves these docs over Streamable HTTP with four
tools:
search_docsreturns the matching sections, ranked, with a URL for each.fetch_pagereturns one page.list_endpointslists every operation in both contracts.get_endpointreturns one operation as markdown, with its parameters, an example request and its responses.
It holds no key and cannot reach the API.
Payments MCP server
Section titled “Payments MCP server”npx -y @avvio/payments mcp runs the MCP server in the @avvio/payments npm
package over stdio. It calls the API with the AVVIO_API_KEY and
AVVIO_ORG_ID in its environment, so an agent can price, send and track
payouts.
What the agent gets on connect
Section titled “What the agent gets on connect”The server briefs the agent on call order, idempotency, bank returns and
sandbox accounts, and adds one prompt: integrate_payouts takes your stack
and use_case, then builds the bank form, recipients, idempotent payouts,
webhooks, reconciliation and tests. It builds from the reference integration
avvio-payout-demo, live at
payoutdemo.avvio.xyz.
The tool reference at the end of this page lists every tool and its arguments.
Hosted server, for model APIs
Section titled “Hosted server, for model APIs”Grok, the OpenAI Responses API and the Claude API call MCP servers from their
own cloud, so they can’t run npx. Point them at the hosted server instead.
The examples use a live AI agent key, which reads and prepares:
https://api.avvio.xyz/business/api/v1/assistant/v1/mcp/assistant/v1/{orgId}/mcp is the same server. The key decides which tools
are offered.
The hosted server isn’t on production yet. Until it is, give the model your
own functions that call the REST routes from your server.
GET /assistant/v1/{orgId}/capabilities lists each tool your key gets: its
input (JSON Schema, the function’s parameters) and its rest route. To run
one, fill {organizationId} and the other path parameters from the arguments,
put a GET’s other arguments in the query and a write’s in the JSON body
(renamed by body, filled in by defaults), send idempotencyKey as the
Idempotency-Key header (a new UUID for a write without one), and never
send confirm. Refuse a tool marked confirm unless the model passed
confirm: true. Drop null arguments, and send numbers as strings where the
schema says string.
This covers reads and a write key’s tools. Preparing a payment for approval
answers 503 ASSISTANT_API_DISABLED in production until the hosted server is
on; enabled in the capabilities response says which.
Grok (xAI Responses API). Send the key in headers as x-api-key (the xAI
SDK calls these extra_headers):
{ "type": "mcp", "server_url": "https://api.avvio.xyz/business/api/v1/assistant/v1/mcp", "server_label": "avvio", "headers": { "x-api-key": "avvio_live_..." }}OpenAI Responses API:
{ "type": "mcp", "server_url": "https://api.avvio.xyz/business/api/v1/assistant/v1/mcp", "server_label": "avvio", "headers": { "x-api-key": "avvio_live_..." }, "require_approval": "always"}Claude API (MCP connector, anthropic-beta: mcp-client-2025-11-20), in the
Messages request:
{ "mcp_servers": [ { "type": "url", "url": "https://api.avvio.xyz/business/api/v1/assistant/v1/mcp", "name": "avvio", "authorization_token": "avvio_live_..." } ], "tools": [{ "type": "mcp_toolset", "mcp_server_name": "avvio" }]}List only the tools the bot needs in allowed_tools (allowed_tool_names in
the xAI SDK). A read-only bot:
get_balance, list_payments, list_payouts, get_payout, find_payee,list_beneficiaries, list_balance_transactions, list_approvals, get_policy, quoteAdd prepare_payment, get_package and answer_question to prepare payments
for approval. Without an invoice, an agent prepares a payment to a saved payee
with prepare_payment_to_payee. Never list send_payout, refund_checkout_payment,
cancel_payout or confirm_funding for a client without an approval step.
Preparing is live only: a test AI agent key reads but isn’t offered
prepare_payment. Try reads and send_payout with a test key, then prepare
with a live AI agent key on a small amount. Only an owner or admin creates an
AI agent key.
If a model sends money, your server mints and stores each idempotencyKey.
A model that invents a new one on retry sends twice.
Four mistakes agents make here
Section titled “Four mistakes agents make here”- Retrying with a new
Idempotency-Key, which sends the payout twice. Persist the key and reuse it (Idempotency). - Treating a timeout as a failure. The payout may exist; retry with the same key.
- Treating
completedas final. A bank can return it days later (Track status & failures). - Inventing corridor fields. Build the form from
GET /recipients/{orgId}/corridors, because fields change with routing.
Writing the integration yourself
Section titled “Writing the integration yourself”Read the Quickstart and the recipes, then Errors before any retry logic, then Go live. Generate a client from the spec instead of hand-rolling HTTP:
npx @openapitools/openapi-generator-cli generate \ -i https://docs.avvio.xyz/partner-payouts.openapi.yaml -g python -o ./avvio --package-name avvio_payoutsThe CLI, MCP tools, endpoint table, samples and sandbox triggers here are
generated from source. If a page and the API disagree, the API is right; tell
us, with the requestId.
Payments MCP tools
Section titled “Payments MCP tools”45 tools, read from the server’s registered tool list. confirm: true marks the money-moving ones.
| Tool | Effect | What it does |
|---|---|---|
list_corridors |
reads | List every currency this organization can pay out to, or pass one currency to use its exact approved provider routing. Read this instead of hardcoding a form: field names differ by corridor and can change. |
get_requirements |
reads | The exact beneficiary fields needed to pay out in one currency, with validation patterns. Call this before create_beneficiary. |
quote |
reads | Indicative price for a corridor with no beneficiary needed: what the recipient gets, the fee, the rate, and the corridor minimum and maximum. Use this while a user is still choosing an amount. It is an estimate, not a locked rate. |
create_beneficiary |
writes | Register who is being paid. Scope it to the end user paying them via endUserId, so each of your users only ever sees their own beneficiaries. Returns destinationAccountId, which send_payout needs. |
list_beneficiaries |
reads | Saved beneficiaries, 50 a page: page on with cursor while hasMore is true before concluding someone is not saved (find_payee searches by name). A platform paying for its own customers passes endUserId so a user only sees theirs; a business paying its own payees leaves it out. |
get_beneficiary |
reads | One beneficiary by the id this API returned, with their payment methods and each destinationAccountId. |
get_ |
reads | One beneficiary by your own id for them: the externalId you sent when you created them. Use this instead of listing everyone and filtering: it is unique per organization, so it returns exactly one or NOT_FOUND. |
update_beneficiary |
writes | Correct a beneficiary’s contact details: name, email, phone, country, individual/business. Only the fields you pass change. Bank details cannot be edited: a wrong account is a new payment method, and the old one is deleted. |
delete_ |
confirm: true | Remove one way of paying a beneficiary, such as an account that closed or one entered wrong. Irreversible, and the destinationAccountId it carried stops being payable, so it requires confirm:true. The beneficiary and their other methods are untouched. |
list_ |
reads | The stated payment reasons this organization may use. Some corridors require one on a payout; read this rather than inventing a value, because a rejected one is a 400 on a payout already promised to somebody. |
send_payout |
confirm: true | This moves real money. Prices the payout and executes it, debiting your balance. Requires confirm:true. If it times out, the outcome is unknown: call again with the same idempotencyKey rather than starting over. A payout the organization’s approval rules hold comes back with an approvalId and waits for a person (list_approvals); it is not sent yet. |
get_payout |
reads | Current state of one payout. Always live, and authoritative, more so than a webhook you may have missed. |
list_payouts |
reads | Recent payouts for this organization, newest first. Filter by reference to find the payout behind your id. This is how you check whether a send whose response was lost (timeout, 5xx) actually went out, before retrying it with the same idempotencyKey. A payout names its payee by destinationAccountId only: match it to list_beneficiaries to find a payee’s payouts. get_payout has the failure reason. |
funding_accounts |
reads | Where to wire money to top up the balance that payouts debit. |
list_events |
reads | The change feed: one row per transition, with a sequence cursor. This is the reconciliation primitive: carry nextSince back as since and you observe every revision. Each row’s data is the webhook body for the same event (amounts, fee, reference). Payout, batch, approval and endpoint events share the feed; pass type to narrow it. |
list_approvals |
reads | Payouts and batch runs waiting on the organization’s human approvers. send_payout answers 202 with approvalId when a policy holds it; this is that queue. Approving is a dashboard action; there is no tool for it, by design. |
get_approval |
reads | One approval by the approvalId a 202 returned. Once status is executed, payoutId is the payout it became. |
list_audit_events |
reads | Who did what, from where, with which credential: every audited mutation on the organization, newest first, refused attempts included. Rows carry the key prefix, actor, IP, requestId, outcome and errorType. Page with cursor = the nextCursor from the last page. |
get_policy |
reads | What this organization is bound by, read live. Call it first: payout caps in USD (null = no cap), the approval threshold and how many approvers a held payout needs, which features are on (mass_payouts, developer), rate limits per minute, idempotency windows, the currencies that require purposeOfPayment, fees.payout (the pre-quote fee schedule; null = only priced inside a quote), and agentWallet (when this business pays AI connections from its agent wallet: balanceUsd and availableUsd, the most an AI payment can be right now; null = they pay from the main balance). Plan sends against it instead of discovering a cap from a 422 or an approval from a 202. |
get_balance |
reads | The organization’s available balance. Check this before sending: an underfunded payout is refused, and the refusal is a 400 rather than a queued payment. |
list_ |
reads | Every change to the balance, newest first, each with balanceAfter: funding, payouts, returns, holds and their release, adjustments. Page with cursor = the nextCursor from the last page. An empty page means no rows yet, not an error. |
get_funding |
reads | Deposit instructions for a payout that requires funding: the address, the exact amount, the network, and an expiry. Only some routings need this; the payout says so with requiresFunding. |
create_payout_link |
confirm: true | Mint a one-time link that collects the recipient’s own bank details and pays them, so you never handle the details yourself. The link is a credential: it is the only thing needed to be paid, so send it to the person being paid and nobody else. Requires confirm:true and an idempotencyKey: if it times out, call again with the same key rather than minting a second link. |
create_product |
writes | Create a catalog product for checkout: one name, one fixed price in one currency. Links made from it copy the name and price at creation. |
list_products |
reads | The checkout catalog, active products first. Images are not on the list. |
create_ |
writes | Create a checkout link a buyer pays on a hosted page. Pass productId, or currency + items. publish:true makes it live and returns shareUrl (send the buyer there). clientReferenceId is your join key, echoed on checkout_payment events. A failed publish still succeeds: the kept draft with publishError, not live. Fix the cause, then publish_checkout_link; never create it again. |
update_ |
writes | Edit a checkout link. A draft takes any create field. A live (sent) link takes exactly one field: expiresAt on its own, a new ISO-8601 instant or null to remove the deadline; anything else on a live link is refused, because repricing a URL a buyer may be looking at is a money bug. |
get_checkout_link |
reads | One checkout link: status, shareUrl, and received (what it has taken in). |
list_checkout_links |
reads | Checkout links, newest first. status is draft, sent (live), cancelled (paused) or expired (past its expiresAt). |
refund_ |
confirm: true | This moves real money. Refunds a card checkout payment to the buyer, whole (omit amount) or in part. Card payments only: any other payment answers 404. Requires confirm:true and an idempotencyKey; the key must hold the refunds scope, granted by an owner or admin. On a timeout, call again with the same idempotencyKey. |
pause_checkout_link |
confirm: true | Stop a live checkout link taking payments. This is permanent: a paused link cannot be republished. Requires confirm:true. |
publish_ |
writes | Make a draft checkout link live and return its shareUrl, the URL to send the buyer to. For a draft whose publish failed on create (publishError). |
list_ |
reads | Payments made on one checkout link, newest first. Amounts are base units with decimals beside them. The authoritative read; never trust a success redirect alone. |
confirm_funding |
confirm: true | Report the transaction that funded a payout. We read the chain before recording it: a hash that does not fund this payout is refused and nothing is written, so a rejection is always safe to correct. One transfer funds exactly one payout. |
cancel_payout |
confirm: true | Stop a payout that has not been funded yet: the recovery for one created by mistake. Once funded it cannot be canceled and you get PAYOUT_NOT_CANCELABLE, which is the honest answer rather than a cancellation that does not happen. |
find_payee |
reads | Saved payees by name: a fuzzy search (first name, nickname, email, typos) returning each one’s payeeId, currencies, accounts (last 4 only) and last payment. Without a query, the ones paid most recently. Use it to tell whether someone is already saved. |
list_payments |
reads | The payment history, as Avvio shows it: every payment out however it was made (in Avvio, by the assistant, by API; to a bank or a wallet), newest first, with who, amount, how, status and when. direction=in lists money that came in. Page with cursor = the nextCursor from the last page. |
prepare_payment |
writes | Pay a bill the business OWES (invoicing its own clients is draft_invoice/send_invoice). Upload the vendor’s invoice as base64 bytes (PDF, PNG, JPEG). It returns status reading: poll get_package(id) until needs_answers (answer questions[].field with answer_question), ready (a person approves at approveUrl), or blocked/failed/void/schedule_proposal (stop and report). New bank details come only this way or from a person; a saved payee with no invoice: prepare_payment_to_payee if offered. |
prepare_ |
writes | Prepare a payment to a SAVED payee with no invoice: payeeId from find_payee or list_beneficiaries, amount in the payee’s currency. Avvio uses the payee’s saved name and account, never details you send; methodId picks one of their saved accounts. Returns the package: report its status, not just “prepared”. ready = a person approves at approveUrl (nothing is sent before); needs_answers = questions[] for you (answer_question) or a person. Refused while a payment to that payee is open (409). Someone new: an invoice via prepare_payment, or a person in Avvio. |
get_package |
reads | A prepared payment: what the person will approve, its checks and open questions. |
answer_question |
writes | Answer one of a prepared payment’s open questions (the same rules as the card in Avvio). |
list_invoices |
reads | The business’s invoices to its clients (money owed to it), as the assistant lists them: filter unpaid (default; oldest due first, with totals per currency), overdue, paid or all; client narrows to one client by name. |
get_invoice |
reads | One invoice: client, amount, status, whether and when it was paid, when it was last emailed. |
draft_invoice |
writes | Draft an invoice to one of the business’s clients. Nothing is sent: it waits in Avvio (reviewUrl) until someone sends it. Returns drafted: false with a question when something is missing or ambiguous. |
send_invoice |
writes | Email an invoice to its client (a sent, unpaid one is emailed again). An AI agent or connected app prepares it only: it returns status prepared and a confirmUrl where a person confirms the send in Avvio; nothing is emailed. A connection granted send emails it. Refused for a paid or voided invoice. |
Tool arguments
Section titled “Tool arguments”list_corridors
Section titled “list_corridors”| Argument | Type | Required | Description |
|---|---|---|---|
currency |
string | — | Optional ISO code, e.g. MXN |
get_requirements
Section titled “get_requirements”| Argument | Type | Required | Description |
|---|---|---|---|
currency |
string | yes | ISO code, e.g. MXN |
| Argument | Type | Required | Description |
|---|---|---|---|
amount |
string | yes | Amount to send, e.g. “200.00” |
to |
string | yes | Destination currency, e.g. MXN |
from |
string | — | Source currency. Defaults to USD. |
create_beneficiary
Section titled “create_beneficiary”| Argument | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The recipient’s full legal name. |
email |
string | — | Optional contact address kept on the beneficiary for your records. Not used to route the payout. |
country |
string | — | ISO-3166 alpha-2, e.g. MX. Required for EUR and GTQ payees. |
currency |
string | yes | The payout currency, ISO 4217, such as MXN. |
type |
string | — | Who is paid. Default individual. |
phone |
string | — | E.164, e.g. +50212345678. Required for GTQ and JMD payees. |
endUserId |
string | — | Only if you are a platform paying on behalf of your own customers: your id for that customer. Leave it out otherwise. |
externalId |
string | — | Your own id for this beneficiary. Makes creation idempotent. |
details |
object | yes | The corridor fields, keyed by the fields[].id values get_requirements returns for this currency, e.g. {“clabeNumber”:“012…”} for MXN. Every value is a string (a number loses leading zeros). Names differ by corridor; never guess them. |
list_beneficiaries
Section titled “list_beneficiaries”| Argument | Type | Required | Description |
|---|---|---|---|
endUserId |
string | — | Your customer’s id, if you are a platform. Never invent one. |
limit |
number | — | 1-100, default 50. |
cursor |
string | — | nextCursor from the previous page. |
get_beneficiary
Section titled “get_beneficiary”| Argument | Type | Required | Description |
|---|---|---|---|
recipientId |
string | yes | The beneficiary’s id. |
get_beneficiary_by_external_id
Section titled “get_beneficiary_by_external_id”| Argument | Type | Required | Description |
|---|---|---|---|
externalId |
string | yes | Your id for this beneficiary, e.g. “payroll-4471”. |
update_beneficiary
Section titled “update_beneficiary”| Argument | Type | Required | Description |
|---|---|---|---|
recipientId |
string | yes | The beneficiary’s id. |
name |
string | — | The recipient’s full legal name. |
email |
string | — | The recipient’s email address. |
phone |
string | — | The recipient’s phone number in E.164, such as +525512345678. |
country |
string | — | ISO-3166 alpha-2, e.g. MX |
type |
string | — | individual or business. |
delete_beneficiary_method
Section titled “delete_beneficiary_method”| Argument | Type | Required | Description |
|---|---|---|---|
recipientId |
string | yes | The beneficiary’s id. |
methodId |
string | yes | From the beneficiary’s paymentMethods[].id. |
confirm |
boolean | yes | Must be true. The account cannot be restored, only re-registered. |
list_payment_reasons
Section titled “list_payment_reasons”| Argument | Type | Required | Description |
|---|---|---|---|
currency |
string | — | The payout currency, e.g. INR: the list depends on the rail that pays it. |
send_payout
Section titled “send_payout”| Argument | Type | Required | Description |
|---|---|---|---|
amount |
string | yes | Decimal string, at most 2 decimals, no commas or symbols. In USD (what you send) unless amountLeg says otherwise. To pay “3,000 MXN”, send amount “3000” with amountLeg “destination”; “3000” alone sends 3,000 USD. |
destinationAccountId |
string | yes | From create_beneficiary or list_beneficiaries. |
endUserId |
string | — | Your id for the customer sending the money, never the recipient. |
endUserName |
string | — | That customer’s display name. |
reference |
string | — | Your payment reference. |
purposeOfPayment |
string | — | A code from list_payment_reasons, where the corridor asks for one. |
expectDestinationAmount |
string | — | What you told the payer they would receive. The send is refused if the binding quote drifts more than 2% from it. |
amountLeg |
string | — | Which side amount describes. ‘source’ (default) takes the fees out of what you send. ‘destination’ pays the beneficiary that exact figure in their currency and adds the fees to your debit. ‘source_net’ means the same but keeps the figure in the sender’s currency (‘send them $200 worth’), converted at the market rate. The two locking modes need capabilities.exactOutput from list_corridors. |
idempotencyKey |
string | yes | Required. A unique id you generate for this payout. If the call times out, call again with this same value, which replays the original payout instead of sending a second one. |
confirm |
boolean | yes | Must be true. Explicit acknowledgement that this moves money. |
get_payout
Section titled “get_payout”| Argument | Type | Required | Description |
|---|---|---|---|
payoutId |
string | yes | The payout’s payoutId. |
list_payouts
Section titled “list_payouts”| Argument | Type | Required | Description |
|---|---|---|---|
reference |
string | — | Your reference from send_payout. |
status |
string | — | pending, processing, completed, failed or canceled. |
endUserId |
string | — | Only payouts sent on behalf of this end user. |
createdAfter |
string | — | ISO-8601 instant, e.g. 2026-10-01T00:00:00Z. |
createdBefore |
string | — | ISO-8601 instant. |
limit |
number | — | How many to return (default 50, at most 100). |
cursor |
string | — | nextCursor from the previous page. |
list_events
Section titled “list_events”| Argument | Type | Required | Description |
|---|---|---|---|
since |
string | — | A sequence from a previous page. Digits only. |
limit |
number | — | 1-500, default 100. |
payoutId |
string | — | Only this payout’s transitions. |
type |
string | — | Comma-separated event types, e.g. payout.completed,payout.failed,payout.returned. Unknown values are a 400. |
list_approvals
Section titled “list_approvals”| Argument | Type | Required | Description |
|---|---|---|---|
status |
string | — | pending, approved, rejected, expired, executing, executed, execution_failed, execution_unknown. |
limit |
number | — | 1-100, default 50. |
get_approval
Section titled “get_approval”| Argument | Type | Required | Description |
|---|---|---|---|
approvalId |
string | yes | The approvalId a 202 returned. |
list_audit_events
Section titled “list_audit_events”| Argument | Type | Required | Description |
|---|---|---|---|
cursor |
string | — | A nextCursor from a previous page. Digits only. |
limit |
number | — | 1-100, default 50. |
action |
string | — | e.g. payout.create, payout_batch.confirm, recipient.delete, api_key.rotate. |
resourceId |
string | — | Everything done to one payout, batch, approval, beneficiary, key or endpoint. |
apiKey |
string | — | A key prefix. |
actorUserId |
string | — | Only events by this dashboard user. |
createdAfter |
string | — | Inclusive, ISO-8601 with a timezone. |
createdBefore |
string | — | Inclusive, ISO-8601 with a timezone. |
list_balance_transactions
Section titled “list_balance_transactions”| Argument | Type | Required | Description |
|---|---|---|---|
cursor |
string | — | A nextCursor from a previous page. Digits only. |
limit |
number | — | 1-100, default 100. |
type |
string | — | Comma-separated: funding, payout, payout_return, hold, hold_release, adjustment. |
orderId |
string | — | Everything that moved for one payout. |
currency |
string | — | Only rows in this currency, such as USD. |
createdAfter |
string | — | Inclusive, ISO-8601 with a timezone. |
createdBefore |
string | — | Inclusive, ISO-8601 with a timezone. |
get_funding
Section titled “get_funding”| Argument | Type | Required | Description |
|---|---|---|---|
payoutId |
string | yes | The payout’s payoutId. |
create_payout_link
Section titled “create_payout_link”| Argument | Type | Required | Description |
|---|---|---|---|
amount |
string | yes | Decimal string, e.g. “200.00”. |
destinationCurrency |
string | yes | ISO code, e.g. MXN |
endUserId |
string | yes | Your id for the person being paid. |
reference |
string | — | Your reference, echoed on the payout it creates. |
expiresInMinutes |
number | — | 1-10080, default 60. |
idempotencyKey |
string | yes | Required. A unique id you generate for this link. Reusing it replays the original link instead of minting a second one. |
confirm |
boolean | yes | Must be true. Explicit acknowledgement that this mints a link that pays out. |
create_product
Section titled “create_product”| Argument | Type | Required | Description |
|---|---|---|---|
name |
string | yes | The product name buyers see. |
currency |
string | yes | ISO code, e.g. USD |
unitAmount |
string | yes | Decimal string above zero, e.g. “150.00”. |
description |
string | — | Shown to buyers on the checkout page. |
create_checkout_link
Section titled “create_checkout_link”| Argument | Type | Required | Description |
|---|---|---|---|
productId |
string | — | The product’s id. |
currency |
string | — | Required without productId. |
items |
array | — | Required without productId. |
successUrl |
string | — | https only. |
cancelUrl |
string | — | Same rule as successUrl. |
clientReferenceId |
string | — | Letters, digits, - and _, up to 200. |
metadata |
object | — | Your own string key-value pairs, echoed back verbatim. |
fromName |
string | — | The seller name shown on the checkout page. |
memo |
string | — | A note shown to the buyer. |
expiresAt |
string | — | When the link stops taking payments: ISO-8601 with a timezone, in the future, at most a year away. Past it the page answers 410 and status reads expired. Omit for no deadline. |
publish |
boolean | — | true to make it live in the same call. |
update_checkout_link
Section titled “update_checkout_link”| Argument | Type | Required | Description |
|---|---|---|---|
linkId |
string | yes | The checkout link’s id. |
expiresAt |
string,null | — | New deadline (ISO-8601 with a timezone, future, within a year), or null to clear it. |
successUrl |
string | — | Drafts only. https only. |
cancelUrl |
string | — | Drafts only. https only. |
clientReferenceId |
string | — | Drafts only. |
metadata |
object | — | Drafts only. Replaced whole. |
memo |
string | — | Drafts only. |
get_checkout_link
Section titled “get_checkout_link”| Argument | Type | Required | Description |
|---|---|---|---|
linkId |
string | yes | The checkout link’s id. |
list_checkout_links
Section titled “list_checkout_links”| Argument | Type | Required | Description |
|---|---|---|---|
status |
string | — | Only links in this status. |
source |
string | — | api: links made with an API key. dashboard: made by a person. Omit for both. |
limit |
number | — | Page size. |
cursor |
string | — | The nextCursor from the previous page. |
refund_checkout_payment
Section titled “refund_checkout_payment”| Argument | Type | Required | Description |
|---|---|---|---|
paymentId |
string | yes | The payment id from list_checkout_payments. |
amount |
string | — | Decimal string in the payment’s currency, e.g. “12.50”. list_checkout_payments gives amountBase in minor units: divide by 10^decimals. Omit to refund everything still refundable. |
reason |
string | — | Why you are refunding. |
note |
string | — | For the merchant’s team; never shown to the buyer. |
idempotencyKey |
string | yes | A new key per refund. Reuse it only to retry that same refund. |
confirm |
boolean | yes | Must be true. The tool refuses to run without it. |
pause_checkout_link
Section titled “pause_checkout_link”| Argument | Type | Required | Description |
|---|---|---|---|
linkId |
string | yes | The checkout link’s id. |
confirm |
boolean | yes | Must be true. The tool refuses to run without it. |
publish_checkout_link
Section titled “publish_checkout_link”| Argument | Type | Required | Description |
|---|---|---|---|
linkId |
string | yes | The draft’s id from create_checkout_link. |
list_checkout_payments
Section titled “list_checkout_payments”| Argument | Type | Required | Description |
|---|---|---|---|
linkId |
string | yes | The checkout link’s id. |
limit |
number | — | Page size. |
cursor |
string | — | The nextCursor from the previous page. |
confirm_funding
Section titled “confirm_funding”| Argument | Type | Required | Description |
|---|---|---|---|
payoutId |
string | yes | The payout’s payoutId. |
transactionHash |
string | yes | 0x-prefixed 32-byte hex. |
confirm |
boolean | yes | Must be true. This commits funds you have already sent. |
cancel_payout
Section titled “cancel_payout”| Argument | Type | Required | Description |
|---|---|---|---|
payoutId |
string | yes | The payout’s payoutId. |
confirm |
boolean | yes | Must be true. Canceling is irreversible. |
find_payee
Section titled “find_payee”| Argument | Type | Required | Description |
|---|---|---|---|
query |
string | — | A name or email, e.g. Maria. |
limit |
number | — | 1-20, default 5. |
list_payments
Section titled “list_payments”| Argument | Type | Required | Description |
|---|---|---|---|
limit |
number | — | How many, newest first (1-50, default 10). |
cursor |
string | — | nextCursor from the previous page. |
from |
string | — | First day, YYYY-MM-DD. |
to |
string | — | Last day, YYYY-MM-DD (included). |
payee |
string | — | Only payments to someone whose name contains this. |
direction |
string | — | Default out. |
inFlight |
boolean | — | Only payments still on their way. |
prepare_payment
Section titled “prepare_payment”| Argument | Type | Required | Description |
|---|---|---|---|
filename |
string | yes | The file name, e.g. inv-104.pdf. |
contentType |
string | yes | The file type: a PDF or a PNG/JPEG image of the invoice. |
dataBase64 |
string | yes | The file, base64-encoded. |
prepare_payment_to_payee
Section titled “prepare_payment_to_payee”| Argument | Type | Required | Description |
|---|---|---|---|
payeeId |
string | yes | A saved payee’s id (list_beneficiaries). |
amount |
string | yes | How much the payee gets, in their currency, e.g. “1200.50”. |
currency |
string | — | ISO code, e.g. EUR. Needed only when the payee is paid in more than one currency. |
methodId |
string | — | One of the payee’s saved accounts: a paymentMethods[].id from list_beneficiaries. |
reference |
string | — | What it is for, shown to the payee: a plain bank memo, A-Z 0-9 and . , ’ / # ( ) & : - (140 characters). |
idempotencyKey |
string | yes | Yours: a retry with the same key is the same request, never a second payment. |
get_package
Section titled “get_package”| Argument | Type | Required | Description |
|---|---|---|---|
packageId |
string | yes | The id prepare_payment or prepare_payment_to_payee returned. |
answer_question
Section titled “answer_question”| Argument | Type | Required | Description |
|---|---|---|---|
packageId |
string | yes | The id prepare_payment or prepare_payment_to_payee returned. |
field |
string | yes | A questions[].field from get_package. |
value |
string | yes | The answer. |
list_invoices
Section titled “list_invoices”| Argument | Type | Required | Description |
|---|---|---|---|
filter |
string | — | Default unpaid. |
client |
string | — | Only invoices to a client with this name. |
get_invoice
Section titled “get_invoice”| Argument | Type | Required | Description |
|---|---|---|---|
invoiceId |
string | yes | From list_invoices or draft_invoice. |
draft_invoice
Section titled “draft_invoice”| Argument | Type | Required | Description |
|---|---|---|---|
client |
string | yes | The client, e.g. “Acme” (a saved client is matched). |
amount |
string | yes | How much, e.g. “1200” or “1,200.50”. |
currency |
string | — | ISO code, e.g. USD. Leave out to use the client’s (or business’s) usual one. |
description |
string | — | What it is for. |
dueDate |
string | — | YYYY-MM-DD. |
dueInDays |
number | — | Due in this many days. |
email |
string | — | The client’s email, if known. |
send_invoice
Section titled “send_invoice”| Argument | Type | Required | Description |
|---|---|---|---|
invoiceId |
string | yes | From list_invoices or draft_invoice. |
Was this page helpful?