Работа с заявками на оплату¶

Примечание: Параметры, отмеченные звездочкой (*), являются обязательными.

Создание заявки на оплату¶

Запрос¶

POST example.com/api/merchant/"merchant"/create_pay_in

Заголовки¶

Name	Value
Content-Type*	application/json

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

Name	Type	Format	Description
order_id*	string max: 255		id заявки в вашей системе
payment_method*	string	enum (card, sbp, score, iban, qr)	Тип оплаты (карты, сбп, номер счёта, IBAN, QR-код)
fiat_amount*	string		Сумма заявки в фиатной валюте
fiat_currency*	string	enum	Валюта заказа.
timeout	int		Таймаут ожидания оплаты в минутах
bank	string	enum ()	Желаемый банк получателя.
sign*	string		Подпись запроса
success_callback_url*	string max: 512		URL для оповещения об успешной оплате
error_callback_url	string max: 512		URL для отмены оплаты со стороны платформы
type_traffic	string	enum (etd, trusted)	Тип трафика
customer	string max: 128		Идентификатор клиента
order_description	string max: 8000		Описание заказа
include_qr_base64	boolean		Вернуть QR-код в теле ответа в виде base64. Учитывается только при `payment_method = qr`, для остальных методов игнорируется. По умолчанию `false`
redirect	boolean		Запросить redirect-режим (возврат `redirect_url`). По умолчанию `false`. Работает только если redirect включён
payment_success_url	string max: 512		URL, куда платёжная страница вернёт клиента после успешной оплаты. Обязателен при `redirect: true`. Не путать с `success_callback_url` (S2S-уведомление)
payment_failure_url	string max: 512		URL, куда платёжная страница вернёт клиента после неуспеха/отмены. Обязателен при `redirect: true`. Не путать с `error_callback_url` (S2S-уведомление)

Redirect-режим (опционально)

Помимо обычного ответа с реквизитами платформа может вернуть готовую ссылку на платёжную страницу (redirect_url), на которую вы перенаправляете клиента. Ссылка возвращается только если redirect включён и в запросе передан redirect: true вместе с обязательными payment_success_url / payment_failure_url. Ответ с реквизитами остаётся по умолчанию — redirect его лишь дополняет.

Методика формирования подписи в запросе:¶

Подпись для создания заявки на оплату формируется путем нахождения SHA256 Хеша от строки:

order_id : fiat_amount : fiat_currency : payment_method : sign_key

Пример формирования подписи:

Строка для подписи:

123456789:1500.00:rub:sbp:test

Результат SHA256:

76c5beb80bb2ea3fd0f67ad8325b0c68ae70d75cf926b77c0f1ac18c05eecfbb

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

{
  "order_id": "123456789",
  "payment_method": "sbp",
  "fiat_amount": "1500.00",
  "fiat_currency": "rub",
  "timeout": 30,
  "bank": "sber",
  "sign": "76c5beb80bb2ea3fd0f67ad8325b0c68ae70d75cf926b77c0f1ac18c05eecfbb",
  "success_callback_url": "https://yourwebsite.com/success",
  "error_callback_url": "https://yourwebsite.com/error",
  "customer": "CUST12345",
  "order_description": "Оплата товаров в интернет-магазине"
}

Параметры ответа¶

