To accept payment host2host (Charge)

Charge request is used for quick payment making in one action. It is performed within the limits of single-staged pattern.

The result of request processing is the withdrawal of monetary assets from client’s card.

 

Request parameters

A request with the required parameters is to be formed at the merchant’s side and to be transferred by POST method through HTTP protocol to URL https://api.wayforpay.com/api

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

 

Parameter

Description

mandatory

transactionType

CHARGE

yes

merchantAccount

Seller identifier. These values are assigned through the WayForPay

yes

merchantAuthType

Authorization type. May take one of the following values:

- simpleSignature (on default)

no

merchantDomainName

Domain name of merchant’s web-site

yes

merchantTransactionType

Transaction type. May take one of the following values:

- SALE - withdraw funds from card

- AUTH - blocking money on the payment card

 

yes

merchantTransactionSecureTtype

Type of security of the transaction. It can take one of the following:

- AUTO

- 3DS

- NON3DS

yes

merchantSignature

Request signature

yes

apiVersion

The protocol version. Default value: 1

yes

serviceUrl

URL, to which the system should send to Merchant a response with the result of the payment

no

orderReference

Unique number of the order in merchant’s system

yes

orderDate

Date of order placing

yes

amount

Amount of order

yes

currency

Currency of order:

UAH (USD, EUR)

yes

holdTimeout

Period of blocking funds in seconds.

Default:

1 728 000 million (20 days).

A minimum of 60 (1 min)

Maximum 1 728 000 (20 days)

no

card

Card number 16 characters

no

expMonth

Card Expiry Date (mounth)

 - MM

no

expYear

Card Expiry Date (year)- YY

no

cardCvv

Card Security Code CVV / CVV2

no

cardHolder

Cardholder Name, as indicated on the card

no

recToken

Card token for recarring withdrawals, without client (without reference to card details)

no

productName[]

Array with the names of ordered products

yes

productPrice[]

Array with the prices per product unit. This information will be visible at the page of order payment

yes

productCount[]

Array with the quantity of ordered goods by 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

clientFirstName

Client First Name

yes

clientLastName

Client Last Name

yes

clientEmail

Client Email

yes

clientPhone

Client Phone

yes

clientCountry

Client Country

yes

clientIpAddress

ip-address from which the client came to the merchant page to complete the purchase

yes

clientAddress

Client address

no

clientCity

Client city

no

clientState

Client state/region

no

clientZipCode

Client postal code

no

Note: fields (card+expMonth+expYear+cardCvv+cardHolder) or recToken should be obligatory.

 

In case of  merchantTransactionSecureTtype= 3DS, there is initially performed the checking of the card for participation in 3d secure program.

If the card does not supports 3D Secure  - there will be returned the response  Declined, code 1120, description Authentication unavailable.

If the card supports 3D Secure  verification the system Wayforpay will return the parameters for authentication of the client.

With these parameters the merchant has to transfer the client to url of issuer for authentication. 

The time during which the session for verification is active - 10 minutes. If within 10 minutes COMPLETE_3DS will not be obtained the system will cancel transaction as unsuccessful.

 

Parameter

Description

Example

merchantAccount

Seller identifier.

test_merch_n1

orderReference

Unique number of the order in merchant’s system

order-1430206527

amount

Amount of order

0.31

currency

Currency of order

UAH

authCode

authorization code - assigned by Bank

null

createdDate

Date of creation request  in psp (UTC)

1430206630

processingDate

date of transaction processing

null

recToken

card token for recurring payments

 

reason

 

Wait 3ds data

transactionStatus

transaction status

InProcessing

reasonCode

Code of refusal

5100

fee

amount of commission

1

d3AcsUrl

Address of ACS server of Issuer to which you want to redirect the user for authentication

https://3dsecure.ukrsibbank.com/acs/auth/start.do

d3Md

Unique identifier which must be transmitted to the url method POST, in time when client will be rerouted

ODMyNzRmNjgtMjEyYS00ODAyLWExYjMtZTc1Y2ZkZTNjYTBi

d3Pareq

PaReq message, which must be  transmitted to the url method POST, in time when client will be rerouted

eJx1kmFvgjAQhv+K8QfQFkHBnE3YNNFF0ajZol+WBi+CAcRSVPbr

1yrO7cP66Z43vXvvroV1LBGH\nK4wqiRxmWJZij61kN2gvgk+bOZ7

