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

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

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

Запрос

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)	Тип оплаты (карты, сбп, номер счёта, IBAN)
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		Описание заказа

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

Подпись для создания заявки на оплату формируется путем нахождения 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)	Тип оплаты (карты, сбп, номер счёта, IBAN)
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)
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 знака после запятой)
sign*	string		Подпись ответа

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

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

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

Из параметров number_score/number_card/phone_number/iban_number выбирается один, в зависимости от используемого метода оплаты.

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

Text	Value
overloading requisite	Перегрузка реквизитов, попробуйте создать заявку на другую сумму, с другим методом оплаты, либо подождать
this payment method is disabled for your merchant	Данный метод оплаты отключен для вашего мерчанта
unexpected error	Непредвиденная ошибка

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

200Ошибка 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": 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)	Тип оплаты (карты, сбп, номер счёта, IBAN)
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)
full_name	string		ФИО получателя
bank_name*	string		Название банка получателя

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

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

{
  "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)	Тип оплаты (карты, сбп, номер счёта, IBAN)
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)
full_name	string		ФИО получателя
bank_name*	string		Название банка получателя

Примечание: 1. Из полей платежных реквизитов (number_card, phone_number, number_score, iban_number) передается только одно в зависимости от метода оплаты. 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"
}