API Документация PLATIMA

PLATIMA API предоставляет простой и безопасный способ интеграции платежной системы в ваш проект. Наш API поддерживает прием платежей, выводы средств и управление балансом.

Базовый URL

https://platima.com/api/v1

Быстрая интеграция

Простое API с понятной документацией

Безопасность

SHA-512 подписи для всех запросов

Поддержка 24/7

Техническая помощь в любое время

Аутентификация

Все запросы к API должны быть подписаны с использованием вашего секретного ключа/ключа проекта. Подпись передается в заголовке Authorization как Bearer {signature}.

Как сформировать подпись

Сформируйте строку для подписи согласно требованиям метода (см. формулы ниже).
Примените SHA‑512 к строке и преобразуйте результат в HEX.
Передайте результат в заголовке Authorization: Bearer {signature}.

Формулы подписи

Баланс: SHA512(api_id + secret_key)
Создание платежа: SHA512(api_key_project + order_id + project_id + amount + currency)
Статус платежа (с order_id): SHA512(api_key_project + id + order_id + project_id)
Статус платежа (без order_id): SHA512(api_key_project + id + project_id)
Создание вывода: SHA512(api_id + secret_key + order_id)
Callback (платёж): SHA256(api_key_project + id + order_id + project_id + amount + currency)

Важно: храните ключи только на сервере. Никогда не используйте их на стороне клиента/браузера.

POST

Получение баланса аккаунта

Получение информации о балансе вашего аккаунта в RUB и USD.

/api/v1/account

Параметры запроса

Параметр	Тип	Обязательный	Описание
`api_id`	integer	Да	Ваш API ID

Заголовки

Content-Type: application/json
Authorization: Bearer {signature}

Формирование подписи

signature = SHA512(api_id + secret_key)

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

{
  "api_id": 123
}

Успешный ответ (200)

{
  "id": 123,
  "username": "user",
  "rub_balance": 15000.50,
  "usd_balance": 250.00
}

POST

Создание платежа

Создание новой платежной ссылки для приема оплаты от клиента.

/api/v1/acquiring

Параметры запроса

Параметр	Тип	Обязательный	Описание
`project_id`	integer	Да	ID проекта
`order_id`	string	Да	Уникальный ID заказа в вашей системе
`amount`	float	Да	Сумма платежа
`currency`	string	Да	Валюта (RUB)
`method`	string	Нет	Метод оплаты: `card` или `sbp`
`success_url`	string	Нет	URL для редиректа после успешной оплаты
`failed_url`	string	Нет	URL для редиректа при неудачной оплате
`callback_url`	string	Нет	URL для отправки callback уведомлений

Формирование подписи

signature = SHA512(api_key_project + order_id + project_id + amount + currency)

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

{
  "project_id": 1,
  "order_id": "ORD-2025-001",
  "amount": 1000.00,
  "currency": "RUB",
  "method": "card",
  "success_url": "https://example.com/success",
  "failed_url": "https://example.com/failed",
  "callback_url": "https://example.com/callback"
}

Успешный ответ (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "link": "https://platima.com/card/550e8400-e29b-41d4-a716-446655440000"
}

POST

Проверка статуса платежа

Получение информации о статусе и деталях платежа.

/api/v1/getpayAcquiring

Параметры запроса

Параметр	Тип	Обязательный	Описание
`project_id`	integer	Да	ID вашего проекта
`id`	string	Да	UUID платежа в системе PLATIMA
`order_id`	string	Нет	Номер платежа в вашей системе (необязательно)

Формирование подписи

С order_id:

signature = SHA512(api_key_project + id + order_id + project_id)

Без order_id:

signature = SHA512(api_key_project + id + project_id)

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

{
  "project_id": 1,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": "ORD-2025-001"
}

Успешный ответ (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": "ORD-2025-001",
  "project_id": 1,
  "amount": 1000.00,
  "currency": "RUB",
  "method": "card",
  "status": "SUCCESS",
  "created_at": "2025-01-10T12:00:00Z",
  "updated_at": "2025-01-10T12:05:00Z"
}

POST

Создание вывода средств

Создание заявки на вывод средств с вашего баланса.

/api/v1/withdrawal/create

Параметры запроса

