Документация API: эндпоинты, модели, ошибки и лучшие практики

Получить CloudPayments бесплатно

Table of contents

Базовые понятия и авторизация

API использует REST поверх HTTPS. Все запросы выполняются по базовому URL https://api.api-platezhi.ru/v1/ с аутентификацией через заголовок Authorization: Bearer . Разделяйте ключи для песочницы и продакшна, храните секреты в Vault/Secrets Manager. Для idempotent POST используйте заголовок Idempotency-Key.

Ресурс Payments: создание, статусы, захват и отмена

Endpoint: POST /payments Поля: amount, currency, order_id, description, capture (true/false), customer, receipt (для 54‑ФЗ), return_url, metadata. Статусы: pending, waiting_for_capture, succeeded, canceled, failed. Действия:

Пример (cURL):

curl -X POST https://api.api-platezhi.ru/v1/payments \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Idempotency-Key: order_1001_try_1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {"value": "1490.00", "currency": "RUB"},
    "order_id": "ORD-1001",
    "capture": false,
    "description": "Оплата заказа #1001",
    "return_url": "https://shop.example.ru/return"
  }'

Ресурс Refunds: частичные и полные возвраты

Endpoint: POST /refunds Поля: payment_id, amount, reason, receipt. Статусы: pending, succeeded, failed. Сценарии: частичный возврат нескольких позиций, возврат доставки, возврат после отмены.

Ресурс Tokens: сохраненные карты и биллинг

Endpoint: POST /tokens — обмен карточных данных/PaymentMethod на токен (через защищенный флоу). Токен хранится у нас, вы оперируете token_id. Для рекуррентных списаний используйте merchant‑initiated flow с 3‑DS при первой оплате.

Вебхуки: формат, подпись, ретраи

Конфигурируются в кабинете. Заголовки: X-Event-Type, X-Request-Id, X-Signature (HMAC SHA‑256). Тело содержит объект data с сущностью события. Мы выполняем ретраи по экспоненциальной схеме до 24 часов. Ответ 2xx подтверждает прием. Подпись вычисляется по сырым байтам тела и секрету endpoint.

Пример payload:

{
  "id": "evt_123",
  "type": "payment.succeeded",
  "created_at": "2025-01-01T10:00:00Z",
  "data": {"object": {"id": "pay_abc", "status": "succeeded", "amount": {"value": "1490.00", "currency": "RUB"}}}
}

Идемпотентность и порядок событий

Каждый POST сопровождайте уникальным Idempotency-Key. События могут приходить не по порядку — храните последнее известное состояние и применяйте версионирование ресурса (version/updated_at). Повторная обработка должна быть безопасной.

Ошибки и коды ответов

Структура ошибки:

{
  "error": {"code": "validation_error", "message": "amount.value is required", "details": [{"field": "amount.value", "reason": "required"}]}
}

Лимиты, пагинация и фильтры

Пагинация: cursor‑based — параметры limit и starting_after. Фильтры: status, created_at_from/to, amount_from/to, metadata.*. Рекомендуем забирать изменения инкрементально и хранить курсор.

Примеры на cURL/Node.js/PHP/Python

Node.js (axios):

await axios.post('https://api.api-platezhi.ru/v1/payments', {
  amount: { value: '990.00', currency: 'RUB' },
  order_id: 'ORD-2002',
  capture: true,
  return_url: 'https://shop.example.ru/return'
}, { headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': 'ORD-2002-try-1' }});

PHP (Guzzle):

$client->post('/v1/payments', [ 'headers' => [ 'Authorization' => 'Bearer '.getenv('API_KEY'), 'Idempotency-Key' => 'ORD-2002-try-1' ], 'json' => [ 'amount' => [ 'value' => '990.00', 'currency' => 'RUB' ], 'order_id' => 'ORD-2002', 'capture' => true, 'return_url' => 'https://shop.example.ru/return' ]]);

Версионирование API и совместимость

Версия указывается в URL и заголовке X-Api-Version. Минорные изменения обратносуместимы, мажорные — с миграционным периодом и dual‑run. Подпишитесь на рассылку изменений и тестируйте в песочнице перед апдейтом в проде.

Получить CloudPayments бесплатно