Merchant API Reference

Complete reference for Payme Merchant API methods.

PaymeMerchant Class

Constructor

new PaymeMerchant(config: PaymeConfig)

Parameters:

Parameter	Type	Required	Description
config.merchantId	string	✅	Merchant ID from Payme Business
config.secretKey	string	✅	Secret key from Payme Business
config.baseURL	string	❌	API base URL (default: production)
config.timeout	number	❌	Request timeout in ms (default: 60000)

Example:

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

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

---

Methods

checkPerformTransaction

Check if a transaction can be performed without creating it.

checkPerformTransaction(
  params: CheckPerformTransactionParams
): Promise<CheckPerformTransactionResult>

Parameters:

interface CheckPerformTransactionParams {
  amount: number;                           // Amount in tiyin
  account: Record<string, string | number>; // Account identifier
}

Returns:

interface CheckPerformTransactionResult {
  allow: boolean;                           // Can transaction be performed
  additional?: Record<string, unknown>;     // Additional data
  detail?: FiscalDetail;                    // Fiscal details (optional)
}

Errors:

Code	Description
-31001	Invalid amount
-31050 to -31099	Account validation errors
-32400	System error

Example:

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

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

---

createTransaction

Create a new transaction and lock the order.

createTransaction(
  params: CreateTransactionParams
): Promise<CreateTransactionResult>

Parameters:

interface CreateTransactionParams {
  id: string;                               // Payme transaction ID (24 chars)
  time: number;                             // Unix timestamp in ms
  amount: number;                           // Amount in tiyin
  account: Record<string, string | number>; // Account identifier
}

Returns:

interface CreateTransactionResult {
  create_time: number;                      // Creation timestamp
  transaction: string;                      // Your transaction ID
  state: TransactionState;                  // Transaction state (1)
  receivers?: Receiver[] | null;            // Chain payment receivers
}

Errors:

Code	Description
-31001	Invalid amount
-31008	Cannot perform operation
-31050 to -31099	Account validation errors

Example:

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

console.log('Transaction ID:', result.transaction);
console.log('State:', result.state); // 1 (created)

---

performTransaction

Complete a transaction and transfer money.

performTransaction(
  params: PerformTransactionParams
): Promise<PerformTransactionResult>

Parameters:

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

Returns:

interface PerformTransactionResult {
  transaction: string;      // Your transaction ID
  perform_time: number;     // Perform timestamp
  state: TransactionState;  // Transaction state (2)
}

Errors:

Code	Description
-31003	Transaction not found
-31008	Cannot perform operation

Example:

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

console.log('Payment completed at:', result.perform_time);
console.log('State:', result.state); // 2 (completed)

---

cancelTransaction

Cancel a transaction (before or after perform).

cancelTransaction(
  params: CancelTransactionParams
): Promise<CancelTransactionResult>

Parameters:

interface CancelTransactionParams {
  id: string;           // Payme transaction ID
  reason: CancelReason; // Cancellation reason (1-5, 10)
}

Cancel Reasons:

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

Returns:

interface CancelTransactionResult {
  transaction: string;      // Your transaction ID
  cancel_time: number;      // Cancel timestamp
  state: TransactionState;  // Transaction state (-1 or -2)
}

Errors:

Code	Description
-31003	Transaction not found
-31007	Order fulfilled, cannot cancel

Example:

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

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

console.log('Cancelled at:', result.cancel_time);
console.log('State:', result.state); // -1 or -2

---

checkTransaction

Get transaction status and details.

checkTransaction(
  params: CheckTransactionParams
): Promise<CheckTransactionResult>

Parameters:

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

Returns:

interface CheckTransactionResult {
  create_time: number;          // Creation timestamp
  perform_time: number;         // Perform timestamp (0 if not performed)
  cancel_time: number;          // Cancel timestamp (0 if not cancelled)
  transaction: string;          // Your transaction ID
  state: TransactionState;      // Current state
  reason: CancelReason | null;  // Cancel reason (if cancelled)
}

