Calling the API from your app

When a merchant installs your app, the platform mints an API key for their workspace and hands it to you, server-to-server, at /install/provision. That key is how your app acts on Sentralbee — reading orders, recording payments, whatever the merchant consented to. There’s no key to paste and no login to manage; the platform did that part. This page is about using that key. It picks up where Install lifecycle leaves off: you’ve received the key and stored it encrypted, and now you want to call the API with it. One thing to hold onto: the key is scoped to exactly the scopes the merchant consented to — your manifest’s scopes, nothing more. If a call needs a permission you didn’t ask for, it comes back rejected. So the API surface your app can reach is decided at install time, not at call time. See Scopes & permissions.

Build a client

You stored the key encrypted, so the first step is always to decrypt it, then build a client with it. The same createCypher you used to encrypt on install decrypts here:

import { createCypher, sentralbeeClient } from '@sentralbee/app-sdk';

const cypher = createCypher(process.env.APP_KEY!); // your own secret; fails closed if unset

const apiKey = await cypher.decryptSecret(row.api_key_enc);
const client = sentralbeeClient({ apiKey });

sentralbeeClient({ apiKey, baseUrl? }) takes the decrypted key. It defaults to the production API at https://api.sentralbee.app; pass baseUrl only if you’re pointing at a dev gateway. The client sends the key on every request for you, so you never build the auth header by hand.

Decrypt the key when you need it and let it go — don’t hold a plaintext key or a built client in a long-lived global. The stored copy stays encrypted at rest.

Record a payment

The one typed method today is markOrderPaid. Your app calls it to record that money arrived against an order — for a “pay by bank transfer” app, this is the whole point: you confirmed the transfer, now you tell Sentralbee the order is paid.

const result = await client.markOrderPaid({
	orderId: 'ord_123',
	amountMinor: 1_400_000, // minor units (kobo/cents)
	reference: 'txn_abc', // idempotency key — the same reference records once
});

Two details matter here. Amounts are in minor units. amountMinor is kobo or cents, not naira or dollars — 1_400_000 is ₦14,000.00. Sending whole units would record a payment a hundred times too small. reference is the idempotency key, and it’s required. Pass the payment’s own reference from your provider. If the same reference comes in twice — a retry, a duplicate webhook, a double-tap — Sentralbee records the payment once. That’s what makes it safe to call this method again after a network blip without paying an order twice. markOrderPaid needs the sale_payment scope. Declare it in your manifest’s scopes so the key the merchant consents to carries it; without it the call is rejected.

Input

Field	Type	Required	Notes
`orderId`	string	yes	The order to record the payment against.
`amountMinor`	number	yes	Amount in minor units (kobo/cents).
`reference`	string	yes	Idempotency key. The same reference is recorded once.
`currency`	string	no	Defaults server-side to the order’s currency.
`provider`	string	no	Free-text label recorded on the payment (e.g. your app’s name).

Result

You get back the order’s payment state after the change:

{
	"order_id": "ord_123",
	"payment_status": "PAID",
	"amount_paid_base": 14000.0,
	"amount_due": 0.0
}

amount_paid_base and amount_due come back in base units (naira/dollars) — the human-readable amounts, the mirror of the minor units you sent in.

Any other endpoint

The typed surface grows on demand, so it stays small on purpose. Until a method exists for what you need, reach for the escape hatch — request(method, path, body) calls any public endpoint with your key attached:

// read an order
const order = await client.request('GET', '/v1/orders/ord_123');

// anything with a body
await client.request('POST', '/v1/some/endpoint', { field: 'value' });

It’s the same authenticated client, just untyped: you pass the method, the path, and an optional body, and you get the parsed JSON back. Everything the key is allowed to do is reachable this way. The API reference documents every endpoint, path, and shape.

When a call fails

Both markOrderPaid and request throw a SentralbeeApiError on any non-2xx response. It carries what you need to react:

import { SentralbeeApiError } from '@sentralbee/app-sdk';

try {
	await client.markOrderPaid({ orderId, amountMinor, reference });
} catch (err) {
	if (err instanceof SentralbeeApiError) {
		// err.status  → the HTTP status (403, 404, …)
		// err.body    → the parsed error JSON from the API
		// err.message → a short summary
	}
	throw err;
}

A 403 here usually means the key lacks a scope the merchant never consented to — check your manifest’s scopes against what the call needs. The Errors page lists the shapes and status codes the API returns.

Where to next

Checkout — where markOrderPaid fits in a payment flow.
Scopes & permissions — what your key is allowed to do.
API reference — every endpoint you can reach with request.
Install lifecycle — how you got the key, and how to store it.
Errors — what a failed call looks like.

Get Started

Build your app

Reference

Build a client

Record a payment

Input

Result

Any other endpoint

When a call fails

Where to next

​Build a client

​Record a payment

​Input

​Result

​Any other endpoint

​When a call fails

​Where to next

Build a client

Record a payment

Input

Result

Any other endpoint

When a call fails

Where to next