Payment formation

To integrate with the WEBPAY system for PCI DSS merchants who handle card data on their own website pages or directly within their application and wish to use the Host2Host integration, please follow the instructions below:

Form a standard POST request (see section Order creation for payment).
Add the wsb_encrypted_data field to the request.
Add the wsb_email field to the request. For this method of operation, this field is mandatory when sending the request.
Optionally, you can add the wsb_return_format field to specify the response format from our system.

Field Name	Mandatory	Description	Notes
`wsb_encrypted_data`	Yes	Contains encrypted JSON in the format `{"cc_pan":"", "cc_exp":"", "cc_cvv":"", "cc_name":""}`	Encrypted using the `RSA` algorithm with the public key from the personal cabinet
`wsb_email`	Yes	Buyer's email address
`wsb_return_format`	No	Result output format	Possible value: `json`

Please Note

When forming the wsb_signature field (the signature formation mechanism is described in the section Electronic Order Signature), the wsb_encrypted_data field also participates in parameter concatenation and is placed at the end before SecretKey. Then the standard payment scenario proceeds.

Field Name	Description
`time`	Request execution time
`orderNumber`	Order number
`invoiceNumber`	Invoice number
`transaction`	Transaction ID
`authorizationCode`	Authorization code
`Rrn`	Unique bank transaction identifier
`trimPan`	Card number in the format `123456xxxxxx1234`
`payee`	Payment recipient
`amount`	Payment amount
`currency`	Payment currency
`acsUrl`	Redirect URL for 3D-Secure authentication
`PaReq`	Parameter passed to the acs page
`TermUrl`	URL for receiving the response from the acs page
`MD`	Token for restoring the session after the acs page
`tokenName`	Token name for restoring the payment session
`token`	Token value for restoring the payment session
`availableOption`	Parameter contains possible values for the `paymentType` field. The list of values depends on the card type and merchant settings. Possible values: `IpsPayment` — IPS terminal (default or, if routing is enabled, the smart-routed terminal) `halva` — Halva terminal `standard` — Halva+ terminal (payment in rubles) `bonus` — Halva+ terminal (payment with bonuses)
`paymentType`	Used to select a payment option for cards. Comes empty, must be filled. Possible values for filling are taken from the `availableOption` field.
`responseCode`	Contains the error code if an error occurs
`responseText`	Contains the error text

Payment option for Halva+ Card

WEBPAY returns in the response:

Example Response

{
  "token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345879566e334b48526e592c",
  "tokenName":"wt",
  "availableOption":"ipsPayment,halva",
  "paymentType":""
}

Upon receiving such a response, the merchant must request the payment option from the client and send us a POST request with the following fields:

$params['wt'] = "effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5
a30345879566e334b48526e592c";
$params['payHalvaPlus'] = 1;
$params['paymentType'] = 'standard'; /* can contain values from the available options received in the availableOption parameter */

PCI DSS Payment Scenario for 3D-Secure 1.0

Step 1

Form a POST request as described in Payment formation and send it to the address https://payment.webpay.by/api/v1/payment — for the production environment or to the address https://payment.webpay.by/api/v1/payment — for the sandbox environment.

Example Request