TZW0Oi2CJJw5nlGVyzDmzqGUDeaDOk1EscsVBRKeXSchdx+1R\

nD0iDkKGcDDmjzfGZ51IXyF2GXGTI11iq1lSocyKA3BSIjlWuZM

096gB5AFQy5bFSRdknBKNjpotE\naKXJqRC1pfkpkqxIdJsmAcizx0Vlol

IbXJMdnw9ndfi1zMLDXs0Oo3qzonQ+DOrpx2gAxNyAnVDI\n

bcpc6thei9F+p9dnuvBNB5GZzji1OkwPfAcojEdwB6P\/5n\/m0k8gMY9q

7ntUyw8CvBbHHHWedvyJ\ngTyneB2bvUdKr3I\/3V5UuHo\/+7F

MxsXhknbtFN+2m11qmrtfMhUT7ch8498AEFOGNA9Nmp+goz8\/\n5Bt+QbuA

authTicket

Authorization Ticket

d185a769977cc297b13bfd0edd9bdd29

merchantSignature

Request signature

09c85c95722fee7c2283d5f189902035

 

After obtaining of data from Wayforpay system the merchant has to transfer to d3AcsUr  through POST method the parameters d3Pareq и d3Md  in the following form:

 

<FORM NAME="MPIFORM" ACTION='${D3ACSURL}' METHOD="POST">
<INPUT TYPE="HIDDEN" NAME="PAREQ" VALUE='${D3PAREQ }'>
<INPUT TYPE="HIDDEN" NAME="MD" VALUE='${D3MD }'>
<INPUT TYPE="HIDDEN" NAME="TERMURL" VALUE='${TEMPURL}'>
</FORM>

TempUrl - url transferred by the merchant, to which the issuer will return response after authentication of the client.

Confirmation of 3d secure verification

After passing by the client of authentication and redirecting to TempUrl with a result obtained from the issuer the merchant sends a COMPLETE_3DS request.

 

Parameter

Description

Mandatory

transactionType

COMPLETE_3DS

yes

authorization_ticket

Authorization ticket

yes

d3ds_md


 

no

d3ds_pares

 

yes

 

Response parameters

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

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 в цифровом ISO 3166-1-Alpha 3

980

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

 

An example of request and response

 

Request
{
"transactionType":"CHARGE",
"merchantAccount":"test_merch_n1",
"merchantAuthType":"SimpleSignature",
"merchantDomainName":"www.super.org",
"merchantTransactionType":"AUTH",
"merchantTransactionSecureType": "NON3DS",
"merchantSignature":"60c5d743b71f79abe48c7183ada4b451",
"apiVersion":1,
"orderReference":"myOrder1",
"orderDate":1421412898,
"amount":0.13,
"currency":"UAH",
"card":"4111111111111111",
"expMonth":"11",
"expYear":"2020",
"cardCvv":"111",
"cardHolder":"TARAS BULBA",
"productName":["Samsung WB1100F","Samsung Galaxy Tab 4 7.0 8GB 3G Black"],
"productPrice":[21.1,30.99],
"productCount":[1,2],
"clientFirstName":"Bulba",
"clientLastName":"Taras",
"clientCountry":"UKR",
"clientEmail":"rob@mail.com",
"clientPhone":"380556667788",
"clientIpAdress":" "
}

 

An example of request on serviceUrl
{
"merchantAccount":"test_merch_n1",
"orderReference":"DH783023",
"merchantSignature":"",
"amount":1547.36,
"currency":"UAH",
"authCode":"541963",
"createdDate":12345678,
"processingDate":12345678,
"cardPan":"41****8217",
"cardType":"visa",
"issuerBankCountry":"980",
"issuerBankName":"Privatbank",
"recToken":"121213321-3213213-3213213-321-3",
"transactionStatus":"Approved",
"reason":"ok",
"reasonCode":"1100",
"fee":0,
"paymentSystem":"card"
}

An example of a correct response from merchant

WayForPay system expects to receive from the server to the merchant next response:

{
"orderReference":"DH783023",
"status":"accept",
"time":1415379863,
"signature":""
}


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, merchantSecretKey  divided with “;” (semi-column) in coding UTF-8

 

Notification of the merchant about transaction status

For authorized and checked orders (as well as in case of change of status of the order) WayForPay server sends to serviceUrl  a request (HTTP_POST) which includes the data of the order. Such information is to be supplemented with the 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.