Getting Started with @joyida/payme

This guide will help you integrate Payme payments into your application in minutes.

Prerequisites

• Bun >= 1.3.9 (this SDK is supported only on Bun)
• Payme Business account
• Secret key from Payme (Merchant API); for Subscribe API you also need merchant ID and password

Installation

bun add @joyida/payme

Getting Your Credentials

1. Register at Payme Business
2. Create a merchant account
3. Get your credentials:
   • Merchant ID: Found in merchant settings
   • Secret Key: Generated in API settings
   • Password: For Subscribe API (card tokenization)

Quick Start - Merchant API

The Merchant API is used for processing payments.

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

// Initialize client (only secretKey is required for Merchant API auth)
const payme = new PaymeMerchant({
  secretKey: 'your_secret_key',
});

// Check if payment is possible
const check = await payme.checkPerformTransaction({
  amount: 500000, // 5000 UZS in tiyin (1 UZS = 100 tiyin)
  account: { order_id: 'ORD-123' }
});

if (check.allow) {
  console.log('✅ Payment allowed');
}

Quick Start - Subscribe API

The Subscribe API is used for card tokenization and recurring payments.

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

// Client-side mode (for card tokenization)
const subscribeClient = new PaymeSubscribe({
  merchantId: 'your_merchant_id'
}, 'client');

// Create card token
const result = await subscribeClient.cardsCreate({
  card: { 
    number: '8600069195406311', 
    expire: '0399' // MMYY format
  },
  save: true
});

console.log('Card token:', result.card.token);

Environment Variables

Create a .env file in your project root:

PAYME_MERCHANT_ID=your_merchant_id
PAYME_SECRET_KEY=your_secret_key
PAYME_PASSWORD=your_password

Then use in your code:

const payme = new PaymeMerchant({
  merchantId: process.env.PAYME_MERCHANT_ID!,
  secretKey: process.env.PAYME_SECRET_KEY!,
});

TypeScript Support

The library is fully typed with TypeScript. No additional @types packages needed!

import type { 
  CreateTransactionParams,
  CreateTransactionResult 
} from '@joyida/payme';

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

const result: CreateTransactionResult = await payme.createTransaction(params);

Next Steps

• Learn about Configuration Options
• Understand the Payment Flow
• Explore Card Tokenization
• Check API Reference
• See Complete Examples

Common Issues

"Invalid credentials" error

Make sure your Merchant ID and Secret Key are correct. Check for:

• Extra spaces in credentials
• Wrong environment (test vs production)
• Expired or revoked keys

"Amount validation failed" error

Remember that amounts must be in tiyin (1 UZS = 100 tiyin):

• ✅ Correct: 500000 (5000 UZS)
• ❌ Wrong: 5000 (50 UZS)

TypeScript errors

Make sure you're using TypeScript 5.0 or higher:

bun add -d typescript@latest

Getting Help

• GitHub Issues
• Official Payme Documentation
• Email: support@joyida.uz