{
  "wsb_storeid":"123456789",
  "wsb_currency_id":"BYN",
  "wsb_version":2,
  "wsb_seed":"1242649174",
  "wsb_test":0,
  "wsb_invoice_item_name":["test"],
  "wsb_invoice_item_price":["0.1"],
  "wsb_invoice_item_quantity":["1"],
  "wsb_operation_type":"",
  "wsb_customer_id":"41432",
  "wsb_encrypted_data":"VYs5XZYA79BORvcPW4LbBM6x4B36lBnQskF7j61UVlsH4ENPrPCs1exkJdCF6fX9nyENvrC434w3tL6HBtY7mxFXFvMBbsNoDbF4OC4lJEPVSSoBASLZH/9M1hBtavKjjDyKWXsCd5HYihp6PRTs3rMtw9+6Dao8hyfucMxyGpzDU/fW7DZdZ1GY3RIRKXJgPOP/AWv1YORy22BtyNs461CKuyXVY5AdeLO7WmV2x9kxexKNncKO4o0voy9KjW/nYj7R1YCQAZ4k1G2ZuXku90+yeo/AVBCXVTOEejwfplw9dFARes6OtQcW10kQmTdMi9200bf3sY2lQ1UZSbNMRw==",
  "wsb_order_num":"ORDER-de35",
  "wsb_total":"0.1",
  "wsb_signature":"87943d79649e10970b23dfd41194e5a503292bba",
  "wsb_tax":"0",
  "wsb_shipping_name":"Shipping Cost",
  "wsb_shipping_price":"0",
  "wsb_discount_name":"Product Discount",
  "wsb_discount_price":"0",
  "wsb_email":"test@test.com",
  "wsb_phone":"",
  "wsb_return_url":"https://test.com/return",
  "wsb_cancel_return_url":"https://test.com/cancel",
  "wsb_notify_url":"https://test.com/",
  "wsb_3ds_payment_option":"auto",
  "*scart":""
}

After sending the request to the specified URL, WEBPAY will return the filled fields acsUrl, PaReq, TermUrl, MD.

Example Response

{
  "data":{
    "token":"92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c",
    "tokenName":"wt",
    "time":"",
    "orderNumber":"",
    "invoiceNumber":"",
    "transaction":"",
    "authorizationCode":"",
    "rrn":"",
    "trimPan":"",
    "payee":"",
    "amount":"",
    "currency":"",
    "responseCode":"",
    "responseText":"",
    "acsUrl":"https:\/\/ucas.npc.by:8443\/pareq\/194978586\/ceb25c48-69f4-4aec-a069-6f5a8f65cd0d\/",
    "PaReq":"eJxVUctSwkAQvPsVFB\/AvmBJqGEpNJZyMKBiWXpbNlOQkoSQhwa+3t0QBG\/dvTM9Oz0wqZNt5xvzIt6l4y7r0e5E3cBykyMGr2iqHBU8YVHoNXbiyFZ4xhdGeN5wIKX2GDNU+1x4EdWR56M0\/mAoqWZdBYvpC+4VtObKevc4kDO1rrnZ6LRUoM3+dhYqnzHOBJCWQoL5LFBccs6temKQ6gTVO64yfQDSEDC7Ki3zg7LtQM4EqnyrNmWZjQj5acp7K9vhVCCX0YvKocK61HGkwmDKPpP7fnjcfs2Dt2P48Fx\/LNf9eTAbA3EVEOkSFadcUMllh\/ERlSPhA2l00Ikbryijdo0ThsyNmF49XAtgE84xNQflC7vkHwOss12KtsLu9IchwsIQu8Dl23ePLj9T2mwY9RilnLsEG8GZxDYLPqSicXEEiGsh7XFIe1uL\/t38FyiprZE=",
    "MD":"92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c",
    "TermUrl":"https:\/\/payment.webpay.by\/?wt=48957735ca99cdb589ef07753ebaaef5=5255737a5a5539684b335a484f456c594b326b34537a6c59566c6c6e5233684d5a314a6b656b355159335934555734776447313662584e4555325645544459305430396c6545394b543152694c3273344d6b6b3454412c2c"
  }
}

Step 2

Next, to continue the session, you need to send the received parameters to the URL address contained in the response field acsUrl. The request is sent using the POST method with the header Content-Type: multipart/form-data, containing in the request body the fields PaReq, MD, TermUrl with the values from the response in step 1.

Please Note

Remove all backslashes\ from the value of the acsUrl field. Replace the value of the TermUrl field with your own URL address where you will process the response from acs.

