Become a payment method

A checkout app is a payment method. When a merchant installs it, your button shows up at their storefront checkout next to the built-in providers — and when a shopper picks it, the storefront hands the payment off to you. This is the same pluggable seam Stripe and Paystack plug into; nothing about your app is hardcoded into the storefront. The storefront never renders payment details itself. It asks the platform to create a checkout with your app, and opens your hosted pay page in an iframe modal. You run the payment however you like — a bank transfer, a wallet, a QR code — and when it clears you tell Sentralbee the order is paid. The storefront polls the order’s status and moves the shopper on. To build one you need three things: an installed app that holds the sale_payment scope, a checkout block in your manifest, and two endpoints of your own — one the platform calls to start a checkout, one that serves the pay page to the shopper.

 shopper picks your method
      │
      ▼
 platform POSTs your checkout.create_path   (session token → your workspace)
      │   → you create a payment and return { redirectUrl }
      ▼
 storefront opens redirectUrl in an iframe modal   (your hosted pay page)
      │   → shopper pays; you confirm it out-of-band
      ▼
 you call client.markOrderPaid(…)           (sale_payment scope)
      │
      ▼
 storefront polls the order status → advances automatically

1. Declare checkout in your manifest

Add a checkout block, and request the sale_payment scope so you can record the payment later:

{
	"provider": "acme-pay",
	"name": "Acme Pay",
	"scopes": [{ "pattern": "sale_payment", "create": true }],
	"checkout": {
		"create_path": "/checkout/sessions",
		"label": "Pay with Acme",
		"description": "Bank transfer, confirmed in seconds",
		"button_color": "#2f4bff",
		"button_text_color": "#ffffff",
		"icon_path": "/icon.svg"
	}
}

The only required field is create_path, and it must start with /. The rest are presentation:

Field	What it does
`create_path`	The path the platform POSTs to start a checkout. Returns `{ redirectUrl }`.
`label`	The button text, e.g. `Pay with Bank Transfer`.
`description`	Helper copy shown with the button.
`button_color` / `button_text_color`	CSS colour strings for the button.
`icon_path`	A leading icon, resolved under your app’s public base (e.g. `/icon.svg`).

The storefront identifies your method by your app’s top-level provider — you own the button, and the storefront hardcodes nothing app-specific. See The manifest for the full schema.

2. Create the checkout

When a shopper picks your method, the platform brokers a call to create_path. It’s session-authed, so the workspace comes from the verified token — never from the body. Create your payment, then return the URL of your hosted pay page:

checkout.post('/sessions', async (c) => {
	const workspace = c.get('workspace'); // from the session token, not the body
	const { orderId, amountMinor, currency } = await c.req.json();

	const session = await createPaymentSession(workspace, {
		orderId,
		amountMinor,
		currency,
	});

	return c.json({ redirectUrl: `${PUBLIC_URL}/pay/${session.id}` });
});

Amounts arrive in minor units (kobo, cents) — the same units the public API uses, so you can pass them straight through when you record the payment.

3. Host your pay page

The redirectUrl opens inside an iframe modal on the storefront. This page is public: the shopper isn’t signed in to your app, so the unguessable session id in the URL is the bearer. Look it up, 404 if it’s unknown, and render the amount and instructions:

pay.get('/:id', (c) => {
	const session = getPaymentSession(c.req.param('id')); // the id is the bearer
	if (!session) return c.notFound();
	return c.html(renderPayPage(session)); // show the amount + how to pay; poll for status
});

The pay page is reachable without a token. Keep the id long and random, scope it to one order, and expire it — treat it like a one-time link, not a page anyone can enumerate.

4. Mark the order paid

However you confirm the payment — a provider webhook, a poll of your own, a bank callback — the last step is the same: tell Sentralbee the order is paid. Build a client with your stored, decrypted app key (see Calling the API) and call markOrderPaid:

const client = sentralbeeClient({ apiKey: decrypt(stored.apiKey) });

const result = await client.markOrderPaid({
	orderId: session.orderId,
	amountMinor: session.amountMinor,
	currency: session.currency,
	reference: providerTransactionId, // idempotency key — REQUIRED, safe to retry
	provider: 'acme-pay', // free-text label recorded on the payment
});
// → { order_id, payment_status, amount_paid_base, amount_due }

Two things matter here. markOrderPaid needs the sale_payment scope, which is why you asked for it in the manifest. And reference is required and is your idempotency key — the same reference is recorded once, so if your confirmation fires twice (webhooks retry, jobs re-run) the order isn’t paid twice. Use the payment’s own transaction id. You don’t signal the storefront directly. It polls the order’s status and advances the shopper as soon as markOrderPaid lands. If you want the modal to close a beat sooner, the pay page may post a hint to the parent — but the poll is the source of truth, so this is only a nicety:

window.parent.postMessage(
	{ source: 'sentralbee-checkout', status: 'paid' },
	'*',
);

The reference app

The Moniepoint “Pay with Bank Transfer” app implements this end to end: create a session, host the pay page, reconcile the transfer from a provider webhook, then markOrderPaid. It’s the canonical checkout app — worth reading alongside this page when you build your own.

Where to next

The manifest — the full checkout and scopes schema.
Calling the API — building the client and storing your key.
Webhooks — receiving signed platform events to reconcile payments.
Concepts & lifecycle — the session token and the golden rule behind c.get("workspace").

Get Started

Build your app

Reference

1. Declare checkout in your manifest

2. Create the checkout

3. Host your pay page

4. Mark the order paid

The reference app

Where to next

​1. Declare checkout in your manifest

​2. Create the checkout

​3. Host your pay page

​4. Mark the order paid

​The reference app

​Where to next

1. Declare checkout in your manifest

2. Create the checkout

3. Host your pay page

4. Mark the order paid

The reference app

Where to next