Payments integration

Development of a payment module is performed on the client`s server side and anticipates creation of scripts or alterations to the source code of a refined web application.

Card payments

Methods of order formation

The WEBPAY system provides two ways of forming payment orders:

1. JSON API.
2. Creation of HTML page with a common HTML form.

Principle of formation of an order and payment for it

1. Formation of an order by creating a request using the JSON API or by creating an HTML page with a common HTML form. Fields required to perform payments should be filled (Payment form fields).
2. Switching over to the payment page of the WEBPAY system (https://securesandbox.webpay.by) to fill in card details (switchover is performed by POST method).
3. Input of card details.
4. Payment for an order.
5. Return to payment module HTML page (the WEBPAY system will send a notification (Payment notification).
6. Payment parameters verification.
7. Rendering of service (delivery of goods).

Formation of an order for payment

To pay for an order you should create a JSON API request or a HTML form with specific fields (fields values and descriptions are presented in the Payment form fields and redirect a customer to a payment page by POST method. Specify https://securesandbox.webpay.by for testing or https://payment.webpay.by for real transactions.

Payment form fields

Main payment form fields

Fields for formation of shopping cart

Additional fields

Parameters for regulating the payment session

There is a mechanism for regulating the time set for payment by the Internet resource. You can pass a parameter in the authorization request that will indicate the time from which the payment interval is calculated (by default, 20 minutes). You can pass the wsb_startsessdatetime parameter with a DateTime value (for example, 2013-03-19T17:34: 28+03: 00) or the wsb_startsesstimeparameter, which contains a value in the UnixTimestamp format (for example, 1396536107) in the authorization request. When passing two parameters, the priority is considered to be wsb_startsessdatetime.

For example, the transaction starts at 22.10.2020 16:33:01, the Internet resource wants the payment session to be valid for 7 minutes, so in the POST request you should pass the time 22.10.2020 16:20:01

Electronic signature of an order

Electronic signature is formed to prevent changes in a payment form and must be present in every order from. Any orders without electronic signature will not be processed by WEBPAY system.

To form an electronic signature you should set a value for "Secret key" field in your billing account settings (Secret key installation).

In every order form you should fill the following fields:

wsb_seed — random symbol sequence (you may use current time, e.g. Unix Timestamp);

wsb_signature — electronic signature itself. It must be formed according to the rules from the following fields:

• wsb_seed
• wsb_storeid
• wsb_order_num
• wsb_test
• wsb_currency_id
• wsb_total
• SecretKey

All fields must be combined in a single string. The order of combination must be preserved.

Depending on the protocol version (wsb_version) MD5 (if version is not specified) or SHA1 (for version 2) of combined string is calculated.

Payment for an order

After order fields formation and start of payment execution a customer must be redirected to the payment page of WEBPAY system (test or real) where he will be granted with ability to fill card details.

After successful payment customer should click the "Back to the site" button. In this case payment form will redirect him to URL specified in wsb_return_url field.

If some error occurs or customer clicks the "Back" button, he will be redirected to URL specified in wsb_cancel_return_url field. In each case there will be wsb_order_num values added to URL. If payment was successful there will be also transaction number value added to WEBPAY system.

Displaying the payment result on the Internet resource side

This functionality allows the Internet resource to display the result of the payment on its side. Immediately after the payment is made, the payer will be redirected to the URL specified by the Internet resource without displaying the payment result on the WEBPAY payment page.

In order for WEBPAY system to redirect the payer to the page of the Internet resource, you should add the following fields to the request to form an order for payment (HTML-form or JSON API):

1. wsb_redirect - takes value 1.
2. wsb_return_format - takes value json.

After the payer has paid for the order, WEBPAY system will redirect him to the URL specified by the Internet resource in the field wsb_return_url — in case of successful payment or wsb_cancel_return_url — in case of unsuccessful payment. WEBPAY system will also send the following parameters with the result of payment to the Internet resource in JSON format:

Payment notification

In case of successful payment when redirecting back to a website page (wsb_return_url value is used) the system sends a number of an order (wsb_order_num value) and transaction number (wsb_tid value) in GET request parameters.

Furthermore, the system will also notify a website about completed operation using wsb_notify_url URL (if specified in form field) or to "Notification URL", which can be set in the billing account settings "Settings" → "Company".

Notifications from the WEBPAY system are sent from the address: 178.163.225.84.

If an URL for notifications was specified in both form field (wsb_notify_url) and the billing account settings, than an address from wsb_notify_url will be used.

In case of notification website should answer with code 200 ("HTTP/1.0 200 OK"). In 30 days, if a website could not receive notification, the system will stop sending request.

It should be considered during development that notification about payment (wsb_notify_url) can be received as well as customer may return to a website page specified in (wsb_return_url) field.

Successful payment notification

There are two ways of receiving notifications about payments:

1. Standard POST request sent from WEBPAY to wsb_notify_url (used by default).
2. SOAP tool (may be enabled by request).

Standard POST request sent from WEBPAY to wsb_notify_url

After an successful payment WEBPAY system sends specifically formed POST request to URL specified in wsb_notify_url field. There is information about payment in that request. Website should check this information in accordance with order execution requirements and answer with code 200 ("HTTP/1.0 200 OK").

Request fields:

wsb_signature is a hex sequence and is a result of MD5 function execution. Text sequence created from combination of the following fields is used as an argument of that function:

• batch_timestamp
• currency_id
• amount
• payment_method
• order_id
• site_order_id
• transaction_id
• payment_type
• rrn
• card — added to the signature, depending on the selected scenario
• SecretKey

In case of necessity you can manually send subsequent notification. To do that go to "Payments" in the billing account setting, find transaction of interest and click the "Send notification" button.

SOAP tool

For SOAP tool (may be enabled by request) the WEBPAY system sends specially formed SOAP request with the Content-Type: text/xml header to URL specified in wsb_notify_url field. Notification structure is described in xsd scheme:

WsbSignature is a hex-sequence and is a result of MD5 function execution. Text sequence created from combination of the following fields is used as an argument of that function:

• batch_timestamp
• currency_id
• amount
• payment_method
• order_id
• site_order_id
• transaction_id
• payment_type
• rrn
• card
• SecretKey

Combination order must be preserved.

Example of a request in accordance with the scheme

The Internet resource must check the received information in accordance with the requirements of the order execution and respond to the request with the code 200.

Answer the code field`s value should be equal to 200 if notification was processed. If it is not equal to 200 than there will be recurrent notification sending. codeDescription value may be spontaneous.

