Платежи — общая информация

POST /deposits

Создание нового платежа. После успешного создания возвращает идентификатор операции и данные для проведения платежа (URL для редиректа, реквизиты, поля ввода и т.д.).

Заголовки

Заголовок	Обязательный	Описание
merchant-id	Да	Идентификатор мерчанта
x-signature	Да	HMAC-SHA256 подпись запроса
Content-Type	Да	application/json

Тело запроса

Поле	Тип	Обязательный	Описание
amount	string	Да	Сумма (например, "100.00")
currency	string	Да	Валюта (RUB, и др.)
paymentMethod	string	Да	Платежный метод (например, card)
userId	string	Да	Идентификатор пользователя мерчанта
merchantOperationId	string	Нет	Идентификатор операции на стороне мерчанта
callbackUrl	string	Нет	URL для отправки колбэков
processingUrl	string	Нет	URL страницы обработки
successUrl	string	Нет	URL для редиректа при успехе
failUrl	string	Нет	URL для редиректа при ошибке
requisites	object	Нет	Реквизиты, специфичные для платежного метода
userData	UserData	Нет	Данные пользователя

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

curl -X POST https://api.arcanumpay.ru/api/v1/deposits \
  -H "Content-Type: application/json" \
  -H "merchant-id: 12345" \
  -H "x-signature: a1b2c3d4e5f6..." \
  -d '{
    "amount": "100.00",
    "currency": "RUB",
    "paymentMethod": "card",
    "userId": "user-123",
    "merchantOperationId": "merch-op-001",
    "callbackUrl": "https://example.com/callback",
    "successUrl": "https://example.com/success",
    "failUrl": "https://example.com/fail",
    "userData": {
      "email": "user@example.com",
      "ipAddress": "192.168.1.1"
    }
  }'

Ответ

Поле	Тип	Описание
operationId	string	UUID созданного платежа
status	number	Статус: 1 (Approved), 2 (Declined), 3 (Processing)
amount	string	Сумма операции
currency	string	Валюта
errorCode	string	Код ошибки (при отклонении)
errorMessage	string	Описание ошибки (при отклонении)
redirectUrl	string	URL для редиректа пользователя
requisites	object	Реквизиты для оплаты
lifetime	number	Время жизни реквизитов в секундах
instruction	object	Инструкция для пользователя
inputFields	array	Динамические поля для ввода
confirmRequired	boolean	Требуется ли подтверждение
confirmation	object	Данные подтверждения

Типы действий

В зависимости от платежного провайдера и метода, ответ может содержать различные данные для завершения платежа:

Redirect

Пользователь должен быть перенаправлен на указанный URL для завершения платежа.

{
  "data": {
    "operationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": 3,
    "amount": "100.00",
    "currency": "RUB",
    "redirectUrl": "https://provider.com/pay/session-123"
  }
}

Requisites (реквизиты для оплаты)

Отображение реквизитов для оплаты (номер карты, кошелек и т.д.).

{
  "data": {
    "operationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": 3,
    "amount": "100.00",
    "currency": "RUB",
    "requisites": {
      "cardNumber": "4111111111111111",
      "bankName": "Example Bank"
    },
    "lifetime": 3600
  }
}

Input Fields (дополнительные поля)

Провайдер запрашивает дополнительные данные (OTP-код, выбор банка и т.д.).

{
  "data": {
    "operationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": 3,
    "amount": "100.00",
    "currency": "RUB",
    "inputFields": [
      {
        "name": "otp_code",
        "label": "OTP Code",
        "type": "string",
        "required": true
      },
      {
        "name": "bank",
        "label": "Select Bank",
        "type": "select",
        "required": true,
        "options": [
          { "value": "bank_a", "label": "Bank A" },
          { "value": "bank_b", "label": "Bank B" }
        ]
      }
    ]
  }
}

Instruction (инструкция)

Текстовая инструкция для пользователя с шагами выполнения.

{
  "data": {
    "operationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": 3,
    "amount": "100.00",
    "currency": "RUB",
    "instruction": {
      "category": "DoPayment",
      "steps": [
        { "title": "Шаг 1", "description": "Откройте мобильное приложение банка" },
        { "title": "Шаг 2", "description": "Подтвердите платеж" }
      ]
    }
  }
}

Confirmation (подтверждение)

Требуется подтверждение по одному из каналов (SMS, email и т.д.).

{
  "data": {
    "operationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": 3,
    "amount": "100.00",
    "currency": "RUB",
    "confirmRequired": true,
    "confirmation": {
      "channels": ["sms"]
    }
  }
}

Ошибки

HTTP-код	Ошибка	Описание
403	Forbidden	Нет доступа к платежному методу
422	NoRouteFound	Не найден маршрут обработки платежа