Предпосылки и учетная запись
Зарегистрируйте аккаунт, подтвердите email и создайте проект. В кабинете доступны тестовые ключи, настройка вебхуков и просмотр логов запросов. Создайте роль для разработчика и ограничьте права по принципу наименьших привилегий.
Получение ключей и среда разработки
- sk_test_xxx и pk_test_xxx — для песочницы
- sk_live_xxx и pk_live_xxx — для продакшна Храните секретные ключи в переменных окружения. Все вызовы делайте по HTTPS; для идемпотентных операций используйте заголовок Idempotency-Key.
Первый платеж: создание и редирект
- Ваш backend вызывает POST /payments с суммой, order_id и return_url.
- В ответе вы получаете payment_id и ссылку на оплату (confirmation_url) или данные для in‑page формы.
- Перенаправьте пользователя на confirmation_url либо откройте форму в модальном окне.
- После завершения — пользователь вернется на return_url.
Пример (Node.js):
const res = await fetch('https://api.api-platezhi.ru/v1/payments', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.SK}`,
'Content-Type': 'application/json',
'Idempotency-Key': `ORD-1001-${Date.now()}`
},
body: JSON.stringify({
amount: { value: '1490.00', currency: 'RUB' },
order_id: 'ORD-1001',
capture: true,
return_url: 'https://shop.example.ru/return'
})
});
Обработка вебхуков и подтверждение заказа
Настройте endpoint, доступный из интернета, например: https://shop.example.ru/webhooks/payments. Подпись X‑Signature проверяйте по секрету, событие idempotency‑обрабатывайте. На payment.succeeded подтвердите заказ, отправьте пользователю письмо и сформируйте чек.
Тестовые сценарии: 3‑DS, отказы, возвраты
- Успешная оплата с 3‑DS challenge
- Отказ по ошибке банка (insufficient_funds)
- Soft‑decline с повтором 3‑DS 2.0
- Частичный возврат и полный возврат В песочнице доступны тестовые PAN и сценарии отказов.
Чек по 54‑ФЗ и фискализация
Передайте в поле receipt позиции, НДС, признак расчета и контакт клиента. Мы сформируем чек, отправим его по email/SMS и вернем реквизиты фискализации в ответе и вебхуке.