Payment SDK

TypeScript SDK для интеграции с payme, click и uzum.

Быстрая документация для интегратора лежит в:

• SDK Docs
• Getting Started
• Next.js Integration
• Provider Guides
• Webhook Guide
• Testing Matrix
• Releasing

Install

npm install uz-payment-sdk

Money Contract

Во всём SDK поле amount передаётся просто в UZS.

• 500 = 500 UZS
• 1250.5 = 1250.5 UZS

Это правило едино для:

• Payme receipts.*
• Click invoice/payment/fiscalization
• Uzum Checkout
• webhook payloads и normalized responses

Внутри драйверов SDK сам конвертирует сумму в provider-specific формат там, где провайдер ожидает минимальные единицы валюты.

Stable Contract

Для интеграции можно считать стабильными такие правила:

• PaymentResult.amount всегда возвращается в UZS
• PaymentResult.success вычисляется из нормализованного status, а не из raw provider payload
• PaymentResult.isTerminal, isSettled, isFinalSuccess, requiresAction дают более безопасные флаги для серверного branching
• transactionId — основной SDK id для дальнейших операций
• providerInvoiceId и providerPaymentId сохраняют official ids провайдера, когда они реально есть
• checkoutReference даёт стабильную ссылку на checkout/order flow без парсинга raw

Эти правила зафиксированы и экспортируются из SDK как:

• SDK_RESULT_CONTRACT
• SDK_SUPPORT_POLICY

Quick Start

import { PaymentsService } from 'uz-payment-sdk';

const payments = new PaymentsService({
  providers: {
    click: {
      serviceId: '101202',
      merchantId: 'merchant-1',
      merchantUserId: 'merchant-user-1',
      secretKey: 'secret',
      apiUrl: 'https://api.click.uz/v2/merchant'
    }
  }
});

const invoice = await payments.createClickInvoice({
  orderId: 'order-123',
  amount: 500,
  phoneNumber: '998901234567'
});

const invoiceUrl = payments.generateInvoiceUrl({
  provider: 'click',
  orderId: 'order-123',
  amount: 500,
  returnUrl: 'https://your-app.uz/payments/return'
});

PaymentsService поддерживает оба стиля:

• create({ provider, ...data })
• create(provider, data)

И поверх этого даёт явные facade methods:

• createClickInvoice
• checkClickInvoice
• checkClickPayment
• checkClickPaymentByOrder
• cancelClickPayment
• createPaymeReceipt
• checkPaymeReceipt
• cancelPaymeReceipt
• getPaymeReceipt
• sendPaymeReceipt
• payPaymeReceipt
• setPaymeReceiptFiscalData
• registerUzumPayment
• completeUzumPayment
• reverseUzumPayment
• refundUzumPayment
• merchantPayUzum
• getUzumReceipts
• purchaseUzumReceipt

Если нужен более низкий уровень, можно работать напрямую с provider clients:

• PaymeClient
• ClickClient
• UzumClient

У этих методов можно передавать optional request options:

• signal
• timeoutMs
• retry

Для server-side интеграции также доступны helper-ы:

• createPaymentsServiceFromEnv
• createWebhookServiceFromEnv
• createPaymentSdkServerServices
• parseProviderWebhookRequest
• processProviderWebhookRequest

Для transport integration доступны:

• createAxiosTransport
• createFetchTransport
• transport и requestDefaults в PaymentSdkConfig

Важно для webhook processing:

• для production нужно передать shared cacheStore (Redis/DB-backed), иначе WebhookService не запустит идемпотентную обработку
• allowInMemoryWebhookIdempotency оставлен только для single-process development и тестов

Error Model

SDK экспортирует typed errors:

• PaymentSdkError
• PaymentValidationError
• PaymentConfigurationError
• PaymentTransportError
• PaymeError
• ClickError

У typed errors доступны поля:

• code
• provider
• httpStatus
• retryable
• category

