Create charge
charges_createCreate 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
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | Amount 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. | |
| source | No | Free-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. | |
| currency | No | Always `USD` today — the only supported currency. | USD |
| feePayer | No | Who 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 |
| metadata | No | Arbitrary 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`. | |
| expiresIn | Yes | Seconds, 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. | |
| externalRef | No | An 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. | |
| idempotencyKey | No | Scoped 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. | |
| splitRecipients | No | Optional 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`. | |
| acceptedPayments | Yes | Every `(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`. |