Merchant API Hujjatlari

Payme Merchant API metodlari uchun to'liq havola.

PaymeMerchant Klass

Konstruktor

new PaymeMerchant(config: PaymeConfig)

Parametrlar:

Parametr	Tur	Majburiy	Tavsif
config.merchantId	string	✅	Payme Business dan savdochi ID
config.secretKey	string	✅	Payme Business dan maxfiy kalit
config.baseURL	string	❌	API asosiy URL (standart: ishlab chiqarish)
config.timeout	number	❌	So'rov vaqti tugashi ms da (standart: 60000)

Misol:

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

const payme = new PaymeMerchant({
  merchantId: 'your_merchant_id',
  secretKey: 'your_secret_key',
  timeout: 30000
});

---

Metodlar

checkPerformTransaction

Tranzaktsiyani yaratmasdan uning bajarilishi mumkinligini tekshiradi.

checkPerformTransaction(
  params: CheckPerformTransactionParams
): Promise<CheckPerformTransactionResult>

Parametrlar:

interface CheckPerformTransactionParams {
  amount: number;                           // Tiyinda suma
  account: Record<string, string | number>; // Akkaunt identifikatori
}

Qaytaradi:

interface CheckPerformTransactionResult {
  allow: boolean;                           // Tranzaktsiya bajarilishi mumkin
  additional?: Record<string, unknown>;     // Qo'shimcha ma'lumotlar
  detail?: FiscalDetail;                    // Fiskal tafsilotlar (ixtiyoriy)
}

Xatolar:

Kod	Tavsif
-31001	Noto'g'ri suma
-31050 dan -31099 gacha	Akkaunt validatsiya xatolari
-32400	Tizim xatosi

Misol:

const result = await payme.checkPerformTransaction({
  amount: 500000,
  account: { order_id: 'ORD-123' }
});

if (result.allow) {
  console.log('To\'lov ruxsat etilgan');
}

---

createTransaction

Yangi tranzaktsiya yaratadi va buyurtmani bloklaydi.

createTransaction(
  params: CreateTransactionParams
): Promise<CreateTransactionResult>

Parametrlar:

interface CreateTransactionParams {
  id: string;                               // Payme tranzaktsiya ID (24 belgi)
  time: number;                             // Unix timestamp ms da
  amount: number;                           // Tiyinda suma
  account: Record<string, string | number>; // Akkaunt identifikatori
}

Qaytaradi:

interface CreateTransactionResult {
  create_time: number;                      // Yaratish vaqti
  transaction: string;                      // Sizning tranzaktsiya ID ingiz
  state: TransactionState;                  // Tranzaktsiya holati (1)
  receivers?: Receiver[] | null;            // Zanjirli to'lov qabul qiluvchilari
}

Xatolar:

Kod	Tavsif
-31001	Noto'g'ri suma
-31008	Operatsiyani bajarib bo'lmaydi
-31050 dan -31099 gacha	Akkaunt validatsiya xatolari

Misol:

const result = await payme.createTransaction({
  id: '5305e3bab097f420a62ced0b',
  time: Date.now(),
  amount: 500000,
  account: { order_id: 'ORD-123' }
});

console.log('Tranzaktsiya ID:', result.transaction);
console.log('Holat:', result.state); // 1 (yaratilgan)

---

performTransaction

Tranzaktsiyani yakunlaydi va pulni o'tkazadi.

performTransaction(
  params: PerformTransactionParams
): Promise<PerformTransactionResult>

Parametrlar:

interface PerformTransactionParams {
  id: string; // Payme tranzaktsiya ID
}

Qaytaradi:

interface PerformTransactionResult {
  transaction: string;      // Sizning tranzaktsiya ID ingiz
  perform_time: number;     // Bajarish vaqti
  state: TransactionState;  // Tranzaktsiya holati (2)
}

Xatolar:

Kod	Tavsif
-31003	Tranzaktsiya topilmadi
-31008	Operatsiyani bajarib bo'lmaydi

Misol:

const result = await payme.performTransaction({
  id: '5305e3bab097f420a62ced0b'
});

console.log('To\'lov yakunlandi:', result.perform_time);
console.log('Holat:', result.state); // 2 (yakunlangan)

---

cancelTransaction

Tranzaktsiyani bekor qiladi (perform dan oldin yoki keyin).

cancelTransaction(
  params: CancelTransactionParams
): Promise<CancelTransactionResult>

