Purchase request is used to effect payment with client on the protected wayforpay site.
Request parameters:
The request with the required parameters is to be formed on the side of merchant and to be transferred by POST method through HTTP protocol to URL https://secure.wayforpay.com/pay
| parameter | description | mandatory |
|---|---|---|
| merchantAccount | Seller identifier. This value is assigned to You from the side of WayForPay | yes |
| merchantAuthType | Authorization type. May take one of the following values: - simpleSignature (on default) - ticket - password | no |
| merchantDomainName | Domain name of merchant’s web-site | yes |
| merchantTransactionType | Transaction type. May take one of the following values: - AUTO (on default) - AUTH - SALE | no |
| merchantTransactionSecureType | Type of safety for transaction completion. May take one of the following values: - AUTO | yes |
| merchantSignature | Request signature | yes |
| apiVersion | Protocol version. Default value: 1 Value 2 - enable the transfer of extended data in the callback to serviceUrl - additional fields, delivery, comments. | no |
| language | Language of payment page. May take one of the following values: - AUTO (will be determined depending on the browser language) - RU (on default) - UA - EN
Additionally:
- DE - German IT - Italian RO - Romanian - ES - Spanish PL - Polish SK - Slovak
- FR - French LV - Latvian CS - Czech | no |
| returnUrl | URL, to which the system has to transfer client with the payment result. *In case of absence of parameter readdressing is performed to the page of payment result checkout psp | no |
| serviceUrl | URL, to which the system has to send a response with the payment result directly to the merchant | no |
| orderReference | Unique number of the order in merchant’s system | no |
| orderNo | Order number in seller’s system | нет |
| orderDate | Date of order placing | yes |
| amount | Amount of order | yes |
| currency | Currency of order UAH | yes |
| alternativeAmount | Alternative amount of order | no |
| alternativeCurrency | Alternative currency of order (USD, EUR) | no |
| holdTimeout | Period of validity of funds blocking in seconds. By default: 1 728 000 (20 days). Maximum 1 728 000 (20 days). Minimal value 60 (1 minute). | no |
| orderLifetime | Sets the interval during which an order can be paid. In seconds | no |
| orderTimeout | Sets the interval within which the order can be paid for. In seconds | no |
| recToken | Card token for recarring withdrawals | no |
| productName[] | Array with the names of ordered productsemail@mail.com | yes |
| productPrice[] | Array with the prices per product units, This information will be visible at the page of payment for order | yes |
| productCount[] | Array with the quantity of ordered products on each item. | yes |
| clientAccountId | Unique identifier in merchant’s system (login, email and etc.) | no |
| socialUri | Unique identifier of resource. Example: https://www.facebook.com/vladislavsolodkiy | no |
| deliveryList | The customer needs to fill out the delivery block. - nova - only the Nova Poshta branch - nova;nova_pl - branches and parcel machines of Nova Poshta, with the possibility of selection - nova_pl - only the Nova parcel machines - meest - ukrpost - other - delivery by address |
no |
| clientFirstName | First name | no |
| clientLastName | Client’s surname | no |
| clientAddress | Client address | no |
| clientCity | Client city | no |
| clientState | Client state/region | no |
| clientZipCode | Client postal code | no |
| clientCountry | Client country in digital ISO 3166-1-Alpha 3 | no |
| clientEmail | Client Email | no |
| clientPhone | Client phone number | no |
| deliveryFirstName | Recipient name | no |
| deliveryLastName | Recipient surname | no |
| deliveryAddress | Recipient address | no |
| deliveryCity | Recipient city | no |
| deliveryState | Recipient state/region | no |
| deliveryZipCode | Recipient postal code | no |
| deliveryCountry | Recipient country | no |
| deliveryEmail | Recipient Email | no |
| deliveryPhone | Recipient phone number | no |
| aviaDepartureDate | Voyage departure time | no |
| aviaLocationNumber | Number of points of transfer | no |
| aviaLocationCodes | Airport codes | no |
| aviaFirstName | Passenger name | no |
| aviaLastName | Passenger surname | no |
| aviaReservationCode | Booking code | no |
| regularBehavior | - preset - so that the client cannot edit the parameters of the regular payment on the payment page | no |
| regularMode | Frequency of regular charges: - client - displays a list of all available recurrence periods to the customer. - none - payment is made without using a regular payment - once - single charge - daily - weekly - quarterly - every three months from the date of first payment - monthly - halfyearly - yearly
| no |
| regularAmount | Amount of regular payment. If not transferred, the amount is taken from the "amount" field | no |
| dateNext | The date of the first write-off of the regular payment in the format DD.MM.YYYY. Date must be greater than current date. | no |
| dateEnd orregularCount | End Date or Number of Payments | no |
| regularOn | When passing value = 1, the checkbox "make payment regular" is enabled, the regularAmount field is locked for editing. | no |
| paymentSystems | The list of payment systems available for client in case of selection of payment method at the payment page. The systems should be divided with semi-column. Available payment systems: - card - googlePay - applePay - privat24 - lpTerminal - delay - bankCash - qrCode - masterPass - visaCheckout - bot - payment method in messengers (bot wayforpay) - payParts (instant installment plan from PrivatBank)* - payPartsMono (purchase of parts from Monobank)* - payPartsPrivat (payment by parts from PrivatBank)* - payPartsAbank (pay in installments from A-Bank)* - instantAbank (instant installment plan from A-Bank)* - globusPlus (payment by parts from Globus+ from Globus Bank)* - OnusInstallment (instant installment plan from Raiffeisen Bank )* - payPartsOtp (instant installment plan from ОТР Bank)* - payPartsSport (payment by parts from Sportbank)*
*For installment payments or installment payments, you can transfer the number of parts available to the client on the payment page, the number of parts is indicated by a comma after ":". For instance: payPartsAbank:2,3,7,10;payParts:5
On default all the payment systems allowed for the merchant are available for client. | no |
| defaultPaymentSystem | Payment system that will be first represented for the payer at payment page. On default - card | no |
Response parameters:
| parameter | description | mandatory |
|---|---|---|
| merchantAccount | Seller identifier | test_merchant |
| orderReference | Unique number of the order in merchant’s system | 1212dd1 |
| merchantSignature | hash_hmac |
|
| amount | Amount of order | 100 |
| currency | Currency of order | UAH |
| authCode | authorization code - assigned by Bank | 324567 |
| | Client Email | |
| phone | Client phone number | +38063-333-33-33 |
| createdDate | Date of creation request in psp (UTC) | 123456789 |
| processingDate | date of transaction processing (UTC) | 12345678 |
| cardPan | Masked card number (44****4444) | 42****4242 |
| cardType | Card type: Visa/MasterCard | Visa |
| issuerBankCountry | Country of card | Ukraine |
| issuerBankName | Name of the Bank card | PrivatBank |
| recToken | card token for recurring payments | 121213321-3213213-3213213-321-3 |
| transactionStatus | transaction status | Approved |
| reason | Reason for refusal | Ok |
| reasonCode | Code of refusal | 1100 |
| fee | Commission psp | 0.00 |
| paymentSystem | The payment system, through which the payment was made. | card |
Test string generating
Parameters for generating a test string by reference
Requests authentication
For the purposes of confirmation of data validity there should be generated and transferred in the request the HMAC_MD5 control signature using SecretKey of merchant.
The line which subjects to HMAC_MD5 is generated through catenation of parameters merchantAccount, merchantDomainName, orderReference, orderDate, amount, currency, productName[0],
productName[1]..., productName[n], productCount[0], productCount[1],..., productCount[n], productPrice[0], productPrice[1],..., productPrice[n] divided with “;” (semi-column) in coding UTF-8
An example of HTTP POST request:
| merchantAccount | test_merchant |
| 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 |
The base line for generating HASH for the example would be: 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
Result HMAC_MD5 and value is: merchantSignature b95932786cbe243a76b014846b63fe92
<?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>
Notification of merchant about status of transaction
For authorized and checked orders (as well as in case of change of order status) the server WayForPay sends to serviceUrl a request (HTTP_POST) which includes the order data.
This information is to be added with a control signature HMAC_MD5.
In case if WayForPay WILL NOT obtain correct response from the merchant’s server the system will send requests during 4 days or until obtaining of correct response.
The merchant's server (or customer's phone) sends a post request to https://secure.wayforpay.com/pay?behavior=offline with fields for PURCHASE.
In response, our server, if successful, returns {"url": "https: \ / \ / secure.wayforpay.com \ / page? Vkh = 5f6204b5-8300-4cfb-851b-749822d1dba8"}.
The URL parameters contain a payment link where the client can go and receive the payment page.
Parameters of request of gate WayForPay to serviceUrl
For the purposes of confirmation of data validity there should be generated and transferred in the request the HMAC_MD5 control signature using SecretKey of merchant.
The line which subjects to HMAC_MD5 is generated through catenation of parameters merchantAccount, orderReference, amount, currency, authCode, cardPan, transactionStatus, reasonCode divided with “;” (semi-column) in coding UTF-8
| Parameter | Description | example |
|---|---|---|
| merchantAccount | Seller identifier. | test_merchant |
| orderReference | Unique number of the order in merchant’s system | 1212dd1 |
| merchantSignature | hash_hmac |
|
| amount | Amount of order | 100 |
| currency | Currency of order | UAH |
| authCode | authorization code - assigned by Bank | 324567 |
| | payer email | |
| phone | Phone number of the payer | +38063-333-33-33 |
| createdDate | Date of creation request in psp (UTC) | 123456789 |
| processingDate | date of transaction processing | 12345678 |
| cardPan | Masked card number | 42****4242 |
| cardType | Card type: Visa/MasterCard | Visa |
| issuerBankCountry | Country of card | Ukraine |
| issuerBankName | Name of the Bank card | PrivatBank |
| recToken | card token for recurring payments | 121213321-3213213-3213213-321-3 |
| transactionStatus | transaction status | Approved |
| reason | Reason for refusal | Ok |
| reasonCode | Code of refusal | 1100 |
| fee | commission psp | 0.00 |
| paymentSystem | The payment system, through which the payment was made. | card |
| repayUrl | Transferred in case of successful payment by the client. Url address at which there may be made repeated payment within the period, transferred in orderTimeout or orderLifetime |
An example of request on 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 = file_get_contents('php://input');
$obj = json_decode($json, TRUE);
$ curl http://you.service.url -d '{"a":"a", "bInt":1}'WayForPay system awaits to obtain from the merchant’s server the following response:
For the purposes of confirmation of data validity there should be generated and transferred in the request the HMAC_MD5 control signature using SecretKey of merchant.
The line which subjects to HMAC_MD5 is generated through catenation of parameters orderReference, status, time divided with “;” (semi-column) in coding UTF-8
{
"orderReference":"DH783023",
"status":"accept",
"time":1415379863,
"signature":""
}