Формирование оплаты

Для осуществления интеграции с системой WEBPAY мерчантов PCI DSS, которые работают с данными карт на страницах своего веб-сайта или непосредственно в своем приложении и хотят использовать интеграцию Host2Host, следуйте, пожалуйста, инструкциям ниже:

Сформируйте стандартный POST-запрос (раздел Формирование заказа для оплаты).
Добавьте в запрос поле wsb_encrypted_data.
Добавьте в запрос поле wsb_email. При данном способе работы это поле является обязательным при отправке запроса.
Дополнительно можно добавить поле wsb_return_format для указания формата ответа от нашей системы.

Название поля	Обязательное поле	Описание	Примечание
`wsb_encrypted_data`	Да	Содержит зашифрованный JSON формата `{"cc_pan":"", "cc_exp":"", "cc_cvv":"", "cc_name":""}`	Шифруется по алгоритму `RSA` с помощью публичного ключа из личного кабинета
`wsb_email`	Да	Электронный адрес покупателя
`wsb_return_format`	Нет	Формат вывода результата	Возможное значение: `json`

Обратите внимание

При формировании поля wsb_signature (механизм формирования подписи указан в разделе Электронная подпись заказа) поле wsb_encrypted_data также участвует в конкатенации параметров и ставится в конец перед SecretKey. Далее происходит стандартный сценарий оплаты.

Название поля	Описание
`time`	Время выполнения запроса
`orderNumber`	Номер заказа
`invoiceNumber`	Номер счета
`transaction`	Id транзакции
`authorizationCode`	Авторизационный код
`Rrn`	Уникальный идентификатор банковской транзакции
`trimPan`	Номер карты в формате `123456xxxxxx1234`
`payee`	Получатель платежа
`amount`	Сумма платежа
`currency`	Валюта платежа
`acsUrl`	Адрес перехода для прохождения 3D-Secure
`PaReq`	Параметр передаваемый на acs страницу
`TermUrl`	Адрес для получения ответа от acs страницы
`MD`	Токен для восстановления сессии после acs-страницы
`tokenName`	Название токена для восстановления платежной сессии
`token`	Значение токена для восстановления платежной сессии
`availableOption`	Параметр содержит возможные значения для поля `paymentType`. Список значений зависит от типа карты и настроек мерчанта. Возможные значения: `IpsPayment` — терминал ips (дефолтный либо, при включенной маршрутизации, смаршрутизированный терминал) `halva` — терминал халвы `standard` — терминал халвы+ (оплата рублями) `bonus` — терминал халвы+ (оплата бонусами)
`paymentType`	Используется при необходимости выбрать вариант оплаты для карт. Приходит пустое значение, его необходимо заполнить. Возможные значения для заполнения берутся из поля `availableOption`.
`responseCode`	При возникновении ошибки содержит код ошибки
`responseText`	Содержит текст ошибки

Оплаты для карточки Халва+

WEBPAY в ответе возвращает:

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

{
  "token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a303458
79566e334b48526e592c",
  "tokenName":"wt",
  "availableOption":"ipsPayment,halva",
  "paymentType":""
}

Мерчант при получении такого ответа должен запросить у клиента вариант оплаты и отправить нам POST-запрос со следующими полями:

$params['wt'] = "effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5
a30345879566e334b48526e592c";
$params['payHalvaPlus'] = 1;
$params['paymentType'] = 'standard'; /* может содержать значения из доступных, полученных в параметре availableOption */

Сценарий проведения PCI DSS платежа по 3D-Secure 1.0

Шаг 1

Сформируйте POST-запрос как описано в Формирование оплаты и отправьте его по адресу https://payment.webpay.by/api/v1/payment — для реальной среды или по адресу https://payment.webpay.by/api/v1/payment — для тестовой среды.

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

