Subscribe API Hujjatlari

Payme Subscribe API uchun to'liq havola - karta tokenizatsiyasi va chek boshqaruvi.

PaymeSubscribe Klass

Konstruktor

new PaymeSubscribe(config: PaymeSubscribeConfig, mode: SubscribeMode)

Parametrlar:

Parametr	Tur	Majburiy	Tavsif
config.merchantId	string	✅	Payme Business dan savdochi ID
config.password	string	⚠️ Faqat server	Subscribe API uchun parol
config.baseURL	string	❌	API asosiy URL (standart: ishlab chiqarish)
config.timeout	number	❌	So'rov vaqti tugashi ms da (standart: 60000)
mode	'client' | 'server'	✅	Operatsiya rejimi

Rejimlar:

• client: Karta tokenizatsiyasi uchun (frontend/mobil)
• server: Karta boshqaruvi va cheklar uchun (backend)

Misol:

import { PaymeSubscribe } from '@joyida/payme';

// Klient tomon rejim
const subscribeClient = new PaymeSubscribe({
  merchantId: 'your_merchant_id'
}, 'client');

// Server tomon rejim
const subscribeServer = new PaymeSubscribe({
  merchantId: 'your_merchant_id',
  password: 'your_password'
}, 'server');

---

Karta Metodlari

cardsCreate (Klient tomon)

Yangi karta tokeni yaratadi.

cardsCreate(params: CardsCreateParams): Promise<CardsCreateResult>

Parametrlar:

interface CardsCreateParams {
  card: {
    number: string;  // Karta raqami (13-19 raqam)
    expire: string;  // Amal qilish muddati (MMYY formati)
  };
  account?: Record<string, unknown>;  // Ixtiyoriy akkaunt ma'lumotlari
  save?: boolean;                     // Karta kelajakda foydalanish uchun saqlansin
  customer?: string;                  // Mijoz identifikatori
}

Qaytaradi:

interface CardsCreateResult {
  card: {
    number: string;     // Maskalangan karta raqami
    expire: string;     // Amal qilish muddati
    token: string;      // Karta tokenni
    recurrent: boolean; // Takroriy to'lovlarni qo'llab-quvvatlaydi
    verify: boolean;    // Tasdiqlash statusi (dastlab false)
  };
}

Misol:

const result = await subscribeClient.cardsCreate({
  card: {
    number: '8600069195406311',
    expire: '0399'
  },
  save: true,
  account: { user_id: '12345' }
});

console.log('Token:', result.card.token);
console.log('Tasdiqlangan:', result.card.verify); // false

---

cardsGetVerifyCode (Klient tomon)

Karta uchun SMS tasdiqlash kodi so'raydi.

cardsGetVerifyCode(
  params: CardsGetVerifyCodeParams
): Promise<CardsGetVerifyCodeResult>

Parametrlar:

interface CardsGetVerifyCodeParams {
  token: string; // cardsCreate dan olingan karta tokenni
}

Qaytaradi:

interface CardsGetVerifyCodeResult {
  sent: boolean;  // SMS yuborilish statusi
  phone: string;  // Maskalangan telefon raqami (masalan, "99890***1234")
  wait: number;   // Keyingi so'rovgacha kutish vaqti (ms)
}

Misol:

const result = await subscribeClient.cardsGetVerifyCode({
  token: 'card_token_here'
});

console.log(`SMS yuborildi ${result.phone}`);
console.log(`${result.wait}ms kutib qayta urinish`);

---

cardsVerify (Klient tomon)

SMS kod bilan kartani tasdiqlaydi.

cardsVerify(params: CardsVerifyParams): Promise<CardsVerifyResult>

Parametrlar:

interface CardsVerifyParams {
  token: string; // Karta tokenni
  code: string;  // SMS tasdiqlash kodi
}

Qaytaradi:

interface CardsVerifyResult {
  card: {
    number: string;     // Maskalangan karta raqami
    expire: string;     // Amal qilish muddati
    token: string;      // Karta tokenni (xuddi shu)
    recurrent: boolean; // Takroriy to'lovlarni qo'llab-quvvatlaydi
    verify: boolean;    // Tasdiqlash statusi (muvaffaqiyatli bo'lsa true)
  };
}

Misol:

const result = await subscribeClient.cardsVerify({
  token: 'card_token_here',
  code: '666666'
});

if (result.card.verify) {
  console.log('✅ Karta tasdiqlandi!');
}

---

cardsCheck (Server tomon)

Karta tokenni holatini tekshiradi.

cardsCheck(params: CardsCheckParams): Promise<CardsCheckResult>

Parametrlar:

interface CardsCheckParams {
  token: string; // Tekshirish kerak bo'lgan karta tokenni
}

Qaytaradi:

