Skip to main content
Glama

Create charge

charges_create

Create a test charge with an amount, accepted token/network pairs, and expiry; pass an idempotency key to prevent duplicate charges on retries.

Instructions

Create a new test charge. Escrow charges and redirectUrl are not available through this server. Pass idempotencyKey to make a retry safe; without it every call creates a new charge.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "amount": "<amount>",
      "acceptedPayments": "<acceptedPayments>",
      "expiresIn": "<expiresIn>"
    },
    "name": "charges_create"
  }
}

Input Schema

NameRequiredDescriptionDefault
amountYesAmount to charge, in `currency` units (e.g. `49.9` = $49.90) — up to 6 decimal places; anything more precise is silently truncated. Required — every charge has a target amount, the first credited transfer that reaches it confirms the charge. With `feePayer: 'payer'` (see below), this is your own desired net amount, not the total the payer ends up sending — the response's `amount` is grossed up to cover `feePercent`, while `merchantAmount` on the response echoes back this exact value.
sourceNoFree-form label for what created this charge (e.g. `"checkout"`, `"invoice"`) — useful if you create charges from more than one flow and want to tell them apart later. Not a fixed enum; use whatever values make sense to you.
currencyNoAlways `USD` today — the only supported currency.USD
feePayerNoWho ends up covering Klappay's `feePercent`. `merchant` (default): `amount` is exactly what you asked for, and Klappay's fee is deducted from your own payout — you net `amount * (1 - feePercent / 100)`. `payer` : `amount` is grossed up at creation time so that, after the same fee deduction, you still net the amount you originally requested — the payer sees and sends the larger, fee-inclusive total. Frozen at creation like every other fee input; does not change how `feeAmount`/`merchantAmount` are computed on read, only what `amount` was set to in the first place.merchant
metadataNoArbitrary key/value data, returned as-is on every read. Put whatever you want in here — none of it is validated, except the `klappay` key, which is reserved for Klappay: if present, it must match `KlappayCheckoutMetadataSchema` exactly, or the whole request is rejected with `400 validation_error`.
expiresInYesSeconds, not minutes or milliseconds — how long the charge stays open before it expires. Required, min 60, max 3600 (60 minutes) — sized off the slowest chain Klappay supports today (Ethereum mainnet, where a safely-confirmed transfer takes up to ~15 minutes), leaving real margin for payer-side delay (gas spikes, wallet friction) on top of that. Cannot be extended or shortened after creation.
externalRefNoAn opaque correlation id from your own system (e.g. an order id) — echoed back on the charge and in every webhook payload. Not interpreted or validated by Klappay.
idempotencyKeyNoScoped to your tenant. Replaying the same key with the exact same request body returns the original charge unchanged instead of creating a duplicate — safe to retry a request after a timeout without double-charging. Reusing the same key with a different body (including a different `escrow` config) is rejected with `409 idempotency_key_reused`, never silently returned as the original charge.
splitRecipientsNoOptional extra recipients for this charge's split — e.g. a supplier or the sales rep who closed the deal — up to 5, each referenced by `recipientId` (see `POST /v1/recipients`), never a raw address. Requires the `charges:split_write` scope in addition to `charges:write`. Frozen at creation exactly like everything else that shapes the split address; cannot be changed afterward. The sum of every `percent` here must fit within `100 - feePercent` (your own net share) — a request that doesn't is rejected with `422 split_recipients_exceed_available_percent`.
acceptedPaymentsYesEvery `(token, network)` pair the payer is allowed to pay with — at least one, up to 18. This list is also the only restriction knob: the payer can use any combination of the pairs listed here, and every transfer on one of them is credited and sums toward the charge total (see `paidWith`) — e.g. a charge accepting USDC and USDT can be confirmed by $9 in USDC plus $1 in USDT, or by USDC arriving on two different accepted networks. To require payment in one specific token on one specific network, list only that single pair — a transfer on any pair not in this list is still recorded (for audit) but never credited. Each network must be live (see `GET /v1/networks` for the current matrix) — an unconfigured `(token, network)` combination for your environment is rejected with `422 token_not_supported`. Every network listed must also share the same split family (which networks are grouped together is an implementation detail, not part of this API's contract) — a charge predicts one split address up front and reuses it across every accepted network, which is only safe within one family; mixing families is rejected with `400 validation_error`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare idempotentHint=false, and the description supplies the operational consequence: without idempotencyKey every call creates a new charge, which is genuine value beyond the boolean. The disclosure that escrow and redirectUrl are unavailable is server-level behavioral context the schema cannot express. It does not cover auth/scope requirements (the schema mentions charges:write and charges:split_write) or the response shape, keeping it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core action, then the unsupported-feature exclusion, then the retry-safety caveat. No hedging, no restatement of the name, and every clause carries actionable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter creation tool with nested objects and no output schema, the description correctly focuses on the two things the schema cannot convey: environment limitations and idempotency failure modes. Given the extremely rich per-field schema, nothing critical is missing, though a one-line note on what is returned (charge id / hosted checkout URL) would help an agent chain calls.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the parameter descriptions are unusually thorough (feePayer math, split percent semantics, acceptedPayments crediting rules), so the schema already carries parameter meaning. The description's only parameter remark is about idempotencyKey, which the schema already documents in detail. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Create a new test charge') and immediately flags the 'test' qualifier, which is meaningful scope. It does not explicitly name or differentiate against siblings like charges_get or charges_check, but the verb/resource pairing is unambiguous enough that an agent can distinguish a creation call from the read/prepare siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear negative guidance: escrow charges and redirectUrl are not available through this server, which prevents a class of doomed attempts. It also gives a conditional instruction for idempotencyKey ('Pass idempotencyKey to make a retry safe'). It stops short of naming an alternative tool for the unsupported escrow/redirect flows, so the agent knows what not to do but not where to go instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.