Payme Kisuke.uz — PayMe API Package

Ushbu paket PayMe.uz merchant API bilan ishlash uchun yaratilgan Go dasturlash tilida yozilgan to'liq paket.

✨ Xususiyatlar

• To'liq Receipts API — Barcha PayMe receipts methodlari qo'llab-quvvatlanadi
• Webhook Handler — PayMe webhook so'rovlarini avtomatik qayta ishlash
• Type Safety — Kuchli type system bilan xatolarni oldini olish
• Error Handling — To'liq xatolarni qayta ishlash
• Test Mode — Test va production muhitlari uchun alohida endpointlar
• Documentation — To'liq hujjatlar va misollar

📦 O'rnatish

go get payme.kisuke.uz

🚀 Tezkor Boshlash

1. Client Yaratish

package main

import (
    "context"
    "fmt"
    "payme.kisuke.uz/pkg/payme"
)

func main() {
    // PayMe client yaratish
    client := payme.NewClient(payme.ClientConfig{
        PaymeID:        "your-payme-id",
        PaymeKey:       "your-payme-key",
        IsTestMode:     true,
        RequisiteName:  "order_id", // charge_id, order_id, yoki id
        Timeout:        30,
    })

    // Receipt yaratish - RequisiteName ga qarab account map yaratish
    account := map[string]interface{}{
        client.RequisiteName: "123", // charge_id, order_id, yoki id
        "card_id":            "9999",
        "reason":             "test_payment",
    }

    // Receipt yaratish
    req := &payme.CreateReceiptRequest{
        Amount:      10000, // 100 so'm (tiyinda)
        Account:     map[string]interface{}{"charge_id": "123"},
        Description: "Test receipt",
        Detail:      map[string]interface{}{"method": "test"},
    }

    ctx := context.Background()
    resp, err := client.CreateReceipt(ctx, req)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Receipt yaratildi: %s\n", resp.Receipt.ID)
}

2. Webhook Handler

package main

import (
    "github.com/gofiber/fiber/v2"
    "payme.kisuke.uz/pkg/payme"
    "time"
)

// SimpleReceiptProvider webhook handler
type SimpleReceiptProvider struct{}

func (rp *SimpleReceiptProvider) CreateReceipt(params map[string]interface{}) (*payme.CreateReceiptResponse, error) {
    // Receipt yaratish logic
    receipt := &payme.Receipt{
        ID:          "receipt_123",
        CreateTime:  time.Now().UnixMilli(),
        State:       payme.ReceiptStateCreated,
        Amount:      10000,
        Currency:    payme.CurrencyUZS,
        Description: "Test receipt",
    }
    
    return &payme.CreateReceiptResponse{Receipt: receipt}, nil
}

// Boshqa methodlarni ham implement qilish kerak...

func main() {
    app := fiber.New()
    
    // Webhook endpoint ni sozlash
    payme.SetupWebhookWithPath(app, "your-payme-key", &SimpleReceiptProvider{}, "/webhook/payme")
    
    app.Listen(":8080")
}

⚙️ Sozlamalar

RequisiteName

RequisiteName field PayMe API ga yuboriladigan account object da qaysi nom ishlatilishini belgilaydi:

• charge_id — PayMe merchant ID (default)
• order_id — Order ID
• id — Universal ID

Bu field ga qarab, account map da to'g'ri nom ishlatiladi:

// charge_id bilan
client.RequisiteName = "charge_id"
account := map[string]interface{}{
    "charge_id": "123",
    "card_id":   "9999",
    "reason":    "test_payment",
}

// order_id bilan  
client.RequisiteName = "order_id"
account := map[string]interface{}{
    "order_id": "123",
    "card_id":  "9999", 
    "reason":   "test_payment",
}

ClientConfig

💰 Currency Codes

PayMe API qo'llab-quvvatlaydigan currency codes:

📚 API Methodlari

Receipts API

Sizning receipts.create Requestingiz

