NAV Navbar
shell javascript python php

1.1 Платежный виджет

1.1.1 Подключение

Для подключения платежного виджета используется скрипт:

https://paymo.ru/paymentgate/iframe/checkout.js

1.1.2 Вызов платежного виджета

Ниже приведен пример для метода set() и open():

<script src="https://paymo.ru/paymentgate/iframe/checkout.js"></script>

<script>
    PaymoFrame.set({
        parent_id: "iframe_parent",
        api_key: "e5ebc0d4-f90b-409b-874c-c729987001da",
        tx_id: "123",
        description: "Тестовый платеж",
        amount: 1000,
        signature: "0cm9ri03f303ed09mf3",
        success_redirect: "http://yoursite.ru/success_redirect",
        fail_redirect: "http://yoursite.ru/success_redirect",
        auto_return: 1,
        rebill: {},
        extra:{
            some_key: "some_value",
            some_key2: "some_value2"
        },
        phone: "79991234567",
        email: "email@mail.com",
        send_post_message: false,
        version: "2.0.0"
    })
</script>

<div id="iframe_parent"></div>

Существует объект PaymoFrame и его два метода для вызова платежного виджета: set() и open().

При использовании метода open() виджет будет отображаться по центру экрана, тогда как при методе set() добавление виджета будет произведен в тот элемент, который передается в параметре parent_id.

Демо-магазин можно посмотреть: Вариант 1 и Вариант 2.

Описание параметров

Название Обязательно Описание
parent_id Да Элемент, в который будет произведено добавление iframe.
api_key Да Ключ магазина, который генерируется автоматически при создании магазина. Доступен на вкладке "Магазины" личного кабинета.
tx_id Да Номер транзакции в магазине. Может быть любым набором символов. Должен быть уникален в пределах выбранного магазина.
description Нет Назначение (описание) платежа.
amount Да Сумма платежа в копейках.
signature Да Формирование подписи. По умолчанию подпись формируется с помощью алгоритма SHA256: sha256("api_key"+"tx_id"+"amount"+"secret_key"). Пример на php: $signature = hash('sha256', $api_key.$tx_id.$amount.$secret_key); secret_key задается в Личном кабинете, раздел Магазины => Настройки => Технические настройки
success_redirect Нет URL для возврата при успешном платеже.
fail_redirect Нет URL для возврата при неуспешном платеже (fail и success URL могут быть одинаковыми).
auto_return Нет Автоматический редирект на success_redirect (или fail_redirect) после оплаты. Задается в секундах, например при: auto_return: 1, редирект произойдет через 1 секунду.
rebill Нет При использовании рекуррентных платежей (см. Рекурректные платежи).
extra Нет Дополнительные параметры платежа (см. Дополнительные параметры платежа).
phone Нет Номер телефона пользователя.
email Нет Email пользователя.
send_post_message Нет Метод postMessage() отправляет сообщение от iframe на сайт мерчанта. При инициализации виджета отправляется сообщение paymo-widget-init. При успешном платеже отправляется сообщение paymo-payment-success, а при неуспешном платеже отправляется сообщение paymo-payment-unsuccess. Уведомления при ошибке инициализации: paymo-init-error-api_key, paymo-init-error-invalid_parameters, paymo-init-error-payment_module, paymo-init-error-invalid_transaction, paymo-init-error-invalid_data, paymo-init-error-amount, paymo-init-error
version Нет Версия платежного виджета. Доступны две версии: 1.0.0 и 2.0.0

1.2 Страница UNIFORM

Пример кода для вставки:

 <div>
     <form action="https://checkout.paymo.ru/uniform/" method="POST">
         <input type="hidden" name="api_key" value="e5ebc0d4-f90b-409b-874c-c729987001da">
         <input type="hidden" name="amount" value="10000">
         <input type="hidden" name="tx_id" value="2484984984984">
         <input type="hidden" name="description" value="Назначение (описание) платежа">
         <input type="hidden" name="signature" value="0cm9ri03f303ed09mf3">
         <input type="hidden" name="email" value="client@e-mail.ru">
         <input type="hidden" name="phone" value="79991234567">
         <input type="hidden" name="success_redirect" value="http://yoursite.com/success">
         <input type="hidden" name="fail_redirect" value="http://yoursite.com/fail">
         <input type="hidden" name="auto_return" value="10">
         <input type="hidden" name="extra_key1" value="value1">
         <input type="hidden" name="extra_key2" value="value2">
         <input type="submit" value="Оплатить">
     </form>
 </div>