Errors:

Code	Description
-31003	Transaction not found

Example:

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

console.log('State:', result.state);
console.log('Created:', new Date(result.create_time));
console.log('Performed:', new Date(result.perform_time));

---

getStatement

Get list of transactions for a period.

getStatement(
  params: GetStatementParams
): Promise<GetStatementResult>

Parameters:

interface GetStatementParams {
  from: number; // Period start (Unix timestamp in ms)
  to: number;   // Period end (Unix timestamp in ms)
}

Returns:

interface GetStatementResult {
  transactions: Transaction[];
}

interface Transaction {
  id: string;                               // Payme transaction ID
  time: number;                             // Creation time in Payme
  amount: number;                           // Amount in tiyin
  account: Record<string, string | number>; // Account identifier
  create_time: number;                      // Creation timestamp
  perform_time: number;                     // Perform timestamp
  cancel_time: number;                      // Cancel timestamp
  transaction: string;                      // Your transaction ID
  state: TransactionState;                  // Current state
  reason: CancelReason | null;              // Cancel reason
  receivers: Receiver[] | null;             // Chain payment receivers
}

Example:

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

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

---

setFiscalData

Receive fiscal data from Payme (optional).

setFiscalData(
  params: SetFiscalDataParams
): Promise<SetFiscalDataResult>

Parameters:

interface SetFiscalDataParams {
  id: string;                  // Payme transaction ID
  type: 'PERFORM' | 'CANCEL';  // Operation type
  fiscal_data: FiscalData;     // Fiscal receipt data
}

interface FiscalData {
  receipt_id: number;    // Receipt ID
  status_code: number;   // Status code
  message: string;       // Status message
  terminal_id: string;   // Terminal ID
  fiscal_sign: string;   // Fiscal sign
  qr_code_url: string;   // QR code URL
  date: string;          // Receipt date
}

Returns:

interface SetFiscalDataResult {
  success: boolean;
}

Example:

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

console.log('Fiscal data saved:', result.success);

---

Types

TransactionState

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

// Constants
enum TransactionStates {
  CREATED = 1,      // Created, awaiting payment
  COMPLETED = 2,    // Completed, money transferred
  CANCELLED = -1,   // Cancelled before perform
  REFUNDED = -2     // Cancelled after perform (refund)
}

CancelReason

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

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

---

Error Codes

Common Errors

Code	Description
-32504	Forbidden (invalid credentials)
-32400	System error
-31001	Invalid amount
-31003	Transaction not found
-31007	Order fulfilled, cannot cancel
-31008	Cannot perform operation

Account Errors

Code	Description
-31050	Account not found
-31051	Invalid account
-31052	Account blocked
-31053	Insufficient balance
...	Custom account errors
-31099	Last account error code

---

Payme Business Integration

IP Whitelist

Payme Business sends callbacks to your billing system only from these IP addresses:

185.234.113.1 - 185.234.113.15

Important

Configure your firewall to allow incoming requests only from these IP addresses.

Authorization

Payme Business uses Basic HTTP Authentication for callback requests.

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

Parameter	Description
login	Request from Payme Business technical specialist
password	Key provided after merchant adds webcheckout

Recommended SSL Settings

# SSL session cache
ssl_session_cache shared:SSL:1m;
ssl_session_timeout 10m;
keepalive_timeout 10m;

Transaction Flow Scenario

Lost Response on CreateTransaction

If Payme Business loses response when calling CreateTransaction, it repeats the request with the same parameters. Your application should handle idempotency.

Debit Operation Error

If an error occurs during debit operations, Payme Business calls CancelTransaction to cancel the transaction.

PerformTransaction Error

If Payme Business doesn't receive a response for PerformTransaction within a long time, payment process is suspended and managed manually by Payme Business staff.

---

Next Steps

• Check Subscribe API Reference
• Learn about Error Handling
• See Payment Flow Guide
• Explore Examples