{
  "charge_id": 123,
  "method": "receipts.create",
  "params": {
    "amount": 10000,
    "account": {
      "charge_id": 108,
      "card_id": "9999",
      "reason": "1232132132132131"
    },
    "description": "DESC",
    "detail": {
      "method": "refill_driver_balance"
    }
  }
}

Response:

{
  "result": {
    "receipt": {
      "_id": "receipt_108_1755113788",
      "create_time": 1755113788877,
      "state": 0,
      "amount": 10000,
      "currency": 860,
      "description": "DESC"
    }
  }
}

GetAllReceipts Method

// Barcha receiptlarni olish
from := time.Now().AddDate(0, -1, 0).UnixMilli() // 1 oy oldin
to := time.Now().UnixMilli()                      // Hozirgi vaqt
count := 10                                       // Maksimal soni

allReceipts, err := client.GetAllReceipts(ctx, from, to, count)
if err != nil {
    log.Printf("Xatolik: %v", err)
} else {
    fmt.Printf("Jami receiptlar: %d\n", len(allReceipts.Receipts))
    
    for _, receipt := range allReceipts.Receipts {
        if receipt != nil {
            fmt.Printf("ID: %s, Summa: %s, Holat: %d\n",
                receipt.ID,
                payme.FormatAmount(receipt.Amount, receipt.Currency),
                receipt.State)
        }
    }
}

Parameters:

• from — Boshlang'ich vaqt (Unix timestamp, millisecond)
• to — Tugash vaqti (Unix timestamp, millisecond)
• count — Maksimal qaytariladigan receipt soni

Response:

{
  "result": [
    {
      "_id": "receipt_1",
      "create_time": 1755113788877,
      "state": 1,
      "amount": 10000,
      "currency": 860
    },
    {
      "_id": "receipt_2",
      "create_time": 1755113788878,
      "state": 0,
      "amount": 20000,
      "currency": 860
    }
  ]
}

🔧 Konfiguratsiya

Environment Variables

PAYME_ID=your-payme-id
PAYME_KEY=your-payme-key
PAYME_TEST_MODE=true
PAYME_TIMEOUT=30

Client Config

type ClientConfig struct {
    PaymeID    string `json:"payme_id"`     // PayMe merchant ID
    PaymeKey   string `json:"payme_key"`    // PayMe secret key
    IsTestMode bool   `json:"is_test_mode"` // Test mode (true/false)
    Timeout    int    `json:"timeout"`      // Request timeout (seconds)
}

🌐 Endpointlar

• Test: https://checkout.test.paycom.uz/api
• Production: https://checkout.paycom.uz/api

📊 Receipt States

💰 Currency Codes (Qo‘shimcha)

🚨 Error Codes

📁 Fayl Strukturasi

payment-kisuke-uz/
├── pkg/
│   └── payme/
│       ├── constants/     # Konstantalar
│       ├── types/         # Data turlari
│       ├── client/        # HTTP client
│       ├── handlers/      # Webhook handler
│       └── payme.go       # Asosiy paket
├── example/               # Misollar
├── go.mod                 # Go moduli
└── README.md              # Hujjat

🧪 Test Qilish

cd payment-kisuke-uz
go mod tidy
go run example/main.go

🔒 Xavfsizlik

• API Key — Har doim xavfsiz saqlang
• HTTPS — Faqat HTTPS orqali ishlatish
• Validation — Barcha inputlarni tekshirish
• Rate Limiting — So'rovlar sonini cheklash

🤝 Hissa Qo'shish

1. Repository ni fork qiling
2. Yangi branch yarating
3. O'zgarishlarni qo'shing
4. Pull request yuboring

📄 License

MIT License — LICENSE faylini ko'ring

📞 Aloqa

• Email: support@kisuke.uz
• Website: https://kisuke.uz
• Documentation: https://payme.kisuke.uz

🙏 Minnatdorchilik

• PayMe.uz — To'lov tizimi
• Go — Dasturlash tili

Made with ❤️ by Kisuke.uz