Параметр	Тип	Обязательный	Описание
`api_id`	integer	Да	Ваш API ID
`order_id`	string	Да	Уникальный ID вывода в вашей системе
`amount`	float	Да	Сумма вывода (мин. 300 RUB для карт)
`currency`	string	Да	Валюта (RUB)
`withdraw_method`	string	Да	Метод вывода: `CARD`
`wallet_detail`	string	Да	Номер карты или адрес кошелька
`callback_url`	string	Нет	URL для отправки callback (должен начинаться с https://)
`json_info`	object	Нет	Дополнительная информация

Лимиты для метода CARD

Минимальная сумма: 300 RUB
Максимальная сумма: 100,000 RUB

Формирование подписи

signature = SHA512(api_id + secret_key + order_id)

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

{
  "api_id": 123,
  "order_id": "WD-2025-001",
  "amount": 5000.00,
  "currency": "RUB",
  "withdraw_method": "CARD",
  "wallet_detail": "4111111111111111",
  "callback_url": "https://example.com/withdrawal-callback"
}

Успешный ответ (200)

{
  "id": 3,
  "order_id": "ORDER_1757955804_3154",
  "method": "CARD",
  "recipient": "4111111111111111",
  "amount": 15000,
  "commission": 50,
  "currency": "RUB",
  "created_at": "2025-09-15T20:03:25+03:00",
  "updated_at": "2025-09-15T20:05:18+03:00",
  "status": "COMPLETED"
}

POST

Проверка статуса вывода

Получение информации о статусе заявки на вывод средств.

/api/v1/withdrawal/status

Параметры запроса

Параметр	Тип	Обязательный	Описание
`api_id`	integer	Да	Ваш API ID
`withdrawal_id`	integer	Да	ID вывода из ответа создания
`order_id`	string	Да	ID вывода в вашей системе

Статусы вывода

Код	Статус	Описание
`0`	В ожидании	Заявка создана и ожидает обработки
`1`	В обработке	Заявка обрабатывается системой
`2`	Выполнено	Средства успешно выведены
`3`	Отклонено	Заявка отклонена

Пример ответа

{
  "success": true,
  "withdrawal_id": 12345,
  "status": 2,
  "status_text": "Выполнено",
  "currency": "RUB",
  "amount": 5000.00,
  "commission": 150.00,
  "created_at": "2025-01-10T12:00:00Z",
  "updated_at": "2025-01-10T12:30:00Z"
}

Callback уведомления

Система автоматически отправляет POST запросы на указанный callback_url при изменении статуса платежа или вывода.

Callback для платежей

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": "ORD-2025-001",
  "project_id": 1,
  "amount": 1000.00,
  "currency": "RUB",
  "amount_pay": 1000.00,
  "currency_pay": "RUB",
  "method": "card",
  "createDateTime": "2025-01-10T12:00:00Z",
  "sign": "abc123..."
}

Callback поступит только при успешном платеже.

Callback для выводов на карты

{
  "id": 10,
  "order_id": "ORDER_1757958349_5312",
  "method": "CARD",
  "recipient": "4111 1111 1111 1111",
  "amount": 4500,
  "commission": 50,
  "currency": "RUB",
  "created_at": "2025-09-15T20:45:49+03:00",
  "updated_at": "2025-09-15T20:47:55+03:00",
  "status": "COMPLETED"
}

Статусы выводов: COMPLETED — вывод успешно выполнен, FAILED — вывод отклонен.

Проверка подписи callback (платеж)

sign = SHA256(api_key_project + id + order_id + project_id + amount + currency)

Требования к обработке callback

Ваш сервер должен отвечать HTTP 200 и телом ответа "ok" или "OK".
Время ответа не должно превышать 30 секунд.
При неуспешном ответе система повторит попытку через 10, 20 и 30 минут.
После 3 неудачных попыток callback будет отменен.

Рекомендация: Всегда проверяйте подпись callback запроса для обеспечения безопасности.

Коды ошибок

API использует стандартные HTTP коды ответов для индикации успешности или неудачи запроса.

HTTP код	Описание	Возможная причина
`200`	OK	Запрос успешно обработан
`400`	Bad Request	Неверные параметры запроса
`401`	Unauthorized	Неверная подпись/отсутствует Authorization
`403`	Forbidden	Метод платежа не разрешен
`404`	Not Found	Ресурс не найден
`405`	Method Not Allowed	Неверный HTTP метод
`500`	Internal Server Error	Внутренняя ошибка сервера

Пример ошибки

{
  "success": false,
  "message": "Insufficient balance. Required: 5150.00"
}

Примеры кода

Выберите операцию и язык — код обновится автоматически

Примечания:

Сумму в подписи форматируйте 1000.00 (ровно 2 знака).
Храните ключи в переменных окружения и отправляйте запросы только с сервера.
Node.js: примеры используют fetch и top‑level await (Node ≥ 18, ESM).
C++: примеры используют libcurl и OpenSSL для работы с HTTP и криптографией.