Взаимодействие по Payment API осуществляется по схеме запрос-ответ. Запросы отправляются в формате JSON методом POST. В качестве безопасного доступа к Payment API во всех методах используется basicAuth или bearerToken и параметр x-api-key в заголовке. Они должны храниться в защищенном месте. Payment API обладает свойством Идемпотентности. В случае сетевой ошибки ответ на дублированный запрос будет аналогичен первому. При этом, обработан дублированный запрос не будет. Идемпотентность обеспечивается за счет передачи в запросе уникального значения в заголовке x-req-id.

Системные ошибки

Уведомления (webhook, callback) предствляют собой POST запросы, отправляемые системой по факту изменения статуса заказа на адрес, указанный в параметре CallbackUrl метода create. Формат уведомлений соответствует ответу на запрос статуса. Система будеет осуществлять повторные попытки отправки уведомлений до получения http-кода 200 или истечения тайм-лимита, с увеличением интервалов между попытками. В заголовке http запроса передается параметр Payment-Sign - подпись, результат подписи исходного тела нотификации (Body из http запроса) приватным ключом по алгоритму SHA1, в кодировке base64. Для валидации подписи необходимо использовать публичный ключ:

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAtlD5ORxXDUgnnD9Ri2IB
UcT2Ru1fMi9kub8errQdLaXdFRDZJ1mNHlMJx+CHkhM5GNkMmidAhPcYRs4h/yIb
YLiRSsR+Zl6krjcrEvrTIZ1BySNAxEuCzWGFM27Ef01xNOSPEgtptAmop6vRuaiS
ha2vB5rHN1hSks1td/7xDcFG+C4cnDsTYp39rUvSSMtkW6FCbBoxNPrNOSlZGykx
OFBhOYd/uOK4z/zFSy07f4rA32KNn3zJE5eb6tzNMRNa6lOL96x0OYzw/P6oaS5b
sugVehAM1TGBCzm4Xmz1VZVBhxd3V7VoJuf/0C0W2Yfer+E/G0s3DDWmjzqhbvrc
Eb0y1kOZn4Z39jswv5Bkk8NyqHfNe0dE4pX+dSnfhC/9J5xFZy/CknclEM/0waY8
36iYIy+MaRsQdWXjbvP1AVk/yq2RlXCaOnK7GPvxAP1qjcgt56cGUOks9H9X6lba
PcJd+KDWde1aZZJLUpxu7JDIVTruDy/KrxDtJYi7Mz40Y6pnsKXzPHzVr0km9LI9
zK1j24OS1RIbO2fMM9D2zNQnSUV//aR+/xb7W2UgL2L0GRl7nDzqQL2dLvStHG9O
yUtnH5R/hPuIZqIDZx1N52F1JwArfDY0j9t5suAqN0VXJe2N77cYJ0x2LDeg+rLl
KsdjLKRDtKpXormCUTs/V+0CAwEAAQ==
-----END PUBLIC KEY-----

Пример для проверки подписи при интеграции средствами openssl. В командной строке выполняем команду:

Декодируем base64:

 certutil -decode catsign.txt sign.txt.dec

Проверяем подпись:

openssl dgst -sha1 -verify PublicStage.key -signature sign.txt.dec callback.txt

Где catsign.txt - подпись из заголовка Payment-Sign, PublicStage.key - публичный ключ, callback.txt - тело коллбека.

В случае успешной проверки будет сообщение Verified OK.

Проверка статуса заказа get обязательна по истечении срока жизни заказа. Через 30 мин после создания заказа отправка уведомления не гарантирована.

Сценарий с вводом карточных данных на PaymentForm не требует от ТСП соответствия требованиям безопасности PCIDSS, в отличие от сценария с вводом данных карты на стороне ТСП.

Открыте платежной формы осуществляется запросом (POST или GET) по адресу:

https://payment.{domen}/{OrderID}

где payment - фиксированное значение

domen - адрес для отправки запросов

OrderID - номер заказа, полученный в ответе на метод создания заказа.

Открытие формы POST-запросом позволяет передать дополнительные параметры, такие как адрес для обратного редиректа по результату оплаты.

Для вызова формы с возможностью редиректа необходимо:

1. Использовать нативную html форму с методом POST

2. В action указать URL формы, поддерживающий функционал редиректов

3. Указать в двух скрытых полях (successUrl, failUrl) ссылки для редиректа

4. В enctype указать application/x-www-form-urlencoded

5. Отправить нативную форму стандартным вызовом submit (POST запрос с переходом)

Пример:

<form
   action="https://payment.{domen}/{OrderID}"
   method="POST"
   enctype="application/x-www-form-urlencoded"
 >
   <input type="hidden" name="successUrl" value="https://domen.test/{OrderID}/success" placeholder="successUrl">
   <input type="hidden" name="failUrl" value="https://domen.test/{OrderID}/fail" placeholder="failUrl">

   <button type="submit">Оплатить</button>
</form>