டெவலப்பர் ஆவணங்கள்

அங்கீகாரம்

டாஷ்போர்டில் «API keys» பகுதியில் விசைகளை உருவாக்கி, ஒவ்வொரு கோரிக்கையிலும் secret key-ஐ 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.

பேமெண்ட்கள்

பேமெண்டை உருவாக்கி வாடிக்கையாளரை அதன் hosted checkout_url-க்கு அனுப்புங்கள் — வாலட்கள், நெட்வொர்க்குகள், உறுதிப்படுத்தல்கள் அனைத்தையும் Kem கவனிக்கும். நிலையை பேமெண்டை fetch செய்து அல்லது சிறப்பாக 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 — விருப்பத்தேர்வு, ஆனால் பரிந்துரைக்கப்படுகிறது — இயல்புநிலை 24 மணி நேரத்திற்குள் அதே key மற்றும் கோரிக்கை உடல் அசல் பதிலை மீண்டும் தரும்.

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"
  }
}

தயாரிப்புகள், மீண்டும் பயன்படுத்தும் கட்டண இணைப்புகள் மற்றும் webhook endpoints டாஷ்போர்டில் அமைக்கப்படுகின்றன; பொது API-key endpoints வழியாக அல்ல. வணிகர் தொடங்கும் பணத்திருப்பம் தற்போது டாஷ்போர்டிலும் merchant API-யிலும் இல்லை.

Webhooks

«Webhooks» பகுதியில் endpoint மற்றும் நிகழ்வுகளை அமைக்கவும். whsec_… கையொப்ப ரகசியம் உருவாக்கும்போது வழங்கப்படும்; அனுமதியுள்ள பயனர்கள் டாஷ்போர்டில் அதை மீண்டும் காணலாம்.

நிகழ்வு 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.

கையொப்பச் சரிபார்ப்பு

ஒவ்வொரு டெலிவரியிலும் Kem-Signature இருக்கும். «<t>.» மற்றும் மூல கோரிக்கை பைட்டுகளின் HMAC-ஐ constant-time ஒப்பீட்டால் சரிபார்த்து, தற்போதைய நேரத்திலிருந்து 300 வினாடிகளுக்கு மேல் வேறுபடும் timestamps-ஐ நிராகரிக்கவும்; 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.

டெலிவரி & மறுமுயற்சிகள்

விரைவாக 2xx பதிலளியுங்கள். தோல்வியுற்ற டெலிவரிகள் backoff உடன் மீண்டும் முயற்சிக்கப்பட்டு பின் dead-letter ஆகும்:

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 ஒப்புதலுக்குப் பிறகு சோதனை key மூலம் பேமெண்டை உருவாக்கி succeeded, failed அல்லது expired நிலைகளை simulate செய்யுங்கள். உண்மையான பரிமாற்றமின்றி பேமெண்ட் நிகழ்வுகளையும் webhooks-ஐயும் சோதிக்கலாம்:

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.