In case of necessity you can manually send subsequent notification. To do that go to "Payments" in the billing account setting, find transaction of interest and click the "Send notification" button.

Payment verification

Before shipping goods (rendering a service) website must verify customer`s payment.

In order to verify a payment API billing command "get_transaction" (only for Internet acquiring) should be executed when returning to a website page specified in wsb_return_url field.

There is an example of code for API command execution below. It is crucial to consider that request must be sent to https://sandbox.webpay.by for test environment and to https://billing.webpay.by for real one.

<!-- API Request -->
$postdata = '*API=&API_XML_REQUEST='.urlencode('
  <?xml version="1.0" encoding="ISO-8859-1" ?>
    <wsb_api_request>
      <!-- Method name -->
      <command>get_transaction</command>
      <authorization>
        <!-- Login from the WEBPAY personal account -->
        <username>your_username</username>
        <!-- Password from the WEBPAY personal account, encrypted in MD5 -->
        <password>your_md5_password</password>
      </authorization>
      <fields>
        <!-- ID of the transaction that is being verified.
          The value comes in the notifier -->
        <transaction_id>123456789</transaction_id>
      </fields>
    </wsb_api_request>
');

$curl = curl_init ("https://sandbox.webpay.by");
curl_setopt ($curl, CURLOPT_HEADER, 0);
curl_setopt ($curl, CURLOPT_POST, 1);
curl_setopt ($curl, CURLOPT_POSTFIELDS, $postdata);
curl_setopt ($curl, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt ($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt ($curl, CURLOPT_SSL_VERIFYHOST, 0);
$response = curl_exec ($curl); curl_close ($curl);
echo $response;

The request results in an XML document containing the following fields:

wsb_signature is a hex sequence and is a result of MD5 function execution. Text sequence created combination of the following fields is used as an argument of that function:

• transaction_id
• batch_timestamp
• currency_id
• amount
• payment_method
• payment_type
• order_id
• rrn
• SecretKey

Combination order must be preserved.

Transaction types

There are following transaction groups by transaction type (поле payment_type field):

These are types for successful payments:

And these are types for refunded payments:

You should also pay attention that there are different minimum and maximum transaction amounts for test and real environments. Minimal amount is 0.1 BYN and maximum is 10000 BYN for test environment, while limits for real environment depend on terms of contract with acquiring bank.

Simplified payment

Description of the work process

Simplified payment is a method of payment with bank card without need for input of all card details to fill in customer`s information when paying to the same service/goods provider. Complete card details are only required for the first time to initiate service binding to that card. In order to make simplified payments possible you should contact WEBPAY technical support support@webpay.by and make some adjustments to interaction scenario between service provider and WEBPAY program complex. This option will make payments more convenient for customers which will increase appeal of a website.

