Subscribe API Reference

Complete reference for Payme Subscribe API - card tokenization and receipt management.

PaymeSubscribe Class

Constructor

new PaymeSubscribe(config: PaymeSubscribeConfig, mode: SubscribeMode)

Parameters:

Parameter	Type	Required	Description
config.merchantId	string	✅	Merchant ID from Payme Business
config.password	string	⚠️ Server only	Password for Subscribe API
config.baseURL	string	❌	API base URL (default: production)
config.timeout	number	❌	Request timeout in ms (default: 60000)
mode	'client' | 'server'	✅	Operation mode

Modes:

• client: For card tokenization (frontend/mobile)
• server: For card management and receipts (backend)

Example:

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

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

// Server-side mode
const subscribeServer = new PaymeSubscribe({
  merchantId: 'your_merchant_id',
  password: 'your_password'
}, 'server');

---

Card Methods

cardsCreate (Client-side)

Create a new card token.

cardsCreate(params: CardsCreateParams): Promise<CardsCreateResult>

Parameters:

interface CardsCreateParams {
  card: {
    number: string;  // Card number (13-19 digits)
    expire: string;  // Expiry date (MMYY format)
  };
  account?: Record<string, unknown>;  // Optional account data
  save?: boolean;                     // Save card for future use
  customer?: string;                  // Customer identifier
}

Returns:

interface CardsCreateResult {
  card: {
    number: string;     // Masked card number
    expire: string;     // Expiry date
    token: string;      // Card token
    recurrent: boolean; // Supports recurring payments
    verify: boolean;    // Verification status (false initially)
  };
}

Example:

const result = await subscribeClient.cardsCreate({
  card: {
    number: '8600069195406311',
    expire: '0399'
  },
  save: true,
  account: { user_id: '12345' }
});

console.log('Token:', result.card.token);
console.log('Verified:', result.card.verify); // false

---

cardsGetVerifyCode (Client-side)

Request SMS verification code for card.

cardsGetVerifyCode(
  params: CardsGetVerifyCodeParams
): Promise<CardsGetVerifyCodeResult>

Parameters:

interface CardsGetVerifyCodeParams {
  token: string; // Card token from cardsCreate
}

Returns:

interface CardsGetVerifyCodeResult {
  sent: boolean;  // SMS sent status
  phone: string;  // Masked phone number (e.g., "99890***1234")
  wait: number;   // Wait time before next request (ms)
}

Example:

const result = await subscribeClient.cardsGetVerifyCode({
  token: 'card_token_here'
});

console.log(`SMS sent to ${result.phone}`);
console.log(`Wait ${result.wait}ms before retry`);

---

cardsVerify (Client-side)

Verify card with SMS code.

cardsVerify(params: CardsVerifyParams): Promise<CardsVerifyResult>

Parameters:

interface CardsVerifyParams {
  token: string; // Card token
  code: string;  // SMS verification code
}

Returns:

interface CardsVerifyResult {
  card: {
    number: string;     // Masked card number
    expire: string;     // Expiry date
    token: string;      // Card token (same)
    recurrent: boolean; // Supports recurring payments
    verify: boolean;    // Verification status (true if successful)
  };
}

Example:

const result = await subscribeClient.cardsVerify({
  token: 'card_token_here',
  code: '666666'
});

if (result.card.verify) {
  console.log('✅ Card verified!');
}

---

cardsCheck (Server-side)

Check card token status.

cardsCheck(params: CardsCheckParams): Promise<CardsCheckResult>

Parameters:

interface CardsCheckParams {
  token: string; // Card token to check
}

Returns:

interface CardsCheckResult {
  card: {
    number: string;     // Masked card number
    expire: string;     // Expiry date
    token: string;      // Card token
    recurrent: boolean; // Supports recurring payments
    verify: boolean;    // Verification status
  };
}

Example:

const result = await subscribeServer.cardsCheck({
  token: 'card_token_here'
});