Оплата с переходом на платёжную страницу, разработанная сервисом оплаты PAYMO. После завершения оплаты клиент будет направлен обратно на страницу интернет-магазина.

Демо-магазин можно посмотреть здесь.

Описание параметров

Название Обязательно Описание
api_key Да Ключ магазина, который генерируется автоматически при создании магазина. Доступен на вкладке "Магазины" личного кабинета.
tx_id Да Номер транзакции в магазине. Может быть любым набором символов. Должен быть уникален в пределах выбранного магазина.
description Нет Назначение (описание) платежа.
amount Да Сумма платежа в копейках.
signature Да Формирование подписи. По умолчанию подпись формируется с помощью алгоритма SHA256: sha256("api_key"+"tx_id"+"amount"+"secret_key"). Пример на php: $signature = hash('sha256', $api_key.$tx_id.$amount.$secret_key); secret_key задается в Личном кабинете, раздел Магазины => Настройки => Технические настройки
success_redirect Нет URL для возврата при успешном платеже.
fail_redirect Нет URL для возврата при неуспешном платеже (fail и success URL могут быть одинаковыми).
auto_return Нет Время (в секундах) для авторедиректа на success или fail URL
phone Нет Номер телефона пользователя.
email Нет Email пользователя.
extra_<key> Нет Дополнительные параметры платежа. В форме может быть несколько дополнительных параметров платежа, которые передаются в виде: "extra_"+"название параметра".

1.3 Выставление счетов

1.3.1 Создание счетов

Пример запроса:

curl -X POST \
  "https://paymo.ru/rest/merchant/invoice/" \
  -H 'content-type: application/json' \
  -d '{
    "api_key": "26785c66-10a0-4485-ab67-7e1558cbfdc6", 
    "contact": "7**********", 
    "price": "1.05", 
    "description": "Тестовый счет", 
    "order": "23"
  }'

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://paymo.ru/rest/merchant/invoice/',
  headers: {
    'content-type': 'application/json'
  },
  body: {
    api_key: '26785c66-10a0-4485-ab67-7e1558cbfdc6',
    contact: '7**********',
    price: '1.05',
    description: 'Тестовый счет',
    order: '22'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

response = requests.post('https://paymo.ru/rest/merchant/invoice/', json={
    'api_key': '26785c66-10a0-4485-ab67-7e1558cbfdc6',
    'contact': '7**********',
    'price': '1.05',
    'description': 'Тестовый счет',
    'order': '22'
})

response.json()

<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://paymo.ru/rest/merchant/invoice/', [
    'json' => [
        'api_key' => '26785c66-10a0-4485-ab67-7e1558cbfdc6',
        'contact' => '7**********',
        'price' => '1.05',
        'description' => 'Тестовый счет',
        'order' => '22'
    ]
]);

$result = json_decode((string)$response->getBody(), true);

Пример ответа:

{
    "result_sms": "success",
    "message_sms": "Счет отправлен на указанный телефон.",
    "url": "https://checkout.paymo.ru/invoice/?invoice=64ab820b365c508f",
    "qr_code_url": "https://paymo.ru/qr/invoice_qr/64ab820b365c508f/"
}

Рассмотрим пример выставления счета на E-mail или по SMS ваших клиентов.

HTTP Request

POST https://paymo.ru/rest/merchant/invoice/

Параметры запроса

Название Обязательно Описание
api_key Да Ключ магазина, который генерируется автоматически при создании магазина. Доступен на вкладке "Магазины" личного кабинета.
contact Нет Номер телефона пользователя (7**********).
contact_email Нет Email пользователя.
price Да Сумма счета в рублях.
description Да Описание счета.
order Да Номер счета в системе магазина.
life_time Нет Дата окончания действия счета, после чего он будет отменен. Формат даты: %d.%m.%Y %H:%M. Временная зона: Москва. Например: 15.10.2015 10:45.
departure_type Нет Тип уведомления покупателя. Сущестует четыре типа уведомления: url, sms-email, sms или email. По умолчанию тип, в завивимости от переданных данных, определяется автоматически.
extra Нет Дополнительные параметры платежа (см. Дополнительные параметры платежа).

