Authorization: Bearer 1pay_live_xxxxxxxxxxxx

curl -X POST https://pay.1app.kz/v1/payments \
  -H "Authorization: Bearer 1pay_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"amount":1500,"payer_phone":"+77011234567","merchant_order_id":"order_1042"}'

const res = await fetch("https://pay.1app.kz/v1/payments", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ONEPAY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": orderId,
  },
  body: JSON.stringify({
    amount: 1500,
    payer_phone: "+77011234567",
    merchant_order_id: orderId,
    comment: "Заказ №1042",
  }),
});
const payment = await res.json();
// payment.id = "pay_..."  payment.status = "PENDING"
// Сохраните payment.id — ждите вебхук payment.completed

{
  "id": "pay_3kQ7v2",
  "status": "PENDING",
  "type": "invoice",
  "amount": 1500,
  "currency": "KZT",
  "payer_phone": "+77011234567",
  "merchant_order_id": "order_1042",
  "created_at": "..."
}

const res = await fetch("https://pay.1app.kz/v1/payments/link", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ONEPAY_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": orderId,
  },
  body: JSON.stringify({ amount: 4990, merchant_order_id: orderId }),
});
const payment = await res.json();
// payment.payment_link = "https://pay.kaspi.kz/pay/..."  → данные для QR

// Любая QR-библиотека по payment.payment_link:
const qrImg = "https://api.qrserver.com/v1/create-qr-code/?size=240x240&data="
  + encodeURIComponent(payment.payment_link);
// <img src={qrImg} />  — клиент сканирует камерой приложения Kaspi

<!-- payment_link пришёл с вашего бэкенда -->
<a href="{{payment_link}}" class="kaspi-btn">Оплатить через Kaspi</a>
<img src="https://api.qrserver.com/v1/create-qr-code/?size=200x200&data={{payment_link}}"
     alt="Сканируйте в Kaspi" />

import crypto from "crypto";

app.post("/webhooks/1pay",
  express.raw({ type: "application/json" }),   // ВАЖНО: сырой body
  (req, res) => {
    const sig = req.get("X-Webhook-Signature") || "";
    const expected = "sha256=" + crypto
      .createHmac("sha256", process.env.ONEPAY_WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

    const ok = sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
    if (!ok) return res.status(401).end();

    const evt = JSON.parse(req.body.toString("utf8"));
    if (evt.event === "payment.completed") {
      // пометьте заказ оплаченным — ИДЕМПОТЕНТНО (ретраи возможны)
      markOrderPaid(evt.data.merchant_order_id);
    }
    res.json({ ok: true });  // отвечайте 2xx, иначе будут ретраи
  }
);

{
  "id": "wh_9aB3cD",
  "event": "payment.completed",
  "created_at": "2026-06-02T09:15:12Z",
  "data": {
    "id": "pay_3kQ7v2",
    "status": "COMPLETED",
    "type": "invoice",
    "amount": 1500,
    "currency": "KZT",
    "payer_phone": "+77011234567",
    "comment": "Заказ #1042",
    "merchant_order_id": "order_1042",
    "payment_link": null,
    "receipt_url": "https://kaspi.kz/receipt/...",
    "created_at": "2026-06-02T09:14:00Z",
    "updated_at": "2026-06-02T09:15:12Z"
  }
}

curl -X POST https://pay.1app.kz/v1/payments/pay_3kQ7v2/cancel \
  -H "Authorization: Bearer 1pay_live_xxx"

curl -X POST https://pay.1app.kz/v1/refunds \
  -H "Authorization: Bearer 1pay_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"payment_id":"pay_3kQ7v2","amount":500,"reason":"частичный возврат"}'

curl -X POST https://pay.1app.kz/v1/clients/check \
  -H "Authorization: Bearer 1pay_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+77011234567"}'
# → {"phone":"+77011234567","registered":true,"name":"И. Иванов"}

import express from "express";
import crypto from "crypto";

const ONEPAY = "https://pay.1app.kz";
const API_KEY = process.env.ONEPAY_API_KEY;
const SECRET  = process.env.ONEPAY_WEBHOOK_SECRET;
const app = express();

// 1) Создать платёж для заказа
app.post("/checkout", express.json(), async (req, res) => {
  const { orderId, phone, amount } = req.body;
  const r = await fetch(`${ONEPAY}/v1/payments`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": orderId,
    },
    body: JSON.stringify({ amount, payer_phone: phone, merchant_order_id: orderId }),
  });
  const payment = await r.json();
  if (!r.ok) return res.status(r.status).json(payment);
  res.json({ payment_id: payment.id });
});