{
  "wsb_storeid":"123456789",
  "wsb_currency_id":"BYN",
  "wsb_version":2,
  "wsb_seed":"1242649174",
  "wsb_test":0,
  "wsb_invoice_item_name":["test"],
  "wsb_invoice_item_price":["0.1"],
  "wsb_invoice_item_quantity":["1"],
  "wsb_operation_type":"",
  "wsb_customer_id":"41432",
  "wsb_encrypted_data":"VYs5XZYA79BORvcPW4LbBM6x4B36lBnQskF7j61UVlsH4ENPrPCs1exkJdCF6fX9nyENvrC434w3tL6HBtY7mxFXFvMBbsNoDbF4OC4lJEPVSSoBASLZH/9M1hBtavKjjDyKWXsCd5HYihp6PRTs3rMtw9+6Dao8hyfucMxyGpzDU/fW7DZdZ1GY3RIRKXJgPOP/AWv1YORy22BtyNs461CKuyXVY5AdeLO7WmV2x9kxexKNncKO4o0voy9KjW/nYj7R1YCQAZ4k1G2ZuXku90+yeo/AVBCXVTOEejwfplw9dFARes6OtQcW10kQmTdMi9200bf3sY2lQ1UZSbNMRw==",
  "wsb_order_num":"ORDER-de35",
  "wsb_total":"0.1",
  "wsb_signature":"87943d79649e10970b23dfd41194e5a503292bba",
  "wsb_tax":"0",
  "wsb_shipping_name":"Стоимость доставки",
  "wsb_shipping_price":"0",
  "wsb_discount_name":"Скидка на товар",
  "wsb_discount_price":"0",
  "wsb_email":"test@test.com",
  "wsb_phone":"",
  "wsb_return_url":"https://test.com/return",
  "wsb_cancel_return_url":"https://test.com/cancel",
  "wsb_notify_url":"https://test.com/",
  "wsb_3ds_payment_option":"auto",
  "*scart":""
}

После отправки запроса на указанный URL, WEBPAY вернет в ответ заполненные поля acsUrl, PaReq, TermUrl, MD.

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

{
  "data":{
    "token":"92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c",
    "tokenName":"wt",
    "time":"",
    "orderNumber":"",
    "invoiceNumber":"",
    "transaction":"",
    "authorizationCode":"",
    "rrn":"",
    "trimPan":"",
    "payee":"",
    "amount":"",
    "currency":"",
    "responseCode":"",
    "responseText":"",
    "acsUrl":"https:\/\/ucas.npc.by:8443\/pareq\/194978586\/ceb25c48-69f4-4aec-a069-6f5a8f65cd0d\/",
    "PaReq":"eJxVUctSwkAQvPsVFB\/AvmBJqGEpNJZyMKBiWXpbNlOQkoSQhwa+3t0QBG\/dvTM9Oz0wqZNt5xvzIt6l4y7r0e5E3cBykyMGr2iqHBU8YVHoNXbiyFZ4xhdGeN5wIKX2GDNU+1x4EdWR56M0\/mAoqWZdBYvpC+4VtObKevc4kDO1rrnZ6LRUoM3+dhYqnzHOBJCWQoL5LFBccs6temKQ6gTVO64yfQDSEDC7Ki3zg7LtQM4EqnyrNmWZjQj5acp7K9vhVCCX0YvKocK61HGkwmDKPpP7fnjcfs2Dt2P48Fx\/LNf9eTAbA3EVEOkSFadcUMllh\/ERlSPhA2l00Ikbryijdo0ThsyNmF49XAtgE84xNQflC7vkHwOss12KtsLu9IchwsIQu8Dl23ePLj9T2mwY9RilnLsEG8GZxDYLPqSicXEEiGsh7XFIe1uL\/t38FyiprZE=",
    "MD":"92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c",
    "TermUrl":"https:\/\/payment.webpay.by\/?wt=48957735ca99cdb589ef07753ebaaef5=5255737a5a5539684b335a484f456c594b326b34537a6c59566c6c6e5233684d5a314a6b656b355159335934555734776447313662584e4555325645544459305430396c6545394b543152694c3273344d6b6b3454412c2c"
  }
}

Шаг 2

Далее для продолжения сессии необходимо отправить полученные параметры на URL адрес, который содержится в ответе в поле acsUrl. Запрос отправляется методом POST с заголовком Content-Type: multipart/form-data, содержащий в теле запроса поля PaReq, MD, TermUrl со значениями из ответа из шага 1.

Обратите внимание

