مستندات توسعه‌دهندگان

احراز هویت

کلیدهای API را از داشبورد در بخش «کلیدهای API» بسازید و کلید محرمانه را به‌صورت Bearer token در هر درخواست بفرستید. کلیدهای آزمایشی (…sk_test_) پرداخت آزمایشی می‌سازند؛ کلیدهای اصلی (…sk_live_) پول واقعی جابه‌جا می‌کنند.

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.

پرداخت‌ها

یک پرداخت بسازید و مشتری را به checkout_url میزبانی‌شده بفرستید — Kem کیف پول‌ها، شبکه‌ها و تأییدها را مدیریت می‌کند. وضعیت را با خواندن پرداخت یا بهتر از آن با وب‌هوک‌ها دنبال کنید.

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 — اختیاری اما توصیه‌شده — در بازه پیش‌فرض 24 ساعته، همان کلید و بدنه درخواست پاسخ اصلی را دوباره برمی‌گردانند.

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).

چرخه عمر پرداخت

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

pending — در انتظار پرداخت · detected — در حال تأیید · succeeded — تکمیل‌شده (فقط در حالت live سفارش را تحویل دهید) · failed / expired — نهایی. سوابق قدیمی ممکن است وضعیت 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.

خطاها و محدودیت‌ها

همه خطاها یک قالب واحد دارند. کدها ثابت‌اند — بر اساس error.code تصمیم بگیرید، نه متن پیام.

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

محصولات، لینک‌های قابل استفاده مجدد و نقاط وب‌هوک در داشبورد تنظیم می‌شوند، نه در API عمومی. شروع بازپرداخت توسط پذیرنده در حال حاضر در داشبورد یا API پذیرنده در دسترس نیست.

وب‌هوک‌ها

در بخش «Webhooks» یک نقطه پایانی و رویدادهایش را تنظیم کنید. راز امضای whsec_… هنگام ایجاد برگردانده می‌شود؛ کاربران مجاز می‌توانند آن را دوباره در داشبورد نمایش دهند.

بدنه رویداد

{
  "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.

راستی‌آزمایی امضاها

هر تحویل هدر Kem-Signature دارد. HMAC روی «‎<t>.‎» و بایت‌های خام درخواست را با مقایسه زمان‌ثابت بررسی کنید، زمان‌هایی با بیش از 300 ثانیه فاصله از اکنون را رد کنید و شناسه رویدادهای تکراری را دوباره پردازش نکنید.

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.

تحویل و تلاش مجدد

سریع با 2xx پاسخ دهید. تحویل‌های ناموفق با فاصله‌های افزایشی تکرار و سپس بایگانی می‌شوند:

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.

آزمایش

پس از تأیید KYB، با کلید آزمایشی پرداخت بسازید و succeeded، failed یا expired را شبیه‌سازی کنید. این درخواست‌ها رویدادها و وب‌هوک‌ها را بدون انتقال واقعی آزمایش می‌کنند:

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.