Here by customer stands for a cardholder that passed authorization on a seller`s website. Authorization is crucial here because it allows to associate that person with some unique number.

Card binding is performed on WEBPAY program complex side. Customer data (card number mask, cardholder`s name, expiration date, email and phone number) are stored in relation to customer`s number. New card can be bound by customer in one click after first successful payment to a service provider.

Activated "Simplified payment" feature will help to avoid needless input of information. Customer can just choose a card from a list only need to enter CVV/CVC.

Payments execution

In order to implement "Simplified payments" service provider just needs to make minimal adjustments to JSON API request or to HTML form of order Formation of an order for payment. Please note that payments in test environment are always executed with one automatically chosen card. In order to be able to add various cards and bind them you have to set wsb_test parameter to 0.

One new field is also added — wsb_customer_id — contains unique number of registered on the service provider`s side customer (with maximum field length of 64 symbols).

This parameter must participate in order`s electronic signature formation. This way order`s signature calculation algorithm is changed and wsb_signature electronic signature must be formed according to the rules from the following fields:

• wsb_seed
• wsb_storeid
• wsb_customer_id
• wsb_order_num
• wsb_test
• wsb_currency_id
• wsb_total
• SecretKey

All fields must be combined in a single string. The order of combination must be preserved. Depending on the protocol version (wsb_version) MD5 (if version is not specified) or SHA1 (for version 2) of combined string is calculated.

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="The name of your Store">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Goods 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Goods 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="20.90">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="7bba5020b4033e9086e5f4240a24163dc0d4562b">
  <input type="hidden" name="wsb_shipping_name" value="Shipping costs">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Discount">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_customer_id" value="1234567">
  <input type="submit" value="Buy">
</form>

Recurring payment

Description

There are two ways in the WEBPAY system to make a payment without participation of the Cardholder:

1. Recurring payments — these are payments with a certain frequency made at the Store request without participation of the Cardholder: whether at certain events or on a regular basis. A specially formed request that is sent to the resource of payment service acts as a requirement of the Store.
2. Credential on File (CoF) — these are payments made on a bound card, in which the frequency of debits is not observed. The initiator of such charges may be:
   • Store,
   • Cardholder.

Before processing recurring (CoF) payments it is essential to make an initiating payment serving as a contract with participation of the Cardholder, and input all data of the card in accordance with the standard scenario. Further processing of recurring (CoF) payments occurs without participation of the Cardholder or transmitting CVV/CVC. The initiating payment supports 3D-Secure (3DS). Recurrent (CoF) payments do not have the ability to provide support for 3DS.

The amount of recurring (CoF) payment may be non-equal to the initiating payment amount. The transaction type settings are made on the WEBPAY side depending on business process of the Store.

Recurring (Credential on File) payments usage scenario

Cardholder performs a transition from the Store`s website via POST request to the payment provider`s resource. After that the Cardholder is offered to enter his bank card details and additional parameters. And next he performs the standard payment scenario as well as, if necessary, passing 3DS.

In case of successful payment completion the service binds the card to the Store`s Cardholder identified by the described below method.

After the payment is complete it is possible to move to the Store`s resource — to one of the URLs specified by the Store (in case of successful (parameter wsb_return_url) or unsuccessful (parameter wsb_cancel_return_url) payment completion). Additional notification is sent to one more URL (parameter wsb_notify_url). Notification with a message about result of initiating payment contains the user ID, the masked card number and expiration date for the subscription on the recurring (CoF) payments mechanism.

