Configuration Guide

Learn how to configure @joyida/payme for different environments and use cases.

Merchant API Configuration

Basic Configuration

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

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

Full Configuration

const payme = new PaymeMerchant({
  merchantId: 'your_merchant_id',
  secretKey: 'your_secret_key',
  baseURL: 'https://checkout.paycom.uz/api', // Optional
  timeout: 30000, // Optional, in milliseconds
});

Configuration Options

Option	Type	Required	Default	Description
merchantId	string	✅ Yes	-	Your merchant ID from Payme Business
secretKey	string	✅ Yes	-	Your secret key from Payme Business
baseURL	string	❌ No	https://checkout.paycom.uz/api	API base URL
timeout	number	❌ No	60000	Request timeout in milliseconds

Subscribe API Configuration

Client-Side Mode

Used for card tokenization (frontend/mobile apps):

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

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

Server-Side Mode

Used for card management and receipts (backend):

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

Configuration Options

Option	Type	Required	Default	Description
merchantId	string	✅ Yes	-	Your merchant ID
password	string	⚠️ Server only	-	Your password for Subscribe API
baseURL	string	❌ No	https://checkout.paycom.uz/api	API base URL
timeout	number	❌ No	60000	Request timeout in milliseconds

Environment-Based Configuration

Development Environment

const payme = new PaymeMerchant({
  merchantId: process.env.PAYME_MERCHANT_ID_TEST!,
  secretKey: process.env.PAYME_SECRET_KEY_TEST!,
  baseURL: 'https://checkout.test.paycom.uz/api', // Test environment
  timeout: 10000, // Shorter timeout for development
});

Production Environment

const payme = new PaymeMerchant({
  merchantId: process.env.PAYME_MERCHANT_ID!,
  secretKey: process.env.PAYME_SECRET_KEY!,
  baseURL: 'https://checkout.paycom.uz/api', // Production (default)
  timeout: 60000, // Longer timeout for production
});

Using Environment Variables

Create a .env file:

# Development
PAYME_MERCHANT_ID_TEST=test_merchant_id
PAYME_SECRET_KEY_TEST=test_secret_key

# Production
PAYME_MERCHANT_ID=prod_merchant_id
PAYME_SECRET_KEY=prod_secret_key
PAYME_PASSWORD=prod_password

# Environment
NODE_ENV=development

Configuration helper:

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

const isDevelopment = process.env.NODE_ENV === 'development';

const payme = new PaymeMerchant({
  merchantId: isDevelopment 
    ? process.env.PAYME_MERCHANT_ID_TEST!
    : process.env.PAYME_MERCHANT_ID!,
  secretKey: isDevelopment
    ? process.env.PAYME_SECRET_KEY_TEST!
    : process.env.PAYME_SECRET_KEY!,
  baseURL: isDevelopment
    ? 'https://checkout.test.paycom.uz/api'
    : 'https://checkout.paycom.uz/api',
  timeout: isDevelopment ? 10000 : 60000,
});

Configuration Factory Pattern

Create a reusable configuration factory:

// config/payme.ts
import { PaymeMerchant, PaymeSubscribe } from '@joyida/payme';

export function createPaymeMerchant() {
  return new PaymeMerchant({
    merchantId: process.env.PAYME_MERCHANT_ID!,
    secretKey: process.env.PAYME_SECRET_KEY!,
    timeout: 30000,
  });
}

export function createPaymeSubscribe(mode: 'client' | 'server') {
  return new PaymeSubscribe({
    merchantId: process.env.PAYME_MERCHANT_ID!,
    password: mode === 'server' ? process.env.PAYME_PASSWORD : undefined,
  }, mode);
}

Usage:

import { createPaymeMerchant, createPaymeSubscribe } from './config/payme';

const merchant = createPaymeMerchant();
const subscribe = createPaymeSubscribe('server');

Timeout Configuration

Understanding Timeouts

The timeout option controls how long to wait for a response from Payme API:

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

Recommended Timeouts

Environment	Recommended Timeout	Reason
Development	10000ms (10s)	Fast feedback during development
Staging	30000ms (30s)	Balance between speed and reliability
Production	60000ms (60s)	Maximum reliability for real payments

Handling Timeout Errors

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

try {
  const result = await payme.createTransaction(params);
} catch (error) {
  if (error instanceof NetworkError && error.timeout) {
    console.error(`Request timed out after ${error.timeout}ms`);
    // Retry logic here
  }
}

Base URL Configuration

Production URL (Default)

const payme = new PaymeMerchant({
  merchantId: 'your_merchant_id',
  secretKey: 'your_secret_key',
  // baseURL: 'https://checkout.paycom.uz/api' (default)
});

Test/Sandbox URL

const payme = new PaymeMerchant({
  merchantId: 'your_merchant_id',
  secretKey: 'your_secret_key',
  baseURL: 'https://checkout.test.paycom.uz/api',
});

Custom URL (Self-Hosted Proxy)

const payme = new PaymeMerchant({
  merchantId: 'your_merchant_id',
  secretKey: 'your_secret_key',
  baseURL: 'https://api.yourdomain.com/payme-proxy',
});

Validation Configuration

The library includes built-in validation. You can disable it if needed:

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

// Validate manually before API call
try {
  Validator.validateAmount(500000);
  Validator.validateCardNumber('8600069195406311');
  Validator.validateCardExpiry('0399');
} catch (error) {
  console.error('Validation failed:', error.message);
}

Security Best Practices

✅ Do's

• Store credentials in environment variables
• Use different credentials for test and production
• Rotate secret keys regularly
• Use HTTPS for all API calls
• Validate all user inputs before sending to Payme

❌ Don'ts

• Never commit credentials to version control
• Never expose secret keys in client-side code
• Never log sensitive data (card numbers, tokens)
• Never use production credentials in development

Next Steps

• Learn about Authentication
• Understand the Payment Flow
• Explore Error Handling