Örgon Pay hujjatlari

Örgon Pay — Kaspi Pay ustidagi to‘lov shlyuzi. Bitta so‘rov bilan to‘lov yaratasiz, xaridor Kaspi.kz ilovasida to‘laydi, serveringizga imzolangan webhook keladi. Pul to‘g‘ridan-to‘g‘ri servisga biriktirilgan Kaspi kassirining hisobiga tushadi — shlyuz pulni saqlamaydi.

Biznes uchun (pay.orgon.kz/kabinet)

Har qanday biznes kabinetda Google, SMS yoki email kod bilan ro‘yxatdan o‘tadi va o‘z Kaspi Pay kassirini ulaydi. To‘lovlar shu kassirning hisobiga tushadi.

• Obuna — oyiga 10 000 ₸ (30 kun), Pay balansidan yechiladi. Balans Kaspi orqali (QR yoki hisob) to‘ldiriladi; muddat tugaganda balans yetsa, obuna o‘zi uzayadi. To‘lanmagan bo‘lsa, API 402 subscription_required qaytaradi.
• Bitta kalit (opk_…), faqat jonli rejim — test rejimi yo‘q. Yangi kalit ochilsa, eskisi darhol ishlamay qoladi.
• Bitta loyiha. Birinchi so‘rov kalitni serveringizga bog‘laydi: X-Device-Id sarlavhasi (doimiy qiymat yuboring), bo‘lmasa IP. Kalit boshqa joydan ishlatilsa, u butunlay bloklanadi (403 key_blocked) — kabinetda yangisini oching. Serverni ko‘chirishdan oldin kabinetda «Serverni almashtirish»ni bosing (kuniga bir marta).

curl https://pay.orgon.kz/api/v1/payments \
  -H "Authorization: Bearer opk_…" \
  -H "X-Device-Id: my-shop-server" \
  -H "Content-Type: application/json" \
  -d '{"type":"invoice","amount":5000,"phone":"+77011234567","description":"Buyurtma №1024"}'

Autentifikatsiya

Kabinet → Servis → API kalitlari. Kalit sk_test_ yoki sk_live_ bilan boshlanadi va faqat bir marta ko‘rsatiladi. Rejimni kalit belgilaydi: test kaliti faqat test to‘lovlarni ko‘radi. Kalitni faqat serverda saqlang. Limit: bitta kalitga daqiqasiga 300 so‘rov.

Authorization: Bearer sk_test_…

To‘lov yaratish

Summa — butun tenge, 1 dan 50 000 000 gacha. Tarmoq xatosida so‘rovni o‘sha Idempotency-Key bilan takrorlang — ikkinchi to‘lov yaratilmaydi.

curl https://pay.orgon.kz/api/v1/payments \
  -H "Authorization: Bearer $ORGON_PAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c2a4e-7b3d-4e8a-a1f0-5c6d7e8f9a0b" \
  -d '{
    "type": "link",
    "amount": 15000,
    "description": "Buyurtma №1042",
    "external_id": "order_1042",
    "metadata": { "order_id": 1042 }
  }'

Javob 201, holat pending. Xaridorni checkout_url ga yuboring:

{
  "id": "pay_2Nf8kQ1xYbV7cR4tLm9Pa3Ws",
  "object": "payment",
  "livemode": false,
  "type": "link",
  "status": "pending",
  "amount": 15000,
  "amount_refunded": 0,
  "currency": "KZT",
  "external_id": "order_1042",
  "checkout_url": "https://pay.orgon.kz/c/pay_2Nf8kQ1xYbV7cR4tLm9Pa3Ws",
  "expires_at": "2026-11-03T09:14:03.512Z",
  "created_at": "2026-11-02T09:14:03.512Z"
}

invoice uchun "phone": "+7 701 555 10 10" majburiy. Boshqa so‘rovlar:

GET  https://pay.orgon.kz/api/v1/payments?limit=20&status=succeeded&starting_after=pay_…
GET  https://pay.orgon.kz/api/v1/payments/{id}
POST https://pay.orgon.kz/api/v1/payments/{id}/cancel
POST https://pay.orgon.kz/api/v1/payments/{id}/refunds   {"amount": 5000, "reason": "…"}

Holatlar

• pending — to‘lov kutilmoqda
• succeeded — to‘landi
• failed — o‘tmadi (failure_reason)
• canceled — siz bekor qildingiz
• expired — muddati tugadi (link va invoice — 24 soat, qr — 5 daqiqa)

Muddati tugagan yoki bekor qilingan to‘lov ham keyinroq succeeded bo‘lishi mumkin (xaridor kechikib to‘lasa) — buyurtmani webhook bo‘yicha tasdiqlang.

Webhook'lar

Kabinet → Servis → Webhook'lar: https:// manzilini qo‘shing, sir (whsec_…) bir marta ko‘rsatiladi. Hodisalar: payment.succeeded, payment.failed, payment.canceled, payment.expired, refund.succeeded. Javob 2xx bo‘lmasa 6 martagacha qayta yuboriladi (1 daq, 5 daq, 30 daq, 2 soat, 12 soat).

POST /orgon/webhook
Orgon-Signature: t=1762075200,v1=5f2b…
{ "id": "evt_…", "type": "payment.succeeded", "livemode": false, "created": 1762075200,
  "data": { "object": { "id": "pay_…", "status": "succeeded", "external_id": "order_1042", … } } }

Imzoni tekshiring: HMAC-SHA256(secret, t + "." + xom_body) = v1, va t 5 daqiqadan eski bo‘lmasin.

import crypto from "crypto";
function verify(secret, rawBody, header) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expect = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expect.length === v1.length && crypto.timingSafeEqual(Buffer.from(expect), Buffer.from(v1));
}

Qaytarish

Faqat to‘langan to‘lovni qaytarish mumkin, to‘liq yoki qismlab. amount berilmasa qolgan summa to‘liq qaytariladi.

Test rejimi

sk_test_ kaliti bilan yaratilgan to‘lov haqiqiy pul yechmaydi. To‘lov sahifasida «To‘lash» va «Rad etish» tugmalari bor — ular webhook'larni haqiqiy to‘lovdagidek yuboradi. Kabinetdagi «Test rejimi» tugmasi test ma'lumotlarini ko‘rsatadi.

Xatolar

HTTP 400
{ "error": { "type": "invalid_request_error", "code": "amount_invalid", "message": "…", "param": "amount" } }

• 401 invalid_api_key — kalit yo‘q yoki bekor qilingan
• 409 cashier_unavailable — jonli rejimda servisga ulangan Kaspi kassiri biriktirilmagan
• 409 idempotency_key_reused — kalit boshqa parametrlar bilan ishlatilgan
• 429 rate_limited — daqiqasiga 300 dan ko‘p so‘rov
• 402 subscription_required — biznes obunasi to‘lanmagan
• 403 key_blocked — kalit boshqa loyihada ishlatilgani uchun bloklangan

Xatolarni matn bo‘yicha emas, type va code bo‘yicha ishlang.