With a successful initiating payment the Store can perform recurring (CoF) payments.

Cardholder ID, card binding options

Cardholder must be registered on the Store website. The Store assigns him an unique identifier that is transmitted in payment requests as a parameter wsb_сustomer_id. This ID for the current Store (wsb_storeid) will be bound to the card.

Fields of the payment form for recurrent payments

The WEBPAY system provides two ways of forming payment orders:

1. JSON API.
2. Creation of HTML page with a common HTML form.

When working with an HTML form, a description of the main fields for making a POST request, see the section Payment form fields.

To specify the use of recurrent (CoF) payments in the authorization request, you must additionally use the following fields.

Payment services URLs for requests

In order to perform recurring (CoF) inquiries use https://securesandbox.webpay.by for test environment and https://payment.webpay.by for real payments.

Initiating payment

In order to execute initiating payment you can use JSON API or create a form with special fields which are described in the table Payment form fields and Additional fields. Then to redirect a customer to payment service page by POST method.

In order to be able to add various cards and bind them you have to set wsb_test parameter to 0.

To prevent unsanctioned alterations there must be an order electronic signature — wsb_signature parameter. Attempts to make payments without an electronic signature will not be considered by the payment system.

Signature is calculated in accordance with the following algorithm:

1. All fields must be combined in a single string. The order of combination must be preserved:
   • wsb_seed
   • wsb_storeid
   • wsb_customer_id
   • wsb_order_num
   • wsb_test
   • wsb_currency_id
   • wsb_total
   • wsb_operation_type
   • SecretKey
2. Depending on the protocol version (wsb_version) MD5 (if version is not specified) or SHA1 (for version 2) of combined string is calculated.

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="The name of your Store">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Goods 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Goods 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="20.90">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="ebefd130602a41f95238b5bd5cd1f3f803456093">
  <input type="hidden" name="wsb_shipping_name" value="Shipping costs">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Discount">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <input type="hidden" name="wsb_customer_id" value="aA1217Zz">
  <input type="hidden" name="wsb_operation_type" value="recurring_bind">
  <input type="submit" value="Buy">
</form>

Notification after initiating the payment

After successful payment the payer will receive an email with a bill and a message about subscription. Notification is sent to the Store in form of specifically formed POST request:

The field wsb_signature formed according to the following rule. All fields must be combined in a single string. The order of combination must be preserved:

• batch_timestamp
• currency_id
• amount
• payment_method
• order_id
• site_order_id
• transaction_id
• payment_type
• rrn
• card
• customer_id
• operation_type
• recurring_token
• offer_exp_date
• SecretKey

MD5 of the string is calculated by default.

Recurring payment (Credential on File)

When working with the JSON API, use the following request.

When working with the HTML form, the following changes are made regarding the initial payment:

Parameter wsb_recurring_token is included to a signature after wsb_operation_type:

• wsb_seed
• wsb_storeid
• wsb_customer_id
• wsb_order_num
• wsb_test
• wsb_currency_id
• wsb_total
• wsb_operation_type
• wsb_recurring_token
• SecretKey

When getting a request for payment for an order WEBPAY system checks validity of recurring (CoF) payment. If validity is expired, payment will not be competed. If validity is not expired, payment goes without payment page for this particular user.

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="The name oа your Store">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Goods 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Goods 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="20.90">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="d1a5110dc27d38a5fed50f98def59029ed5e1564">
  <input type="hidden" name="wsb_shipping_name" value="Shipping costs">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="discount">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <input type="hidden" name="wsb_customer_id" value="aA1217Zz">
  <input type="hidden" name="wsb_operation_type" value="recurring_pay">
  <input type="hidden" name="wsb_recurring_token" value="123456789">
  <input type="submit" value="Купить">
</form>

Notification after recurring payment

After successful payment Store receives notification with the same field that were described in the previous chapter with some exceptions. Request will not include offer_exp_date field and this filed is not included into combination for signature calculation.

