Руководство интегратора: Платежи

API Платежей

Введение в Payments API v2

Данный API позволяет принимать платежи (СБП и другие методы) с предварительной верификацией плательщика через сервис Pina Market.

Схема работы

Авторизация: Вы получаете ссылку, пользователь переходит по ней и подтверждает личность.
Токен: Вы получаете зашифрованный токен плательщика (содержит ФИО).
Создание платежа: Вы отправляете токен, имя плательщика и сумму. Система сверяет имя.
Оплата: Пользователь сканирует QR-код или переходит по ссылке.

Важно: Суммы в запросах передаются в копейках (целое число).
Пример: 100.00 RUB -> 10000.

Шаг 1: Получение ссылки на авторизацию

POST /payments/auth-url

Необходимо перенаправить пользователя на полученный auth_url.

Запрос (JSON)

{
  "user_id": "user_12345",         // Ваш ID пользователя (обязательно)
  "redirect_url": "https://yoursite.com/profile", // Куда вернуть юзера (обязательно)
  "callback_url": "https://api.yoursite.com/callback" // Опционально
}

Если callback_url не указан, токен будет автоматически сохранен в V-DAR, и его можно получить методом GET /api/v2/payments/user/{user_id}.

Пример ответа (200 OK)

{
  "auth_url": "https://pina.market/auth?userId=user_12345&redirectURL=...&authID=550e8400...",
  "auth_id": "550e8400-e29b-41d4-a716-446655440000"
}

Получение токена (если не использован callback_url)

GET /payments/user/{user_id}

{
  "user_id": "user_12345",
  "token": "gAAAAABl...", // Зашифрованный токен (длинная строка)
  "auth_datetime": "2025-01-25T12:00:00Z"
}

Шаг 2: Создание платежа

POST /payments/create

Параметр	Тип	Описание
`merchant_site_id`	UUID	Обязательно ID торговой точки (из админки)
`amount`	Integer	Обязательно Сумма в копейках (минимум 100, максимум 100000000)
`operation_id`	String	Обязательно Ваш уникальный номер заказа
`payer_name`	String	Обязательно ФИО плательщика (должно совпадать с данными в токене)
`payer_token`	String	Обязательно Токен, полученный на шаге авторизации
`description`	String	Назначение платежа (опционально, максимум 500 символов)
`callback_url`	URL	URL для callback-уведомлений о статусе платежа (опционально)
`sbp_redirectURL`	URL	URL для редиректа пользователя после успешной оплаты через СБП (опционально)

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

{
  "amount": 150000,                  // 1500.00 RUB
  "merchant_site_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "operation_id": "ORDER-998877",
  "description": "Оплата заказа #998877",
  "payer_name": "Иванов Иван Иванович",
  "payer_token": "gAAAAABl...",     // Токен от авторизации
  "callback_url": "https://yoursite.com/webhook",  // Опционально
  "sbp_redirectURL": "https://yoursite.com/success"  // Опционально
}

Пример ответа (200 OK)

{
  "payment_id": "789e4567-e89b-12d3-a456-426614174000",
  "payment_url": "https://qr.nspk.ru/AD10006R2FEC8HUS90BPA0GU38QOOA7U?type=01&bank=100000000000&sum=150000&cur=RUB&crc=A1B2",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAA...", // Base64 картинка QR
  "created_at": "2025-01-25T12:30:00.123456Z",
  "expires_at": "2025-01-25T13:30:00.123456Z",
  "operation_id": "ORDER-998877",
  "amount": 150000,
  "status": "pending"
}

Шаг 3: Проверка статуса

GET /payments/{payment_id}/status

Рекомендуется опрашивать статус каждые 3-5 секунд до получения финального статуса (PAID, FAILED, EXPIRED).

Пример ответа (Успешная оплата)

{
  "payment_id": "789e4567-e89b-12d3-a456-426614174000",
  "status": "PAID_VERIFIED",
  "operation_id": "ORDER-998877",
  "amount": 150000,
  "created_at": "2025-01-25T12:30:00Z",
  "paid_at": "2025-01-25T12:32:15Z",
  "name_verification_status": "VERIFIED",
  "payer_name": "Иванов Иван Иванович"
}

Статусы платежей

Статус	Описание
CREATED	Платёж создан, ожидает оплаты
PAID_PENDING_VERIFICATION	Оплачен, проверяется ФИО
PAID_VERIFIED	Оплачен и проверен, средства зачислены
PAID_MANUAL_REVIEW	Оплачен, требует ручной проверки (не найден в выписке за 45 минут)
FAILED_REJECTED	Отклонён платёжным шлюзом (RJCT)
FAILED_VERIFICATION	Не прошёл проверку ФИО (MISMATCH)
REFUNDING	Возврат в процессе
REFUNDED	Полностью возвращён
PARTIALLY_REFUNDED	Частично возвращён
EXPIRED	Истёк срок (45 минут), только для неоплаченных платежей
Старые статусы (для обратной совместимости):
PENDING	Эквивалент PAID_PENDING_VERIFICATION
PAID	Эквивалент PAID_VERIFIED или PAID_MANUAL_REVIEW
FAILED	Эквивалент FAILED_REJECTED или FAILED_VERIFICATION

Коды ошибок API (400 Bad Request)

Код ошибки	Описание
`PAYER_NAME_MISMATCH`	Имя `payer_name`, переданное в запросе, не совпадает с именем, зашифрованным в `payer_token`. Возможна попытка подмены данных.
`DUPLICATE_OPERATION_ID`	Платеж с таким `operation_id` уже существует. Используйте уникальные ID заказов.
`AMOUNT_TOO_SMALL`	Сумма платежа меньше минимально допустимой (минимум 100 копеек = 1.00 RUB).
`AMOUNT_TOO_LARGE`	Сумма платежа больше максимально допустимой (максимум 100000000 копеек = 1,000,000.00 RUB).
`PAYMENT_CREATION_ERROR`	Общая ошибка создания платежа (внутренняя ошибка системы).
`INVALID_TOKEN`	Не удалось расшифровать `payer_token`. Возможно, он поврежден или устарел.
`SITE_NOT_FOUND`	Указанный `merchant_site_id` не существует.