Build payments, commerce, and operations with TenkiPay

Quickstart

Integrate hosted checkout into your web application in four high-level steps, then follow the end-to-end guide below to go from zero to a verified payment in the sandbox and then live.

1. 1. Create an app

   Open the Business Portal, then Developer Center, and create one app per product or deployment.

2. 2. Issue a test key

   Choose only the scopes your backend requires and store the secret in a secret manager.

3. 3. Sign a request

   Sign the exact method, path, timestamp, and raw JSON body with HMAC SHA-256.

4. 4. Simulate payment

   Open the returned checkout URL and simulate success or failure without moving funds.

Choose the right TenkiPay surface

TenkiPay combines developer APIs with first-party customer, business, and agent channels. The HMAC merchant key grants access only to endpoints published in the OpenAPI contract; role-based app APIs require their own approved account and access token.

Environments and credentials

The API hostname is the same in both environments. The credential prefix selects the environment and every resource is isolated by business, developer app, and environment.

Credentials expire after 180 days in sandbox and 365 days in live. An app may have at most 10 active keys per environment. Rotate by issuing a replacement, deploying it, confirming successful traffic, and then revoking the old key.

Authentication

Every merchant API request is authenticated with an HMAC signature. Send the three authentication headers on reads and writes; send Idempotency-Key on write endpoints that require it.

{timestamp}\n{UPPERCASE_METHOD}\n{/api/path}\n{exact_raw_body}

Idempotency and safe retries

Idempotency prevents a timeout or network retry from creating duplicate payment resources. Generate the key in your backend and persist it with your local operation before calling TenkiPay.

Keys must be 8-191 characters and may contain letters, numbers, period, underscore, colon, and hyphen. A practical format is order-1001-checkout-v1. Use a new key only for a genuinely new business operation.

Create a server-side payment session and send the customer to the returned URL. The hosted page supports TenkiPay account sign-in and QR approval from an already signed-in TenkiPay app. Poll the merchant API or treat the signed webhook as the fulfilment trigger.

{
  "merchant_reference": "ORDER-1001",
  "amount": "250.00",
  "currency": "SLE",
  "description": "Online store order 1001",
  "success_url": "https://shop.example.com/orders/1001/paid",
  "cancel_url": "https://shop.example.com/orders/1001",
  "customer_name": "Optional customer name",
  "customer_phone": "+23276000000"
}

{
  "status": true,
  "message": "Checkout session created.",
  "data": {
    "session_id": "CS-20260805-EXAMPLE",
    "checkout_url": "https://me.tenkipay.com/checkout/CS-20260805-EXAMPLE",
    "merchant_reference": "ORDER-1001",
    "status": "AUTH_PENDING",
    "environment": "test",
    "approval_methods": ["TENKIPAY_APP_QR", "TENKIPAY_WEB_LOGIN"],
    "amount": "250.00",
    "currency": "SLE",
    "expires_at": "2026-08-05T13:00:00Z"
  }
}

<form method="POST" action="/payments/tenkipay">
  <input type="hidden" name="_csrf" value="{{ csrfToken }}">
  <input type="hidden" name="order_id" value="ORDER-1001">
  <button type="submit">Pay with TenkiPay</button>
</form>

app.post('/payments/tenkipay', requireUser, verifyCsrf, async (req, res) => {
  const order = await orders.findPendingForCustomer(
    req.body.order_id,
    req.user.id
  );
  if (!order) return res.sendStatus(404);

  // Return a canonical decimal string such as "249.50", not a JS float.
  order.expectedAmount = await orders.recalculateTotal(order.id);

  const session = await createSignedTenkiPayCheckout(order);
  await orders.attachCheckout(order.id, {
    sessionId: session.session_id,
    idempotencyKey: `checkout:${order.id}:v1`
  });

  return res.redirect(303, session.checkout_url);
});

import crypto from 'node:crypto';

const TENKIPAY_ORIGIN = process.env.TENKIPAY_BASE_URL || 'https://me.tenkipay.com';

async function signedTenkiPayRequest(method, path, payload, idempotencyKey) {
  const body = payload === null ? '' : JSON.stringify(payload);
  const timestamp = new Date().toISOString();
  const canonical = [timestamp, method.toUpperCase(), path, body].join('\n');
  const signature = crypto.createHmac('sha256', process.env.TENKIPAY_SECRET_KEY)
    .update(canonical, 'utf8')
    .digest('hex');

  const response = await fetch(`${TENKIPAY_ORIGIN}${path}`, {
    method,
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
      'X-TenkiPay-Key': process.env.TENKIPAY_PUBLIC_KEY,
      'X-TenkiPay-Timestamp': timestamp,
      'X-TenkiPay-Signature': signature,
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {})
    },
    ...(body ? { body } : {}),
    signal: AbortSignal.timeout(15000)
  });

  const result = await response.json();
  if (!response.ok) throw new Error(`TenkiPay ${response.status}: ${result.message}`);
  return result.data;
}

function createSignedTenkiPayCheckout(order) {
  return signedTenkiPayRequest(
    'POST',
    '/api/v1/merchant/checkout/sessions',
    {
      merchant_reference: order.reference,
      amount: order.expectedAmount,
      currency: order.currency,
      description: `Order ${order.reference}`,
      success_url: `${process.env.STORE_URL}/orders/${order.id}/payment-return`,
      cancel_url: `${process.env.STORE_URL}/orders/${order.id}`
    },
    `checkout:${order.id}:v1`
  );
}

function retrieveTenkiPayCheckout(sessionId) {
  const safeSessionId = encodeURIComponent(sessionId);
  return signedTenkiPayRequest(
    'GET',
    `/api/v1/merchant/checkout/sessions/${safeSessionId}`,
    null
  );
}