Из значения поля acsUrl нужно убрать все обратные слэши \. Значение поля TermUrl предварительно замените на свой URL адрес, где вы будете обрабатывать ответ от acs.

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

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://ucas.npc.by:8443/pareq/194978586/ceb25c48-69f4-4aec-a069-6f5a8f65cd0d/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('PaReq' => 'eJxVUctSwkAQvPsVFB\\/AvmBJqGEpNJZyMKBiWXpbNlOQkoSQhwa+3t0QBG\\/dvTM9Oz0wqZNt5xvzIt6l4y7r0e5E3cBykyMGr2iqHBU8YVHoNXbiyFZ4xhdGeN5wIKX2GDNU+1x4EdWR56M0\\/mAoqWZdBYvpC+4VtObKevc4kDO1rrnZ6LRUoM3+dhYqnzHOBJCWQoL5LFBccs6temKQ6gTVO64yfQDSEDC7Ki3zg7LtQM4EqnyrNmWZjQj5acp7K9vhVCCX0YvKocK61HGkwmDKPpP7fnjcfs2Dt2P48Fx\\/LNf9eTAbA3EVEOkSFadcUMllh\\/ERlSPhA2l00Ikbryijdo0ThsyNmF49XAtgE84xNQflC7vkHwOss12KtsLu9IchwsIQu8Dl23ePLj9T2mwY9RilnLsEG8GZxDYLPqSicXEEiGsh7XFIe1uL\\/t38FyiprZE=','TermUrl' => 'https:\\/\\/payment.webpay.by\\/?wt=48957735ca99cdb589ef07753ebaaef5=5255737a5a5539684b335a484f456c594b326b34537a6c59566c6c6e5233684d5a314a6b656b355159335934555734776447313662584e4555325645544459305430396c6545394b543152694c3273344d6b6b3454412c2c','MD' => '92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c'),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: multipart/form-data'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

После отправки запроса у вас появится форма, куда плательщику в поле ввода необходимо ввести 3D-Secure код, полученный через СМС на номер мобильного телефона, к которому привязана его банковская карточка.

После того как плательщик ввел 3D-Secure смс-код и нажал кнопку Подтвердить, на ваш URL адрес для обработки ответа от acs, указанный ранее в поле TermUrl, придут параметры — token, PaRes, MD — необходимые для восстановления сессии в WEBPAY.

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

{
  "token":"e801cb1e1b80685bb6fd81ec0617233b=5a6a6c596130xxxxxx5535545731764f586c49536e46795a47524c4e5568544b7a67724c32525461574e6f6446685a63334e514d47746f5931453051305a4c52566848546c424764xxxxxx4554a754e47704f5a772c2c",
  "PaRes":"eJxVUe1ugkAQfBXjA3gfSCtmvQSqrTTB2JbWyD88NoVUAQ9o5e17h1jtbmdvd2Z21kIU4U4f0PZKBQQYFXFnzjIktmQWRa3J1Y5FLB2XEo4BtVlRW5YCM64kAuUHcpmcZ5LSC WR89fiTGzObs",
  "MD":"d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=547159794b415849646e5242754b35545865694b5766726d62"
}

Шаг 3

Вам необходимо отправить POST-запрос в WEBPAY с параметрами, которые пришли от acs в шаге 2.

Для восстановления сессии в WEBPAY следует отправить POST-запрос по адресу https://payment.webpay.by/api/v1/payment?wt={token} — для реальной среды или по адресу https://payment.webpay.by/api/v1/payment?wt={token} — для тестовой среды, где:

token — значение поля token, которое пришло в ответе от aсs в шаге 2 (также вместо этого параметра можно передавать параметр MD).

Тело запроса должно содержать параметры MD и PaRes, также полученные от acs на шаге 2.

Шаг 4

WEBPAY получает от вас запрос из шага 3, обрабатывает, отправляет в процессинг и возвращает вам ответ в формате JSON. Обратите внимание, что ответ приходит от сервиса WEBPAY во вложении data.

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

{
  "data":{
    "token":"e801cb1e1b80685bb6fd81ec0617233b=5a6a6c596130xxxxxx5535545731764f586c49536e46795a47524c4e5568544b7a67724c32525461574e6f6446685a63334e514d47746f5931453051305a4c52566848546c424764xxxxxx4554a754e47704f5a772c2c",
    "tokenName":"wt",
    "time":"2023.06.26 13:25:58",
    "orderNumber":"ORDER-de35",
    "invoiceNumber":"796529012",
    "transaction":"608120887",
    "authorizationCode":"885415",
    "rrn":"001783883631",
    "trimPan":"512722xxxxxx8665",
    "payee":"\u041e\u041e\u041e \u00ab\u0412\u0415\u0411 \u041f\u042d\u0419\u00bb",
    "amount":"0.10",
    "currency":"BYN",
    "responseCode":"",
    "responseText":"",
    "acsUrl":""
  }
}

