Принять платеж (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 (будет определяться в зависимости от языка браузера)

- RU (по умолчанию)

- UA

- EN

нет

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

- credit

- qrCode

- masterPass

- visaCheckout

- bot - метод оплаты в месенджерах (бот wayforpay)

- payParts (мгновенная рассрочка от ПриватБанка)*

- payPartsMono (покупка частями от Монобанка)*

- payPartsPrivat (оплата частями от ПриватБанка )*

- payPartsAbank (плати частями от А-Банка)*

- instantAbank (рассрочка А-Банка)*

*Для платежей в рассрочку или оплаты частями можно передавать доступное для клиента кол-во частей на платежной странице, кол-во частей  указываем через запятую после ":". Например: 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

email плательщика

email@mail.com

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

www.market.ua

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

email плательщика

email@mail.com

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

 
 
Пример запроса на serviceUrl
{
"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
$json = file_get_contents('php://input');
$obj = json_decode($json, TRUE);
 
 
Пример эмитирующий работу запрос на Service URL
$ 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":""
}