interface CardsCheckResult {
  card: {
    number: string;     // Maskalangan karta raqami
    expire: string;     // Amal qilish muddati
    token: string;      // Karta tokenni
    recurrent: boolean; // Takroriy to'lovlarni qo'llab-quvvatlaydi
    verify: boolean;    // Tasdiqlash statusi
  };
}

Misol:

const result = await subscribeServer.cardsCheck({
  token: 'card_token_here'
});

console.log('Tasdiqlangan:', result.card.verify);
console.log('Takroriy:', result.card.recurrent);

---

cardsRemove (Server tomon)

Karta tokenni o'chiradi.

cardsRemove(params: CardsRemoveParams): Promise<CardsRemoveResult>

Parametrlar:

interface CardsRemoveParams {
  token: string; // O'chirish kerak bo'lgan karta tokenni
}

Qaytaradi:

interface CardsRemoveResult {
  success: boolean; // O'chirish statusi
}

Misol:

const result = await subscribeServer.cardsRemove({
  token: 'card_token_here'
});

if (result.success) {
  console.log('✅ Karta tokenni o\'chirildi');
}

---

Chek Metodlari

receiptsCreate (Server tomon)

Yangi chek yaratadi.

receiptsCreate(
  params: ReceiptsCreateParams
): Promise<ReceiptsCreateResult>

Parametrlar:

interface ReceiptsCreateParams {
  amount: number;                    // Tiyinda suma
  account: Record<string, unknown>;  // Akkaunt identifikatori
  description?: string;              // Chek tavsifi
  detail?: ReceiptDetail;            // Fiskal tafsilotlar
}

interface ReceiptDetail {
  receipt_type?: number;
  shipping?: {
    title: string;
    price: number;
  };
  items: ReceiptItem[];
}

interface ReceiptItem {
  title: string;        // Tovar nomi
  price: number;        // Tovar narxi tiyinda
  count: number;        // Soni
  code: string;         // IKPU kodi
  units?: number;       // Birlik turi
  vat_percent: number;  // QQS foizi
  package_code: string; // Paket kodi
}

Qaytaradi:

interface ReceiptsCreateResult {
  receipt: {
    _id: string;        // Chek ID
    create_time: number;
    pay_time: number;
    cancel_time: number;
    state: number;      // 0 (to'lov kutmoqda)
  };
}

Misol:

const result = await subscribeServer.receiptsCreate({
  amount: 500000,
  account: { order_id: '123' },
  description: 'Buyurtma #123 uchun to\'lov',
  detail: {
    receipt_type: 0,
    items: [
      {
        title: 'Tovar Nomi',
        price: 500000,
        count: 1,
        code: '00702001001000001',
        vat_percent: 15,
        package_code: '123456'
      }
    ]
  }
});

console.log('Chek ID:', result.receipt._id);

---

receiptsPay (Server tomon)

Karta tokenni bilan chek to'laydi.

receiptsPay(params: ReceiptsPayParams): Promise<ReceiptsPayResult>

Parametrlar:

interface ReceiptsPayParams {
  id: string;    // Chek ID
  token: string; // Karta tokenni
  payer?: {      // Ixtiyoriy to'lovchi ma'lumotlari
    phone: string;
  };
}

Qaytaradi:

interface ReceiptsPayResult {
  receipt: {
    _id: string;
    state: number; // 1 (to'langan)
  };
}

Misol:

const result = await subscribeServer.receiptsPay({
  id: 'receipt_id_here',
  token: 'card_token_here',
  payer: {
    phone: '998901234567'
  }
});

if (result.receipt.state === 1) {
  console.log('✅ To\'lov muvaffaqiyatli!');
}

---

receiptsSend (Server tomon)

SMS orqali chek invoice yuboradi.

receiptsSend(params: ReceiptsSendParams): Promise<ReceiptsSendResult>

Parametrlar:

interface ReceiptsSendParams {
  id: string;    // Chek ID
  phone: string; // Telefon raqami (998XXXXXXXXX)
}

Qaytaradi:

interface ReceiptsSendResult {
  success: boolean;
}

Misol:

const result = await subscribeServer.receiptsSend({
  id: 'receipt_id_here',
  phone: '998901234567'
});

if (result.success) {
  console.log('✅ SMS yuborildi');
}

---

receiptsCancel (Server tomon)

Chekni bekor qiladi.

receiptsCancel(
  params: ReceiptsCancelParams
): Promise<ReceiptsCancelResult>

Parametrlar:

interface ReceiptsCancelParams {
  id: string; // Bekor qilish kerak bo'lgan chek ID
}

Qaytaradi:

interface ReceiptsCancelResult {
  receipt: {
    _id: string;
    cancel_time: number;
    state: number; // 2 (bekor qilingan) yoki 3 (to'lovdan keyin bekor qilingan)
  };
}

