Accept payment (Purchase)

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

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, RUR)

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. You can pass one or more values ​​through ";" List of Values:

- nova 

- meest 

- justin

- 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

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 


Transmission of one or more periods through ";"

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 

or 

regularCount

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

- credit

- 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)*

*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

email

Client Email

email@mail.com

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

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

 

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

 
 
Example 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);
?>
 
 
 
Example of a request:
<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.

 

 

 

 To implement payments in the mobile application

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

email

payer email

email@mail.com

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

https://hpp.psp.loc/repay/40aef950b5dc8dbb6c9e670e45af0f56

 

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 string to parse (example)
$json = file_get_contents('php://input');
$obj = json_decode($json, TRUE);

 

 
 
An example of work imitating request Service URL
$ 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

 
 
 
An example of a correct response from merchant
{
"orderReference":"DH783023",
"status":"accept",
"time":1415379863,
"signature":""
}