window.addEventListener('message', async (event) => {
  if (event.origin !== 'https://me.tenkipay.com') return;

  switch (event.data?.type) {
    case 'tenkipay.checkout.completed':
      // Verify the session from your server before fulfilling the order.
      await refreshOrderStatus(event.data.session_id);
      break;

    case 'tenkipay.checkout.cancelled':
      // Customer cancelled. Keep the order unpaid and free any reserves.
      await refreshOrderStatus(event.data.session_id);
      break;
  }
});

Checkout status model

Treat status values as case-sensitive stable codes. Only ACSC means the payment completed successfully.

Issue an itemized invoice with a stable external reference. TenkiPay returns a collection reference and payment URL that can be shared, embedded, or rendered as a QR code.

{
  "external_reference": "INV-ERP-1042",
  "customer_name": "Aminata Kamara",
  "customer_email": "aminata@example.com",
  "description": "August services",
  "currency": "SLE",
  "allow_partial_payments": false,
  "issued_on": "2026-08-05",
  "due_on": "2026-08-20",
  "publish": true,
  "items": [
    { "description": "Professional services", "quantity": 1, "unit_amount": "850.00" }
  ]
}

Reconcile using amount_due, amount_paid, and amount_outstanding. Test invoices and all resulting payment resources remain in the sandbox environment.

TenkiMarkit is TenkiPay's native commerce channel. A business publishes its storefront and listings, customers discover products through the public marketplace, and the platform carries the cart, order, payment, and receipt flow without a separate ecommerce integration.

TenkiMarkit catalog and order administration are not exposed as public Merchant API v1 endpoints. This prevents developers from depending on internal portal routes; integrations should use the documented Checkout or TenkiOps contracts.

Integrate TenkiPass verification at a gate, service desk, vehicle, or partner application. Redemption is idempotent and should occur only when the service is actually delivered.

{ "token": "TKPASS-..." }

Connect an existing hotel, retail, fuel, pharmacy, school, restaurant, or delivery system to TenkiOps. Workspaces, catalog, sales, fulfilment context, stock, rooms, stays, and checkout remain isolated by business and API environment.

All paths in this table are relative to /api/v1/merchant. GET calls require operations:read; POST calls require operations:write and an idempotency key. A sale can have multiple checkout attempts. Stock is posted only after verified payment, and a hotel room remains occupied until the final checkout balance is settled.

Webhooks

Webhooks are the asynchronous source of payment notifications. Configure separate test and live HTTPS endpoints in Developer Center. The signing secret is shown once and is different from your API secret key.

{unix_timestamp}.{exact_raw_request_body}

{
  "id": "evt_live_01J...",
  "event": "checkout.payment_completed",
  "livemode": true,
  "api_version": "2026-08-05",
  "created_at": "2026-08-05T12:35:18Z",
  "data": {
    "object": {
      "session_id": "CS-20260805-EXAMPLE",
      "merchant_reference": "ORDER-1001",
      "status": "ACSC",
      "environment": "live",
      "amount": "250.00",
      "currency": "SLE",
      "transaction_id": "TXN-...",
      "message_id": "MSG-...",
      "end_to_end_id": "E2E-...",
      "uetr": "...",
      "merchant": { "merchant_code": "MCH-...", "business_name": "Example Ltd", "display_name": "Example" },
      "debtor": { "name": "Customer", "account": "..." },
      "creditor": { "name": "Example Ltd", "account": "..." },
      "authorized_at": "2026-08-05T12:35:17Z",
      "completed_at": "2026-08-05T12:35:18Z"
    }
  }
}

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/tenkipay',
  express.raw({ type: 'application/json', limit: '256kb' }),
  async (req, res) => {
    const deliveryId = req.get('X-TenkiPay-Delivery');
    const timestamp = req.get('X-TenkiPay-Timestamp');
    const received = req.get('X-TenkiPay-Signature') || '';
    const rawBody = req.body.toString('utf8');
    const timestampNumber = Number(timestamp);

    if (!deliveryId || !timestamp || !/^v1=[a-f0-9]{64}$/.test(received)) {
      return res.sendStatus(401);
    }
    if (!Number.isInteger(timestampNumber) ||
        Math.abs(Date.now() / 1000 - timestampNumber) > 300) {
      return res.sendStatus(401);
    }

    const signedPayload = Buffer.concat([
      Buffer.from(`${timestamp}.`, 'utf8'),
      req.body
    ]);
    const digest = crypto
      .createHmac('sha256', process.env.TENKIPAY_WEBHOOK_SECRET)
      .update(signedPayload)
      .digest('hex');
    const expected = `v1=${digest}`;
    const valid = received.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

    if (!valid) return res.sendStatus(401);

    const event = JSON.parse(rawBody);
    await enqueueOnce(deliveryId, event);
    return res.sendStatus(204);
  }
);

Errors, rate limits, and retry decisions

All API errors use a predictable JSON envelope. Validation errors include field-level details; internal exceptions are logged by TenkiPay and returned as sanitized messages.

{
  "status": false,
  "message": "Validation failed.",
  "errors": {
    "amount": ["The amount field must have 0-2 decimal places."]
  }
}

Use exponential backoff with jitter and a finite retry budget. A reasonable starting policy is 1, 2, 5, 10, and 30 seconds. When the final write response is uncertain, retrieve the resource by its TenkiPay or merchant reference before creating anything new.

Sandbox

Keys beginning with pk_test_ create test resources. The hosted simulator can complete or fail checkouts and emit test webhooks, but the wallet execution service rejects every sandbox session before authentication, debit, credit, ledger, or settlement logic.