The Store also receives a notification in response to a request to pay a recurring payment.

// Response about a successful recurring payment

Content-Type: application/x-www-form-urlencoded
batch_timestamp=1586712564&currency_id=BYN&amount=15&payment_method=cc&order_id=294088281&site_order_id=ORDER-15&transaction_id=650449721&
payment_type=10&rrn=210476022664&wsb_signature=66e6be413ea2d8638174e3b69f1ffd32&action=0&rc=W0001%2800%29&approval=210476&
rc_text=Операция завершена успешно&card=516052xxxxxx9495&customer_id=test_1&operation_type=recurring_pay&recurring_token=650449721

// Response to a recurring payment error

Content-Type: application/x-www-form-urlencoded
batch_timestamp=1586714748&currency_id=BYN&amount=35&payment_method=cc&order_id=0&site_order_id=ORDER-16&transaction_id=0&payment_type=2&
rrn=&wsb_signature=25ac063bbf766c4401858439f3fbd61c&action=4&rc=W0319&approval=&rc_text=Ошибка&card=516052xxxxxx9495&customer_id=test_1&
operation_type=recurring_bind&recurring_token=0&offer_exp_date=2022-10-31

Card unbinding from recurring (Credential on File) payments

To unbind the card from recurrent (CoF) payments using the JSON API, use the following request.

When working with an HTML form, the request to unbind the card from recurrent (CoF) payments must consist of the following set of fields:

• wsb_version
• wsb_seed
• wsb_storeid
• wsb_customer_id
• wsb_operation_type
• wsb_recurring_token
• wsb_signature

Parameter wsb_signature calculated by combining the following fields into a single string:

• wsb_seed
• wsb_storeid
• wsb_customer_id
• wsb_operation_type
• wsb_recurring_token
• SecretKey

The order of combination must be preserved. Depending on the protocol version (wsb_version) MD5 (if version is not specified) or SHA1 (for version 2) of combined string is calculated.

<!DOCTYPE html>
  <html>
    <head>
      <title></title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    </head>
    <?php
      $secret_key = 'jPwe3d5nmN';
      $wsb_storeid = '507990464';
      $wsb_seed = time();
      $wsb_customer_id = '111333';
      $operation_type = 'recurring_unbind';
      $wsb_recurring_token = 904928145;
      $wsb_signature = sha1($wsb_seed.$wsb_storeid.$wsb_customer_id.$operation_type.$wsb_recurring_token.$secret_key);
    ?>
    <body>
      <form action="http://securesandbox.webpay.by" method="post" target="_blanc">
        <input type="hidden" name="*scart">
        <input type="hidden" name="wsb_version" value="2" />
        <input type="hidden" name="wsb_seed" value="<?=$wsb_seed?>">
        <input type="hidden" name="wsb_storeid" value="<?=$wsb_storeid?>">
        <input type="hidden" name="wsb_customer_id" value="<?= $wsb_customer_id ?>">
        <input type="hidden" name="wsb_operation_type" value="<?= $operation_type ?>">
        <input type="hidden" name="wsb_recurring_token" value="<?= $wsb_recurring_token ?>">
        <input type="hidden" name="wsb_signature" value="<?= $wsb_signature ?>">
        <input type="submit" value="Unsubscribe from recurring payments">
      </form>
      </body>
  </html>

Notification after unbinding card from the recurrent payments

For each unbinding request WEBPAY sends a positive or negative answer.

// Example of an answer about successful unbinding

Content-Type: application/json; charset=utf-8
{"batch_timestamp":1586734397,"customer_id":"test_1","operation_type":"recurring_unbind","recurring_token":"606799416","rc":"0",
"rc_text":"Operation success"}

// Error answer example

Content-Type: application/json; charset=utf-8
{"batch_timestamp":1586734514,"customer_id":"test_12","operation_type":"recurring_unbind","recurring_token":"606799416","rc":"1018",
"rc_text":"Operation failed"}

Complete or partial refund

After successful card binding or recurring (CoF) payment via WEBPAY system, transaction gets the following status depending on acquiring bank:

In case when it is required to execute complete or partial refund you should use API (See: Managing operations). In advance you should send an inquiry to WEBPAY support to support@webpay.by specifying IP address that will be used to send requests. Depending on acquiring bank and transaction type there will be different API requests for void/refund.

