Documentación para desarrolladores

Autenticación

Crea claves API en el panel, en «Claves API», y envía la clave secreta como Bearer token en cada petición. Las claves de prueba (sk_test_…) crean pagos de prueba; las claves live (sk_live_…) mueven dinero real.

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.

Pagos

Crea un pago y envía a tu cliente a su checkout_url alojada: Kem se encarga de billeteras, redes y confirmaciones. Sigue el estado consultando el pago o, mejor, con 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 — opcional pero recomendado: dentro de la ventana predeterminada de 24 horas, la misma clave y el mismo cuerpo devuelven la respuesta original.

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

Ciclo de vida del pago

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

pending — esperando el pago · detected — confirmando · succeeded — completado (entrega solo en modo live) · failed / expired — terminales. Los pagos históricos también pueden tener estado 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.

Errores y límites

Todos los errores usan un mismo sobre. Los códigos son estables: bifurca por error.code, nunca por el mensaje.

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

Productos, enlaces reutilizables y endpoints de webhooks se configuran en el panel, no mediante los endpoints públicos con clave API. Iniciar reembolsos no está disponible actualmente en el panel ni en la API del comercio.

Webhooks

Añade un endpoint en «Webhooks» y elige sus eventos. Su secreto de firma whsec_… se devuelve al crearlo; los usuarios autorizados pueden volver a revelarlo en el panel.

Cuerpo del evento

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

Verificación de firmas

Cada entrega lleva Kem-Signature. Verifica en tiempo constante el HMAC sobre «<t>.» más los bytes originales, rechaza marcas temporales a más de 300 segundos del momento actual y deduplica los ids de evento.

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.

Entrega y reintentos

Responde 2xx rápido. Las entregas fallidas se reintentan con backoff y luego pasan a 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.

Pruebas

Tras aprobar el KYB, crea un pago con una clave de prueba y simula succeeded, failed o expired. Estas llamadas prueban los eventos y webhooks sin una transferencia real:

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.