Name	Type	Format	Description
internal_transaction_id*	string max: 72		Внутренний ID транзакции в системе
order_id*	string max: 255		Id заявки в вашей системе
payment_method*	string	enum (card, sbp, score, iban, qr)	Тип оплаты (карты, сбп, номер счёта, IBAN, QR-код)
fiat_amount*	string		Сумма заявки
fiat_currency*	string		Валюта заказа. Доступные значения приведены в списке регионов
number_score	string (20)		Номер счёта (в случае оплаты по номеру счёта)
number_card	string (16)		Номер карты (в случае оплаты по номеру карты)
phone_number	string min 11 max:13		Номер телефона (в случае оплаты по СБП)
iban_number	string max: 34		IBAN (в случае оплаты по IBAN)
qr_file_id	int		Идентификатор файла QR-кода в системе (в случае оплаты по QR-коду)
qr_file_url	string max: 512		Готовый URL для получения файла QR-кода (в случае оплаты по QR-коду)
qr_data_uri	string	data-URI	QR-код в формате base64 (только при `payment_method = qr` и `include_qr_base64 = true`)
bank*	string max: 64		Код банка получателя
bank_name*	string max: 72		Название банка получателя (полное, строкой)
bik	string		БИК получателя, (только в случае номера счёта)
full_name	string max: 128		ФИО получателя
reject_callback_url*	string max: 512		URL для отмены оплаты со стороны мерчанта
summ_transaction*	string		Сумма транзакции (число с 2 знаками после запятой)
currency*	string		Код валюты
usdt_amount*	string		Сумма в USDT
merchant_spent_usdt*	string		Сумма USDT, зачисляемая мерчанту (4 знака после запятой)
exchange_rate*	string		Курс обмена (4 знака после запятой)
redirect*	boolean		Признак redirect-заявки
redirect_url	string max: 512		Готовая ссылка на платёжную страницу. Только для redirect-заявок
sign*	string		Подпись ответа

Методика формирования подписи в ответе:¶

Подпись для ответа формируется путем нахождения SHA256 Хеша от строки:

order_id : summ_transaction : number_score/number_card/phone_number/iban_number/qr_file_id : sign_key

Из параметров number_score/number_card/phone_number/iban_number/qr_file_id выбирается один, в зависимости от используемого метода оплаты. Для payment_method = qr в подпись входит qr_file_id; поля qr_file_url, qr_data_uri и redirect_url в подписи не участвуют.

Примечание по оплате через QR-код: при payment_method = qr реквизитом является сам QR-код, поэтому поля bank, bank_name и full_name в ответе не передаются.

Возможные ошибки в ответе¶

Text	Value
overloading requisite	Перегрузка реквизитов, попробуйте создать заявку на другую сумму, с другим методом оплаты, либо подождать
this payment method is disabled for your merchant	Данный метод оплаты отключен для вашего мерчанта
unexpected error	Непредвиденная ошибка
Redirect mode is not enabled for this merchant, currency and payment method	Redirect-режим не подключён; обратитесь к менеджеру для подключения
payment_success_url and payment_failure_url are required in redirect mode	В redirect-режиме оба URL обязательны
Invalid redirect value	Передано нераспознанное значение флага `redirect`
payment_success_url must be a string / payment_failure_url must be a string	URL передан не строкой
payment_success_url exceeds the allowed length (512 characters)	URL длиннее 512 символов (аналогично для `payment_failure_url`)

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

200200 (оплата по QR-коду)200 (redirect-режим)Ошибка 400 и остальные 4xx

{
  "ok": true,
  "internal_transaction_id": "TRX-20240215-093045-987654321098",
  "order_id": "123456789",
  "payment_method": "sbp",
  "fiat_amount": "1500.00",
  "fiat_currency": "rub",
  "summ_transaction": "1500.00",
  "currency": "rub",
  "usdt_amount": "15.8765",
  "merchant_spent_usdt": "15.2500",
  "exchange_rate": "98.2472",
  "number_card": "1234567890123456",
  "bank": "sber",
  "bank_name": "Сбер",
  "full_name": "Иванов Иван Иванович",
  "reject_callback_url": "https://yourwebsite.com/reject",
  "sign": "0df855e39b7910879cf2e91365ac06008a525f25e15f2f36575158342aa8f280"
}