Support Matrix

Provider	Covered now	Notes
Payme	receipts.create, receipts.check, receipts.cancel, receipts.get, receipts.send, receipts.pay, receipts.set_fiscal_data, hosted invoice URL, optional card token flow (cards.create, cards.get_verify_code, cards.verify, cards.check)	public SDK amount всегда в UZS
Click	invoice.create, invoice.status, payment.status, payment.status_by_mti, payment.reversal, hosted invoice URL, fiscalization submit/get endpoints	invoice flow и payment flow разделены по official docs
Uzum Checkout	payment.register, payment.getOrderStatus, payment.getOperationState, payment.merchantPay, payment.getReceipts, acquiring.complete, acquiring.refund, acquiring.reverse, acquiring.purchaseReceipt	merchant callbacks вынесены в отдельный toolkit
Uzum Merchant API	typed request/response helpers для /check, /create, /confirm, /reverse, /status, basic auth validation helper	нужно реализовать свой HTTP handler в приложении

Provider Examples

Payme

const payments = new PaymentsService({
  providers: {
    payme: {
      merchantId: process.env.PAYME_MERCHANT_ID!,
      key: process.env.PAYME_KEY!,
      apiUrl: process.env.PAYME_API_URL!,
    }
  }
});

const receipt = await payments.createPaymeReceipt({
  orderId: 'order-1',
  amount: 2500,
});

await payments.sendPaymeReceipt({
  transactionId: receipt.transactionId,
  phone: '998901234567',
});

Click

const status = await payments.checkClickPayment({
  paymentId: '1946296773',
});

await payments.cancelClickPayment({
  paymentId: '1946296773',
});

Uzum

const registered = await payments.registerUzumPayment({
  orderId: '504e8fa5-2eab-456a-acc3-822147fd0c533',
  amount: 1500,
  returnUrl: 'https://merchant.example/return',
});

await payments.refundUzumPayment({
  orderId: registered.transactionId,
  amount: 1500,
});

Uzum Merchant Webhook Toolkit

import {
  createUzumMerchantCheckResponse,
  createUzumMerchantConfirmErrorResponse,
  validateUzumMerchantAuthorization,
} from 'uz-payment-sdk';

Доступно:

• validateUzumMerchantAuthorization
• createUzumMerchantAuthorizationHeader
• createUzumMerchantCheckResponse
• createUzumMerchantCheckErrorResponse
• createUzumMerchantCreateResponse
• createUzumMerchantCreateErrorResponse
• createUzumMerchantConfirmResponse
• createUzumMerchantConfirmErrorResponse
• createUzumMerchantReverseResponse
• createUzumMerchantReverseErrorResponse
• createUzumMerchantStatusResponse
• createUzumMerchantStatusErrorResponse

Важно: helper-ы для Uzum Merchant API повторяют официальный webhook contract провайдера. Если Uzum требует raw amount в минимальных единицах, в этих webhook responses нужно следовать именно official schema.

Webhook Forwarding Env

• ENTERPRISE_WEBHOOK_URL
• ENTERPRISE_WEBHOOK_SECRET
• ENTERPRISE_WEBHOOK_TIMEOUT_MS
• ENTERPRISE_WEBHOOK_SOURCE
• ENTERPRISE_WEBHOOK_HEADER_PREFIX

Repo Layout

• src/core — стабильные SDK contracts и общие правила
• src/providers/payme — low-level Payme client
• src/providers/click — low-level Click client
• src/providers/uzum — low-level Uzum client
• src/payments — high-level facade и нормализация результатов
• src/webhooks — webhook parsing, normalization и Uzum merchant toolkit
• src/server — server-only helpers для Next.js/fetch runtimes
• docs/examples — минимальные примеры интеграции

Scripts

• npm run typecheck
• npm run test:contracts
• npm test
• npm run test:bun
• npm run test:matrix
• npm run build
• npm run release:smoke