Developer documentation

Authentication

Create API keys in the dashboard under API keys, and send the secret key as a Bearer token on every request. Test keys (sk_test_…) create test payments; live keys (sk_live_…) move real money.

Authorization: Bearer sk_live_...   # or sk_test_...
Base URL: https://api-business.kemapp.io

Complete business verification (KYB) before creating payments. In the current API this applies to both test and live keys, even though a test key can be created earlier. Owners, admins, developers and custom roles with API-key management permission can create keys; select the intended organization first.

Call this API from your server. Each key belongs to one business and one mode; no X-Org header is needed. Reads return only that key's mode. Keep secrets in your server's secret store, and revoke compromised keys in the dashboard. Dashboard sessions and their private endpoints use a separate authentication flow.

Payments

Create a payment and send your customer to its hosted checkout_url — Kem handles wallets, networks and confirmations. Track state by fetching the payment or, better, through webhooks.

curl -X POST https://api-business.kemapp.io/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
  "amount": "25.000000",
  "currency": "USDT",
  "merchant_reference": "order-1042",
  "customer_email": "[email protected]",
  "description": "Pro plan",
  "return_url": "https://yourshop.example/thanks",
  "metadata": {
    "order_id": "1042"
  }
}'

{
  "id": "pay_example",
  "status": "pending",
  "mode": "test",
  "amount": "25.000000",
  "amount_minor": 25000000,
  "amount_refunded_minor": 0,
  "fee_bps": null,
  "fee_minor": null,
  "net_minor": null,
  "currency": "USDT",
  "network": null,
  "merchant_reference": "order-1042",
  "customer_email": "[email protected]",
  "description": "Pro plan",
  "return_url": "https://yourshop.example/thanks",
  "metadata": {
    "order_id": "1042"
  },
  "checkout_url": "https://dashboard.business.kemapp.io/pay/pay_example",
  "checkout_expires_at": "2026-09-22T13:30:00+00:00",
  "transaction_id": null,
  "detected_at": null,
  "confirmation_pending": false,
  "created_at": "2026-09-22T13:00:00+00:00",
  "updated_at": "2026-09-22T13:00:00+00:00"
}

Returns HTTP 201. Example ids are placeholders. Save the returned id, mode and order reference, then use the returned checkout_url rather than constructing a checkout address.

amount

Required decimal string, e.g. 25 or 25.000000. Positive, at most six decimal places; no JSON number or scientific notation.

currency

USDT; defaults to USDT when omitted.

merchant_reference

Optional order/reference string. Store the returned payment id against your own order.

customer_email

Optional valid customer email.

description

Optional description displayed with the payment.

return_url

Optional destination after checkout. A browser redirect is not proof of successful payment.

metadata

Optional JSON object stored on the payment and returned by payment reads. It is not currently copied into webhook payloads.

Idempotency-Key — optional but recommended — within the default 24-hour window, the same key and request body replay the original response.

The default retention window is 24 hours and keys are scoped to the business. Within that window, the same key and body replay the original response; a changed body returns 409. After expiry, reuse can create another payment. Keep test and live idempotency keys distinct, and use a fresh key for each new order or simulation scenario.

curl "https://api-business.kemapp.io/v1/payments?limit=20&status=succeeded" \
  -H "Authorization: Bearer sk_test_..."

List responses contain data, has_more and next_cursor. Pass next_cursor as cursor on the next request, retaining your filters. Both reads return HTTP 200. A payment belonging to another business or mode is returned as payment_not_found.

amount — decimal string with 6 places in responses ("25.000000"); amount_minor — the same value as an integer in micro-USDT.

fee_minor and net_minor are null while a payment is in flight and are frozen when it succeeds. Reconcile your payout against net_minor, not amount_minor — the difference is our fee (fee_bps).

Payment lifecycle

pending → detected → succeeded · failed · expired · refunded (legacy)

pending — awaiting payment · detected — confirming · succeeded — completed (fulfill only in live mode) · failed / expired — terminal. Historical payments can also be refunded.

The default checkout window is 30 minutes. A pending payment with a submitted transaction hash gets a default 24-hour grace period after that window; confirmation_pending and payment.confirmation_delayed flag the delay. Detected payments wait for settlement or a terminal failure. Neither a hash, a redirect, nor a delayed-confirmation event proves payment. Use the payment's status and your stored mode before fulfilling an order.

Errors & limits

