jami-mcp

Create checkout

jami_create_checkout

Create a checkout for a published product or custom amount in Ethiopian birr, returning a payment link or direct mobile payment prompt via Telebirr, M-Pesa, or CBE Birr.

Instructions

Start a checkout and get back how the buyer pays — either for one of the organization's published products, or for ANY amount with no product ("charge this buyer 1,237 ETB for order #1042").

Buyers pay in ETB via Telebirr, M-Pesa or CBE Birr; nothing is added on top. In LIVE mode a "direct" checkout pushes a real payment prompt to the buyer's phone, so only call this when the user actually wants to charge someone.

What to charge:

Product: product_id (p_… token or 24-char id, must be published). amount_minor only for flexible-price (pwyw) products.
Custom amount: omit product_id, pass amount_minor (≥ 100 = 1.00 ETB) and description (what the buyer sees, ≤ 120 chars).

How to collect it:

Direct push: pass gateway + customer_email + customer_phone. The prompt goes straight to the buyer's phone (kind 'direct').
Payment link: omit gateway. You get a Jami link in checkout_url (kind 'redirect') to send the buyer by SMS/Telegram/email; they pick the method and enter their details there, and can retry a failed attempt until the link expires (30 min). customer_* is optional.

Args:

customer_email / customer_phone: required for a direct push; optional for a link. Phone like "251911223344" or "0911223344". Sandbox magic numbers: 251900000001 = instant success, 251900000002 = instant failure.
gateway: 'telebirr' | 'mpesa' | 'cbe'. Omit for a payment link.
amount_minor: integer santim. 123700 = 1,237.00 ETB.
metadata: optional string map (e.g. { "orderId": "1042" }) stored on the order and sent back on order webhooks.

Returns: { session_id, kind: 'free' | 'redirect' | 'direct', checkout_url, order_id }.

free: completed instantly; order_id is set.
redirect: send the buyer to checkout_url.
direct: the buyer confirms on their phone; call jami_wait_for_checkout next.

Input Schema

TableJSON Schema

Name	Required	Description
`gateway`	No	Payment method for paid products
`metadata`	No	Your own key/values, returned on order webhooks (max 20 keys)
`product_id`	No	Product token (p_…) or id. Omit for a custom-amount checkout.
`description`	No	Custom amount only: what the buyer is paying for, e.g. "Order #1042"
`success_url`	No	Where to send the buyer after paying
`amount_minor`	No	Integer santim. Required for custom amounts (≥ 100) and pay-what-you-want products; ignored for fixed prices
`checkout_link`	No	Checkout link token (cl_…) to attribute this session to
`customer_name`	No
`customer_email`	No	Buyer email for the receipt. Required with gateway; optional for a payment link
`customer_phone`	No	Buyer phone, e.g. "251911223344"
`collected_fields`	No	Answers to the product's checkout fields, keyed by field id
`customer_external_id`	No	Your own user id, stored on the customer record

Output Schema

TableJSON Schema

Name	Required	Description	Default
`kind`	Yes
`order_id`	Yes
`session_id`	Yes
`checkout_url`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Oct 16, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations declare mutation/non-idempotent/open-world, but the description adds substantial context they don't carry: LIVE mode pushes a real payment prompt to a phone, link expiry is 30 minutes, failed attempts can be retried, ETB-only payment with nothing added on top, and sandbox magic numbers for instant success/failure. This is unusually rich operational disclosure.

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

Conciseness4/5

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

Well front-loaded with the core outcome first, then structured 'What to charge' / 'How to collect it' / Args / Returns sections that are easy to scan. It is somewhat long and a few lines (phone format, amount_minor units) duplicate schema text, but the structure justifies the length.

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

Completeness5/5

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

Covers modes, gateway selection, when-to-call caution, error/retry behavior, expiry, and next-step routing; an output schema exists yet the description still summarizes the return shape (session_id/kind/checkout_url/order_id) and how to act on each kind. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema description coverage is already 92%, so the schema carries most parameter detail. The description nonetheless adds cross-parameter semantics the schema cannot express: product_id vs. amount_minor mutual exclusion, gateway-driven kind selection, and required/optional status of customer_email/customer_phone per mode. It omits explanation of secondary params (success_url, checkout_link, collected_fields, customer_external_id), keeping it from a 5.

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

Purpose5/5

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

States a specific verb+resource ('Start a checkout and get back how the buyer pays') and immediately distinguishes the two modes it serves: a published product vs. an arbitrary custom amount. It also names the sibling workflow it feeds into (jami_wait_for_checkout), so an agent can place it in the toolset without opening the schema.

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

Usage Guidelines5/5

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

Explicitly states when NOT to call it ('only call this when the user actually wants to charge someone') and lays out the decision between direct push vs. payment link with the exact parameter conditions (pass gateway vs. omit gateway). It routes the agent to jami_wait_for_checkout for the direct case, which is explicit alternative guidance.

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

Deploy Server