// 2) Вебхук — узнаём об оплате
app.post("/webhooks/1pay", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.get("X-Webhook-Signature") || "";
  const exp = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  if (sig.length !== exp.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(exp)))
    return res.status(401).end();

  const evt = JSON.parse(req.body.toString("utf8"));
  switch (evt.event) {
    case "payment.completed":  markOrderPaid(evt.data.merchant_order_id);   break;
    case "payment.refunded":   recordRefund(evt.data.merchant_order_id);     break;
    case "payment.cancelled":
    case "payment.expired":    markOrderUnpaid(evt.data.merchant_order_id); break;
  }
  res.json({ ok: true });
});

app.listen(3000);

Authorization: Bearer 1pay_platform_xxxxxxxxxxxx

const res = await fetch("https://pay.1app.kz/platform/merchants", {
  method: "POST",
  headers: { "Authorization": `Bearer ${PLATFORM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Школа Алмаз",
    external_id: "school_42",
    commission_rate: 3,
    initial_balance: 0,
  }),
});
const school = await res.json();   // school.id = "mer_..."  — сохраните у себя

const r = await fetch(`https://pay.1app.kz/platform/merchants/${schoolId}/devices`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${PLATFORM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Касса", phone: "+7 7XX XXX XX XX" }),
});
const { device } = await r.json();  // device.id → кассиру пришёл SMS

await fetch(`https://pay.1app.kz/platform/merchants/${schoolId}/devices/${device.id}/otp`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${PLATFORM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ otp: "1234" }),
});
// device.status = "ACTIVE" → школа готова принимать платежи

// Пополнить
await fetch(`https://pay.1app.kz/platform/merchants/${schoolId}/balance/topup`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${PLATFORM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ amount: 5000, note: "апрель" }),
});

// Остаток
const b = await (await fetch(`https://pay.1app.kz/platform/merchants/${schoolId}/balance`,
  { headers: { "Authorization": `Bearer ${PLATFORM_KEY}` } })).json();
// { commission_rate: 3, commission_balance: 5000, accepting: true }

// Счёт на телефон
const p = await (await fetch(`https://pay.1app.kz/platform/merchants/${schoolId}/payments`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${PLATFORM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ amount: 4990, payer_phone: "+77011234567", merchant_order_id: "order_1" }),
})).json();
// p.id = "pay_..."  p.status = "PENDING"

// QR-ссылка (без номера телефона)
const l = await (await fetch(`https://pay.1app.kz/platform/merchants/${schoolId}/payments/link`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${PLATFORM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ amount: 4990, merchant_order_id: "order_2" }),
})).json();
// l.payment_link = "https://pay.kaspi.kz/pay/..."

GET https://pay.1app.kz/platform/merchants/:id/stats   # оборот, баланс, ставка, объём за сегодня
GET https://pay.1app.kz/platform/stats                  # агрегат по всем школам платформы

const { secret } = await (await fetch("https://pay.1app.kz/platform/webhook", {
  method: "PUT",
  headers: { "Authorization": `Bearer ${PLATFORM_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://api.example.com/webhooks/1pay",
    events: ["payment.completed", "payment.refunded", "merchant.depleted"],
  }),
})).json();  // secret — сохраните для проверки подписи

{
  "id": "wh_...",
  "event": "payment.completed",
  "merchant_id": "mer_...",
  "merchant_external_id": "school_42",
  "data": { "id": "pay_...", "status": "COMPLETED", "amount": 4990, "merchant_order_id": "order_1" }
}

const API = "https://pay.1app.kz";
const KEY = process.env.ONEPAY_PLATFORM_KEY;
const h = { "Authorization": `Bearer ${KEY}`, "Content-Type": "application/json" };

// 1) Завести школу
const school = await (await fetch(`${API}/platform/merchants`,
  { method: "POST", headers: h, body: JSON.stringify({ name: "Школа Алмаз", external_id: "school_42", commission_rate: 3 }) }
)).json();

// 2) В UI школы: /devices → SMS → /devices/:id/otp → ACTIVE
// 3) Пополнить баланс
await fetch(`${API}/platform/merchants/${school.id}/balance/topup`,
  { method: "POST", headers: h, body: JSON.stringify({ amount: 5000 }) });

// 4) Платёж от имени школы
const pay = await (await fetch(`${API}/platform/merchants/${school.id}/payments`,
  { method: "POST", headers: h, body: JSON.stringify({ amount: 4990, payer_phone: "+77011234567", merchant_order_id: "ord_1" }) }
)).json();
// 5) На ваш платформенный вебхук прилетит payment.completed (merchant_external_id = "school_42")