console.log('Verified:', result.card.verify);
console.log('Recurrent:', result.card.recurrent);

---

cardsRemove (Server-side)

Remove card token.

cardsRemove(params: CardsRemoveParams): Promise<CardsRemoveResult>

Parameters:

interface CardsRemoveParams {
  token: string; // Card token to remove
}

Returns:

interface CardsRemoveResult {
  success: boolean; // Removal status
}

Example:

const result = await subscribeServer.cardsRemove({
  token: 'card_token_here'
});

if (result.success) {
  console.log('✅ Card token removed');
}

---

Receipt Methods

receiptsCreate (Server-side)

Create a new receipt.

receiptsCreate(
  params: ReceiptsCreateParams
): Promise<ReceiptsCreateResult>

Parameters:

interface ReceiptsCreateParams {
  amount: number;                    // Amount in tiyin
  account: Record<string, unknown>;  // Account identifier
  description?: string;              // Receipt description
  detail?: ReceiptDetail;            // Fiscal details
}

interface ReceiptDetail {
  receipt_type?: number;
  shipping?: {
    title: string;
    price: number;
  };
  items: ReceiptItem[];
}

interface ReceiptItem {
  title: string;        // Item name
  price: number;        // Item price in tiyin
  count: number;        // Quantity
  code: string;         // IKPU code
  units?: number;       // Unit type
  vat_percent: number;  // VAT percentage
  package_code: string; // Package code
}

Returns:

interface ReceiptsCreateResult {
  receipt: {
    _id: string;        // Receipt ID
    create_time: number;
    pay_time: number;
    cancel_time: number;
    state: number;      // 0 (waiting for payment)
  };
}

Example:

const result = await subscribeServer.receiptsCreate({
  amount: 500000,
  account: { order_id: '123' },
  description: 'Payment for order #123',
  detail: {
    receipt_type: 0,
    items: [
      {
        title: 'Product Name',
        price: 500000,
        count: 1,
        code: '00702001001000001',
        vat_percent: 15,
        package_code: '123456'
      }
    ]
  }
});

console.log('Receipt ID:', result.receipt._id);

---

receiptsPay (Server-side)

Pay receipt with card token.

receiptsPay(params: ReceiptsPayParams): Promise<ReceiptsPayResult>

Parameters:

interface ReceiptsPayParams {
  id: string;    // Receipt ID
  token: string; // Card token
  payer?: {      // Optional payer info
    phone: string;
  };
}

Returns:

interface ReceiptsPayResult {
  receipt: {
    _id: string;
    state: number; // 1 (paid)
  };
}

Example:

const result = await subscribeServer.receiptsPay({
  id: 'receipt_id_here',
  token: 'card_token_here',
  payer: {
    phone: '998901234567'
  }
});

if (result.receipt.state === 1) {
  console.log('✅ Payment successful!');
}

---

receiptsSend (Server-side)

Send receipt invoice via SMS.

receiptsSend(params: ReceiptsSendParams): Promise<ReceiptsSendResult>

Parameters:

interface ReceiptsSendParams {
  id: string;    // Receipt ID
  phone: string; // Phone number (998XXXXXXXXX)
}

Returns:

interface ReceiptsSendResult {
  success: boolean;
}

Example:

const result = await subscribeServer.receiptsSend({
  id: 'receipt_id_here',
  phone: '998901234567'
});

if (result.success) {
  console.log('✅ SMS sent');
}

---

receiptsCancel (Server-side)

Cancel receipt.

receiptsCancel(
  params: ReceiptsCancelParams
): Promise<ReceiptsCancelResult>

Parameters:

interface ReceiptsCancelParams {
  id: string; // Receipt ID
}

Returns:

interface ReceiptsCancelResult {
  receipt: {
    _id: string;
    cancel_time: number;
    state: number; // 2 (cancelled) or 3 (cancelled after pay)
  };
}

Example:

