How to Integrate Payme Into a Website: Developer Guide

The short answer

Payme integration works "in reverse": your site does not poll Payme — Payme calls your endpoint to ask whether a payment can be accepted, create a transaction, perform it and cancel it if needed. You need to:

1. Register as a merchant and create a cashbox.
2. Implement the Merchant API methods on your server.
3. Send the customer to the Payme checkout page with the order reference.
4. Pass the sandbox tests and switch to the live key.

Merchant registration

• Register your business in the Payme Business dashboard and sign the agreement.
• Create a cashbox for the site. You get a cashbox ID (merchant ID), a test key and a live key.
• In the cashbox settings, set your endpoint URL and the account field Payme uses to find an order, for example order_id.

Keep keys in environment variables, never in the repository.

How Payme calls your server

Every call is a JSON-RPC 2.0 POST request with an Authorization: Basic ... header that encodes Paycom:<cashbox key>. Always respond with HTTP 200 and put any error in the response body.

function isPaymeAuthorized(header: string | null, key: string): boolean {
  if (!header?.startsWith("Basic ")) return false;
  const decoded = Buffer.from(header.slice(6), "base64").toString();
  const sep = decoded.indexOf(":");
  return decoded.slice(0, sep) === "Paycom" && decoded.slice(sep + 1) === key;
}

On failed authorization, return error -32504.

Merchant API methods

Amounts arrive in tiyin, times in milliseconds.

Transaction states

• 1 — created, waiting to be performed.
• 2 — performed, money charged, the order can be fulfilled.
• -1 — cancelled before being performed.
• -2 — cancelled after being performed (refund).

Store in your table: the Payme transaction ID, order ID, amount, state, create_time, perform_time, cancel_time and the cancellation reason. Every method response is built from these fields.

Key handling rules

• Idempotency. A repeated CreateTransaction or PerformTransaction with the same id must return the same result, not create a new record.
• One order, one active transaction. If an order already has a transaction in state 1, reject a new one with a different id using an error from the account range.
• Timeout. A transaction not performed within the time set in the documentation gets cancelled, and PerformTransaction on it returns an error.
• Cancelling after performing is allowed only if your business process permits a refund. If the goods can no longer be returned, respond with the "cannot cancel" error.
• Fiscal data. If your cashbox requires fiscalization, pass receipt items with IKPU codes in the documented format.

Checkout link

The customer is sent to the Payme checkout page. The link encodes the cashbox ID, the account field and the amount in tiyin, plus an optional return URL. Note: the customer returning to your site does not confirm payment. The order becomes "paid" only in PerformTransaction.

Testing in the sandbox

Payme provides a sandbox where you enter your endpoint URL and test key and run scenarios: wrong authorization, nonexistent order, wrong amount, create, perform, cancel before and after performing, repeated calls. Switch to the live key only once every scenario passes.

The full specification is in the Payme developer documentation.

Typical integration errors

• Amount in sum instead of tiyin: the amount check fails on every order.
• Responding with HTTP 401 or 500 instead of HTTP 200 with an error object.
• Creating a new record on a repeated CreateTransaction instead of returning the existing one.
• Marking the order paid on CreateTransaction instead of PerformTransaction.
• Time in seconds instead of milliseconds.
• The test key left in production after launch.