{
  "ok": true,
  "internal_transaction_id": "TRX-20240215-093045-987654321098",
  "order_id": "123456789",
  "payment_method": "qr",
  "fiat_amount": "1500.00",
  "fiat_currency": "rub",
  "summ_transaction": "1500.00",
  "currency": "rub",
  "usdt_amount": "15.8765",
  "merchant_spent_usdt": "15.2500",
  "exchange_rate": "98.2472",
  "qr_file_id": 42,
  "qr_file_url": "https://example.com/api/merchant/your_merchant/qr_file/42",
  "qr_data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAywAAAMy...",
  "reject_callback_url": "https://yourwebsite.com/reject",
  "sign": "0df855e39b7910879cf2e91365ac06008a525f25e15f2f36575158342aa8f280"
}

Примечание: поле qr_data_uri присутствует только если в запросе был передан include_qr_base64 = true. Значение представляет собой data-URI и может быть подставлено напрямую в атрибут src тега <img>.

{
  "ok": true,
  "internal_transaction_id": "TRX-20240215-093045-987654321098",
  "order_id": "123456789",
  "payment_method": "sbp",
  "fiat_amount": "1500.00",
  "fiat_currency": "rub",
  "summ_transaction": "1500.00",
  "currency": "rub",
  "usdt_amount": "15.8765",
  "merchant_spent_usdt": "15.2500",
  "exchange_rate": "98.2472",
  "phone_number": "79001234567",
  "bank": "sber",
  "bank_name": "Сбер",
  "full_name": "Иванов Иван Иванович",
  "reject_callback_url": "https://yourwebsite.com/reject",
  "sign": "0df855e39b7910879cf2e91365ac06008a525f25e15f2f36575158342aa8f280",
  "redirect": true,
  "redirect_url": "https://pay.example.com/TRX-20240215-093045-987654321098"
}

Примечание: redirect_url присутствует только для redirect-заявок.

{
  "ok": false,
  "error": "message"
}

Получение файла QR-кода¶

Метод позволяет получить файл QR-кода по его идентификатору. Используется при оплате по QR-коду (payment_method = qr), если вам нужен сам файл, а не base64 в теле ответа.

Запрос¶

GET example.com/api/merchant/"merchant"/qr_file/"qr_file_id"

Важная информация

Выше приведён пример структуры URL. Готовый URL для получения файла передаётся в поле qr_file_url — при создании заявки, при запросе статуса заявки и в callback-уведомлениях. Рекомендуем использовать именно его, а не собирать URL самостоятельно.

Заголовки¶

Name	Value
Content-Type*	application/json
X-Api-Key*	X-Api-Key

Заголовки ответа¶

Name	Description
Content-Type	MIME-тип файла (например, image/png)
Content-Disposition	Имя файла (формат RFC 5987 для поддержки Unicode)

Параметры ответа¶

Метод возвращает бинарные данные файла QR-кода. Формат файла определяется заголовком Content-Type.

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

200Ошибка 400 и остальные 4xx

Заголовки:

Content-Type: image/png
Content-Disposition: inline; filename="qr.png"; filename*=UTF-8''qr.png

Тело ответа:

Бинарные данные файла

{
  "ok": false,
  "error": "message"
}

Отмена/подтверждение заявки на оплату со стороны платформы¶

Описание: Данный запрос представляет собой callback со стороны платформы при отмене или подтверждении заявки. Запрос отправляется платформой на указанный URL мерчанта (success_callback_url или error_callback_url) для уведомления об изменении статуса заявки.

Запрос¶

POST error_callback_url

или

POST success_callback_url

Заголовки¶

Name	Value
Content-Type*	application/json

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