Параметры ответа

Название Обязательно Описание
result Нет Результат выполнения операции success / fail.
message Нет Сообщение с информацией о результате выполнения операции.
result_sms Нет Результат выполнения операции success / fail.
message_sms Нет Сообщение с информацией о результате отправки ссылки на счет на указанный номер телефона.
result_email Нет Результат выполнения операции success / fail.
message_email Нет Сообщение с информацией о результате отправки ссылки на счет на указанный email.
url Нет Ссылка на счет.
qr_code_url Нет Ссылка на qr код, в котором закодирован url на счет.

1.3.2 Получение статуса счета

Пример запроса:

curl -X POST \
  "https://paymo.ru/rest/merchant/invoice/status/" \
  -H 'content-type: application/json' \
  -d '{
    "api_key": "26785c66-10a0-4485-ab67-7e1558cbfdc6", 
    "order": "23"
  }'

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://paymo.ru/rest/merchant/invoice/status/',
  headers: {
    'content-type': 'application/json'
  },
  body: {
    api_key: '26785c66-10a0-4485-ab67-7e1558cbfdc6',
    order: "23"
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

response = requests.post('https://paymo.ru/rest/merchant/invoice/status/', json={
    'api_key': '26785c66-10a0-4485-ab67-7e1558cbfdc6',
    'order': '23'
})

response.json()

<?php
$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://paymo.ru/rest/merchant/invoice/status/', [
    'json' => [
        'api_key' => '26785c66-10a0-4485-ab67-7e1558cbfdc6',
        'order' => '23'
    ]
]);

$result = json_decode((string)$response->getBody(), true);

Пример ответа:

{
    "result": "success",
    "message": "Счет найден.",
    "status": "processing",
    "url": "https://checkout.paymo.ru/invoice/?invoice=64ab820b365c508f",
    "qr_code_url": "https://paymo.ru/qr/invoice_qr/64ab820b365c508f/"
}

HTTP Request

POST https://paymo.ru/rest/merchant/invoice/status/

Параметры запроса

Название Обязательно Описание
api_key Да Ключ магазина, который генерируется автоматически при создании магазина. Доступен на вкладке "Магазины" личного кабинета.
order Да Номер счета в системе магазина.

Параметры ответа

Название Обязательно Описание
result Да Результат выполнения операции success / fail.
message Да Сообщение с информацией о результате выполнения операции.
status Да Статус счета. (см. Возможные статусы счета)
url Нет Ссылка на счет.
qr_code_url Нет Ссылка на qr код, в котором закодирован url на счет.

1.3.3 Start и Finish CallBacks

Такие же, как и в п. 1.7 Start и Finish CallBacks

Отличия есть только в Finish CallBack. Дополнительно передаются следующие параметры:

Название Описание
order_id Номер счета.
invoice_status Статус счета. (см. Возможные статусы счета)

1.3.4 Возможные статусы счета

Название Описание
save Сохранен
processing Не оплачен.
deposited Оплачен.
declined Отменен.
inactive Не активен.

1.4 Статус платежа

1.4.1 Получение статуса платежа

Пример запроса:

curl -X POST \
  "https://paymo.ru/rest/merchant/transaction/status/get/" \
  -H 'content-type: application/json' \
  -d '{
    "hash_sum": "6fad00e9f8b62749e51edd1a6843a4cd2f568418289440f8e6d26a5b212016de", 
    "transaction": "5bfa60f6-10db-43b0-7d37-c34bef543147", 
    "api_key": "26785c66-10a0-4485-ab67-7e1558cbfdc6"
  }'

var request = require("request");
var sha256 = require("sha256");


var api_key = '26785c66-10a0-4485-ab67-7e1558cbfdc6';
var transaction = '5bfa60f6-10db-43b0-7d37-c34bef543147';
var amount = 3.99;
var secret_key = 'your_secret_key';

var params = [api_key, transaction, parseInt(amount * 100).toString(), secret_key];

var hash_sum = sha256(params.join(''));

