Subscribe API Documentation

Complete technical reference for Payme Subscribe API - card tokenization and recurring payments.

Protocol Overview

The Payme Subscribe API uses JSON-RPC 2.0 protocol for all communications. All requests and responses are JSON-encoded.

JSON-RPC Handshake

Request Format

{
  "id": "unique-request-id",
  "method": "cards.create",
  "params": {
    "card": {
      "number": "8600069195406311",
      "expire": "0399"
    },
    "save": true
  }
}

Response Format

{
  "id": "unique-request-id",
  "result": {
    "card": {
      "token": "ed12345a6789000bcdef",
      "verify": false,
      "number": "8600***6311",
      "expire": "0399",
      "recurrent": true
    }
  }
}

Error Response Format

{
  "id": "unique-request-id",
  "error": {
    "code": -31050,
    "message": "Invalid card number"
  }
}

---

Endpoints

Test Environment

https://checkout.test.paycom.uz/api

Use this endpoint for integration testing and development.

Production Environment

https://checkout.paycom.uz/api

Use this endpoint for live transactions.

---

Authorization

Client-Side (Card Tokenization)

Client-side card tokenization uses the X-Auth header with only the merchant ID.

POST /api/cards.create
X-Auth: merchant_id
Content-Type: application/json

Server-Side (Card Management & Receipts)

Server-side API calls require the X-Auth header with both merchant ID and password.

POST /api/cards.check
X-Auth: merchant_id:password
Content-Type: application/json

The X-Auth header is constructed as merchantId:password in plain text (not hashed).

---

Card Tokenization Flow

The card tokenization process follows these steps:

1. Create Card Token - Client submits card details and receives a temporary token
2. Request Verification Code - Client requests SMS verification code for the card
3. Verify Card - Client submits the SMS code to confirm card ownership
4. Use Token - Server can now use the verified token for payments

Storing Unencrypted Card Data is Strictly Prohibited

Never store card numbers, expiry dates, or any card-related data in unencrypted form. Always use the token provided by the Subscribe API for any card-related operations. Violation of this requirement may result in serious legal consequences and PCI DSS compliance violations.

---

Form Implementation Requirements

When implementing card collection forms, you must adhere to the following requirements:

Prohibited Attributes

Form Constraints

HTML forms used for card data collection must NOT include:

• name attribute on input fields collecting card data
• action attribute on the form element
• Any attribute that could cause data to be submitted to your servers

The card data must be sent directly to Payme's servers using their provided SDK or iframe integration.

Required Elements

Your payment form must include:

1. "Powered by Payme" Label - A visible link to Payme
2. Terms of Service Link - Link to Payme's terms of service
3. Privacy Policy Link - Link to Payme's privacy policy

Secure Frame Integration

Always use Payme's secure iframe or SDK for card input fields. Never create custom card input components.

---

Security Best Practices

Tokenization

Card tokenization is the core security mechanism. Key points:

• Tokens are non-reversible - You cannot derive the original card number from a token
• Tokens are merchant-specific - A token created for one merchant cannot be used by another
• Tokens can be verified - Check card.verify status before using for payments

What to Store

Safe Data to Store

• Card token (card.token)
• Masked card number (card.number - format: 8600***6311)
• Expiry date (card.expire)
• Verification status (card.verify)
• Recurring capability (card.recurrent)

Prohibited Data

Never store:

• Full card number
• CVV/CVC codes
• Card PIN
• SMS verification codes

---

Testing and Test Cards

Before going live, thoroughly test your integration using Payme's test environment.

Test Credentials

To access the test merchant dashboard:

Parameter	Value
Login (Phone)	phone
Password	qwerty
SMS Code	666666

SMS Code for All Test Cards

The SMS verification code for all test cards is 666666. This code works regardless of the card type or expected behavior.

Test Cards

Use the following test cards to verify different scenarios:

Card Number	Expiry	Comment
8600 0609 2109 0842	03/99	SMS-info not connected
3333 3364 1580 4657	03/99	Card expired
4444 4459 8745 9073	03/99	Card blocked
8600 1434 1777 0323	03/99	Unknown system error
8600 1343 0184 9596	03/99	10s delay simulation (ends in error)
8600 4954 7331 6478	03/99	Success card
8600 0691 9540 6311	03/99	Success card

Test Scenarios

1. Success Cards (8600 4954 7331 6478, 8600 0691 9540 6311) - Complete tokenization and payment successfully
2. Expired Card (3333 3364 1580 4657) - Verify proper handling of expired cards
3. Blocked Card (4444 4459 8745 9073) - Test blocked card error handling
4. SMS Not Connected (8600 0609 2109 0842) - Test scenario when SMS verification is unavailable
5. Delay Simulation (8600 1343 0184 9596) - Test timeout handling (10 second delay before error)
6. Unknown Error (8600 1434 1777 0323) - Test handling of unexpected errors

---

Compliance Requirements

When using Payme Subscribe API, you must comply with:

1. PCI DSS Compliance - Ensure your systems meet PCI DSS requirements
2. Data Protection - Follow local data protection regulations
3. User Consent - Obtain explicit user consent before storing card tokens
4. Clear Disclosure - Clearly explain how card data is processed and stored

---

Next Steps

• Subscribe API SDK Reference - Complete SDK documentation
• Card Tokenization Guide - Implementation guide
• Receipt Management - Managing recurring payments
• Error Handling - Error codes and handling