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

Kem Business API மூலம் USDT பணம் பெற தேவையான அனைத்தும்: அங்கீகாரம், பேமெண்ட் endpoints, உங்கள் ஆர்டர் நிலையை இயக்கும் கையொப்பமிடப்பட்ட webhooks.

அங்கீகாரம்

டாஷ்போர்டில் «API keys» பகுதியில் விசைகளை உருவாக்கி, ஒவ்வொரு கோரிக்கையிலும் secret key-ஐ Bearer token ஆக அனுப்புங்கள். சோதனை விசைகள் (sk_test_…) சோதனை பேமெண்ட்களை உருவாக்கும்; நேரடி விசைகள் (sk_live_…) உண்மையான பணத்தை நகர்த்தும்.

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

பேமெண்ட்கள்

பேமெண்டை உருவாக்கி வாடிக்கையாளரை அதன் hosted checkout_url-க்கு அனுப்புங்கள் — வாலட்கள், நெட்வொர்க்குகள், உறுதிப்படுத்தல்கள் அனைத்தையும் Kem கவனிக்கும். நிலையை பேமெண்டை fetch செய்து அல்லது சிறப்பாக webhooks வழியாக பின்தொடருங்கள்.

POST/v1/payments

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_01J...",
  "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",
  "checkout_url": "https://pay.kemapp.io/pay_01J...",
  "checkout_expires_at": "2026-07-13T13:30:00+00:00",
  "transaction_id": null,
  "detected_at": null,
  "confirmation_pending": false,
  "created_at": "2026-07-13T13:00:00+00:00",
  "updated_at": "2026-07-13T13:00:00+00:00"
}

Idempotency-Key — விருப்பத்தேர்வு ஆனால் பரிந்துரைக்கப்படுகிறது — அதே key உடன் மறுமுயற்சி நகல் உருவாக்காமல் அசல் பேமெண்டையே திருப்பித் தரும்.

GET/v1/payments— query: status, limit (1–100, default 20), cursor · returns has_more, next_cursor

GET/v1/payments/{id}

amount — decimal string with 6 places ("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

pending — பரிமாற்றத்திற்குக் காத்திருப்பு · detected — சங்கிலியில் கண்டறியப்பட்டு உறுதிப்படுத்தப்படுகிறது · succeeded — உங்கள் வாலட்டில் பணம் உறுதி (இதில் ஆர்டரை நிறைவேற்றுங்கள்) · failed / expired — இறுதி. திரும்பப்பணம் webhook நிகழ்வுகளாக வரும்.

checkout window: 30 minutes, then → expired

பிழைகள் & வரம்புகள்

எல்லா பிழைகளும் ஒரே உறையில் வரும். குறியீடுகள் நிலையானவை — செய்தியில் அல்ல, error.code அடிப்படையில் கிளை பிரியுங்கள்.

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

401 unauthorized	missing or invalid API key
404 payment_not_found	unknown payment id (or a live id with a test key)
409 idempotency_conflict	Idempotency-Key reused with a different body — identical retries replay the original response
422 validation_error	malformed body — bad amount, unsupported currency. message reads “{field}: {reason}”
429 rate_limited	over the per-key budget: 100 writes/min, 1000 reads/min

தயாரிப்புகள், கட்டண இணைப்புகள், webhook endpoints, திரும்பப்பணம் அனைத்தும் டாஷ்போர்டிலிருந்து நிர்வகிக்கப்படுகின்றன — அவற்றுக்கு பொது REST endpoints இன்னும் இல்லை.

Webhooks

டாஷ்போர்டில் «Webhooks» பகுதியில் endpoint சேர்த்து தேவையான நிகழ்வுகளைத் தேர்ந்தெடுங்கள். ஒவ்வொரு endpoint-க்கும் தனி whsec_… கையொப்ப ரகசியம் — உருவாக்கும்போது ஒருமுறை மட்டும் காட்டப்படும்.

payment.created	A payment intent was created (API or checkout link).
payment.detected	The transfer was seen on-chain / in the KEM ledger; confirming.
payment.succeeded	Funds are confirmed in your business wallet. Fulfill on this event.
payment.failed	The payment failed.
payment.expired	The checkout window closed without payment.
payment.confirmation_delayed	The customer paid, but it couldn't be confirmed inside the checkout window. Don't treat this as expired — hold the order.
payment.refund.created	A refund was initiated from the dashboard.
payment.refund.succeeded	The refund settled back to the customer.

நிகழ்வு payload

{
  "id": "payment_event_01J...",
  "type": "payment.succeeded",
  "created": "2026-07-13T13:04:12+00:00",
  "data": {
    "payment": {
      "id": "pay_01J...",
      "status": "succeeded",
      "amount_minor": 25000000,
      "currency": "USDT",
      "merchant_reference": "order-1042",
      "network": "TRON",
      "product_id": null,
      "payment_link_id": null
    }
  }
}

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

ஒவ்வொரு டெலிவரியிலும் Kem-Signature header இருக்கும். உங்கள் endpoint ரகசியத்துடன் «<t>.» + மூல உடலில் HMAC-ஐ மீண்டும் கணக்கிட்டு constant-time ஒப்பீடு செய்யுங்கள். பொருந்தாதவற்றை நிராகரியுங்கள்.

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

import crypto from "node:crypto";

export function verifyKemSignature(rawBody, header, secret) {
  // header: "t=1720000000,v1=hex"
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)               // secret: whsec_...
    .update(`${parts.t}.`)
    .update(rawBody)                            // the RAW request bytes
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

import hashlib, hmac

def verify_kem_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=") for p in header.split(","))
    expected = hmac.new(
        secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

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

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

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

சோதனை

சோதனை key மூலம் பணம் நகர்த்தாமல் முழு சுழற்சியிலும் பேமெண்டை இயக்கலாம் — மாற்றங்களை simulate செய்து உங்கள் webhooks வருவதைப் பாருங்கள்:

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