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

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

Endpoint

POST /v1/payments

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

Параметр	Тип	Обязательный	Описание
ext_id	string	Да	Уникальный ID заказа в вашей системе (макс. 255 символов)
amount	number	Да	Сумма платежа в RUB (100 - 300 000)
method	string	Нет	Метод оплаты: SBP, CARD, SIM, CROSS_BORDER. По умолчанию CARD
bank	string	Нет	Код банка (фильтр)
country	string	Нет	Код страны для CROSS_BORDER: TJ, KZ, UZ, KG
client_id	string	Нет	ID клиента/плательщика в вашей системе
notify_url	string	Нет	URL для webhook уведомлений
notification_token	string	Нет	Токен для валидации webhook (см. Webhooks)

Notification Token

Параметр notification_token позволяет передать произвольный токен, который будет возвращён в заголовке X-Notification-Token при отправке webhook. Используйте его для валидации входящих уведомлений.

Пример запроса (СБП)

curl -X POST https://api.settler.pw/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Identity: your-api-key" \
  -H "X-Signature: calculated-signature" \
  -d '{
    "ext_id": "order_12345",
    "amount": 5000,
    "method": "SBP",
    "client_id": "user_789",
    "notify_url": "https://your-site.com/webhook",
    "notification_token": "your-secret-token"
  }'

Client ID

Параметр client_id позволяет отслеживать платежи конкретного клиента. Используйте ID пользователя из вашей системы (email, номер телефона, внутренний ID).

Пример запроса (Cross-Border)

curl -X POST https://api.settler.pw/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Identity: your-api-key" \
  -H "X-Signature: calculated-signature" \
  -d '{
    "ext_id": "order_67890",
    "amount": 10000,
    "method": "CROSS_BORDER",
    "country": "TJ",
    "bank": "dcbank"
  }'

Cross-Border

При методе CROSS_BORDER клиент переводит деньги на реквизиты в указанной стране. Сумма автоматически конвертируется по курсу ЦБ РФ.

Пример запроса (SIM)

curl -X POST https://api.settler.pw/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "X-Identity: your-api-key" \
  -H "X-Signature: calculated-signature" \
  -d '{
    "ext_id": "order_99999",
    "amount": 3000,
    "method": "SIM"
  }'

SIM

При методе SIM клиент переводит средства на номер SIM-карты (мобильный оператор).

Ответ (СБП/Карта/SIM)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "ext_id": "order_12345",
  "amount": 5000,
  "currency": "RUB",
  "status": "PENDING",
  "method": "SBP",
  "requisites": {
    "type": "sbp",
    "value": "+79001234567",
    "bank": "Сбербанк",
    "bank_code": "sberbank",
    "holder": "Иван И."
  },
  "payment_url": "https://pay.settler.pw/invoice?id=550e8400-e29b-41d4-a716-446655440000",
  "valid_until": "2026-01-30T12:30:00Z",
  "created_at": "2026-01-30T12:15:00Z"
}

Payment URL

Поле payment_url содержит ссылку на страницу оплаты. Вы можете перенаправить клиента на эту страницу, где он увидит реквизиты и сможет подтвердить перевод.

Ответ (Cross-Border)

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "ext_id": "order_67890",
  "amount": 10000,
  "currency": "RUB",
  "status": "PENDING",
  "method": "CROSS_BORDER",
  "requisites": {
    "type": "phone",
    "value": "+992901234567",
    "bank": "dcbank",
    "bank_name": "DC Bank (Таджикистан)",
    "holder": "Иван И.",
    "country": "TJ",
    "currency": "TJS",
    "amount_local": 1237.39
  },
  "payment_url": "https://pay.settler.pw/invoice?id=660e8400-e29b-41d4-a716-446655440001",
  "valid_until": "2026-01-30T12:30:00Z",
  "created_at": "2026-01-30T12:15:00Z"
}

Поля ответа

Поле	Тип	Описание
id	string	Уникальный ID платежа (UUID)
ext_id	string	Ваш ID заказа
amount	number	Сумма платежа в RUB
currency	string	Валюта (RUB)
status	string	Статус платежа
method	string	Метод оплаты
requisites	object	Реквизиты для оплаты
requisites.type	string	Тип: sbp, card, sim или phone
requisites.value	string	Номер телефона или номер карты
requisites.bank	string	Название банка
requisites.bank_code	string	Код банка (например: sberbank, tinkoff, alfabank)
requisites.bank_name	string	Название банка (для CROSS_BORDER)
requisites.holder	string	Имя получателя
requisites.country	string	Код страны (для CROSS_BORDER)
requisites.currency	string	Валюта реквизитов (для CROSS_BORDER)
requisites.amount_local	number	Сумма в локальной валюте (для CROSS_BORDER)
payment_url	string | null	URL страницы оплаты (если есть)
valid_until	string	Время истечения платежа (ISO 8601)
created_at	string	Время создания (ISO 8601)

Методы оплаты

Метод	Описание
CARD	Банковская карта
SBP	Система быстрых платежей
SIM	Оплата на SIM-карту (мобильный оператор)
CROSS_BORDER	Трансграничный перевод (TJ, KZ, UZ, KG)

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

Статус	Описание
PENDING	Ожидает оплаты
PROCESSING	Клиент подтвердил перевод, ожидает верификации
COMPLETED	Успешно завершён
CANCELLED	Отменён (таймаут или вручную)
DISPUTE	Открыта апелляция

Ошибки

Код	HTTP	Описание
PAY_001	500	Внутренняя ошибка
PAY_002	400	Неверные параметры (ext_id, amount, method)
PAY_003	409	Заказ с таким ext_id уже существует
PAY_004	503	Нет доступных реквизитов
PAY_005	429	Слишком много платежей с одинаковой суммой

Пример ответа с ошибкой

{
  "error": "PAY_003",
  "message": "Payment order already exists",
  "data": {
    "ext_id": "order_12345"
  }
}