var options = {
  method: 'POST',
  url: 'https://paymo.ru/rest/merchant/transaction/status/get/',
  headers: {
    'content-type': 'application/json'
  },
  body:
    {
      hash_sum: hash_sum,
      transaction: transaction,
      api_key: api_key
    },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

from Crypto.Hash import SHA256

api_key = '26785c66-10a0-4485-ab67-7e1558cbfdc6'
transaction = '5bfa60f6-10db-43b0-7d37-c34bef543147'
amount = 3.99
secret_key = 'your_secret_key'

params = [api_key, transaction, str(int(amount * 100)), secret_key]

hash_sum = SHA256.new(''.join(params).encode()).hexdigest()

response = requests.post('https://paymo.ru/rest/merchant/transaction/status/get/', json={
    'hash_sum': hash_sum,
    'transaction': transaction,
    'api_key': api_key
})

response.json()

<?php
$api_key = '26785c66-10a0-4485-ab67-7e1558cbfdc6';
$transaction = '5bfa60f6-10db-43b0-7d37-c34bef543147';
$amount = 3.99;
$secret_key = 'your_secret_key';

$params = [$api_key, $transaction, (string) $amount * 100, $secret_key];

$hash_sum = hash('sha256', implode('', $params));

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://paymo.ru/rest/merchant/transaction/status/get/', [
    'json' => [
        'hash_sum' => $hash_sum,
        'transaction' => $transaction,
        'api_key' => $api_key
    ]
]);

$result = json_decode((string)$response->getBody(), true);

Пример ответа:

{
    "result": "success",
    "message": "Transaction find",
    "status": "deposited",
    "id": 508,
    "time": "2014-11-26T09:34:11.686600+00:00",
    "sum": "3.99",
    "commission": "0"
}

Метод используется для получения статуса конкретного платежа.

HTTP Request

POST https://paymo.ru/rest/merchant/transaction/status/get/

Параметры запроса

Название Обязательно Описание
api_key Да Ключ магазина, который генерируется автоматически при создании магазина. Доступен на вкладке "Магазины" личного кабинета.
transaction Да Идентификатор транзакции.
hash_sum Да Формирование подписи: sha256("api_key"+"transaction"+"amount"+"secret_key"). Пример на php: $signature = hash('sha256', $api_key.$transaction.$amount.$secret_key);
secret_key задается в разделе Магазины => Настройки => Технические настройки
amount сумма платежа в копейках.

Параметры ответа

Название Обязательно Описание
result Да Результат выполнения платежа success / fail.
message Да Сообщение с информацией о результате выполнения платежа.
status Да Статус транзакции.

1.4.2 Возможные статусы платежа

Название Описание
processing Платеж в обработке.
deposited Транзакция совершена успешно.
declined Транзакция неуспешна.
wait_external Ожидается подтверждение от внешней платежной системы.
refunded Осуществлен полный возврат денежных средств.
approved Денежные средства захолдированы, ожидается подтверждение платежа.
part_deposited Произведено частичное списание захолдированных средств.
part_refunded Произведен частичный возврат денежных средств.

1.5 Возврат платежа

Пример запроса:

curl -X POST \
  "https://paymo.ru/rest/v2/payment/refund/" \
  -H 'content-type: application/json' \
  -d '{
    "api_key": "ef592cb4-90fc-4b45-bc40-0a656fb9e613",
    "tx_id": "6315",
    "refund_amount": 124.83,
    "signature": "bd91c62c1f1b55edd427d09bcb6b726d"
  }'

var request = require("request");
var sha256 = require("sha256");

var api_key = '26785c66-10a0-4485-ab67-7e1558cbfdc6';
var tx_id = '6315';
var refund_amount = 124.83;
var secret_key = 'your_secret_key';

var signature = sha256(api_key + tx_id + secret_key);

var options = { 
  method: 'POST',
  url: 'https://paymo.ru/rest/v2/payment/refund/',
  headers: {
     'content-type': 'application/json'
  },
  body: { 
    api_key: api_key,
    tx_id: tx_id,
    refund_amount: refund_amount,
    signature: signature
  },
  json: true 
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

from Crypto.Hash import SHA256

api_key = '26785c66-10a0-4485-ab67-7e1558cbfdc6'
tx_id = '6315'
refund_amount = 124.83
secret_key = 'your_secret_key'

params = [api_key, tx_id, secret_key]

signature = SHA256.new(''.join(params).encode()).hexdigest()

response = requests.post('https://paymo.ru/rest/v2/payment/refund/', json={ 
    'api_key': api_key,
    'tx_id': tx_id,
    'refund_amount': refund_amount,
    'signature': signature
})

response.json()

<?php
$api_key = '26785c66-10a0-4485-ab67-7e1558cbfdc6';
$tx_id = '6315';
$refund_amount = 124.83;
$secret_key = 'your_secret_key';

$signature = hash('sha256', $api_key . $tx_id . $secret_key);

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://paymo.ru/rest/v2/payment/refund/', [
    'json' => [
        'api_key' => $api_key,
        'tx_id' => $tx_id,
        'refund_amount' => $refund_amount,
        'signature' => $signature
    ]
]);