Сценарий проведения PCI DSS платежа по 3D-Secure 2.0

Шаг 1

Для осуществления интеграции по проведению PCI DSS платежа по 3D-Secure 2.0, следуйте инструкциям ниже:

Сформируйте POST-запрос как описано в Формирование оплаты.
Добавьте в запрос поле wsb_tds_notification_url, которое должно содержать значение URL адреса, на который произойдет перенаправление плательщика после прохождения 3D-Secure проверки и на который вам вернутся параметры с результатом прохождения 3D-Secure сессии.
Отправьте запрос по адресу https://payment.webpay.by/api/v1/payment — для реальной среды или по адресу https://payment.webpay.by/api/v1/payment — для тестовой среды.

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

{
  "wsb_storeid":"123456789",
  "wsb_currency_id":"BYN",
  "wsb_version":2,
  "wsb_seed":"1242649174",
  "wsb_test":0,
  "wsb_invoice_item_name":["test"],
  "wsb_invoice_item_price":["0.1"],
  "wsb_invoice_item_quantity":["1"],
  "wsb_operation_type":"",
  "wsb_customer_id":"41432",
  "wsb_encrypted_data":"LxWN6haDcxu7K2prY2t4P7enfuejEsU7lbD2xvaa8lwQcLQAhchW8xvUXPZWPiYpWuMKtaC3emwALfw9wcB388Gj86Kh7pVSGyljckcFY69tSmvUrUCJYvpNIvYLcBALotXRQCZiijn+ryaXyS0Ymu8G6S6sahWH2UkIEsZJrmMdq2N5fy4sB6fFmDZCtJdCpZHgpCiK9GjX1gvwiB7pOu4vJEwxVmPdheeYsYQiruk+be9U+ENK0EqRA7rZQlrM80lOxw2j2dF2KZYeVbdo5BiYX11bcHNZcgfTbu2zGTQF6MRkV/VPjUuJ+hkMTYPl9XeUYLq8+fMk3QauP/+AXg==",
  "wsb_order_num":"ORDER-de35",
  "wsb_total":"0.1",
  "wsb_signature":"87943d79649e10970b23dfd41194e5a503292bba",
  "wsb_tax":"0",
  "wsb_shipping_name":"Стоимость доставки",
  "wsb_shipping_price":"0",
  "wsb_discount_name":"Скидка на товар",
  "wsb_discount_price":"0",
  "wsb_email":"test@test.com",
  "wsb_phone":"",
  "wsb_return_url":"https://test.com/return",
  "wsb_cancel_return_url":"https://test.com/cancel",
  "wsb_notify_url":"https://test.com/",
  "wsb_3ds_payment_option":"auto",
  "*scart":"",
  "wsb_tds_notification_url":"https://companyname.com/test/"
}

После отправки запроса на указанный URL, WEBPAY вернет в ответ заполненные поля token, acsUrl, creq.

Обратите внимание

При прохождении 3D-Secure проверки по Frictionless flow (процесс 3D-Secure аутентификации без участия держателя карты. Банк-эмитент самостоятельно собирает данные о транзакции, в том числе и об устройстве, с которого она совершается, и оценивает возможный уровень мошенничества. Если угроз не обнаруживается, подтверждение платежа проходит незаметно для плательщика), на запрос из шага 1 будет получен ответ из шага 3.

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

{
  "data":{
    "token":"17efa805408c3d0496476f7ef66d5a8f=62554e714f44564b4d30524f4f553148526a527263466c775748687861545a765758466e53476833516d6f3353457458565564595345643157585242636e6c5056573956516e4275575652564e475a4564544a7753672c2c",
    "tokenName":"wt",
    "time":"",
    "orderNumber":"",
    "invoiceNumber":"",
    "transaction":"",
    "authorizationCode":"",
    "rrn":"",
    "trimPan":"",
    "payee":"",
    "amount":"",
    "currency":"",
    "responseCode":"",
    "responseText":"",
    "acsUrl": "https:\/\/emvacs.qiwi.com\/acs\/api\/3ds2\/creqbrw",
    "threeDSSessionData":"",
    "creq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhkYjQ3Njc4LTMxMGMtNDg1MS04MTA0LTEyYWFjZTVkY2M4ZSIsImFjc1RyYW5zSUQiOiJkODY4NjJkYi0zYWUwLTQ3ZjMtODdjYi02OTBlNmIxZTEzNjEiLCJkc1RyYW5zSUQiOiI2ODk5YzZmMy03N2JhLTRmNzAtYWY5NS0yNDkyZjQwNjZlMjQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0="
  }
}

