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 | 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 | |
| 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
{
"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":" "
}
{
"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.
