Создание подписочного платежа
Рекуррентные платежи по банковской карте позволяют списывать средства по токену сохранённой карты без повторного ввода реквизитов плательщиком. При активной привязке списание выполняется через GATE (init_payment).
Для включения функционала в проекте обратитесь к сопровождающему менеджеру 1Payment.
Формат запросов и подписи — в разделе Формат запроса к API.
Принцип работы
Процесс работы с подписками по картам состоит из четырёх этапов:
- Первый платёж (привязка карты) — проведите успешный платёж с параметром
subscription=1через форму оплаты или GATE (host2host). Плательщик вводит данные карты и проходит 3-D Secure при необходимости. - Получение токена — после успешной оплаты 1Payment передаёт уникальный
tokenв колбеке наnotify_urlили в ответе запроса статуса. Сохраните его для последующих списаний. - Автосписание (рекуррент) — для повторных оплат ваш сервер вызывает GATE (
init_payment), передавая сохранённыйtokenвместо полейaccount,card_holder,year,monthиcvc. - Уведомление — после каждой попытки списания приходит колбек с финальным результатом транзакции.
Техническая информация
| Этап | Эндпоинт | Методы |
|---|---|---|
| Регистрация подписки (форма) | https://api.1payment.com/init_form | GET, POST |
| Регистрация подписки (GATE) | https://api.1payment.com/init_payment | GET, POST |
| Рекуррентное списание (GATE) | https://api.1payment.com/init_payment | POST (рекомендуется), GET |
Формат ответа: JSON. Для карт в запросах GATE указывайте payment_type=card.
1. Получение токена (первый платёж)
Для привязки карты проведите успешный платёж с параметром subscription=1. Подробнее о параметрах формы и GATE — в разделах Создание платежа по форме и Создание платежа по host2host (GATE). Ниже — обязательный набор для привязки.
Обязательные параметры (инициация через форму)
| Параметр | Тип | Описание |
|---|---|---|
partner_id | Integer | Ваш уникальный ID в системе 1Payment. |
project_id | Integer | Идентификатор вашего проекта. |
amount | Number | Сумма платежа при привязке (например, 50.00). |
subscription | Integer | Флаг создания подписки. Всегда 1. Без него токен в ответе не вернётся. |
user_data | String | Ваш уникальный ID заказа для сопоставления. |
shop_url | String | URL сайта, на котором совершается покупка. |
sign | String | Контрольная подпись (см. ниже). |
Обязательные параметры (инициация через GATE)
| Параметр | Тип | Описание |
|---|---|---|
partner_id | Integer | Ваш уникальный ID в системе 1Payment. |
payment_type | String | Всегда card. |
project_id | Integer | Идентификатор вашего проекта. |
account | String | Номер банковской карты. |
card_holder | String | Имя держателя карты (как указано на карте). |
year | String | Год окончания действия карты, две последние цифры (например, 22). |
month | String | Месяц окончания действия карты (например, 01). |
cvc | String | CVV/CVC код карты. |
amount | Number | Сумма платежа при привязке (например, 50.00). |
subscription | Integer | Флаг создания подписки. Всегда 1. Без него токен в ответе не вернётся. |
user_data | String | Ваш уникальный ID заказа для сопоставления. |
shop_url | String | URL сайта источника платежа. |
sign | String | Контрольная подпись (см. ниже). |
Дополнительные параметры (инициация)
| Параметр | Тип | Описание |
|---|---|---|
description | String | Описание платежа. |
success_url | String | URL возврата клиента при успехе (форма). |
failure_url | String | URL возврата клиента при ошибке (форма). |
return_url | String | URL возврата плательщика после оплаты (GATE). |
ip | String | IP-адрес плательщика (GATE). |
user_id | String | ID плательщика в вашей системе. |
Подпись при регистрации через форму — префикс init_form. Через GATE — префикс init_payment.
MD5(init_form + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)MD5(init_payment + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)После финального статуса SUCCESS сохраните значение token из колбека или из ответа Статусы платежей.
2. Рекуррентное списание (повторные платежи)
Для автоматического списания отправьте запрос на GATE с сохранённым token. Не передавайте account, card_holder, year, month и cvc — вместо них используется только token.
Обязательные параметры (рекуррент)
| Параметр | Тип | Описание |
|---|---|---|
partner_id | Integer | Ваш уникальный ID в системе 1Payment. |
payment_type | String | Всегда card. |
project_id | Integer | Идентификатор вашего проекта. |
amount | Number | Сумма очередного списания (например, 500.00). |
token | String | Токен, полученный при первом успешном платеже (из колбека или запроса статуса). |
user_data | String | Новый уникальный ID транзакции на вашей стороне. |
shop_url | String | URL сайта источника платежа. |
sign | String | Контрольная подпись (префикс init_payment). |
Дополнительные параметры (рекуррент)
| Параметр | Тип | Описание |
|---|---|---|
description | String | Описание платежа. |
ip | String | IP-адрес плательщика. |
return_url | String | URL возврата плательщика после оплаты. |
user_id | String | ID плательщика в вашей системе. |
Формирование подписи (sign)
Подпись: MD5, lowercase (hex). Общие правила — Формат запроса к API.
Формула:
MD5(init_payment + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)Пример строки до хеширования:
init_paymentamount=500.00&partner_id=1234&payment_type=card&project_id=5678&shop_url=https://test.com&token=card_t_1a2b3c&user_data=card_order_888secret_keyПроверка подписи (рекуррентное списание)
Проверка подписи {{method}}
Вставьте параметры запроса (JSON), API key и подпись. Виджет автоматически проверит корректность.
amount=500.00&partner_id=1234&payment_type=card&project_id=5678&shop_url=https://test.com&token=card_t_1a2b3c&user_data=card_order_888init_paymentamount=500.00&partner_id=1234&payment_type=card&project_id=5678&shop_url=https://test.com&token=card_t_1a2b3c&user_data=card_order_88859785c76ce35d08da343e6b8eec1e459Примеры запроса
const crypto = require('crypto');
const axios = require('axios');
// 1. Инициация подписки через форму (первичная привязка)
async function setupCardSubscriptionForm(apiKey, params) {
const sortedKeys = Object.keys(params).sort();
const queryString = sortedKeys.map((k) => `${k}=${params[k]}`).join('&');
const baseString = `init_form${queryString}${apiKey}`;
params.sign = crypto.createHash('md5').update(baseString).digest('hex');
const response = await axios.post('https://api.1payment.com/init_form', params);
return response.data; // поле url — ссылка на форму
}
// 2. Инициация подписки через GATE
async function setupCardSubscriptionGate(apiKey, params) {
const sortedKeys = Object.keys(params).sort();
const queryString = sortedKeys.map((k) => `${k}=${params[k]}`).join('&');
const baseString = `init_payment${queryString}${apiKey}`;
params.sign = crypto.createHash('md5').update(baseString).digest('hex');
const response = await axios.post('https://api.1payment.com/init_payment', params);
return response.data; // redirect_url при необходимости 3-D Secure
}
// 3. Рекуррентное списание (по токену)
async function chargeCardByToken(apiKey, params) {
const sortedKeys = Object.keys(params).sort();
const queryString = sortedKeys.map((k) => `${k}=${params[k]}`).join('&');
const baseString = `init_payment${queryString}${apiKey}`;
params.sign = crypto.createHash('md5').update(baseString).digest('hex');
const response = await axios.post('https://api.1payment.com/init_payment', params);
return response.data;
}
const apiKey = process.env.ONEPAYMENT_API_KEY;
// Пример: привязка через форму
const setupFormData = {
partner_id: 1234,
project_id: 5678,
amount: '50.00',
subscription: 1,
user_data: 'card_setup_777',
shop_url: 'https://test.com',
};
// setupCardSubscriptionForm(apiKey, setupFormData).then(console.log);
// Пример: привязка через GATE
const setupGateData = {
partner_id: 1234,
payment_type: 'card',
project_id: 5678,
account: '4111111111111111',
card_holder: 'TEST',
year: '22',
month: '01',
cvc: '111',
amount: '50.00',
subscription: 1,
user_data: 'card_setup_777',
shop_url: 'https://test.com',
};
// setupCardSubscriptionGate(apiKey, setupGateData).then(console.log);
// Пример: списание
const recurringData = {
partner_id: 1234,
payment_type: 'card',
project_id: 5678,
token: 'card_t_1a2b3c',
amount: '500.00',
user_data: 'card_order_888',
shop_url: 'https://test.com',
};
chargeCardByToken(apiKey, recurringData).then(console.log);Ответ API
При успешном рекуррентном запросе (200):
{
"order_id": "8p3brmb19gfg0sg8gcwhws8kgc748s87",
"status": 2,
"status_description": "PENDING",
"status_code": 0
}| Поле | Описание |
|---|---|
order_id | ID платежа в системе 1Payment; используйте для запроса статуса. |
status | Числовой код состояния (2 — ожидание). |
status_description | Текстовое описание статуса (PENDING и др.). |
status_code | Код ошибки при отказе (см. коды отказов). |
redirect_url | URL для 3-D Secure, если требуется дополнительная аутентификация (может отсутствовать). |
При первом платеже с subscription=1 через форму в ответе будет поле url (см. Создание платежа по форме); через GATE — redirect_url при необходимости 3-D Secure (см. Создание платежа по host2host (GATE)). После успешной оплаты поле token приходит в колбеке на notify_url или в ответе запроса статуса — без subscription=1 токен не выдаётся.
Ошибка запроса (400):
{
"error_code": 2
}Уведомления о статусе (колбеки)
При успешной привязке карты или рекуррентном списании система отправляет POST-запрос в формате JSON на ваш notify_url.
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
payment_type | String | Да | Тип платежа (card). |
order_id | String | Да | ID платежа в системе 1Payment. |
project_id | Integer | Да | ID вашего проекта. |
status | Integer | Да | Состояние: 2 (ожидание), 3 (успех), 4 (отказ). |
status_description | String | Да | PENDING, SUCCESS или FAILURE. |
init_time | String | Да | Время создания платежа. |
status_time | String | Да | Время получения финального статуса. |
merchant_price | Number | Да | Стоимость для плательщика. |
init_price | Number | Нет | Сумма при инициации. |
user_price | Number | Да | Отчисления партнёра. |
currency | String | Да | Валюта платежа (ISO 4217). |
account | String | Да | Маска номера карты. |
user_data | String | Да | ID транзакции, переданный при создании. |
sign | String | Да | Контрольная подпись колбека. |
token | String | Нет | Токен для последующих списаний — сохраните при первом успешном платеже. |
test | Integer | Нет | 1 при тестовых платежах. |
status_code | String | Нет | Код причины отказа. |
Важно: ваш сервер должен вернуть HTTP 200 OK. Иначе система повторяет отправку колбека раз в минуту в течение 10 минут.
Проверка подписи колбека: MD5 от всех параметров в алфавитном порядке через & + API_KEY (без префикса init_payment). Подробнее — в разделе Формат запроса к API.
Токен также можно получить через запрос статуса платежа — поле token в ответе API.