Parametrlar:

interface CancelTransactionParams {
  id: string;           // Payme tranzaktsiya ID
  reason: CancelReason; // Bekor qilish sababi (1-5, 10)
}

Bekor Qilish Sabablari:

enum CancelReasons {
  RECIPIENT_NOT_FOUND = 1,
  DEBIT_ERROR = 2,
  EXECUTION_ERROR = 3,
  TIMEOUT = 4,
  REFUND = 5,
  UNKNOWN = 10
}

Qaytaradi:

interface CancelTransactionResult {
  transaction: string;      // Sizning tranzaktsiya ID ingiz
  cancel_time: number;      // Bekor qilish vaqti
  state: TransactionState;  // Tranzaktsiya holati (-1 yoki -2)
}

Xatolar:

Kod	Tavsif
-31003	Tranzaktsiya topilmadi
-31007	Buyurtma bajarilgan, bekor qilib bo'lmaydi

Misol:

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

const result = await payme.cancelTransaction({
  id: '5305e3bab097f420a62ced0b',
  reason: CancelReasons.TIMEOUT
});

console.log('Bekor qilindi:', result.cancel_time);
console.log('Holat:', result.state); // -1 yoki -2

---

checkTransaction

Tranzaktsiya holati va tafsilotlarini oladi.

checkTransaction(
  params: CheckTransactionParams
): Promise<CheckTransactionResult>

Parametrlar:

interface CheckTransactionParams {
  id: string; // Payme tranzaktsiya ID
}

Qaytaradi:

interface CheckTransactionResult {
  create_time: number;          // Yaratish vaqti
  perform_time: number;         // Bajarish vaqti (bajarilmagan bo'lsa 0)
  cancel_time: number;          // Bekor qilish vaqti (bekor qilinmagan bo'lsa 0)
  transaction: string;          // Sizning tranzaktsiya ID ingiz
  state: TransactionState;      // Joriy holat
  reason: CancelReason | null;  // Bekor qilish sababi (agar bekor qilingan bo'lsa)
}

Xatolar:

Kod	Tavsif
-31003	Tranzaktsiya topilmadi

Misol:

const result = await payme.checkTransaction({
  id: '5305e3bab097f420a62ced0b'
});

console.log('Holat:', result.state);
console.log('Yaratildi:', new Date(result.create_time));
console.log('Bajarildi:', new Date(result.perform_time));

---

getStatement

Davrdagi tranzaktsiyalar ro'yxatini oladi.

getStatement(
  params: GetStatementParams
): Promise<GetStatementResult>

Parametrlar:

interface GetStatementParams {
  from: number; // Davr boshhi (Unix timestamp ms da)
  to: number;   // Davr oxiri (Unix timestamp ms da)
}

Qaytaradi:

interface GetStatementResult {
  transactions: Transaction[];
}

interface Transaction {
  id: string;                               // Payme tranzaktsiya ID
  time: number;                             // Payme da yaratilish vaqti
  amount: number;                           // Tiyinda suma
  account: Record<string, string | number>; // Akkaunt identifikatori
  create_time: number;                      // Yaratish timestamp
  perform_time: number;                     // Bajarish timestamp
  cancel_time: number;                      // Bekor qilish timestamp
  transaction: string;                      // Sizning tranzaktsiya ID ingiz
  state: TransactionState;                  // Joriy holat
  reason: CancelReason | null;              // Bekor qilish sababi
  receivers: Receiver[] | null;             // Zanjirli to'lov qabul qiluvchilari
}

Misol:

const result = await payme.getStatement({
  from: Date.now() - 86400000, // 24 soat oldin
  to: Date.now()
});

console.log('Tranzaktsiyalar:', result.transactions.length);
result.transactions.forEach(tx => {
  console.log(`${tx.id}: ${tx.state} - ${tx.amount} tiyin`);
});

---

setFiscalData

Payme dan fiskal ma'lumotlarni oladi (ixtiyoriy).

setFiscalData(
  params: SetFiscalDataParams
): Promise<SetFiscalDataResult>

Parametrlar:

interface SetFiscalDataParams {
  id: string;                  // Payme tranzaktsiya ID
  type: 'PERFORM' | 'CANCEL';  // Operatsiya turi
  fiscal_data: FiscalData;     // Fiskal чек ma'lumotlari
}