Installment cards

Payments with "PriorBank" JSC cards and "MTBank" CJSC (Halva) with installment plans

In order to make payments with "PriorBank" JSC cards and "MTBank" CJSC (Halva) with installment plans it is enough to form JSON API request or standard authorization request (HTML form) in accordance with Formation of an order for payment.

Goods paid for with "PriorBank" JSC cards and "MTBank" CJSC (Halva) cards with installment plans are a subject to specific installment plan type. Service provider may have a few different types of installment plans (1 month, 3 month etc.). There is a specific terminal number for service providers in "PriorBank" JSC cards and "MTBank" CJSC (Halva) for each installment plan type. Which installment plan to use is determined on the service provider`s side. Let us assume that there are two active installment plan types:

To specify the type of installment plan in the authorization request you have to additionally send wsb_terminal parameter, which should contain terminal number in accordance with the installment plan type. This value is passed by the acquiring bank to the Store when the agreement is concluded. For example, for an order with 3-month installment plan.

Present parameter should be involved in the order`s signature formation. This way, when specifying installment plan type in the authorization request, changes the order`s signature calculation algorithm. Electronic signature wsb_signature should be formed in accordance with the following rule from values of the following fields:

• wsb_seed
• wsb_storeid
• wsb_order_num
• wsb_test
• wsb_currency_id
• wsb_total
• wsb_terminal
• SecretKey

All fields must be combined in a single string. The order of combination must be preserved. Depending on the protocol version (wsb_version) MD5 (if version is not specified) or SHA1 (for version 2) of combined string is calculated.

Features of working with "PriorBank" JSC installment cards

The payment scenario will start after sending the request. In this scenario only the "PriorBank" JSC installment card is allowed to be entered for payment. When working with only one installment plan type, the Store doesn`t need to pass the wsb_terminal field.

Features of working with "MTBank" CJSC (Halva) installment cards

The payment scenario will start after sending the request. In this scenario only the "MTBank" CJSC (Halva or X-card where the Halva installment card is binding to) installment card is allowed to be entered for payment. When working with only one installment plan type, the Store doesn`t need to pass the wsb_terminal field. The WEBPAY system will determine the card entered by the payer and based on it, the payment will be made at the appropriate terminal.

If the Store is enabled to accept payments by installment cards of "MTBank" CJSC (Halva), a page with a block of information for payment will be displayed.

When the customer enters X-card (the product of "MTBank" CJSC) and click the "Pay" button, the payer will be offered a choice of payment methods available for this product.

Payments with Halva Plus card

To make payments with Halva Plus card it is enough to form standard authorization request in accordance with Formation of an order for payment. When filling in Halva Plus card details and with allowance to pay with accumulated bonuses customer will see a separate page with payment type choice. On this page he will be able to choose the way he wants to pay for an order.

If payment with accumulated bonuses is not allowed, a separate page with payment type choice will not be shown and payment will be automatically made with BYN charged from Halva Plus card

Apple Pay Payments

Description

Apple Pay is a payment method for paying for goods and services using cards stored in Apple devices. Users are authenticated using Face ID, Touch ID, or password when using Apple Pay, and payments are made using tokenized card data.

Advantages of Apple Pay technology in comparison with card operations:

• customer convenience — all card details are already stored in the Apple device and the user just needs to select a card from the list to start the payment process;
• increased conversion — the authentication of the payment is carried out by the face or the fingerprint. The user does not need to wait and enter the sms password. This reduces the risk of payment errors and customer refusal to pay, and increases the conversion rate.

Apple Pay support on devices

Apple Pay payment technology is supported on devices:

• iPhone — iPhone models with Face ID feature, Touch ID (except the iPhone 5s);
• iPad — iPad Pro, iPad Air, iPad and iPad mini models with Touch ID or Face ID;
• Apple Watch — Apple Watch Series 1 and Apple Watch Series 2, and later models;
• Mac — Mac models with Touch ID.

Payment execution

The user has an additional button "Pay Apple Pay" on the payment page when using the device that support Apple Pay technology.

When the user click the button, the payment process starts using the saved card on the device. It is also possible to enter the card number for payment without using Apple Pay technology.

Activation

There is no additional actions are required on the store`s side to enable Apple Pay payment technology. The WEBPAY system automatically connect the Apple Pay to all of our customers. If the Apple Pay button does not appear on the payment page of your store this may be due to the following reasons:

