Charge any amount

Send an amount and a description from your server and the buyer pays exactly that. There's no product to create first. Use it when your own system decides the price:

• a cart total or an invoice;
• a wallet top-up, a deposit or a booking fee;
• anything priced per request, such as delivery or a quote.

If you sell a fixed catalog and want hosted pages, checkout links or license keys, use a product instead. Product or custom amount? compares the two.

Charge 1,237 ETB

You need an API token. Custom amounts only work from your server, never from a browser.

npm install jami-sdk  # 0.5.0 or later

import { Jami } from 'jami-sdk';

const jami = new Jami({ token: process.env.JAMI_TOKEN! });

const checkout = await jami.createCheckout({
  amount: 123700,                        // 1,237.00 ETB in santim
  description: 'Order #1042 — 3 prints', // what the buyer sees
  metadata: { orderId: '1042' },         // optional, comes back on the webhook
  customer: { email: 'buyer@example.com', phone: '251911223344' },
  gateway: 'telebirr',                   // 'telebirr' | 'mpesa' | 'cbe'
});

const status = await jami.waitForCheckout(checkout.sessionId);
console.log(status.status, status.orderId); // 'completed' '6710c31f…'

curl https://jami.bio/api/jamidev/checkout \
  -H "Authorization: Bearer $JAMI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 123700,
    "description": "Order #1042 — 3 prints",
    "metadata": { "orderId": "1042" },
    "customer": { "email": "buyer@example.com", "phone": "251911223344" },
    "gateway": "telebirr"
  }'

This one pushes the prompt to the buyer's phone. If you don't have their phone, or you'd rather send them a link, leave out gateway; see the next section. In a sandbox organization, use phone 251900000001 to pay instantly or 251900000002 to see a failure.

Collect the payment: push or link

Every checkout, for a custom amount or for a product, can be collected in one of two ways. You choose with gateway.

Direct push is the example above: your server talks to the buyer's phone, and no Jami page is involved.

Payment link:

const { checkoutUrl, sessionId } = await jami.createCheckout({
  amount: 123700,
  description: 'Order #1042 — 3 prints',
  metadata: { orderId: '1042' },
});

await sendSms(buyerPhone, `Pay for your order: ${checkoutUrl}`);
// Store sessionId; the order.completed webhook carries it.

The same works for a product: jami.createCheckout({ productId: 'p_…' }), plus amount for a flexible-price product. Nothing is charged until the buyer pays on the link.

Payment links

A link is made for one checkout: one amount, one buyer, one payment. On the page the buyer:

• sees your organization's name, the amount and the description (or the product's title, description and first image);
• enters their phone, and their email for the receipt unless you passed customer;
• picks Telebirr, CBE Birr, or More, which opens ArifPay's page with every method on the account, M-Pesa included;
• confirms the prompt and lands on the success page, which links back to your successUrl if you set one.

The amount is locked: the buyer can't change it.

Retries. If an attempt fails (wrong PIN, timed out, rejected), the link stays open, says why, and offers Try again. The buyer can retry until the link expires. While a prompt is on its way, a new attempt is refused for 150 seconds, so a double tap can't send two prompts.

Expiry. A link lasts as long as its session: 30 minutes from createCheckout. After that the page says it has expired and nothing more can be paid. The checkout.session.expired webhook fires then, not after each failed attempt, and its failure is the last attempt's reason (or session_expired if nobody tried). Jami closes expired sessions itself within about 30 seconds, so the webhook arrives even if nobody opens the link or polls it.

Paid. Once paid, the link shows "Already paid" with the receipt. You get order.completed as for any checkout.

Status while it's open. Polling a link's session returns an extra attempt object, so you can tell "the buyer is trying" from "the last try failed":

{ "status": "open", "attempt": { "inFlight": false, "lastFailure": { "code": "payment_timed_out", "message": "…" } } }

Sandbox. Links work in a sandbox organization. Enter 0900000001 on the page to pay instantly or 0900000002 to fail; any other number opens the simulator.

Links need an API token. A checkout started without a token, such as from your product's own page, works as before.

What the buyer sees

The description takes the place of a product title:

• on the payment prompt on their phone, and on the payment link if you sent one;
• in their receipt email and your sale email;
• on the hosted success, cancel and error pages;
• in the latest orders on your dashboard overview, in GET /orders (description) and in order webhooks.

In the dashboard's Orders list these payments appear under Custom payment.

Write it the way you'd write a line on a receipt: Order #1042 — 3 prints, Wallet top-up, Booking deposit, 12 Oct. Keep it under 120 characters.

On the hosted cancel and error pages, Try again goes back to the payment link. For a direct push there's no page to go back to, so the button is hidden; start a new checkout from your own site.

Match the payment to your order

You have two handles, and the webhook carries both:

• sessionId, returned by createCheckout. Store it next to your order. Every order and session webhook has it as data.sessionId.
• metadata, your own key/values. They're saved on the order and sent back in order.created and order.completed as data.metadata.

const event = await jami.webhooks.verify({ payload: rawBody, signature, secret });

if (event.type === 'order.completed') {
  const { metadata, description, amount, sessionId } = event.data;
  await markPaid(metadata.orderId, { amount, sessionId }); // amount is 123700
}

data.description is the description you sent; for product checkouts it's null. See Webhooks for the full payload.

Rules

Buyers pay exactly amount. Fees come out when you withdraw, never at checkout.

Errors

All 400, with the message in error:

The SDK checks amount and description before sending, and throws JamiValidationError. Other errors, such as an invalid email, a missing phone or a bad token, are the same as for any checkout.

Product or custom amount?

Both produce the same orders, webhooks and payouts, and both work in sandbox.