Name	Type	Format	Description
order_id*	string max: 255		ID заявки в вашей системе
standart_sign*	string		Стандартная подпись
type*	string	enum (pay_in)	Тип операции
status*	string	enum (successful, rejected_timeout, rejected_merchant, rejected_gate)	Статус заявки (successful - успешно, rejected_timeout - отклонено по таймауту, rejected_merchant - отклонено мерчантом, rejected_gate - отклонено поддержкой платформы)
fiat_amount*	string		Сумма заявки в фиатной валюте
usdt_amount*	string		Сумма заявки в USDT
merchant_spent_usdt*	string		Сумма USDT, зачисляемая мерчанту
fiat_currency*	string		Код фиатной валюты
exchange_rate*	string		Обменный курс
payment_method*	string	enum (card, sbp, score, iban, qr)	Тип оплаты (карты, сбп, номер счёта, IBAN, QR-код)
created_at*	string	ISO 8601	Дата и время создания заявки
updated_at*	string	ISO 8601	Дата и время обновления заявки
old_fiat_amount	string		Предыдущая сумма заявки (только при изменении суммы)
new_fiat_amount	string		Новая сумма заявки (только при изменении суммы)
number_card	string		Номер карты (передается только при payment_method = card)
phone_number	string		Номер телефона (передается только при payment_method = sbp)
number_score	string		Номер счёта (передается только при payment_method = score)
iban_number	string		IBAN (передается только при payment_method = iban)
qr_file_id	int		Идентификатор файла QR-кода (передается только при payment_method = qr)
qr_file_url	string max: 512		Готовый URL для получения файла QR-кода (передается только при payment_method = qr)
full_name	string		ФИО получателя
bank_name*	string		Название банка получателя
redirect*	boolean		Признак redirect-заявки
redirect_url	string max: 512		Ссылка на платёжную страницу (только для redirect-заявок)

Примечание: 1. Для удобства подключения при подтверждении/отмене заявки id может передаваться и в url, и в параметрах запроса. Со своей стороны вы можете фактически использовать только 1 из методов приёма id. 2. Поля old_fiat_amount и new_fiat_amount передаются только в случае, если сумма заявки была изменена. 3. Из полей платежных реквизитов (number_card, phone_number, number_score, iban_number, qr_file_id + qr_file_url) передается только то, которое соответствует методу оплаты.

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

{
  "order_id": "123456789",
  "standart_sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "type": "pay_in",
  "status": "successful",
  "fiat_amount": "5000.00",
  "usdt_amount": "49.8765",
  "merchant_spent_usdt": "49.2500",
  "fiat_currency": "rub",
  "exchange_rate": "100.2472",
  "payment_method": "card",
  "created_at": "2024-02-15T09:30:45Z",
  "updated_at": "2024-02-15T09:45:12Z",
  "number_card": "4276345439581234",
  "phone_number": null,
  "number_score": null,
  "iban_number": null,
  "full_name": "Иванов Иван Иванович",
  "bank_name": "Сбербанк"
}

Пример запроса с изменением суммы¶

{
  "order_id": "123456789",
  "standart_sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "type": "pay_in",
  "status": "successful",
  "fiat_amount": "5000.00",
  "usdt_amount": "49.8765",
  "merchant_spent_usdt": "49.2500",
  "fiat_currency": "rub",
  "exchange_rate": "100.2472",
  "payment_method": "card",
  "created_at": "2024-02-15T09:30:45Z",
  "updated_at": "2024-02-15T09:45:12Z",
  "old_fiat_amount": "4800.00",
  "new_fiat_amount": "5000.00",
  "number_card": "4276345439581234",
  "phone_number": null,
  "number_score": null,
  "iban_number": null,
  "full_name": "Иванов Иван Иванович",
  "bank_name": "Сбербанк"
}

Запрос статуса заявки на оплату¶

Запрос¶

GET example.com/api/merchant/"merchant"/status_pay_in/"order_id"/

Заголовки¶

Name	Value
Content-Type*	application/json
X-Api-Key*	X-Api-Key

Параметры ответа¶

