Перейти к содержимому

Создание подписочного платежа

Рекуррентные платежи по банковской карте позволяют списывать средства по токену сохранённой карты без повторного ввода реквизитов плательщиком. При активной привязке списание выполняется через GATE (init_payment).

Для включения функционала в проекте обратитесь к сопровождающему менеджеру 1Payment.

Формат запросов и подписи — в разделе Формат запроса к API.

Принцип работы

Процесс работы с подписками по картам состоит из четырёх этапов:

  1. Первый платёж (привязка карты) — проведите успешный платёж с параметром subscription=1 через форму оплаты или GATE (host2host). Плательщик вводит данные карты и проходит 3-D Secure при необходимости.
  2. Получение токена — после успешной оплаты 1Payment передаёт уникальный token в колбеке на notify_url или в ответе запроса статуса. Сохраните его для последующих списаний.
  3. Автосписание (рекуррент) — для повторных оплат ваш сервер вызывает GATE (init_payment), передавая сохранённый token вместо полей account, card_holder, year, month и cvc.
  4. Уведомление — после каждой попытки списания приходит колбек с финальным результатом транзакции.

Техническая информация

ЭтапЭндпоинтМетоды
Регистрация подписки (форма)https://api.1payment.com/init_formGET, POST
Регистрация подписки (GATE)https://api.1payment.com/init_paymentGET, POST
Рекуррентное списание (GATE)https://api.1payment.com/init_paymentPOST (рекомендуется), GET

Формат ответа: JSON. Для карт в запросах GATE указывайте payment_type=card.

1. Получение токена (первый платёж)

Для привязки карты проведите успешный платёж с параметром subscription=1. Подробнее о параметрах формы и GATE — в разделах Создание платежа по форме и Создание платежа по host2host (GATE). Ниже — обязательный набор для привязки.

Обязательные параметры (инициация через форму)

ПараметрТипОписание
partner_idIntegerВаш уникальный ID в системе 1Payment.
project_idIntegerИдентификатор вашего проекта.
amountNumberСумма платежа при привязке (например, 50.00).
subscriptionIntegerФлаг создания подписки. Всегда 1. Без него токен в ответе не вернётся.
user_dataStringВаш уникальный ID заказа для сопоставления.
shop_urlStringURL сайта, на котором совершается покупка.
signStringКонтрольная подпись (см. ниже).

Обязательные параметры (инициация через GATE)

ПараметрТипОписание
partner_idIntegerВаш уникальный ID в системе 1Payment.
payment_typeStringВсегда card.
project_idIntegerИдентификатор вашего проекта.
accountStringНомер банковской карты.
card_holderStringИмя держателя карты (как указано на карте).
yearStringГод окончания действия карты, две последние цифры (например, 22).
monthStringМесяц окончания действия карты (например, 01).
cvcStringCVV/CVC код карты.
amountNumberСумма платежа при привязке (например, 50.00).
subscriptionIntegerФлаг создания подписки. Всегда 1. Без него токен в ответе не вернётся.
user_dataStringВаш уникальный ID заказа для сопоставления.
shop_urlStringURL сайта источника платежа.
signStringКонтрольная подпись (см. ниже).

Дополнительные параметры (инициация)

ПараметрТипОписание
descriptionStringОписание платежа.
success_urlStringURL возврата клиента при успехе (форма).
failure_urlStringURL возврата клиента при ошибке (форма).
return_urlStringURL возврата плательщика после оплаты (GATE).
ipStringIP-адрес плательщика (GATE).
user_idStringID плательщика в вашей системе.

Подпись при регистрации через форму — префикс 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_idIntegerВаш уникальный ID в системе 1Payment.
payment_typeStringВсегда card.
project_idIntegerИдентификатор вашего проекта.
amountNumberСумма очередного списания (например, 500.00).
tokenStringТокен, полученный при первом успешном платеже (из колбека или запроса статуса).
user_dataStringНовый уникальный ID транзакции на вашей стороне.
shop_urlStringURL сайта источника платежа.
signStringКонтрольная подпись (префикс init_payment).

Дополнительные параметры (рекуррент)

ПараметрТипОписание
descriptionStringОписание платежа.
ipStringIP-адрес плательщика.
return_urlStringURL возврата плательщика после оплаты.
user_idStringID плательщика в вашей системе.

Формирование подписи (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_888
Строка для MD5: 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_888
Ожидаемая подпись: 59785c76ce35d08da343e6b8eec1e459
Подпись не совпадает

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

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_idID платежа в системе 1Payment; используйте для запроса статуса.
statusЧисловой код состояния (2 — ожидание).
status_descriptionТекстовое описание статуса (PENDING и др.).
status_codeКод ошибки при отказе (см. коды отказов).
redirect_urlURL для 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_typeStringДаТип платежа (card).
order_idStringДаID платежа в системе 1Payment.
project_idIntegerДаID вашего проекта.
statusIntegerДаСостояние: 2 (ожидание), 3 (успех), 4 (отказ).
status_descriptionStringДаPENDING, SUCCESS или FAILURE.
init_timeStringДаВремя создания платежа.
status_timeStringДаВремя получения финального статуса.
merchant_priceNumberДаСтоимость для плательщика.
init_priceNumberНетСумма при инициации.
user_priceNumberДаОтчисления партнёра.
currencyStringДаВалюта платежа (ISO 4217).
accountStringДаМаска номера карты.
user_dataStringДаID транзакции, переданный при создании.
signStringДаКонтрольная подпись колбека.
tokenStringНетТокен для последующих списаний — сохраните при первом успешном платеже.
testIntegerНет1 при тестовых платежах.
status_codeStringНетКод причины отказа.

Важно: ваш сервер должен вернуть HTTP 200 OK. Иначе система повторяет отправку колбека раз в минуту в течение 10 минут.

Проверка подписи колбека: MD5 от всех параметров в алфавитном порядке через & + API_KEY (без префикса init_payment). Подробнее — в разделе Формат запроса к API.

Токен также можно получить через запрос статуса платежа — поле token в ответе API.

Связанные разделы

Статья была полезна?