Birinchi to‘lovingizga
aniq va sodda yo‘l.

FlowKey Unit muhitida mahsulotingiz uchun to‘lov jarayonlarini yarating va tekshiring.

Kirish

API JSON, Bearer autentifikatsiyasi va butun kichik pul birliklaridan foydalanadi. Faqat UZS qo‘llanadi. 100 kichik birlik = 1 so‘m. Barcha javoblarda livemode: false.

Sinov API’sining asosiy manzili:

OpenAPI 3.1 spetsifikatsiyasini yuklab olish

https://flowkey.173.212.216.216.sslip.io/api/v1

Yuqoridagi manzil ushbu o‘rnatmaning APP_URL qiymatidir. Haqiqiy pul uchun endpoint mavjud emas.

Tayyor to‘lov sahifasi va HTML tugmalar

Faqat HTML ishlatadigan sayt uchun Dasturchilar bo‘limida belgilangan summali to‘lov havolasini yarating va HTML tugmasini sahifangizga qo‘shing. Sahifani e’lon qiling, tugmani oching va sinov to‘lovini bajaring. Natija Tranzaksiyalar bo‘limida chiqadi. Maxfiy API kalitni HTML ichiga qo‘ymang.

Backend integratsiyasi uchun serveringizdan to‘lov sessiyasi yarating:

curl -X POST "https://flowkey.173.212.216.216.sslip.io/api/v1/checkout/sessions" \
  -H "Authorization: Bearer $FLOWZA_KEY" \
  -H "Idempotency-Key: order-checkout-001" \
  -H "Content-Type: application/json" \
  -d '{"title":"Kursga kirish","amount_minor":12500000,"currency":"UZS"}'

Javobda id, url, expires_at va livemode: false keladi. Xaridorni url manziliga yo‘naltiring. Sessiya 30 daqiqada tugaydi. Bir xil idempotency kaliti va ma’lumotlar o‘sha sessiyani qaytaradi; o‘zgargan ma’lumotlar 409 xatosini beradi.

Qayta ishlatiladigan to‘lov havolasi buyurtma yoki xaridorni aniqlamaydi. Buyurtma uchun sessiya ID’sini backendingizda saqlang. GET /api/v1/checkout/sessions/{id} endpointiga o‘sha server API kaliti bilan so‘rov yuborsangiz, holat va to‘lov qaytadi. Buyurtmani bajarishdan oldin shu javobni yoki imzolangan webhookni tekshiring. Brauzerdagi muvaffaqiyat xabari to‘lov tasdig‘i emas.

Tezkor boshlash

1. Hisob yarating va Unit muhitini sozlashni yakunlang.
2. Kabinet ichida loyiha yarating. Birinchi API kaliti avtomatik beriladi. Qo‘shimcha kalitlarni Ulash → API kalitlari bo‘limida yarating.
3. To‘liq maxfiy kalitni darhol saqlang. U faqat bir marta ko‘rsatiladi.
4. Serverdagi muhit o‘zgaruvchilarini sozlang va quyidagi so‘rovni yuboring.
5. Saqlangan natijani Tranzaksiyalar va Umumiy ko‘rinish bo‘limlarida ko‘ring.

export BASE_URL="https://flowkey.173.212.216.216.sslip.io"
export FLOWZA_KEY="YOUR_UNIT_API_KEY"

curl -X POST "$BASE_URL/api/v1/payments" \
  -H "Authorization: Bearer $FLOWZA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-payment-001" \
  -d '{"amount_minor":12500000,"currency":"UZS","result":"successful"}'

Autentifikatsiya

Har bir dasturiy so‘rov Authorization headerida sinov API kalitini talab qiladi. Kalit faqat o‘zi yaratilgan loyihaga kirish beradi. Brauzer sessiyasi alohida HTTP-only cookie ishlatadi; maxfiy kalitni frontend kodiga qo‘ymang.

Authorization: Bearer fz_test_<your-secret>

Bekor qilingan yoki noto‘g‘ri kalit HTTP 401 qaytaradi. Loyiha API so‘rovlari daqiqasiga 120 ta, kabinetdagi o‘zgarishlar foydalanuvchiga daqiqasiga 60 ta bilan cheklangan. Kirish urinishlari elektron pochta uchun daqiqasiga 10 ta bilan cheklangan.

API kalitlari

Kalitlarni yaratish va bekor qilish: Dasturchilar → API kalitlari. 256 bitli tasodifiy maxfiy kalitning SHA-256 xeshi saqlanadi. Kabinetda faqat niqoblangan boshlanish qismi qoladi. Almashtirish uchun yangi kalit yarating, server sozlamasini yangilang va eski kalitni bekor qiling.

Maxfiy kalitlarni loglarga, URL’ga, manba kodiga yoki brauzer paketlariga joylamang.