Example Request

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://ucas.npc.by:8443/pareq/194978586/ceb25c48-69f4-4aec-a069-6f5a8f65cd0d/',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => array('PaReq' => 'eJxVUctSwkAQvPsVFB\\/AvmBJqGEpNJZyMKBiWXpbNlOQkoSQhwa+3t0QBG\\/dvTM9Oz0wqZNt5xvzIt6l4y7r0e5E3cBykyMGr2iqHBU8YVHoNXbiyFZ4xhdGeN5wIKX2GDNU+1x4EdWR56M0\\/mAoqWZdBYvpC+4VtObKevc4kDO1rrnZ6LRUoM3+dhYqnzHOBJCWQoL5LFBccs6temKQ6gTVO64yfQDSEDC7Ki3zg7LtQM4EqnyrNmWZjQj5acp7K9vhVCCX0YvKocK61HGkwmDKPpP7fnjcfs2Dt2P48Fx\\/LNf9eTAbA3EVEOkSFadcUMllh\\/ERlSPhA2l00Ikbryijdo0ThsyNmF49XAtgE84xNQflC7vkHwOss12KtsLu9IchwsIQu8Dl23ePLj9T2mwY9RilnLsEG8GZxDYLPqSicXEEiGsh7XFIe1uL\\/t38FyiprZE=','TermUrl' => 'https:\\/\\/payment.webpay.by\\/?wt=48957735ca99cdb589ef07753ebaaef5=5255737a5a5539684b335a484f456c594b326b34537a6c59566c6c6e5233684d5a314a6b656b355159335934555734776447313662584e4555325645544459305430396c6545394b543152694c3273344d6b6b3454412c2c','MD' => '92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c'),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: multipart/form-data'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

After sending the request, a form will appear where the payer must enter the 3D-Secure code received via SMS on the mobile phone number linked to their bank card.

After the payer enters the 3D-Secure SMS code and clicks the Confirm button, the parameters — token, PaRes, MD — necessary for restoring the session in WEBPAY will be sent to your URL address for processing the response from acs, which was specified earlier in the TermUrl field.

Example Response

{
  "token":"e801cb1e1b80685bb6fd81ec0617233b=5a6a6c596130xxxxxx5535545731764f586c49536e46795a47524c4e5568544b7a67724c32525461574e6f6446685a63334e514d47746f5931453051305a4c52566848546c424764xxxxxx4554a754e47704f5a772c2c",
  "PaRes":"eJxVUe1ugkAQfBXjA3gfSCtmvQSqrTTB2JbWyD88NoVUAQ9o5e17h1jtbmdvd2Z21kIU4U4f0PZKBQQYFXFnzjIktmQWRa3J1Y5FLB2XEo4BtVlRW5YCM64kAuUHcpmcZ5LSC WR89fiTGzObs",
  "MD":"d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=547159794b415849646e5242754b35545865694b5766726d62"
}

Step 3

You need to send a POST request to WEBPAY with the parameters received from acs in step 2.

To restore the session in WEBPAY, send a POST request to the address https://payment.webpay.by/api/v1/payment?wt={token} — for the production environment or to the address https://payment.webpay.by/api/v1/payment?wt={token} — for the sandbox environment, where:

token — the value of the token field received in the response from acs in step 2 (the MD parameter can also be passed instead of this parameter).

The request body must contain the parameters MD and PaRes, also received from acs in step 2.

Step 4

WEBPAY receives your request from step 3, processes it, sends it to processing, and returns a response to you in JSON format. Please note that the response comes from the WEBPAY service nested within data.

Example Response

{
  "data":{
    "token":"e801cb1e1b80685bb6fd81ec0617233b=5a6a6c596130xxxxxx5535545731764f586c49536e46795a47524c4e5568544b7a67724c32525461574e6f6446685a63334e514d47746f5931453051305a4c52566848546c424764xxxxxx4554a754e47704f5a772c2c",
    "tokenName":"wt",
    "time":"2023.06.26 13:25:58",
    "orderNumber":"ORDER-de35",
    "invoiceNumber":"796529012",
    "transaction":"608120887",
    "authorizationCode":"885415",
    "rrn":"001783883631",
    "trimPan":"512722xxxxxx8665",
    "payee":"\u041e\u041e\u041e \u00ab\u0412\u0415\u0411 \u041f\u042d\u0419\u00bb",
    "amount":"0.10",
    "currency":"BYN",
    "responseCode":"",
    "responseText":"",
    "acsUrl":""
  }
}

PCI DSS Payment Scenario for 3D-Secure 2.0

Step 1