Misol:

const result = await subscribeServer.receiptsCancel({
  id: 'receipt_id_here'
});

console.log('Bekor qilish vaqti:', result.receipt.cancel_time);
console.log('Holat:', result.receipt.state);

---

receiptsCheck (Server tomon)

Chek holatini tekshiradi.

receiptsCheck(
  params: ReceiptsCheckParams
): Promise<ReceiptsCheckResult>

Parametrlar:

interface ReceiptsCheckParams {
  id: string; // Tekshirish kerak bo'lgan chek ID
}

Qaytaradi:

interface ReceiptsCheckResult {
  state: number; // 0= kutmoqda, 1= to'langan, 2= bekor qilingan, 3= to'lovdan keyin bekor qilingan
}

Misol:

const result = await subscribeServer.receiptsCheck({
  id: 'receipt_id_here'
});

console.log('Chek holati:', result.state);

---

receiptsGet (Server tomon)

Chek tafsilotlarini oladi.

receiptsGet(params: ReceiptsGetParams): Promise<ReceiptsGetResult>

Parametrlar:

interface ReceiptsGetParams {
  id: string; // Olish kerak bo'lgan chek ID
}

Qaytaradi:

interface ReceiptsGetResult {
  receipt: Receipt; // To'liq chek obyekti
}

interface Receipt {
  _id: string;
  create_time: number;
  pay_time: number;
  cancel_time: number;
  state: number;
  type: number;
  external: boolean;
  operation: number;
  category: string | null;
  error: string | null;
  description: string;
  detail: ReceiptDetail | null;
  amount: number;
  currency: number;
  commission: number;
  account: Record<string, unknown>[];
  card: CardInfo | null;
  merchant: {
    _id: string;
    name: string;
    organization: string;
    address: string;
    epos: {
      merchantId: string;
      terminalId: string;
    };
    date: number;
    logo: string | null;
    type: string;
    terms: string | null;
  };
  meta: {
    source: string;
    owner: string;
  };
  processing_id: number | null;
}

Misol:

const result = await subscribeServer.receiptsGet({
  id: 'receipt_id_here'
});

console.log('Suma:', result.receipt.amount);
console.log('Holat:', result.receipt.state);
console.log('Karta:', result.receipt.card?.number);

---

receiptsGetAll (Server tomon)

Sana oralig'ida barcha cheklarni oladi.

receiptsGetAll(
  params: ReceiptsGetAllParams
): Promise<ReceiptsGetAllResult>

Parametrlar:

interface ReceiptsGetAllParams {
  from: number;    // Davr boshhi (Unix timestamp ms da)
  to: number;      // Davr oxiri (Unix timestamp ms da)
  offset?: number; // Sahifalash offset (standart: 0)
  limit?: number;  // Natijalar limit (standart: 50)
}

Qaytaradi:

interface ReceiptsGetAllResult {
  receipts: Receipt[]; // Cheklar massivi
}

Misol:

const result = await subscribeServer.receiptsGetAll({
  from: Date.now() - 86400000, // 24 soat oldin
  to: Date.now(),
  limit: 50
});

console.log('Topildi:', result.receipts.length);
result.receipts.forEach(receipt => {
  console.log(`${receipt._id}: ${receipt.state} - ${receipt.amount}`);
});

---

Konstantalar

Chek Holatlari

enum RECEIPT_STATES {
  WAITING = 0,              // To'lov kutmoqda
  PAID = 1,                 // To'langan
  CANCELLED = 2,            // Bekor qilingan
  CANCELLED_AFTER_PAY = 3   // To'lovdan keyin bekor qilingan
}

Foydalanish:

import { RECEIPT_STATES } from '@joyida/payme';

if (receipt.state === RECEIPT_STATES.PAID) {
  console.log('Chek to\'langan');
}

---

Xato Ishlash

Barcha Subscribe API xatoliklar tavsirli xabarlarga xaritalangan. To'liq xato kodi ro'yxati uchun rasmiy Payme hujjatlarini tekshiring.

Umumiy xatolar:

import { PaymeError } from '@joyida/payme';

try {
  await subscribeClient.cardsCreate(params);
} catch (error) {
  if (error instanceof PaymeError) {
    console.error('Xato kodi:', error.code);
    console.error('Xabar:', error.message);

    // Muayyan xatolarni ishlash
    if (error.code === -31050) {
      console.error('Noto\'g\'ri karta raqami');
    }
  }
}

---

Keyingi Qadamlar

• Merchant API Hujjatlari ni tekshiring
• Karta Tokenizatsiyasi haqida bilib oling
• Chek Boshqaruvi ni o'rganing
• Xatolarni Ishlash ni ko'ring