API для эквайринга

Общие принципы

Настройки у клиента

У клиента в настройках CRM для API-эквайринга указываются следующие параметры:

• Идентификатор продавца (MerchantID), являющегося клиентом и эквайера, и CRM
• URL для регистрации счёта (на стороне эквайера)
• Секретный ключ
• Булев признак использования онлайн-кассы
• Параметры чека для ОФД

Идентификатор продавца - строка с макс. длиной 36 символов. Выдаётся эквайером.

Секретный ключ - строка с длиной 8-64 символа. Допустимы только символы ASCII, исключая пробел. Формируется пользователем и сохраняется на обеих сторонах, либо формируется эквайером.

Схема взаимодействия CRM и эквайера

Платёж производится одностадийным способом:

1. Клиент инициирует оплату счёта в CRM (нажимает кнопку "Оплатить")
2. CRM отправляет запрос к эквайеру на URL для регистрации счёта,
   предоставляя параметры счёта, а также CallbackUrl и ReturnUrl
3. Эквайер возвращает URL для оплаты и OrderId (идентификатор транзакции эквайера)
4. CRM перенаправляет браузер клиента на URL для оплаты
5. По мере выполнения оплаты эквайер уведомляет CRM о статусах платежа посредством вызовов CallbackUrl
   (как минимум один раз: при успешном или неуспешном завершении процесса оплаты)
6. Эквайер перенаправляет браузер клиента на ReturnUrl

Формат запросов

При вызове URL для регистрации счёта CRM использует HTTP-метод POST в формате JSON и Content-Type равным application/json; charset="utf-8".

При получении входящих запросов от эквайера на CallbackUrl CRM так же ожидает метод POST. Допустимые форматы: JSON или application/x-www-form-urlencoded.

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

Выполняется на основе уникального в рамках эквайера MerchantID.

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

При вызове URL для регистрации счёта CRM добавляет в запрос электронную подпись. При получении запросов на CallbackUrl CRM так же ожидает от эквайера аналогичную подпись.

Подпись представляет собой HTTP-заголовок "Content-Signature", равный Base64(HMAC-SHA256(Body, ASCII(Key))),
т.е. формируется следующим образом:

1. Берётся полное содержимое тела POST-запроса
2. Вычисляется подпись HMAC-SHA256, где в качестве ключа выступают ASCII-коды символов строки секретного ключа
3. Полученная бинарная подпись преобразуется в Base64-строку
4. В запрос добавляется HTTP-заголовок "Content-Signature" с полученной строкой в качестве значения

При несовпадении подписи при вызове CallbackUrl вернёт соответствующую ошибку.

Секретный ключ по сети не передаётся.

Также для избежания повторной обработки запроса на регистрацию счёта CRM формирует и передаёт в качестве параметра ключ идемпотентности.

Функции

Регистрация счёта (CRM->эквайер)

Вызывается при нажатии пользователем кнопки "Оплатить" в CRM.

Список параметров:

{
	"idempotenceKey": "e0a51c144a1e43e2b43555938f36c56b", // Ключ идемпотентности
	"merchantId": "123", // Идентификатор продавца
	"amount": 123.45, // Общая сумма
	"currency": 643, // Код валюты по ISO 4217
	"language": "ru", // Желательный язык интерфейса при оплате
	"invoiceNumber": "3628", // Идентификатор платежа в CRM
	"clientName": "Иванов И.И.", // Имя клиента
	"clientEmail": "some@mail.com", // E-mail клиента
	"clientPhone": "79251234567", // Номер мобильного телефона клиента
	"description": "Оплата за курс английского языка", // Общее описание платежа
	"receipt": { // Параметры чека для ОФД
		"taxCode": "UsnIncome", // Идентификатор системы налогообложения
		"email": "some@mail.com", // E-mail клиента для отправки чека
		"items": [{ // Товарные позиции в чеке
			"name": "Оплата за курс английского языка", // Наименовании позиции
			"amount": 123.45, // Сумма
			"quantity": 1, // Количество
			"vatCode": 22, // Идентификатор ставки НДС
			"paymentSubject": "Service", // Признак предмета расчёта
			"paymentMode": "FullPrepayment" // Признак способа расчета
		}]
	},
	"callbackUrl": "https://demo.t8s.ru/Acquire/ApiCallback", // URL для обратных вызовов
	"returnUrl": "https://demo.t8s.ru/Acquire/ApiComplete" // URL для возврата на сайт продавца
}

Возвращаемые данные должны быть представлены в виде JSON.

В случае успеха функция должна возвращать объект с двумя обязательными полями:

• OrderId: идентификатор транзакции эквайера
• PayUrl: URL страницы оплаты

В случае ошибки функция должна возвращать текст ошибки в поле «Error». Этот текст может быть отображён для пользователя CRM.

Если возвращаемый код состояния HTTP свидетельствует об ошибке, так же будет отображён соответствующий ему текст ошибки, но текст в поле «Error» имеет больший приоритет.

Обратный вызов (CallbackUrl, эквайер->CRM)

Вызывается эквайером при изменении статуса платежа при оплате.

Обязательным является только вызов при статусе "succeeded" или ошибке/отказе.
Статусы "pending ,"authorized" и "confirmation", являющиеся переходными в процессе оплаты, на данный момент игнорируются, но сохраняются в логах CRM.

Список параметров:

В случае ошибки функция возвращает поле: "Error" с кодом состояния HTTP 500.