$result = json_decode((string)$response->getBody(), true);

Пример ответа:

{
    "result": true,
    "refund_amount": "124.83"
}

При выполнении данного метода вызывается Finish callback, согласно механизму модулей и отправляется письмо мерчанту "Отчет об успешном возврате средств".

HTTP Request

POST https://paymo.ru/rest/v2/payment/refund/

Параметры запроса

Название Обязательно Описание
api_key Да Ключ магазина, который генерируется автоматически при создании магазина. Доступен на вкладке "Магазины" личного кабинета.
tx_id Да Идентификатор транзакции.
signature Да Формирование подписи: sha256("api_key"+"tx_id"+"secret_key"). Пример на php: $signature = hash('sha256', $api_key.$tx_id.$secret_key);
secret_key задается в разделе Магазины => Настройки => Технические настройки
refund_amount Нет Сумма частичного возврата, в рублях. Указывается, если сумма возвращается не полностью. Если сумма не указана или равняется нулю, то платеж возвращается полностью.
refund_amount_kop Нет Сумма частичного возврата в копейках. Приоритет выше, чем у refund_amount. Если переданы оба параметра, то будет учитываться только refund_amount_kop
available_amount Нет Данный параметр можно использовать, чтобы избежать случайных повторных запросов при частичных возвратах. В данном параметре необходимо передавать доступную сумму платежа. Например, если платеж был на 100 р, available_amount = 100. После частичного возврата на 10 рублей, available_amount будет равен 90 р. Если сделать еще один запрос с available_amount = 100, возврат не произойдет и в ответе будет возвращена ошибка.

Параметры ответа

Название Описание
result Результат выполнения операции true / false.
refund_amount Сумма возврата
errors Массив, содержащий код ошибки.

Возможные коды ошибок

Название Код ошибки Описание
AMOUNT_INVALID 17004 Неверно указана сумма возврата
PART_REFUND_IMPOSSIBLE 18001 Частичный возврат невозможен
REST_REFUND_DENIED 18002 Возврат запрещен
TERMINAL_INVALID 21002 Проблемы с терминалом либо некорректный api-key магазина
TRANSACTION_REQUIRED 22001 Не указан номер транзакции
TRANSACTION_INVALID 22002 Неверно указан номер транзакции
TRANSACTION_NOT_DEPOSITED 22004 Транзакция находится в статусе, при котором невозможен возврат
API_KEY_REQUIRED 81001 Не указан api-key магазина
API_KEY_INVALID 81002 Некорректный api-key магазина
UNKNOWN_ERROR 92004 Неизвестная ошибка
MODULE_INVALID 95002 Ошибка платежного модуля
SIGNATURE_REQUIRED 96001 Не указана сигнатура
SIGNATURE_INVALID 96002 Неверно указана сигнатура
SECRET_KEY_INVALID 96003 В магазине не сгенерирован secret key.

1.6 Рекуррентные платежи

1.6.1 Параметры рекуррента для iframe виджета

Пример использования:

{
  "rebill": {
    "amount": 100, 
    "period": "1.0", 
    "end": "31-12-2026", 
    "start_at": "20-10-2023"
  }
}

При инициализации iframe на сайте мерчанта необходимо добавить следующие параметры:

Название Обязательно Описание
amount Да Сумма в рублях (например 15 или 15.60).
period Да Периодичность платежа в формате <кол-во месяцев>.<кол-во дней> (например, 3.0 - каждые 3 месяца, 1.0 - каждый месяц, 0.40 - каждые 40 дней).
end Да Дата окончания ребиллов в формате DD-MM-YYYY (например, 20-12-2015 - после 20-го декабря 2015 ребиллы прекращаются).
start_at Нет Дата первого рекуррентного платежа в формате DD-MM-YYYY (например, 20-10-2016 - 20-е октября 2016); время списания берётся от времени первоначального платежа.