const result = await subscribeServer.receiptsCancel({
  id: 'receipt_id_here'
});

console.log('Cancelled at:', result.receipt.cancel_time);
console.log('State:', result.receipt.state);

---

receiptsCheck (Server-side)

Check receipt status.

receiptsCheck(
  params: ReceiptsCheckParams
): Promise<ReceiptsCheckResult>

Parameters:

interface ReceiptsCheckParams {
  id: string; // Receipt ID
}

Returns:

interface ReceiptsCheckResult {
  state: number; // 0=waiting, 1=paid, 2=cancelled, 3=cancelled_after_pay
}

Example:

const result = await subscribeServer.receiptsCheck({
  id: 'receipt_id_here'
});

console.log('Receipt state:', result.state);

---

receiptsGet (Server-side)

Get receipt details.

receiptsGet(params: ReceiptsGetParams): Promise<ReceiptsGetResult>

Parameters:

interface ReceiptsGetParams {
  id: string; // Receipt ID
}

Returns:

interface ReceiptsGetResult {
  receipt: Receipt; // Complete receipt object
}

interface Receipt {
  _id: string;
  create_time: number;
  pay_time: number;
  cancel_time: number;
  state: number;
  type: number;
  external: boolean;
  operation: number;
  category: string | null;
  error: string | null;
  description: string;
  detail: ReceiptDetail | null;
  amount: number;
  currency: number;
  commission: number;
  account: Record<string, unknown>[];
  card: CardInfo | null;
  merchant: {
    _id: string;
    name: string;
    organization: string;
    address: string;
    epos: {
      merchantId: string;
      terminalId: string;
    };
    date: number;
    logo: string | null;
    type: string;
    terms: string | null;
  };
  meta: {
    source: string;
    owner: string;
  };
  processing_id: number | null;
}

Example:

const result = await subscribeServer.receiptsGet({
  id: 'receipt_id_here'
});

console.log('Amount:', result.receipt.amount);
console.log('State:', result.receipt.state);
console.log('Card:', result.receipt.card?.number);

---

receiptsGetAll (Server-side)

Get all receipts in date range.

receiptsGetAll(
  params: ReceiptsGetAllParams
): Promise<ReceiptsGetAllResult>

Parameters:

interface ReceiptsGetAllParams {
  from: number;    // Period start (Unix timestamp in ms)
  to: number;      // Period end (Unix timestamp in ms)
  offset?: number; // Pagination offset (default: 0)
  limit?: number;  // Results limit (default: 50)
}

Returns:

interface ReceiptsGetAllResult {
  receipts: Receipt[]; // Array of receipts
}

Example:

const result = await subscribeServer.receiptsGetAll({
  from: Date.now() - 86400000, // 24 hours ago
  to: Date.now(),
  limit: 50
});

console.log('Found receipts:', result.receipts.length);
result.receipts.forEach(receipt => {
  console.log(`${receipt._id}: ${receipt.state} - ${receipt.amount}`);
});

---

Constants

Receipt States

enum RECEIPT_STATES {
  WAITING = 0,              // Waiting for payment
  PAID = 1,                 // Paid
  CANCELLED = 2,            // Cancelled
  CANCELLED_AFTER_PAY = 3   // Cancelled after payment
}

Usage:

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

if (receipt.state === RECEIPT_STATES.PAID) {
  console.log('Receipt paid');
}

---

Error Handling

All Subscribe API errors are mapped to descriptive messages. Check the official Payme documentation for complete error code list.

Common errors:

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

try {
  await subscribeClient.cardsCreate(params);
} catch (error) {
  if (error instanceof PaymeError) {
    console.error('Error code:', error.code);
    console.error('Message:', error.message);
    
    // Handle specific errors
    if (error.code === -31050) {
      console.error('Invalid card number');
    }
  }
}

---

Next Steps

• Check Merchant API Reference
• Learn about Card Tokenization
• Explore Receipt Management
• See Error Handling