Быстрый старт: интеграция приема платежей за 1 день

Table of contents

• Предпосылки и учетная запись
• Получение ключей и среда разработки
• Первый платеж: создание и редирект
• Обработка вебхуков и подтверждение заказа
• Тестовые сценарии: 3‑DS, отказы, возвраты
• Чек по 54‑ФЗ и фискализация
• Примеры кода: Node.js, PHP, Python, Java
• Чек‑лист перед выходом в прод
• Частые ошибки и способы решения

Предпосылки и учетная запись

Зарегистрируйте аккаунт, подтвердите email и создайте проект. В кабинете доступны тестовые ключи, настройка вебхуков и просмотр логов запросов. Создайте роль для разработчика и ограничьте права по принципу наименьших привилегий.

Получение ключей и среда разработки

• sk_test_xxx и pk_test_xxx — для песочницы
• sk_live_xxx и pk_live_xxx — для продакшна Храните секретные ключи в переменных окружения. Все вызовы делайте по HTTPS; для идемпотентных операций используйте заголовок Idempotency-Key.

Первый платеж: создание и редирект

1. Ваш backend вызывает POST /payments с суммой, order_id и return_url.
2. В ответе вы получаете payment_id и ссылку на оплату (confirmation_url) или данные для in‑page формы.
3. Перенаправьте пользователя на confirmation_url либо откройте форму в модальном окне.
4. После завершения — пользователь вернется на 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 и вернем реквизиты фискализации в ответе и вебхуке.

Пример фрагмента:

"receipt": {
  "customer": {"email": "user@example.ru"},
  "items": [
    {"name": "Футболка", "price": "1490.00", "quantity": 1, "tax": "none", "payment_mode": "full_prepayment"}
  ]
}

Примеры кода: Node.js, PHP, Python, Java

PHP (Guzzle) и Python (requests) примеры смотрите в Документации API. Для Java — OkHttp/Apache HttpClient. Для мобильных платформ доступны SDK и примеры потоков Apple/Google Pay.

Чек‑лист перед выходом в прод

• Секреты в безопасном хранилище, ротация
• Идемпотентность для POST
• Подпись вебхуков и 2xx ответы
• Обработаны retry и таймауты
• Набор тест‑кейсов 3‑DS/Decline пройден
• ККТ/54‑ФЗ настроена, реквизиты в ответах сохраняются
• Мониторинг, алерты и логи включены
• Политика возвратов и SLA опубликованы

Частые ошибки и способы решения

• 401 Unauthorized: проверьте ключ и среду (test vs live)
• 409 Idempotency conflict: используйте уникальный ключ на попытку
• Вебхук не приходит: проверьте публичную доступность, SSL и ответы 2xx
• Дублирование списаний: примените идемпотентность и проверку статусов по webhook_id

Готово! Создайте свой первый платеж в песочнице и переходите к подключению альтернативных методов (СБП, Apple/Google Pay).