Принять платеж (Purchase)
Запрос Purchase используется для проведения платежа клиентом на защищенной странице WayForPay.
Параметры запроса:
Запрос c необходимыми параметрами формируется на стороне торговца и передается методом POST по протоколу HTTP на URL https://secure.wayforpay.com/pay
Параметр | Описание | Обязательное |
merchantAccount | Идентификатор продавца. Данное значение присваивается Вам со стороны WayForPay | да |
merchantAuthType | Тип авторизации. Может принимать одно из следующих значений: - SimpleSignature (по умолчанию) - ticket - password | нет |
merchantDomainName | Доменное имя веб-сайта торговца | да |
merchantTransactionType | Тип транзакции. Может принимать одно из следующих значений: - AUTO (по умолчанию) - AUTH - SALE | нет |
merchantTransactionSecureType | Тип безопасности для прохождение транзакции. Может принимать одно из следующих значений: - AUTO | да |
merchantSignature | Подпись запроса | да |
apiVersion | Версия протокола. Значение по-умолчанию: 1 Значение 2 - включают передачу в колбэке на serviceUrl расширенных данных - доп поля, доставка, комментарии. | нет |
language | Язык платежной страницы. Может принимать одно из следующих значений: - AUTO (будет определяться в зависимости от языка браузера) - UA (по умолчанию) - RU - EN Дополнительно: - DE - немецкий - IT - итальянский - RO - румынский - ES - испанский - PL - польский - SK - словацкий - FR - французский - LV - латвийский | нет |
returnUrl | URL, на который система должна перенаправлять клиента с результатом платежа. *В случае отсутствия параметра переадресация происходит на страницу результата оплаты checkout psp | нет |
serviceUrl | URL, на который система должна отправлять ответ с результатом платежа напрямую мерчанту | нет |
orderReference | Уникальный номер заказа в системе торговца | да |
orderDate | Дата размещение заказа | да |
orderNo | Номер заказа в системе продавца | нет |
amount | Сумма заказа | да |
currency | Валюта заказа UAH (USD, EUR, RUB) | да |
alternativeAmount | Альтернативная сумма заказа | нет |
alternativeCurrency | Альтернативная валюта заказа (USD, EUR, RUB) | нет |
holdTimeout | Время действия блокировки средств в секундах. По умолчанию 1 728 000 (20 дней). Максимум 1 728 000 (20 дней). Минимальное значение 60(1 минута). | нет |
orderTimeout | Устанавливает интервал, в течении которого будет доступна возможность повторно оплатить заказ на платежной странице. В секундах | нет |
orderLifetime | Устанавливает интервал, в течении которого заказ может быть оплачен. В секундах | нет |
recToken | Токен карты для рекарринговых списаний | нет |
productName[] | Массив с наименованием заказанных товаров | да |
productPrice[] | Массив с ценами за единицу товара. Данная информация будет видна на странице оплаты заказа | да |
productCount[] | Массив с количеством заказанного товара по каждой позиции. | да |
clientAccountId | уникальный идентификатор клиента в системе торговца (логин, email и т.д.) | нет |
socialUri | Уникальный идентификатор ресурса. Пример: https://www.facebook.com/vladislavsolodkiy | нет |
deliveryList | Добавляет на платежной странице блок доставки, который клиенту необходимо будет заполнить. Можно передать одну или несколько значений через ";" Список значений: - nova - Новая Почта - meest - Мист экспресс - justin - Джастин - ukrpost - Укрпочта - other - адресная доставка | нет |
clientFirstName | Имя клиента | нет |
clientLastName | Фамилия клиента | нет |
clientAddress | Адрес клиента | нет |
clientCity | Город клиента | нет |
clientState | Штат/Область клиента | нет |
clientZipCode | Почтовый индекс клиента | нет |
clientCountry | Страна клиента в цифровом ISO 3166-1-Alpha 3 | нет |
clientEmail | Email клиента | нет |
clientPhone | Номер телефона клиента | нет |
deliveryFirstName | Имя получателя | нет |
deliveryLastName | Фамилия получателя | нет |
deliveryAddress | Адрес получателя | нет |
deliveryCity | Город получателя | нет |
deliveryState | Штат/Область получателя | нет |
deliveryZipCode | Почтовый индекс получателя | нет |
deliveryCountry | Страна получателя | нет |
deliveryEmail | Email получателя | нет |
deliveryPhone | Номер телефона получателя | нет |
aviaDepartureDate | Время отправления рейса | нет |
aviaLocationNumber | Количество пунктов пересадок | нет |
aviaLocationCodes | Коды аэропортов | нет |
aviaFirstName | Имя пассажира | нет |
aviaLastName | Фамилия пассажира | нет |
aviaReservationCode | Код резервирования | нет |
regularMode | Периодичности регулярного списания: - client - отображает клиенту на выбор список всех доступных периодов повторения. - none - оплата происходит без использования регулярки - once - списание один раз - daily - ежедневно - weekly - еженедельно - quarterly - ежеквартально (раз в три месяца начиная с даты первого платежа) - monthly - ежемесячно - halfyearly - раз в пол года - yearly - раз в год Передача одного или нескольких периодов через ";" | нет |
regularAmount | Сумма регулярного платежа. Если не передан - берется сумма из поля "amount" | нет |
dateNext | Дата первого списания регулярного платежа в формате ДД.ММ.ГГГГ. Дата должна быть больше текущей даты | нет |
dateEnd или regularCount | Дата окончания или количество платежей | нет |
regularOn | При передаче значения = 1, чекбокс "сделать платеж регулярным" включен, поле regularAmount заблокировано для редактирования. | нет |
paymentSystems | Список платежных систем, доступных клиенту при выборе способа оплаты на платежной странице. Системы должны быть разделены точкой с запятой. Доступные платежные системы: - card - googlePay - applePay - privat24 - lpTerminal - delay - bankCash - qrCode - masterPass - visaCheckout - bot - метод оплаты в месенджерах (бот wayforpay) - payParts (мгновенная рассрочка от ПриватБанка)* - payPartsMono (покупка частями от Монобанка)* - payPartsPrivat (оплата частями от ПриватБанка )* - payPartsAbank (плати частями от А-Банка)* - instantAbank (рассрочка А-Банка)*- instantAbank (рассрочка А-Банка)* - globusPlus (оплата частями Глобус+ Глобус банк)* - payPartsOschad (оплата частями Ощадбанк)* - OnusInstallment (рассрочка Райффайзен Банк)
*Для платежей в рассрочку или оплаты частями можно передавать доступное для клиента кол-во частей на платежной странице, кол-во частей указываем через запятую после ":". Например: payPartsAbank:2,3,7,10;payParts:5 По умолчанию клиенту доступны все разрешенные мерчанту системы оплаты. | нет |
defaultPaymentSystem | Платежная система, которая первой отобразится плательщику на платежной странице. По умолчанию - card | нет |
Параметры ответа:
Параметр | Описание | Пример |
merchantAccount | Идентификатор продавца | test_merch_n1 |
orderReference | Уникальный номер заказа в системе торговца | 1212dd1 |
merchantSignature | hash_hmac | |
amount | Сумма заказа | 100 |
currency | Валюта заказа | UAH |
authCode | Код авторизации - присваивается банком | 324567 |
| email плательщика | |
phone | Номер телефона плательщика | +38063-333-33-33 |
createdDate | Дата создания запроса в psp (UTC) | 123456789 |
processingDate | Дата процессирования транзакции (UTC) | 12345678 |
cardPan | Маскированный номер карты (44****4444) | 42****4242 |
cardType | Типа карты: Visa/MasterCard | Visa |
issuerBankCountry | Страна карты | Ukraine |
issuerBankName | Имя Банка карты | PrivatBank |
recToken | Токен карты для рекаренговых списаний | 121213321-3213213-3213213-321-3 |
transactionStatus | статус транзакции | Approved |
reason | Причина отказа | Ok |
reasonCode | Код отказа | 1100 |
fee | Комиссия psp | 0.00 |
paymentSystem | Платежная система, через которую был осуществлен платеж. | card |
Генерирование тестовой строки
Параметры генерирования тестовой строки по ссылке
Аутентификация запросов
В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца.
Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchantAccount, merchantDomainName, orderReference, orderDate, amount, currency, productName[0], productName[1]..., productName[n], productCount[0], productCount[1],..., productCount[n], productPrice[0], productPrice[1],..., productPrice[n] разделенных “;” (точка с запятой) в кодировке UTF-8
Пример HTTP POST запроса:
merchantAccount | test_merch_n1 |
merchantDomainName | |
orderReference | DH783023 |
orderDate | 1415379863 |
amount | 1547.36 |
currency | UAH |
productName | ["Процессор Intel Core i5-4670 3.4GHz","Память Kingston DDR3-1600 4096MB PC3-12800"] |
productCount | [1,1] |
productPrice | [1000,547.36] |
merchantSignature | b95932786cbe243a76b014846b63fe92 |
Базовая строка для генерации HASH для приведенного примера будет равна:
test_merchant;www.market.ua;DH783023;1415379863;1547.36;UAH;Процессор Intel Core i5-4670 3.4GHz;Память Kingston DDR3-1600 4096MB PC3-12800;1;1;1000;547.36
Результат HMAC_MD5 и значение параметра merchantSignature будет строка 3f787303ac524389b4a76383f9508251
Пример PHP
<?php
$string = "test_merchant;www.market.ua;DH783023;1415379863;1547.36;UAH;Процессор Intel Core i5-4670 3.4GHz;Память Kingston DDR3-1600 4096MB PC3-12800;1;1;1000;547.36";
$key = "dhkq3vUi94{Z!5frxs(02ML";
$hash = hash_hmac("md5",$string,$key);
?>
Пример запроса:
<form method="post" action="https://secure.wayforpay.com/pay" accept-charset="utf-8">
<input name="merchantAccount" value="test_merch_n1">
<input name="merchantAuthType" value="SimpleSignature">
<input name="merchantDomainName" value="www.market.ua">
<input name="merchantSignature" value="b95932786cbe243a76b014846b63fe92">
<input name="orderReference" value="DH783023">
<input name="orderDate" value="1415379863">
<input name="amount" value="1547.36">
<input name="currency" value="UAH">
<input name="orderTimeout" value="49000">
<input name="productName[]" value="Процессор Intel Core i5-4670 3.4GHz">
<input name="productName[]" value="Память Kingston DDR3-1600 4096MB PC3-12800">
<input name="productPrice[]" value="1000">
<input name="productPrice[]" value="547.36">
<input name="productCount[]" value="1">
<input name="productCount[]" value="1">
<input name="clientFirstName" value="Вася">
<input name="clientLastName" value="Пупкин">
<input name="clientAddress" value="пр. Гагарина, 12">
<input name="clientCity" value="Днепропетровск">
<input name="clientEmail" value="some@mail.com">
<input name="defaultPaymentSystem" value="card">
<button type="submit">Оплатить</button>
</form>
Уведомление мерчанта о статусе транзакции
Для авторизованных и проверенных заказов (а также при смене статуса заказа) сервер WayForPay направляет на serviceUrl запрос (HTTP_POST) включающий в себя данные заказа.
Данная информация дополняется контрольной подписью HMAC_MD5.
В случае, если WayForPay НЕ получит корректный ответ от сервера торговца, то система будет направлять запросы в течении 4-х суток или до получения правильного ответа.
Сервер торговца (или телефон клиента ) посылает пост запрос на https://secure.wayforpay.com/pay?behavior=offline с полями для PURCHASE.
В ответ наш сервер в случае успеха отдает {"url":"https:\/\/secure.wayforpay.com\/page?vkh=5f6204b5-8300-4cfb-851b-749822d1dba8"}.
В параметре url находится ссылка для оплаты, по которой клиент может перейти и получить платежную страницу.
Параметры запроса шлюза WayForPay на serviceUrl *
В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца.
Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchantAccount, orderReference, amount, currency, authCode, cardPan, transactionStatus, reasonCode разделенных “;” (точка с запятой) в кодировке UTF-8
Параметр | Описание | Пример |
merchantAccount | Идентификатор продавца | test_merch_n1 |
orderReference | Уникальный номер заказа в системе торговца | 1212dd1 |
merchantSignature | hash_hmac | |
amount | Сумма заказа | 100 |
currency | Валюта заказа | UAH |
authCode | код авторизации - присваивается банком | 324567 |
| email плательщика | |
phone | Номер телефона плательщика | +38063-333-33-33 |
createdDate | дата создания запроса в psp | 123456789 |
processingDate | дата процессирования транзакции | 12345678 |
cardPan | маскированный номер карты | 42****4242 |
cardType | типа карты: Visa/MasterCard | Visa |
issuerBankCountry | Страна карты | Ukraine |
issuerBankName | Имя Банка карты | PrivatBank |
recToken | токен карты для рекаренговых списаний | 121213321-3213213-3213213-321-3 |
transactionStatus | статус транзакции | Approved |
reason | Причина отказа | Ok |
reasonCode | Код отказа | 1100 |
fee | Комиссия psp | 0.00 |
paymentSystem | Платежная система, через которую был осуществлен платеж. | card |
repayUrl | Передается если оплата клиентом была неуспешна. Url адрес по которому можно повторно оплатить в рамках времени переданного в orderTimeout или orderLifetime. | https://secure.wayforpay.com/repay/40aef950b5dc8dbb6c9e670e45af0f56 |
{
"merchantAccount":"test_merchant",
"orderReference":"DH783023",
"merchantSignature":"",
"amount":1547.36,
"currency":"UAH",
"authCode":"541963",
"email":"client@mail.ua",
"phone":"380501234567",
"createdDate":12345678,
"processingDate":12345678,
"cardPan":"41****8217",
"cardType":"visa",
"issuerBankCountry":"980",
"issuerBankName":"Privatbank",
"recToken":"",
"transactionStatus":"Approved",
"reason":"ok",
"reasonCode":"1100",
"fee":0,
"paymentSystem":"card"
}
$json = file_get_contents('php://input');
$obj = json_decode($json, TRUE);
$ curl http://you.service.url -d '{"a":"a", "bInt":1}'
Система WayForPay ожидает получить от сервера торговца следующий ответ:
В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца.
Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров orderReference, status, time разделенных “;” (точка с запятой) в кодировке UTF-8
{
"orderReference":"DH783023",
"status":"accept",
"time":1415379863,
"signature":""
}