Name	Type	Format	Description
order_id*	string max: 255		Id заявки в вашей системе
type*	string	enum (pay_in)	Тип операции
status*	string	enum (expectation, successful, rejected_timeout, rejected_merchant, rejected_gate)	Статус заявки (expectation - в ожидании оплаты, successful - успешно, rejected_timeout - отклонено по таймауту, rejected_merchant - отклонено мерчантом, rejected_gate - отклонено поддержкой платформы)
fiat_amount*	string		Сумма заявки в фиатной валюте
usdt_amount*	string		Сумма заявки в USDT
merchant_spent_usdt*	string		Сумма USDT, зачисляемая мерчанту
fiat_currency*	string		Код фиатной валюты
exchange_rate*	string		Обменный курс
payment_method*	string	enum (card, sbp, score, iban, qr)	Тип оплаты (карты, сбп, номер счёта, IBAN, QR-код)
created_at*	string	ISO 8601	Дата и время создания заявки
updated_at*	string	ISO 8601	Дата и время обновления заявки
old_fiat_amount	string		Предыдущая сумма заявки (только при изменении суммы)
new_fiat_amount	string		Новая сумма заявки (только при изменении суммы)
number_card	string		Номер карты (передается только при payment_method = card)
phone_number	string		Номер телефона (передается только при payment_method = sbp)
number_score	string		Номер счёта (передается только при payment_method = score)
iban_number	string		IBAN (передается только при payment_method = iban)
qr_file_id	int		Идентификатор файла QR-кода (передается только при payment_method = qr)
qr_file_url	string max: 512		Готовый URL для получения файла QR-кода (передается только при payment_method = qr)
full_name	string		ФИО получателя
bank_name*	string		Название банка получателя
redirect*	boolean		Признак redirect-заявки
redirect_url	string max: 512		Ссылка на платёжную страницу (только для redirect-заявок)

Примечание: 1. Из полей платежных реквизитов (number_card, phone_number, number_score, iban_number, qr_file_id + qr_file_url) передается только то, которое соответствует методу оплаты. 2. Поля old_fiat_amount и new_fiat_amount передаются только в случае, если сумма заявки была изменена.

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

200Ошибка 400 и остальные 4xx

{
  "ok": true,
  "order_id": "123456789",
  "type": "pay_in",
  "status": "expectation",
  "fiat_amount": "1500.00",
  "usdt_amount": "15.8765",
  "merchant_spent_usdt": "15.2500",
  "fiat_currency": "rub",
  "exchange_rate": "98.2472",
  "payment_method": "card",
  "created_at": "2024-02-15T09:30:45Z",
  "updated_at": "2024-02-15T09:45:12Z",
  "number_card": "4276345439581234",
  "phone_number": null,
  "number_score": null,
  "iban_number": null,
  "full_name": "Иванов Иван Иванович",
  "bank_name": "Сбербанк"
}

{
  "ok": false,
  "error": "message"
}

Отмена заявки на оплату со стороны мерчанта¶

Запрос¶

POST example.com/api/merchant/"merchant"/rejected_pay_in/

Заголовки¶

Name	Value
Content-Type*	application/json

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

Name	Type	Format	Description
order_id*	string max: 255		id заявки в вашей системе
standart_sign*	string		Стандартная подпись

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

200Ошибка 400 и остальные 4xx

{
  "ok": true
}

{
  "ok": false,
  "error": "message"
}

Установка статуса от клиента¶

Метод позволяет мерчанту установить статус от клиента для заявки на оплату. Используется для передачи информации о том, подтвердил ли клиент оплату на своей стороне или отклонил её.

Запрос¶

POST example.com/api/merchant/"merchant"/set_client_status_pay_in

Заголовки¶

Name	Value
Content-Type*	application/json
X-Api-Key*	X-Api-Key

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

Name	Type	Format	Description
order_id*	string max: 255		id заявки в вашей системе
status*	string	enum (payment_confirmed, payment_rejected)	Статус от клиента (payment_confirmed - клиент подтвердил оплату, payment_rejected - клиент отклонил оплату)

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

{
  "order_id": "123456789",
  "status": "payment_confirmed"
}

Параметры ответа¶

Name	Type	Format	Description
order_id*	string max: 255		id заявки в вашей системе
status_from_client*	string	enum (payment_confirmed, payment_rejected)	Установленный статус от клиента

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

200Ошибка 400 и остальные 4xx

{
  "ok": true,
  "order_id": "123456789",
  "status_from_client": "payment_confirmed"
}

{
  "ok": false,
  "error": "message"
}