simulated_result maydoni quyidagi maydonning muqobil nomi sifatida ham qabul qilinadi: result. Faqat bitta natija maydonini yuboring; zid qiymatlar rad etiladi.

To‘lov yaratish

POST /api/v1/payments

So‘rovda Idempotency-Key headeri majburiy: 8–128 ta harf, raqam, chiziqcha yoki pastki chiziq. Bir xil kalit va ma’lumotlar asl to‘lovni qaytaradi. Ma’lumotlar o‘zgarsa HTTP 409 qaytadi. Kalitlar loyiha doirasida amal qiladi.

{
  "amount_minor": 12500000,
  "currency": "UZS",
  "result": "successful"
}

Yangi to‘lov uchun HTTP 201, bir xil takroriy so‘rov uchun HTTP 200 (ID va vaqt namunaviy):

{
  "id": "cm_example_payment",
  "amount_minor": 12500000,
  "currency": "UZS",
  "status": "successful",
  "project_id": "cm_example_project",
  "livemode": false,
  "created_at": "2026-10-25T12:00:00.000Z"
}

To‘lovni olish

GET /api/v1/payments/:id

curl "$BASE_URL/api/v1/payments/$PAYMENT_ID" \
  -H "Authorization: Bearer $FLOWZA_KEY"

Xuddi shu shakldagi to‘lov javobini qaytaradi. Mavjud bo‘lmagan yoki boshqa loyihaga tegishli to‘lov HTTP 404 qaytaradi.

To‘lov holati

• successful — muvaffaqiyatli sinov natijasi.
• failed — muvaffaqiyatsiz sinov natijasi.
• pending — ushbu MVP’da kutilayotgan holatda qoladi; avtomatik hisob-kitob yoki holat almashinuvi yo‘q.

Kabinetdagi to‘lov hajmiga faqat muvaffaqiyatli sinov summalari qo‘shiladi. Jami tranzaksiyalarda barcha natijalar hisoblanadi.

Webhooklar

Dasturchilar → Webhooklar bo‘limida ochiq HTTPS endpointingizni ro‘yxatdan o‘tkazing va hodisalarni tanlang: payment.successful, payment.failed, va/yoki payment.pending. Bir marta ko‘rsatiladigan imzolash kalitini saqlang.

To‘lovlar tegishli hodisalarni atomik ravishda navbatga qo‘shadi. Avtomatik yetkazish uchun npm run worker buyrug‘ini ishga tushiring. Jami besh urinish: darhol, so‘ng 1 daqiqa, 5 daqiqa, 30 daqiqa va 2 soatdan keyin. Qo‘lda qayta yuborish limitni yangilamaydi. Hodisa bir necha marta kelishi mumkin: event ID orqali dublikatni ajrating. Faqat tasdiqlangan HTTP 2xx javobi yetkazildi deb belgilanadi. Javob muddati 5 soniya.

Yo‘naltirishlar kuzatilmaydi. To‘g‘ridan-to‘g‘ri IP, localhost, xususiy tarmoq, metadata, rezerv va IPv6 manzillari rad etiladi. Har bir urinishda DNS tekshiriladi va ulanish tasdiqlangan manzilga bog‘lanadi.

{
  "id": "delivery_id",
  "type": "payment.successful",
  "data": { "id": "payment_id", "amount_minor": 12500000,
    "currency": "UZS", "status": "successful",
    "project_id": "project_id", "livemode": false,
    "created_at": "2026-10-25T12:00:00.000Z" }
}

Imzoni serveringizda tekshiring

Header: Flowza-Signature: t=TIMESTAMP,v1=HEX_HMAC. Vaqt belgisi va nuqtadan keyingi aynan xom javob tanasi imzolanadi. Besh daqiqadan eski yoki kelajakdagi vaqtni rad eting, doimiy vaqtli taqqoslashdan foydalaning va yetkazish ID’lari orqali dublikatni ajrating.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, signatureHeader, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signatureHeader ?? '');
  if (!match) return false;
  const [, timestamp, signature] = match;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody).digest();
  const actual = Buffer.from(signature, 'hex');
  return actual.length === expected.length && timingSafeEqual(actual, expected);
}
// JSON ajratishdan OLDIN tekshiring. Dublikatlarni rad etish uchun yetkazish ID’larini saqlang.
// Ilova hodisani qabul qilgandan keyingina 2xx qaytaring.

Xatolarni boshqarish

{
  "error": { "message": "Unit muhitining Bearer API kaliti kerak." }
}

Tarmoq xatosida o‘sha idempotency kaliti va o‘zgarmagan ma’lumotlar bilan qayta urinib ko‘ring. Kutish oralig‘ini bosqichma-bosqich oshiring. Validatsiya yoki kirish xatosini tuzatmasdan qayta yubormang.