Every error uses one envelope. Codes are stable — branch on error.code, never on the message.

HTTP 4xx/5xx
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency-Key reused with a different request"
  }
}

Products, reusable payment links and webhook endpoints are configured in the dashboard, not through the public API-key endpoints. Merchant-initiated refunds are currently unavailable in both the dashboard and merchant API.

Webhooks

Add an endpoint in the dashboard under Webhooks and choose its events. Each endpoint has a whsec_… signing secret returned at creation; authorized users can reveal it again in the dashboard.

Event payload

{
  "id": "evt_example",
  "type": "payment.succeeded",
  "created": "2026-09-22T13:04:12+00:00",
  "data": {
    "payment": {
      "id": "pay_example",
      "status": "succeeded",
      "amount_minor": 25000000,
      "currency": "USDT",
      "merchant_reference": "order-1042",
      "network": null,
      "product_id": null,
      "payment_link_id": null,
      "fee_minor": 0,
      "net_minor": 25000000
    }
  }
}

This is a zero-fee success example. fee_minor and net_minor are nullable before success. Payment webhooks currently omit mode, customer_email and the original metadata. Keep your own payment-id-to-order/mode mapping; retrieve an unknown payment with the appropriate key before acting. A simulated payment.succeeded must not fulfill a live order.

Verifying signatures

Every delivery carries a Kem-Signature header. Verify the HMAC over "<t>." plus the raw request bytes in constant time, reject timestamps more than 300 seconds from now, and deduplicate event ids.

Kem-Signature: t=<unix_timestamp>,v1=<hmac_sha256_hex>

signed_input = "<t>." + raw_request_body
v1 = HMAC_SHA256(endpoint_secret, signed_input)   # secret: whsec_...

# reject replays: drop the delivery when |now - t| > 300s
# also deduplicate the event body id before applying business effects

import crypto from "node:crypto";

export function verifyKemSignature(rawBody, header, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof header !== "string") return false;
  const match = /^t=([0-9]{1,16}),v1=([0-9a-fA-F]{64})$/.exec(header.trim());
  if (!match) return false;

  const timestamp = Number(match[1]);
  if (!Number.isSafeInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = crypto.createHmac("sha256", secret)
    .update(match[1] + ".")
    .update(rawBody) // exact bytes, before JSON parsing
    .digest();
  const received = Buffer.from(match[2], "hex");
  return crypto.timingSafeEqual(expected, received);
}

import hashlib
import hmac
import re
import time

def verify_kem_signature(raw_body: bytes, header: str, secret: str) -> bool:
    if not isinstance(header, str):
        return False
    match = re.fullmatch(r"t=([0-9]{1,16}),v1=([0-9a-fA-F]{64})", header.strip())
    if match is None:
        return False
    if abs(time.time() - int(match[1])) > 300:
        return False

    expected = hmac.new(
        secret.encode(), (match[1] + ".").encode() + raw_body, hashlib.sha256
    ).digest()
    return hmac.compare_digest(expected, bytes.fromhex(match[2]))

Verify before parsing JSON: use a Buffer from express.raw in Node, or raw request bytes such as request.get_data() in Flask. Do not reserialize a parsed object. These examples reject malformed headers, invalid signatures, and timestamps over five minutes in the past or future. Keep the receiver's clock synchronized.

Delivery & retries

Answer with a 2xx quickly. Failed deliveries are retried with backoff, then dead-lettered:

1m · 5m · 30m · 2h · 12h · 24h

There are seven attempts including the initial delivery. The delays above apply between retries. Deliveries may repeat or arrive out of order: deduplicate by the top-level event id, durably record or queue the event before acknowledging it, and keep fulfillment idempotent per payment. The timestamp/signature is refreshed on each retry. Review failed deliveries in Webhooks; use a payment read when you need its latest state.

Testing

After KYB approval, create a payment with a test key and simulate succeeded, failed or expired. These calls exercise payment events and webhooks without requiring a real transfer:

curl -X POST https://api-business.kemapp.io/v1/payments/{id}/_simulate/succeeded \
  -H "Authorization: Bearer sk_test_..."

Replace {id} with a test payment id. Supported event names are succeeded, failed and expired; live keys are rejected. Create a fresh payment for each terminal outcome. Use simulation for test payments rather than sending real funds. Test and live payments can notify the same subscribed webhook endpoint, so retain the mode from creation.