Шаг 2

Далее для продолжения сессии необходимо отправить полученные параметры на URL адрес, который содержится в ответе в поле acsUrl. Запрос отправляется методом POST с заголовком Content-Type: application/x-www-form-urlencoded, содержащий в теле запроса поле creq со значением из ответа из шага 1.

Обратите внимание

Из значения поля acsUrl нужно убрать все обратные слэши \.

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

POST /acs/api/3ds2/creqbrw HTTP/1.1
Host: emvacs.qiwi.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 327

creq=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhkYjQ3Njc4LTMxMGMtNDg1MS04MTA0LTEyYWFjZTVkY2M4ZSIsImFjc1RyYW5zSUQiOiJkODY4NjJkYi0zYWUwLTQ3ZjMtODdjYi02OTBlNmIxZTEzNjEiLCJkc1RyYW5zSUQiOiI2ODk5YzZmMy03N2JhLTRmNzAtYWY5NS0yNDkyZjQwNjZlMjQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0%3D

После того как плательщик ввел 3D-Secure смс-код и нажал кнопку Подтвердить, произойдет перенаправление на URL адрес, который был вами указан в шаге 1 в поле wsb_tds_notification_url, также на указанный URL будут отправлены параметры с результатом 3D-Secure сессии, необходимые для восстановления сессии в WEBPAY.

Шаг 3

Для восстановления сессии в WEBPAY следует отправить POST-запрос с заголовком Content-Type: application/x-www-form-urlencoded по адресу https://payment.webpay.by?wt={token} — для реальной среды или по адресу https://securesandbox.webpay.by?wt={token} — для тестовой среды, где:

token — значение поля token, которое пришло в ответе от aсs в шаге 2.

Тело запроса должно содержать параметры, полученные от acs на шаге 2 (может быть несколько параметров, например, CRes и threeDSSessionData).

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

POST /?wt=92a2b7aefffcf9d7291e2a068bb0346c%3D526b5a5252557073596e497264314e4c56336c6c64475253556e4e7556474e3565574572596d523156545a48616d6377544752574f486432556d7830526e686155486c495a456f774d484e506432396a5557706859772c2c HTTP/1.1
Host: payment.webpay.by
Content-Type: application/x-www-form-urlencoded
Content-Length: 324

cres=ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiNjcyMDYxNmItYjJkNy00MjE2LTljM2EtNzcyNzZjN2Q0OWM3IiwKICAibWVzc2FnZVR5cGUiIDogIkNSZXMiLAogICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICJhY3NUcmFuc0lEIiA6ICJiYTA4NjMxZi0yZjRkLTQ2MDgtODU3Yi1jMGM5ZmVjYWQ5NDEiLAogICJjaGFsbGVuZ2VDb21wbGV0aW9uSW5kIiA6ICJZIiwKICAidHJhbnNTdGF0dXMiIDogIlkiCn0

WEBPAY получает от вас запрос, обрабатывает, отправляет в процессинг и возвращает вам ответ в формате JSON.

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

{
  "time": "2023.07.14 11:59:03",
  "orderNumber": "ORDER-d213e35",
  "orderNote": "",
  "invoiceNumber": "181060384",
  "transaction": "909062398",
  "authorizationCode": "KDNVSQ",
  "rrn": "319511005218",
  "trimPan": "220073xxxxxx8210",
  "payee": "ООО «ВЕБ ПЭЙ»",
  "customerName": "",
  "customerAddress": "",
  "serviceDate": "",
  "pdfUrl": "https://billing.webpay.by/?kjBNq4f1l1qbIoUeyp7Zpjo6yFeuB%2BPKpl6r1PEBFyzKalsJb84uIMYjM3lYKbn3s1pNEnXRZLqTRKSvomJUVHOd9lnQ3y0zleHOx4VN1ab%2FWQ%3D%3D",
  "language": "ru",
  "items": [
    {
      "name": "test",
      "quantity": 1,
      "price": "0.10",
      "totalAmount": "0.10",
      "commission": "0.00"
    }
  ],
  "amount": "0.10",
  "currency": "BYN"
}