interface FiscalData {
  receipt_id: number;    // Чек ID
  status_code: number;   // Status kodi
  message: string;       // Status xabari
  terminal_id: string;   // Terminal ID
  fiscal_sign: string;   // Fiskal imzo
  qr_code_url: string;   // QR kod URL
  date: string;          // Чек sanasi
}

Qaytaradi:

interface SetFiscalDataResult {
  success: boolean;
}

Misol:

const result = await payme.setFiscalData({
  id: '5305e3bab097f420a62ced0b',
  type: 'PERFORM',
  fiscal_data: {
    receipt_id: 123456,
    status_code: 0,
    message: 'Muvaffaqiyat',
    terminal_id: 'T001',
    fiscal_sign: 'ABC123',
    qr_code_url: 'https://...',
    date: '2024-01-15T10:30:00Z'
  }
});

console.log('Fiskal ma\'lumotlar saqlandi:', result.success);

---

Turlar

TransactionState

type TransactionState = 1 | 2 | -1 | -2;

// Konstantalar
enum TransactionStates {
  CREATED = 1,      // Yaratilgan, to'lovni kutmoqda
  COMPLETED = 2,    // Yakunlangan, pul o'tkazilgan
  CANCELLED = -1,   // Perform dan oldin bekor qilingan
  REFUNDED = -2     // Perform dan keyin bekor qilingan (qaytarish)
}

CancelReason

type CancelReason = 1 | 2 | 3 | 4 | 5 | 10;

// Konstantalar
enum CancelReasons {
  RECIPIENT_NOT_FOUND = 1,
  DEBIT_ERROR = 2,
  EXECUTION_ERROR = 3,
  TIMEOUT = 4,
  REFUND = 5,
  UNKNOWN = 10
}

---

Xato Kodlari

Umumiy Xatolar

Kod	Tavsif
-32504	Taqiqlangan (noto'g'ri maxfiy ma'lumotlar)
-32400	Tizim xatosi
-31001	Noto'g'ri suma
-31003	Tranzaktsiya topilmadi
-31007	Buyurtma bajarilgan, bekor qilib bo'lmaydi
-31008	Operatsiyani bajarib bo'lmaydi

Akkaunt Xatolari

Kod	Tavsif
-31050	Akkaunt topilmadi
-31051	Noto'g'ri akkaunt
-31052	Akkaunt bloklangan
-31053	Yetarli balans yo'q
...	Maxsus akkaunt xatolari
-31099	Oxirgi akkaunt xato kodi

---

Payme Business Integratsiyasi

IP Ro'yxati

Payme Business callback so'rovlarini faqat quyidagi IP manzillaridan yuboradi:

185.234.113.1 - 185.234.113.15

Muhim

So'rovlarni faqat shu IP manzillaridan qabul qilish uchun firewall sozlang.

Autorizatsiya

Payme Business callback so'rovlari uchun Basic HTTP Autentifikatsiyasidan foydalanadi.

Authorization: Basic base64(login:password)
Content-Type: application/json

Parametr	Tavsif
login	Payme Business texnik mutaxassisidan so'rang
password	Merchant webcheckout qo'shgandan keyin berilgan kalit

Tavsiya etilgan SSL Sozlamalari

# SSL sessiya kesh
ssl_session_cache shared:SSL:1m;
ssl_session_timeout 10m;
keepalive_timeout 10m;

Tranzaktsiya Oqimi Senariysi

CreateTransaction da Javob Yo'qolishi

Agar Payme Business CreateTransaction chaqiruvida javobni yo'qotsa, u bir xil parametrlar bilan so'rovni takrorlaydi. Ilovangiz idempotentlikni qo'llab-quvvatlishi kerak.

Debit Operatsiyasi Xatosi

Debit operatsiyalari paytida xatolik yuz berganda, Payme Business tranzaktsiyani bekor qilish uchun CancelTransaction chaqiradi.

PerformTransaction Xatosi

Agar Payme Business PerformTransaction uchun uzoq vaqt davomida javob olmasa, to'lov jarayoni to'xtatiladi va Payme Business xodimlari tomonidan qo'lda boshqariladi.

---

Keyingi Qadamlar

• Subscribe API Hujjatlari ni tekshiring
• Xatolarni Ishlash haqida bilib oling
• To'lov Oqimi Qo'llanmasi ni ko'ring
• Misollarni o'rganing