To implement integration for conducting a PCI DSS payment via 3D-Secure 2.0, follow the instructions below:

Form a POST request as described in Payment formation.
Add the wsb_tds_notification_url field to the request, which should contain the value of the URL address to which the payer will be redirected after completing the 3D-Secure check and to which the parameters with the result of the 3D-Secure session will be returned.
Send the request to the address https://payment.webpay.by/api/v1/payment — for the production environment or to the address https://payment.webpay.by/api/v1/payment — for the sandbox environment.

Example Request

{
  "wsb_storeid":"123456789",
  "wsb_currency_id":"BYN",
  "wsb_version":2,
  "wsb_seed":"1242649174",
  "wsb_test":0,
  "wsb_invoice_item_name":["test"],
  "wsb_invoice_item_price":["0.1"],
  "wsb_invoice_item_quantity":["1"],
  "wsb_operation_type":"",
  "wsb_customer_id":"41432",
  "wsb_encrypted_data":"LxWN6haDcxu7K2prY2t4P7enfuejEsU7lbD2xvaa8lwQcLQAhchW8xvUXPZWPiYpWuMKtaC3emwALfw9wcB388Gj86Kh7pVSGyljckcFY69tSmvUrUCJYvpNIvYLcBALotXRQCZiijn+ryaXyS0Ymu8G6S6sahWH2UkIEsZJrmMdq2N5fy4sB6fFmDZCtJdCpZHgpCiK9GjX1gvwiB7pOu4vJEwxVmPdheeYsYQiruk+be9U+ENK0EqRA7rZQlrM80lOxw2j2dF2KZYeVbdo5BiYX11bcHNZcgfTbu2zGTQF6MRkV/VPjUuJ+hkMTYPl9XeUYLq8+fMk3QauP/+AXg==",
  "wsb_order_num":"ORDER-de35",
  "wsb_total":"0.1",
  "wsb_signature":"87943d79649e10970b23dfd41194e5a503292bba",
  "wsb_tax":"0",
  "wsb_shipping_name":"Shipping Cost",
  "wsb_shipping_price":"0",
  "wsb_discount_name":"Product Discount",
  "wsb_discount_price":"0",
  "wsb_email":"test@test.com",
  "wsb_phone":"",
  "wsb_return_url":"https://test.com/return",
  "wsb_cancel_return_url":"https://test.com/cancel",
  "wsb_notify_url":"https://test.com/",
  "wsb_3ds_payment_option":"auto",
  "*scart":"",
  "wsb_tds_notification_url":"https://companyname.com/test/"
}

After sending the request to the specified URL, WEBPAY will return the filled fields token, acsUrl, creq.

Please Note