• the acquiring bank does not yet support Apple Pay payments;
• you receive donations;
• you sell goods or services that are not allowed to be sold through Apple Pay (cigarettes, weapons, cryptocurrencies, etc);
• your store has been found to be violating the Apple Pay terms of use.

You can contact your WEBPAY manager to solve your issue or to activate Apple Pay payments for your store with necessary steps.

Promo code for the VISA and MASTERCARD discount program usage

VISA/MASTERCARD discount program description

This mechanics is meant to be used with payments execution for service provider`s orders, which is a member of VISA/MASTERCARD discount program. This program involves discount if the payment is made with any VISA/MASTERCARD cards. You can also participate in VISA discount programs if the payment is made with one of the premium card types. If customer wants to use one of the VISA premium cards on the service provider`s side, WEBPAY controls the payment to be made with the specified card type.

The mechanism of working with a VISA and MASTERCARD promo code description:

1. The customer wants to use one of the any VISA/MASTERCARD card or VISA premium card on the service provider`s side, WEBPAY controls the payment to be made with the specified card type or specified type of the VISA premium card.
2. In accordance with specified premium card type service provider assigns values for discount and promo code. Discount amount is sent in wsb_discount_price (see: Fields for formation of shopping cart) field and must be considered in the order`s total price. It is also possible to send a discount description text in wsb_discount_name field. When working with the JSON API, use the following request.
3. If the promo code value is passed and the service provider participates in the VISA or MASTERCARD discount program, the WEBPAY system checks the payer`s card for compliance with the promo code. If a difference is found, the payment is prohibited.

The values of possible promo codes for VISA/MASTERCARD cards that are passed in the wsb_discount_promo_code field are shown in the table below:

The values of possible promo codes for VISA premium cards that are passed in the wsb_discount_promo_code field are shown in the table below:

For example, if you choose to pay with a premium VISA Gold card, the authorization request will look like this.

The register of symbols of the promo code does not matter in this case. If you are allowed to make a payment without selecting the card type, the wsb_discount_promo_code field can be omitted or left empty.

Testing out VISA/MASTERCARD discount program

The process of test payment request execution is similar to the JSON API or the one described in Formation of an order for payment apart from minor changes:

1. You must contact WEBPAY technical support support@webpay.by to enable your account to work under the VISA/MASTERCARD discount program.
2. You need to send wsb_test parameter with 0 values to make different card numbers input available.
3. You can use any numbers with 16 characters for VISA or MASTERCARD cards. You can generate such numbers with some help from http://www.getcreditcardnumbers.com. When generating premium card numbers, use the following first 6 digits of the card (BIN card):

Visa Offers Platform

To enable the possibility of working with the Visa Offers Platform (VSP) system, you need to contact WEBPAY technical support support@webpay.by.

Technical documentation on integration with the VOIP system can be found here.

Operations through the AIS "Raschet" (ERIP)

Payment execution scenario through AIS "Raschet" (ERIP)

To perform a payment with ability to pay for purchase through AIS "Raschet" (ERIP) it is necessary to form JSON API request or a standard authorization request (Formation of an order for payment). For test environment, please, use this address https://securesandbox.webpay.by, and for making real payments this: https://payment.webpay.by.

If you need to create an invoice with ability to pay for purchase until a certain date, you need to pass the wsb_due_date field in authorization request. The value of this field must contain a timestamp in the Unix Timestamp format, until which the invoice will be available for payment.

After finishing the request a page with payment details will be displayed.

If the client is connected to receive payments for orders only through AIS "Raschet" (ERIP), a page with payment information block will be displayed.

If the client has an ability to pay for purchase not only through ERIP, but also by using a bank card, then payment page will show additional info block to enter card details.

You can also define an active tab with a payment instrument (card Payment / Payment through ERIP). When passing the wsb_tab field with the value erip in the POST request, the active tab will be "Payment through ERIP".

The payer has an ability to save order info to perform a payment later. To do this he needs to click the "Pay later" button. As a result, order information will be sent to the specified email.

Here are examples of emails with order details that will be sent to the payer.

If the client have set up an ability to receive payments only through AIS "Raschet" (ERIP).

If the client have set up an ability to pay for purchases with a bank card or through AIS "Raschet" (ERIP).

Payment notification

If you make a payment through AIS "Raschet" (ERIP), the WEBPAY system notifies the Internet resource about performed operation by the wsb_notify_url (if it is specified in the form`s field or in the billing account settings). The transmitted fields are similar to those described in Standard POST request sent from WEBPAY to wsb_notify_url but with some exceptions. So, the payment_method field will contain the erip value. If the Internet-resource receives notification, it must reply with the 200 ("HTTP/1.0 200 OK"). The requests transmission will be ended after 30 days if the Internet-resource has eventually failed to accept notification.

Invoicing via FTP in AIS "Raschet" (ERIP)

Format of the uploadable file to the FTP-server (файл *.bill):

1. Billing account ID;
2. Invoice number;
3. Amount;
4. Commodity/service name;
5. Invoice expiration date (dd.MM.yyyy HH:mm:ss);
6. Late fee — not required;
7. Full name — not required;

File name: id billing-account_date+time.bill.

Example: 1234567_250817125700.bill

Example of a uploadable file:

123456789;789-Test;123.56;Goods 1;01.12.2017 16:51:29;1.86;Ivanov Ivan

123456789;789-Test;123.56;Goods 1;01.12.2017 16:51:29;; — a file example in case of some of the required fields are not filled.

After the invoicing a corresponding notification will come to the Store`s email:

1. Successful invoicing
2. Ошибочное

FTP setup

Parameters of WEBPAY FTP:

User name: merchant

Host name (Port) for test environment: erip-ftp-test.webpay.by (port 2100)

Host name (Port) for real environment: erip-ftp.webpay.by (port 21)

Password (the same regardless of the environment used): YJmsJs4TpveX

An example of filling in the parameters in Total Commander:

Payment of ERIP invoices for an arbitrary amount

It is possible to accept payments for services on one personal account an unlimited number of times when working through the ERIP and until the expiration date of the previously created account. This method of accepting payments is suitable for those organizations that, for example, have a contract with the buyer and the payment will be made in parts under the same contract for different amounts. Another example is the payment of a monthly subscription fee or the balance replenishment for next calculations under one contract.

To activate this functionality, it is necessary to provide for such a scenario when concluding a contract with the ERIP.

Additional technical settings of the WEBPAY service are not required except for the following actions:

• you need to create an invoice in your WEBPAY personal account (Invoice creation from personal cabinet WEBPAY) for a certain/undefined buyer or via the API (Creating an invoice) with zero amount to pay with the permission to pay the invoice unlimited number of times;
• the buyer will be able to enter the amount for payment independently when making a payment.

API for creating an invoice without moving to the payment page

Description of the order creation mechanism

You should contact WEBPAY technical support at support@webpay.by to enable this functionality.

The service is used for invoices creation to pay in the WEBPAY system by API. Request is sent using POST method to URL-address: https://sand-box.webpay.by/woc/order for test creation of the invoice, or to URL-address https://api.webpay.by/woc/order for real creation of the invoice. Each request must be signed by the Hmac algorithm which description is presented later in the second section.

Description of the request parameters and its example

For example, let`s examine a request which is formed in JSON format.

Description of the response parameters

Response of the WEBPAY system upon successful order creation.

WEBPAY response to an error, for example:

Hmac signature generation mechanism

To fulfill an invoice creation request you must add a signature to the request using the Hmac algorithm. The signature is formed as follows — the Authorization http-header is added to the request. It has the following form:

Where:

• HmacSHA512 — signature algorithm,
• apiKey — Store`s resource ID number,
• nonce — randomly generated string,
• digest — Hmac signature.

The following http-request fields are used in the signature:

• METHOD\n
• RESOURCE\n
• QUERY_STRING\n
• CONTENT_TYPE\n
• APIKEY\n
• NONCE\n
• PAYLOAD\n

Fields description