When passing the 3D-Secure check via Frictionless flow (the 3D-Secure authentication process without the cardholder's participation. The issuing bank independently collects transaction data, including the device from which it is made, and assesses the possible level of fraud. If no threats are detected, payment confirmation happens unnoticed by the payer), the response from step 3 will be received for the request from step 1.

Example Response

{
  "data":{
    "token":"17efa805408c3d0496476f7ef66d5a8f=62554e714f44564b4d30524f4f553148526a527263466c775748687861545a765758466e53476833516d6f3353457458565564595345643157585242636e6c5056573956516e4275575652564e475a4564544a7753672c2c",
    "tokenName":"wt",
    "time":"",
    "orderNumber":"",
    "invoiceNumber":"",
    "transaction":"",
    "authorizationCode":"",
    "rrn":"",
    "trimPan":"",
    "payee":"",
    "amount":"",
    "currency":"",
    "responseCode":"",
    "responseText":"",
    "acsUrl": "https:\/\/emvacs.qiwi.com\/acs\/api\/3ds2\/creqbrw",
    "threeDSSessionData":"",
    "creq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhkYjQ3Njc4LTMxMGMtNDg1MS04MTA0LTEyYWFjZTVkY2M4ZSIsImFjc1RyYW5zSUQiOiJkODY4NjJkYi0zYWUwLTQ3ZjMtODdjYi02OTBlNmIxZTEzNjEiLCJkc1RyYW5zSUQiOiI2ODk5YzZmMy03N2JhLTRmNzAtYWY5NS0yNDkyZjQwNjZlMjQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0="
  }
}

Step 2

Next, to continue the session, you need to send the received parameters to the URL address contained in the response field acsUrl. The request is sent using the POST method with the header Content-Type: application/x-www-form-urlencoded, containing in the request body the field creq with the value from the response in step 1.

Please Note

Remove all backslashes \ from the value of the acsUrl field.

Example Request

POST /acs/api/3ds2/creqbrw HTTP/1.1
Host: emvacs.qiwi.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 327

creq=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhkYjQ3Njc4LTMxMGMtNDg1MS04MTA0LTEyYWFjZTVkY2M4ZSIsImFjc1RyYW5zSUQiOiJkODY4NjJkYi0zYWUwLTQ3ZjMtODdjYi02OTBlNmIxZTEzNjEiLCJkc1RyYW5zSUQiOiI2ODk5YzZmMy03N2JhLTRmNzAtYWY5NS0yNDkyZjQwNjZlMjQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0%3D

After sending the request, a form will appear where the payer must enter the 3D-Secure code received via SMS on the mobile phone number linked to their bank card.

After the payer enters the 3D-Secure SMS code and clicks the Confirm button, a redirect will occur to the URL address you specified in step 1 in the wsb_tds_notification_urlfield. Also, the parameters with the result of the 3D-Secure session, necessary for restoring the session in WEBPAY, will be sent to this URL.

Step 3

To restore the session in WEBPAY, send a POST request with the header Content-Type: application/x-www-form-urlencoded to the address https://payment.webpay.by?wt={token} — for the production environment or to the address https://securesandbox.webpay.by?wt={token} — for the sandbox environment, where:

token — the value of the token field received in the response from acs in step 2.

The request body must contain the parameters received from acs in step 2 (there may be several parameters, for example, CRes and threeDSSessionData).

Example Request

POST /?wt=92a2b7aefffcf9d7291e2a068bb0346c%3D526b5a5252557073596e497264314e4c56336c6c64475253556e4e7556474e3565574572596d523156545a48616d6377544752574f486432556d7830526e686155486c495a456f774d484e506432396a5557706859772c2c HTTP/1.1
Host: payment.webpay.by
Content-Type: application/x-www-form-urlencoded
Content-Length: 324

cres=ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiNjcyMDYxNmItYjJkNy00MjE2LTljM2EtNzcyNzZjN2Q0OWM3IiwKICAibWVzc2FnZVR5cGUiIDogIkNSZXMiLAogICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICJhY3NUcmFuc0lEIiA6ICJiYTA4NjMxZi0yZjRkLTQ2MDgtODU3Yi1jMGM5ZmVjYWQ5NDEiLAogICJjaGFsbGVuZ2VDb21wbGV0aW9uSW5kIiA6ICJZIiwKICAidHJhbnNTdGF0dXMiIDogIlkiCn0

WEBPAY receives your request, processes it, sends it to processing, and returns a response to you in JSON format.

Example Response

{
  "time": "2023.07.14 11:59:03",
  "orderNumber": "ORDER-d213e35",
  "orderNote": "",
  "invoiceNumber": "181060384",
  "transaction": "909062398",
  "authorizationCode": "KDNVSQ",
  "rrn": "319511005218",
  "trimPan": "220073xxxxxx8210",
  "payee": "ООО «ВЕБ ПЭЙ»",
  "customerName": "",
  "customerAddress": "",
  "serviceDate": "",
  "pdfUrl": "https://billing.webpay.by/?kjBNq4f1l1qbIoUeyp7Zpjo6yFeuB%2BPKpl6r1PEBFyzKalsJb84uIMYjM3lYKbn3s1pNEnXRZLqTRKSvomJUVHOd9lnQ3y0zleHOx4VN1ab%2FWQ%3D%3D",
  "language": "ru",
  "items": [
    {
      "name": "test",
      "quantity": 1,
      "price": "0.10",
      "totalAmount": "0.10",
      "commission": "0.00"
    }
  ],
  "amount": "0.10",
  "currency": "BYN"
}