Basic information

Present guide describes development process of a payment module for payments receipt on the Internet using WEBPAY system and test environment (Sandbox) usage to test out a module during development.

Development procedure

  1. Take a close look at present guide.
  2. Open the web test environment application for modules in development at the following URL: https://sandbox.webpay.by, using parameters received in the letter from your personal WEBPAY manager.
  3. Get familiar with Sandbox interface and fill in required fields (Company profile).
  4. Proceed with payment module development in accordance with present guide.
  5. Test out your module.
  6. Receive a letter with new parameters for payment module transition from test environment into real payment system (Transition from test into real environment).
  7. Make alterations to your payment module.

Web application interface

Web application interfaces of Sandbox test system and real system are equal. Pay attention to URL of the current environment in your browser (https://sandbox.webpay.by for test environment and https://billing.webpay.by for real one). Before development starts we recommend to launch the web application and get familiar with its content (Personal Cabinet).

Application home page

The following page will be shown when opening the web application:

Main screen of the app

There is main statistics about your billing account shown on this page. Here you can also form statistics for specific period of time. There is navigation panel of the left which provides you control over your account as well as required information on past transactions.

Secret key installation

Secret key is required to form electronic signature of your every payment (Electronic signature of an order). This parameter is required to be filled in and it is impossible to execute transactions without it. To install a key you should fill the SecretKey field. To do that you should go to "Settings" → "Company". This field may contain random symbol sequence except for the sign &.

Setting the secret key

Financial operations overview

Use "Payments" option in the menu to view all financial operations. This page contains all financial operations (transactions) with cards processed online.

Viewing payments

Each transaction is linked to invoice (account). Invoice may be of three types of transactions, such as:

  • Authorized — payment is in state of authorization (funds on the payer`s card are frozen). In this state payer`s account was not yet debited (fund are just frozen) and money was not yet credited to your bank account.
  • Completed — card was charged with the required amount and money will be transferred to your bank account in time period specified by acquiring bank.
  • System — system transaction.

There is a number in the "Account ID" field to which all transactions are linked. To view all transactions linked to this number as well as all parameters of a payment you should click the link. As a result you will be redirected to a page with information about this invoice.

Information about the payment

Login into WEBPAY Personal Cabinet

Access to the Personal Cabinet is performing by an internet browser using protected communication channel.

To access the WEBPAY Personal Cabinet you must enter one of the following addresses:

https://billing.webpay.by — for real environment;

https://sandbox.webpay.by — for test environment.

In the opened window you must type in login and password provided by your personal manager from WEBPAY company.

Log in to your WEBPAY account

Important!

Pay attention that your connections must be protected, so necessarily use "https" protocol instead of "http".

In case of successful authorization you`ll be directed to the monitoring panel page. Monitoring panel is conditionally split into five blocks:

  • block of statistics forming for the date interval — manages statistics display for the selected date interval;
  • invoices statistics block — this block displays information about invoices that have already been paid, are waiting to be paid, or have expired and also about total number of invoices. Moreover, you can quickly translate from this block to the Invoices section by pressing the "Invoices" button and create a new invoice by pressing the "New Invoice" button;
  • exchange rates block;
  • payment statistics block — displays a balance for selected period of time and located here button allows you to quickly translate to the payment section. The "Current Account Balance" field displays the total amount of Completed Payments and Recurrent Payments, minus the amount of Refunds;
  • payment methods statistics block — displays the percentage of statistics on the fraction of bank cards.

On the left side of the screen there is a hiding menu, from which you can translate to the "Invoices", "Payments", "Payments log", "Reports" and "Settings" sections.

The dashboard

Filling parameters of WEBPAY Personal Cabinet ("Company")

Before getting started you should check the main settings of your billing account. To do that, go to the menu entry "Settings" → "Company". In this section you can change information about your organization (address, city, postal code, contact phone number). Also in this section you can make the following changes:

  • input the "Secret Key" (this entity is REQUERED in case of integration with the site. Skip to section Integration);
  • input "Notification URL", which will be using by the system to send you specifically formed queries with payment details;
  • change system language (it uses Russian by default);
  • set time and date format;
  • set the fractional part (number of decimal places for prices in EUR, USD and RUB currencies).

To change the other data (company name, company website, legal body name) you`ll have to contact your personal WEBPAY manager.

WEBPAY Personal Account Parameters

Accounts creation ("Users")

Open your personal cabinet and proceed to "Settings" → "Users". Here you can add, remove and manage user accounts of your company which have access to WEBPAY.

Accounts

To create a new user, click on the "Add User" button in the "Settings" → "Users" menu.

Adding an account

You will need to specify the following fields in the popped-up form:

  • username (login from 4 to 12 Latin letters),
  • first name,
  • last name,
  • phone,
  • email,
  • country,
  • state,
  • ZIP code,
  • city,
  • address,
  • password,
  • password confirmation.

In the "Groups" list you should also specify the rights for account owner:

  • administrator,
  • buyer,
  • system account,
  • guest.

If you want to allow the new account to create invoices and users and edit their data, you need to select "Billing Account" from the pop-up list.

Creating a new account
  • leave "Yes" in the "Multi login",
  • choose "No" in the "Active" field if you plan to make that account active later. Otherwise choose "Yes".

Press "Save" button to finish account creation.

You also have an ability to create accounts for your standing customers. To do this you need to select "Consumer Account" from the pop-up list. Then you`ll be able to make an invoice to that customer by selecting him from the list.

In the "Users" menu you can always check already created accounts or edit them. To edit an account you need to select one and then press "Edit user" button, which locates in the top right corner of the screen.

Filling in your account details

Payment information viewing

In the "Payments" menu you can view all payments received for the benefit of your company and paid by credit card online.

  • transaction ID — a unique transaction number (if transaction ID is specified, the transaction has been completed successfully),
  • invoice ID,
  • payment method,
  • sum,
  • 3DS — if payer`s card participates in 3D-Secure procedure this field should contain "Yes",
  • payer,
  • processing gateway,
  • status,
  • batch date.
Payment information

For the convenience of searching and working with information in the "Payments" and "Payments log" menu you can search for payments according to the interested parameters. To do this, use the window at the top of the list. You can expand the window to get advanced search options. By default, we recommend to sort payments by payment date. You can search by the following parameters:

  • specify a time interval for searching;
  • specify the RRN (unique transaction number assigned by the processing center);
  • specify the email, tied to the transaction;
  • specify the invoice ID;
  • specify the transaction ID;
  • specify the card number;
  • specify the transaction status.
Advanced search according to parameters

In the "Invoices" menu you can view all invoices filed by your company, including already paid one. The following information is available in the list:

  • creation date — a date when the invoice was filed;
  • invoice ID — a unique invoice ID;
  • invoice name — an invoice name in the WEBPAY system;
  • invoice PO — a name, you have specified when filed the invoice;
  • buyer — a buyer for which the invoice is issued;
  • payment method — a method that was used to meet the invoice (Internet-acquiring or ERIP);
  • order amount and currency — total amount and currency of the invoice;
  • due date — a date until which the invoice can be paid;
  • payment status.
Information about issued invoices

Additional information will be shown after clicking an invoice:

Additional information about issued invoices

Payments log

All payment attempts made by bank card, including unsuccessful ones, are displayed in the "Payments log" menu with textual information about the operation result. The list contains the following information:

  • ID — request ID in the WEBPAY system;
  • transaction ID — a unique transaction number (if transaction ID is specified, the transaction has been completed successfully);
  • creation date;
  • batch date;
  • payment method;
  • type — payment system of the bank card;
  • payment instrument — partially covered bank card number;
  • response code — processing center response code;
  • response text — decryption of the processing center response;
  • account ID;
  • 3DS — is specified as "Yes" if the payer`s card participates in the 3D-Secure procedure.
Payments log

After clicking the "Transaction ID" field the "Transaction log" windows will be opened. You can also find a link to the receipt that the payer received after successful payment.

Журнал операций по платежу

Accounting for completed payments

To get a report about payment made through AIS "Raschet" (ERIP) and/or Internet-acquiring, as well as the reconciliation results of the received funds, you need to go to the reporting system: https://merchant-sandbox.webpay.by for the test environment or https://merchant.webpay.by for the real environment. Use the same Login and Password as you use to access your Personal WEBPAY Cabinet.

You can export reports from the cabinet to MS Excel. Also you can receive reports to your email in .xlsx files or in JSON format without entering the system. Please, get acquainted with API for receiving reports to learn how to activate that feature.

Log in to the reporting system

Accounting for transactions made through AIS "Raschet" (ERIP)

Select "ERIP" → "Payment results" the menu entity. A report with the order payment results and information about funds transferring will show up. Record in the report appears immediately after payment. Later, upon the formation of the AIS "Raschet" registries, the reports will be supplemented with information about funds transfer. The reconciliation performs automatically, and then gets a successful or unsuccessful status.

Report ERIP → Payment results
Report fields description
Name Description
Payment status

Payment processing result. Possible values:

Successful payment — the WEBPAY system did confirm the payment success;

Payment error — the WEBPAY system did NOT confirm the payment success;

NOT confirmed by WEBPAY — ERIP reconciliation report contains information about a non-existent operation.

Reconciliation status

WEBPAY data reconciliation status with the data from ERIP reports. Possible values:

Not confirmed by the bank (ERIP) — confirmation of a successful transaction in the WEBPAY system has NOT been received from ERIP;

Successful reconciliation — confirmation of a successful transaction in the WEBPAY system has been received from ERIP;

Reconciliation error — confirmation of a successful transaction in the WEBPAY system has been received from ERIP, but there is a discrepancy in the payment parameters.

Payment time Date of the payment performed in the WEBPAY system.
Business account Value that identifies the consumer of a commodity or service.
ERIP request ID Single identifier for the requests sequence for ERIP payments.
ERIP transaction ID Operation account number in the ERIP central unit.
Number of service Service number of the Store.
Settlement agent code Three last numbers of the settlement agent`s sort code.
Amount Payment amount in the WEBPAY system.
Currency Payment currency in the WEBPAY system.
Authorization type

Payment method. Possible values:

MS — card with a magnet stripe.

BC — BELCARD card.

NONE — the payer is not identified.

CASH — payment in cash in the Cash Settlement Center.

CASHIN — payment in cash in the payment and inquiry terminal.

WEBPAY transaction ID ERIP identifier in the context of payment requests.
Message dispatcher code Regional node subscriber`s code.
Message number ERIP message number.
Message formation date ERIP message forming date.
Payment document number ERIP payment document number.
Funds transfer date Funds transfer date according to ERIP data.
Settlement agent`s business account Settlement agent`s business account from which was performed the settlement with service provider.
Transferred amount Amount transferred for the current payment according to the ERIP data.
Currency Currency of the current ERIP payment.
Transaction date Transaction date by the ERIP data.
Transaction number in the Account agent ERIP operation number in the Account agent.
Amount Authorization Tool Information about payment tool.

To see all AIS "Raschet" (ERIP) transactions you need to select the "ERIP" → "Transaction log" menu entity. As a result, you will see a report that in real time displays information about the stages of order payment and refund. Payment is performed in three stages:

  • Service Info,
  • Transaction Start,
  • Transaction Result.

Funds refund is performed in two stages:

  • Storn Start,
  • Storn Result.
Report fields description
Name Description
Request ID Single identifier for the requests sequence for ERIP payments.
Operation status

The result of operation. Possible values:

Successful operation — the WEBPAY system did confirm the operation success.

Execution error — the WEBPAY system did NOT confirm the operation success.

Duplicate operation — the WEBPAY system already contains this operation.

Operation Type

Type of operation in accordance with ERIP protocol:

SERVICE_INFO — receiving the order data.

TRANSACTION_START — start of the order payment.

TRANSACTION_RESULT — order payment result.

STORN_START— start of the refund request.

STORN_RESULT — refund request result.

Request date Date of forming the request to ERIP.
ERIP transaction ID Operation account number in the ERIP central unit.
WEBPAY transaction ID ERIP identifier in the context of payment requests.
WEBPAY business account Value that identifies the consumer of a commodity or service.
Number of service Service number of the Store.
Amount Payment amount in the WEBPAY system.
Currency Payment currency in the WEBPAY system.
Authorization type Type of funds authorization when order is paid.
Settlement agent Settlement agent`s code.

Accounting for transactions made through Internet-acquiring

Select the "Payments" → "Reconciliation report" menu entity. A report with the order payment results and information about the reconciliation of payment with the acquiring bank. Record in the report appears immediately after payment.

Report fields description
Name Description
Invoice status

The result of payment processing. Possible values:

Authorization — funds is blocked on the payer`s card.

Authorization reset — funds is unblocked on the payer`s card.

Partial authorization reset — part of the funds is unblocked on the payer`s card.

Completion — funds debited from the payer`s account.

Full refund — funds was written-off from the Store`s operation account and returned to the payer`s card.

Partial refund — part of the funds was written-off from the Store`s operation account and returned to the payer`s card.

Reconciliation status

WEBPAY data reconciliation status with the data from the bank reports. Possible values:

Not confirmed by the bank — confirmation of a successful transaction in the WEBPAY system has NOT been received from the bank.

Successful reconciliation — confirmation of a successful transaction in the WEBPAY system has been received from the bank.

Reconciliation error — confirmation of a successful transaction in the WEBPAY system has been received from the bank, but there is a discrepancy in the payment parameters.

Merchant ID Store`s ID in the WEBPAY system.
Trader`s website Website connected to the WEBPAY system.
Trader`s order number Unique order identifier assigned by the Store.
WEBPAY account number Order number in the WEBPAY system.
Terminal number Terminal number set by the acquiring bank.
Processing Acquiring bank processing number.
Date and time of the authorization Date of payment in the WEBPAY system.
Amount Payment amount in the WEBPAY system.
Currency Payment currency in the WEBPAY system.
RRN of the acquiring bank processing Unique transaction ID set by the processing center.
Authorization code of the issuing bank Authorization code assigned by the issuing bank.
Date and time of financial write-off Date of the payment financial completion in the WEBPAY system.
Amount of financial completion Amount of the payment financial completion in the WEBPAY system.

If "Priorbank" JSC, "MTBank" CJSC, "Dabrabyt" JSC are your acquiring bank, you can use the menu entity "Payments" → "Received funds" to see information about the reflection of funds in the acquiring bank. It will show the report which contains information about successful transactions reflected in the bank.

Report fields description
Name Description
Date of payment registration/refund at the bank Date of reflection of funds in the acquiring bank.
Amount to transfer Total amount (minus the commission) that will go to the Store`s operation account.
Transfer currency The currency in which funds are credited.
Trader`s order number Unique order identifier assigned by the Store.
Terminal number Terminal number set by the acquiring bank.
Merchant ID Store`s ID in the WEBPAY system.
Trader`s website Website connected to the WEBPAY system.
WEBPAY order number Order number in the WEBPAY system.
Authorization code of the issuing bank Authorization code set by the issuing bank.
RRN Unique transaction ID set by the processing center.
Compensation amount Payment amount in the WEBPAY system.
Compensation commission Bank commission.
Date and time of the authorization Date of payment in the WEBPAY system.

Advanced payment page settings

Important!

To brand a payment page contact your manager managers@webpay.by

Possibility of extended payment page settings:

  • company logo placement,
  • using brand color in buttons and lines,
  • page font choosing,
  • the card background changing (color or image),
  • the page background changing (color or image),
  • the payment button text changing,
  • typing additional text on the page.
Opportunities for changes to the payment page

9.1. Logo

The logo must be in png format. The maximum image height is 100px (pixels) and the size is no more than 500 KB. We recommend using a transparent background.

9.2. Brand colors

Color is transmitted in hexadecimal code — Hex Code (the color value is presented as "#XYXYXY"). This color will display:

  • payment button,
  • card background,
  • lower bounds of data entry fields,
  • the inscriptions "Payment by card", "Payment by ERIP", "EN", "RU".

9.3. Page font

You can choose from five available fonts:

  • Montserrat,
  • Roboto,
  • Segoe UI,
  • ProximaNova,
  • Helvetica.

9.4. Card background

You can use either a color or an image as a card background. Color is transmitted in hexadecimal code — Hex Code (the color value is presented as "#XYXYXY"). ! The background card color is the brand color. The image must be in png format. The maximum image height is 285px (pixels), the maximum width is 430px (pixels), and the file size is not more than 500 KB. A transparent background is recommended.

9.5. Page Background

You can use either a color or an image as a card background. Color is transmitted in hexadecimal code — Hex Code (the color value is presented as "#XYXYXY"). The image must be in png format. The maximum file size is not more than 1 MB. The image is scaled keeping the proportions to fit entirely inside the page.

9.6. Change the payment button text

9.7. Typing additional text on the page

Invoice Statuses & Types

Invoice statuses

You can review the invoice status by selecting the "Invoices" entity in the menu. All invoices in the WEBPAY system are divided into the following groups:

Pending — the invoice receives this status straight after its forming and sending a notification to the payer`s email. You can see invoice amount in the "Invoice total" field.

Pending

Authorized — the invoice receives this status straight after successful authorization. In other words, when money is already blocked on the buyer`s card, but still not debited. The transaction gets the "Authorized" status.

Authorized

Paid — the invoice receives this status straight after successful payment. In other words, when money is debited from the buyer`s card. Amount paid by the payer will be displayed in the "Amount paid" field. The transaction gets the "Completed" status.

Paid

Not paid — a payment was not made during the specified period of time. In order to prolong the payment period you should click the "Edit invoice" button.

Not paid

Voided — the payment was reset after authorization, i.e. money on the buyer`s card account was unblocked. The transaction gets the "Voided" status.

Voided

Partial refunded — a partial refund to the buyer`s card account was initiated. The amount in the "Amount paid" field is equal to the difference between the order and returned amount. The transaction gets the "Refunded" status.

Partial refunded

Refunded — full refund to the buyer`s card account was initiated. The amount in the "Amount paid" field is equal to zero. The transaction gets the "Refunded" status.

Refunded

Recurrent — a recurring (CoF) payment. This is a payment made with a bound card without payer involvement.

Recurrent

Important!

Please note, when you perform payment through AIS "Raschet" (ERIP), the invoices will be getting only the "Pending", "Paid" and "Not paid" statuses.

Types of operations in the WEBPAY system

In event of any claims regarding the quality of provided commodities/services, the buyer has the right to apply to online store with a request to cancel the payment.

To return the written off funds the payer must contact the seller (online store or online resource).

According to the rules of international payment systems, a refund can only be made on the bank card from which the payment was accomplished. It is recommended to keep a copy of the payment notice received by email when making a payment.

Important!

Please, note that refund/exchange in the WEBPAY system can only be accomplished for payments made through Internet-acquiring. Payments made through AIS "Raschet" (ERIP) cannot be refunded/exchanged.

Authorization confirmation and cancellation

At the payment time required amount is blocked on the payer`s card, which becomes unavailable for use. "Authorized"payment in the WEBPAY system receives the correspond status.

The real debit of funds from the payer`s card occurs after the financial confirmation of the payment. After the financial confirmation has been completed, funds from the customer`s card are credited to your company`s operating account in accordance with the terms established by the Internet-acquiring agreement.

Financial confirmation can be performed automatically or manually. Automatic confirmation is performed after 24 hours since the authorization. Based on your wish, we may set the financial confirmation time from 1 second to 72 hours.

A payment for which the financial confirmation has been completed is marked in the WEBPAY system as "Completed".

There are two payment processing types in WEBPAY system:

  1. One-stage payments — payments that are instantly financially completed (Completed transaction type), so funds are instantly charged from payer`s card. The main advantage of this payment type is that funds are transferred to company`s bank account in a period specified by acquiring bank. On the other hand, refund to your customers may take up to 30 days depending on issuing bank.
  2. Two-stage payments — payments that lead to freezing of funds on the payer`s card at first (Authorized transaction type), and only after that in specified period of time they become financially completed (Completed transaction type). The main advantage of this payment type is that company has additional time to check goods or services availability. In case of order`s cancellation all funds will be instantly unfrozen. On the other hand, there is a delay before funds reach company`s bank account equal to authorization period combined with transfer period specified by acquiring bank.
The list of successful transactions

Authorized payments in the WEBPAY system can be financially completed or cancelled.

The payment cancellation procedure includes the following stages:

  • go to "Payments" section;
  • select the required payment to open it and then click the "Void" button — it will cancel the authorization of the transaction.

After pressing the "Void" button, the payment will be rejected, the entire paid amount will be unlocked on the payer`s bank card, and will become available for use. The transaction will receive the "Voided" status.

Make void of authorization

If you press the "Complete" button, the authorization for bank card will be confirmed, transaction will complete, the funds will debit from the payer`s card, and the transaction will acquire the "Completed" status.

Financial completion of authorization

Full and partial refund

If the payment has already been completed, in other words, the transaction received the "Completed"status, you cannot void the payment. In such case you will have to make a "Refund" or "Partial refund" to get your money back.

The refund procedure includes the following stages:

  • go to "Payments" section;
  • select the required payment to open it;
  • click the "Refund" button;
  • in the amount field on the opened page select full or partial refund. If you want a partial refund, enter the amount which will be refunded to the payer`s card he used to pay for purchase;
  • click the "Refund" button.

After that the funds will be returned to the payer`s card. The transfer usually performs during a week for a Belarus banks cards. For a foreign banks cards the procedure can take up to a month. This parameter largely depends on the bank that issued the card. After a successful refund, the transaction acquires the "Refunded" status.

Make refund of the transaction

Introduction to Sandbox development environment

WEBPAY Sandbox is the substantive web application, which serves as prototype of real system and meant for testing and familiarizing with capabilities of real WEBPAY environment. There is no difference in capabilities between Sandbox and real system apart from cards processing meaning there will be no real transactions. Development and testing of payment modules should be always done in test environment.

Test environment parameters

Name Description
Test environment URL: https://sandbox.webpay.by
Login: sent via email
Password: sent via email
Unique store ID (wsb_storeid): sent via email

The following card parameters can be used to perform testing transactions (for test environment only):

type: VISA

number: 434179xxxxxx0051 (this field is not editable by default)

CVV/CVC2: any three numbers

expiration date: any. To manually get a transaction error fill in December of the next year. For example, if the current year is 2019, then fill in 12/20.

Transition from test into real environment

Please note that a bunch of requirements must be met in order to move from test environment into a real one.

Change of payment page address

To perform real payments you must create a form with special fields and redirect customer to payment page https://payment.webpay.by by POST method.

Payment pages URLs:

Important!

In real environment requests to https://payment.webpay.by must be performed from domain name stated in the Internet-acquiring contract. Furthermore, sub-domains are treated as separate domains in accordance with payment systems rules. So if in your contract you specified https://test.by, than redirection to your payment page is also should be happening from https://test.by. In case of redirection from https://bill.test.by transaction will be blocked. Referer URL is regularly checked in accordance with payment systems and acquiring banks. If you are going to use an URL different from the one specified in the contract please contact your personal WEBPAY manager.

Web application interface URL is also changing:

Change of store ID

Store ID value in WEBPAY system is stored in wsb_storeid field. This parameter is created when registering and is sent in email by your personal WEBPAY manager. You must change its value to the one from real environment.

Change of test payment flag

When executing payments in a test environment value of field wsb_test equal to 1 was used to mark payment for an order should not be executed for real but emulated. To execute payments in real environment you must set 0.

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 https://docs.webpay.by/payment-json.html.
  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

Important!

All text fields must be filled with text in UTF-8.

Main payment form fields

Name Required field Field description Notes
*scart yes Field does not contain value and designates the type of the request.
wsb_storeid yes Store ID in WEBPAY system. This ID is created during registration in the system and is sent in the email.
wsb_store no Store name that will be shown on the payment form. By default, it is taken from the billing account settings. Maximum field length of 64 symbols.
wsb_order_num yes Unique order ID given by the store. Maximum field length of 64 symbols. The value can not begin with 0 (zero) when paying via ERIP.
wsb_currency_id yes Currency ID. Three-letter code in accordance with ISO4271 standard. Accepted values: BYN, USD, EUR, RUB
wsb_version yes Payment form version. Current version number: 2
wsb_language_id no Payment form language ID. Accepted values: russian, english. When empty the value is determined by browser settings.
wsb_seed yes Random symbol sequence used in electronic signature the order. See: Electronic signature of an order.
wsb_signature yes Control value (electronic signature) of the order is a result of SHA1 function execution (for version 2, see wsb_version field) or MD5, if there is no protocol version specified. This value is a hex sequence. See: Electronic signature of an order.
wsb_return_url no URL a customer is redirected to if the payment was successful. Order ID (wsb_order_num) and transaction numbers (wsb_tid) are added to present URL in WEBPAY system.
wsb_cancel_return_url no URL a customer is redirected to if the payment was not successful. Values of order ID (wsb_order_num) are added to present URL.
wsb_notify_url no

This URL is called independently from the URL specified in wsb_return_url field. The main purpose of this URL is to notify website about successful payment in case user did not click the "Back to the site" button on the payment form. By default, it is taken from the billing account settings.

Warning! Sending notifications is only possible to standard ports: 80 (http), 443 (https), 8080 (http_alt), 8443(pcsync-https).

See: Payment notification.
wsb_test yes

Field that designates whether the payment is real or not.

1 — test payment;

0 — real payment.

In Sandbox test environment the value should be 1.
wsb_customer_name no Customer name. Maximum field length of 255 symbols.
wsb_customer_address no Customer address. Maximum field length of 255 symbols.
wsb_service_date no Effective dates of rendering of services or delivery of goods. Maximum field length of 255 symbols.

Fields for formation of shopping cart

Name Required field Field description Notes
wsb_invoice_item_name[{n}] yes Item name. Index {n} should start with 0 and increase by 1 for each next position.
wsb_invoice_item_quantity[{n}] yes Integer that designates the amount of each item. Index {n} should start with 0 and increase by 1 for each next position.
wsb_invoice_item_price[{n}] yes Price for an item. Number stands for a price of one item (BYN, USD, EUR, RUB with two characters after dot or comma). Index {n} should start with 0 and increase by 1 for each next position.
wsb_tax no Tax amount in BYN which is added to the final price of the order. When paying via ERIP this field does not count (tax amount is added to the price of goods).
wsb_shipping_name no Delivery method. Maximum field length of 255 symbols.
wsb_shipping_price no Shipping price which is added to the final price of the order.
wsb_discount_name no Discount description. Maximum field length of 255 symbols.
wsb_discount_price no Discount amount which is deducted from the final price of the order. Value should be a positive number (without "-" minus).
wsb_discount_promo_code no Contains the value of the discount promo code for the order when working with the VISA and MASTERCARD discount programs. Maximum field length of 32 symbols.
wsb_total yes

This field is calculated. The value of this field is the final price of the order which is calculated by the following formula:

wsb_total = wsb_invoice_item_quantity[0] * wsb_invoice_item_price[0] + wsb_invoice_item_quantity[1] * wsb_invoice_item_price[1] +

...

wsb_invoice_item_quantity[n] * wsb_invoice_item_price[n] + wsb_tax + wsb_shipping_price - wsb_discount_price.

Payment will not be performed if wsb_total and calculated value of goods are not equal. An error will be shown to a customer.

Additional fields

Name Required field Field description Notes
wsb_order_tag no Order tag is used to categorize orders, group orders or for other reasons. Maximum field length of 64 symbols.
wsb_email no Customer`s email address. Value of this field will be automatically put into appropriate field of the payment form.
wsb_phone no The customer`s phone number.
wsb_order_contract no Number of contract with the customer.
wsb_tab no Determining the active tab with the appropriate payment tool (card payment/ERIP). Possible values: erip, cardPayment. If there is no field the order of tabs is standard — payment by card, then ERIP.
wsb_card_number_short no

Determination of the possibility of making a payment for the card specified by the payer.

The WEBPAY system makes a comparison of the card number data (the first 6 and the last 4 digits) between the transmitted card number in this field and what the payer entered when paying.

If the first 6 and last 4 digits of the card number match, the payment is allowed, otherwise the payment attempt is rejected and an error is displayed to the payer.

The value is an integer that consists of the first 6 and last 4 digits of the card number. For example: 1234561234.

Code example

<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="1">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_customer_name" value="Ivanov Ivan">
  <input type="hidden" name="wsb_customer_address" value="Minsk Shafarnyanskaya str. 11-54">
  <input type="hidden" name="wsb_service_date" value="Delivery till 1 january 2016 year">
  <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_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <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="31.40">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="266e9c04a24dfb5fc75775c42a831a49488f8303">
  <input type="hidden" name="wsb_tax" value="10.50">
  <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_order_contract" value="Contract №152/12-1 12.01.19">
  <input type="submit" value="Buy">
</form>

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

Code example

<input type="hidden" name="wsb_startsesstime" value="1603383601">
<input type="hidden" name="wsb_startsessdatetime" value="2020-10-22T16:20:01+03:00">

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.

Code example

$wsb_seed = 1242649174;
$wsb_storeid = 11111111;
$wsb_order_num = "ORDER-12345678";
$wsb_test = 1;
$wsb_currency_id = "BYN";
$wsb_total = 21.90;
$SecretKey = "12345678901234567890";
// Value of the merged string:
// 124264917411111111ORDER-123456781BYN21.9012345678901234567890
// for protocol version 2 (wsb_version = 2)
$wsb_signature = sha1($wsb_seed.$wsb_storeid.$wsb_order_num.$wsb_test.$wsb_currency_id.$wsb_total.$SecretKey);
// 338d1647833079f9353907ad266ec0bb5264c0d9
// if version is not specified
$wsb_signature = md5($wsb_seed.$wsb_storeid.$wsb_order_num.$wsb_test.$wsb_currency_id.$wsb_total.$SecretKey);
// 5b712daa1743d1a62dfdb7054b3978a1

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.

Important!

It is possible that customer will not click the "Back" button on a payment form. In order to inform about successful operation WEBPAY system after some time sends special notification (Payment notification).

Order payment

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.

Set Notification URL

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.

Important!

Please note that the time of the payment session is 20 minutes and the payer can make a payment during this time, in this regard, the notification does not come immediately after sending an authorization request for payment to the WEBPAY system.

The notification is sent only after the WEBPAY system receives the payment result. By default, the notification is sent only for successful operations. If you need to receive notifications and for unsuccessful payments, we recommend contacting WEBPAY technical support.

If within 20 minutes after the authorization request was sent by the Internet resource, the payer was not redirected to the addresses wsb_return_url or wsb_cancel_return_url and/or the notification was not received by the Internet resource, we recommend to use the GetTransactionStatus API method to manage card transactions or contact the WEBPAY support service at support@webpay.by to clarify the status of the transaction.

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:

Name Description
batch_timestamp Transaction execution time
currency_id Transaction currency
amount Transaction amount
payment_method Transaction methods. Possible values:
  • test — without real processing,
  • cc — card,
  • erip — ERIP
  • apple — Apple Pay payment
order_id Order number in the WEBPAY system
site_order_id Order number (name) set by store
transaction_id Transaction number
payment_type Transaction type. Successful payments are equal to 1 or 4
rrn Transaction number in VISA/MASTERCARD/BELCARD system
wsb_signature Electronic signature (calculated if "Secret key" is set in the billing account options)
action Payment processing code
rc WEBPAY operation result internal code
approval Processing operation code
country_alpha_three_code Country code of the issuing bank in ISO 3166-1 alpha-3. To include this field in the notifier, you must contact the support@webpay.by

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
  • 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.

Code example

application/x-www-form-urlencoded

{batch_timestamp=1562591640&currency_id=USD&amount=300&payment_method=cc&order_id=127386&site_order_id=16&transaction_id=858578101&
payment_type=4&rrn=786755995452&wsb_signature=001a1e46c8ba6c9934dc60975ecc9f75&action=0&rc=W0001%2800%29&approval=786755&
country_alpha_three_code=USA}

SOAP tool

For SOAP tool (may be enabled by request) the WEBPAY system sends specially formed SOAP request 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.

Important!

SecretKey field is only considered in a real environment.

Code example

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://ws.webpay.by/notifier">
  <xs:element name="NotifierRequest">
    <xs:complexType>
      <xs:sequence>
        <xs:element minOccurs="1" maxOccurs="1" name="BatchTimestamp" type="xs:int"/>
        <xs:element minOccurs="1" maxOccurs="1" name="CurrencyId" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="Amount" type="xs:decimal"/>
        <xs:element minOccurs="1" maxOccurs="1" name="PaymentMethod" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="OrderId" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="SiteOrderId" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="TransactionId" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="PaymentType" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="RRN" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="WsbSignature" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="Action" type="xs:string"/>
        <xs:element minOccurs="1" maxOccurs="1" name="RC" type="xs:string"/>
        <xs:element minOccurs="0" name="Card" type="xs:string"/>
        <xs:element minOccurs="0" name="CountryAlphaThreeCode" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example of a request in accordance with the scheme

Code example

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
      <ns2:NotifierRequest xmlns:ns2="http://ws.webpay.by/notifier">
        <ns2:BatchTimestamp>1550480633</ns2:BatchTimestamp>
        <ns2:CurrencyId>BYN</ns2:CurrencyId>
        <ns2:Amount>547.5</ns2:Amount>
        <ns2:PaymentMethod>cc</ns2:PaymentMethod>
        <ns2:OrderId>117524</ns2:OrderId>
        <ns2:SiteOrderId>19020402513459776</ns2:SiteOrderId>
        <ns2:TransactionId>610030693</ns2:TransactionId>
        <ns2:PaymentType>4</ns2:PaymentType>
        <ns2:RRN>145043593722</ns2:RRN>
        <ns2:WsbSignature>e71ceb051ff142c843bc3d520ac35a21</ns2:WsbSignature>
        <ns2:Action>0</ns2:Action>
        <ns2:RC>W0001(00)</ns2:RC>
        <ns2:Approval>145043</ns2:Approval>
        <ns2:Card>434444xxxxxx0001</ns2:Card>
        <ns2:Cardholder>pv</ns2:Cardholder>
        <ns2:CountryAlphaThreeCode>USA</ns2:CountryAlphaThreeCode>
        <ns2:OrderTag>onlinePayment</ns2:OrderTag>
      </ns2:NotifierRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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.

Code example

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://ws.webpay.by/notifier">
  <xs:element name="NotifierResponse">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="code" type="xs:string"/>
        <xs:element name="codeDescription" type="xs:string"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

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.

Code example

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ns2:NotifierResponse xmlns:ns2="http://ws.webpay.by/notifier">
      <ns2:code>200</ns2:code>
      <ns2:codeDescription>OK</ns2:codeDescription>
    </ns2:NotifierResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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.

Request example

<!-- 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:

Name Description
transaction_id Transaction number
batch_timestamp Transaction execution time
currency_id Transaction currency
amount Transaction amount
payment_method Transaction methods. Possible values:
  • test — without real processing
  • cc — card
  • apple — Apple Pay payment
payment_type Transaction type. Successful payments are equal to 1 or 4
order_id Order number in WEBPAY system
rrn Transaction number in VISA/MASTERCARD/BELCARD system
wsb_signature Electronic signature (calculated if "Secret key" is set in the billing account options)

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.

Important!

If for any reason no response is received from the WEBPAY system we recommend to repeat the request with an increasing frequency of up to 1 hour. If the WEBPAY system has not returned a response, then mark such operations and send them to support@webpay.by.

Transaction types

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

Type Value Description
1 Completed Completed
2 Declined Declined
3 Pending Pending
4 Authorized Authorized
5 Partial Refunded Partial Refunded
6 System System
7 Voided Void after authorization
8 Failed Error during operation execution
9 Partial Voided Partial Void
10 Recurrent Recurring payment (CoF)
11 Refunded Refunded

Important!

You should pay attention to transaction type while writing code of an inquiry. Such notification type is meant to notify website about successfully competed transactions and refunded transactions.

These are types for successful payments:

Type Value Description
1 Completed Completed
4 Authorized Authorized
10 Recurrent Recurring payment (CoF)

And these are types for refunded payments:

Type Value Description
5 Partial Refunded Частично возвращенная
7 Voided Сброшенная после авторизации
9 Partial Voided Частичный сброс
11 Refunded Возвращенная

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.

Initiating payment in the Simplified payment scenario

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.

Repeat payment in the Simplified payment scenario

Important!

Customers are still able to choose standard payment scheme. They just only need not to choose a card from the list of bound ones. Even if customer has one (or a few) bound card he can pay without usage of advantages of simplified payments.

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.

Code example

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

Important!

  1. If you did not make changes to interaction protocol with WEBPAY program complex, all payments will be executed by default.
  2. In order to be able to add various cards and bind them you need to set wsb_test parameter to 0.
  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.

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 https://docs.webpay.by/payment-json.html.
  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.

Important!

All text fields must use UTF-8 charset.

Name Required field Field description Notes
wsb_customer_id yes Unique user ID in the Store. Maximum field length of 64 symbols.
wsb_operation_type yes Action ID for recurring payments. Possible values:
  • recurring_bind — bind the card to account
  • recurring_pay — make a recurring (CoF) payment
  • recurring_unbind — unbind the card from account
wsb_recurring_token yes Unique token of binding the card to user ID in the Store (wsb_customer_id) The value of this field appropriates the recurring_token field value, which was transferred in a notification after binding the card.

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.

Important!

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

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.

Code example

<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:

Name Description
batch_timestamp Transaction execution time
currency_id Transaction currency
amount Transaction amount
payment_method Transaction methods. Possible values: сс — card; test — without real processing
order_id Order number in WEBPAY system
site_order_id Order number (name) set by Store
transaction_id Transaction number
payment_type Transaction type. See Transaction types
rrn Transaction number in VISA/MASTERCARD system
wsb_signature Electronic signature
action Payment processing code
rc WEBPAY operation result internal code
approval Processing operation code
rc_text Textual representation of WEBPAY internal code
card Masked card number used for binding and operation
customer_id Customer ID in the Store`s system
operation_type Completed operation naming: recurring_bind — bind the card to the account; recurring_pay — execute recurring (CoF) payment; recurring_unbind — unbind the card from the account
recurring_token Card binding token meant for future recurring (CoF) payments execution
offer_exp_date Card`s expiration date in YYYY-MM-DD format (e.g. 2020-10-31)

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.

Important!

If for any reason no notification is received and the payer claims that the payment is made successfully, we recommend to use the GetTransactionStatus API method to manage card transactions or contact the WEBPAY support service at support@webpay.by to clarify the status of the transaction.

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.

Code example

<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 example

// 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.

Code example

<!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.

Response example

// 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:

Acquiring bank Transaction type Transaction status
"Priorbank" JSC Initiating Authorized → Completed
Recurring Recurrent
Credential on File Completed
"MTBank" CJSC
"Belagroprombank" JSC
"BPS-Sberbank" JSC
Initiating Authorized → Completed
Recurring Authorized → Completed

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.

Acquiring bank Transaction type Request type Transaction status
"Priorbank" JSC Initiating, Recurring TransactionCancel (with the specified amount for refund to cardholder) Voided
Credential on File TransactionRefund (with the specified amount for refund to cardholder) Refunded
"MTBank" CJSC
"Belagroprombank" JSC
"BPS-Sberbank" JSC
Initiating TransactionCancel (with the specified amount for refund to cardholder) Voided
Recurring TransactionComplete (partial financial conclusion for an amount that should be charged in favour of the Store) Completed
TransactionRefund (with the specified amount for refund to cardholder) 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:

Installment plan type Terminal number
1 month 90000001
3 month 80000003

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.

Payment page for payment by Halva installment card

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.

Selecting the payment method for the X-card

Code example

<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="950f99293b3aa0d26ab11f69af7f4ba5441e42b5">
  <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_terminal" value="80000003">
  <input type="submit" value="Buy">
</form>

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.

The choice of method of payment if payment is made by Halva Plus

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.

Payment page type with Apple Pay

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:

Card type Promo code value
VISA visa
MASTERCARD (Maestro and BELKART-MAESTRO cards are not included) mastercard

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:

Card type Promo code value
VISA Gold gold
VISA Platinum platinum
VISA Infinite infinite

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.

Code example

<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_customer_name" value="Ivanov Ivan">
  <input type="hidden" name="wsb_customer_address" value="Minsk Shafarnyanskaya str. 11-54">
  <input type="hidden" name="wsb_service_date" value="Shipping till 1 january 2016 year">
  <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_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <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="31.40">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="bc8ea3bee19c247d090c79c8bbb7974f9484db96">
  <input type="hidden" name="wsb_tax" value="10.50">
  <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_order_contract" value="Договор №152/12-1 от 12.01.19">
  <input type="hidden" name="wsb_discount_promo_code" value="gold">
  <input type="submit" value="Buy">
</form>

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):
Card type BIN card
VISA Gold 480066
VISA Platinum 417685
VISA Infinite 455674

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.

Payment page for ERIP

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".

Payment page for ERIP and Internet acquiring

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.

Later payment

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

Notification for later payment ERIP

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

Notification for later payment ERIP and Internet acquiring

Code example

<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="1">
  <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="266e9c04a24dfb5fc75775c42a831a49488f8303">
  <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_due_date" value="1586684975">
  <input type="submit" value="Buy">
</form>

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 invoicingSuccessful invoicing
  2. ОшибочноеError invoicingNotification about a non-unique file

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:

Example of FTP settings

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

Field name Type of data Required Field description Encoding and misc.
resourceId String yes Store ID in the WEBPAY system
resourceOrderNumber String yes Unique order number in the WEBPAY system
validThrough Date no Date, to which the order can be paid
shortDescription String no Short description of the order
creationTime Date no Creation date of the order
longDescription String no Detailed description of the order
languageCode String no Language code as specified in ISO 639-1
items Array yes Array of order items multiple
item ComplexType yes Order item items/
name String yes Commodity name items/item/
quantity Integer yes Quantity of goods items/item/
price ComplexType yes One item cost items/item/
amount BigDecimal yes One item cost items/item/price/
currency String yes Item currency as specified in ISO 4217 items/item/price/
urls Map yes Addresses array multiple
name Enum yes Possible values:
resourceReturnUrl — URL for redirection in case of successful authorization;
resourceCancelUrl — URL for redirection in case of unsuccessful authorization;
resourceNotifyUrl — URL for notification sending (paymentStatus).
urls/
url String yes URL corresponding to the above type ('name') urls/
customer ComplexType no Name of the commodity/service receiver
resourceCustomerId String yes ID of the commodity/service receiver customer/
name String no First name of the commodity/service receiver customer/
surname String no Second name of the commodity/service receiver customer/
email String no Email of the commodity/service receiver customer/
phone String no Phone number of the commodity/service receiver customer/
discounts Array no Array of order discount items multiple
discount ComplexType yes Order discount discount/
name String yes Discount name discount/
promoCode String no Promo code discount/
type String no Discount type discount/
value ComplexType yes Discount value description discount/
amount BigDecimal yes Discount value discount/value/
currency String yes Item currency as specified in ISO 4217 discount/value/
shippings Array no Array of shippings multiple
shipping ComplexType yes Order shipping shipping/
name String yes Shipping name shipping/
value ComplexType yes Shipping value description shipping/
amount BigDecimal yes Shipping value shipping/value/
currency String yes Item currency as specified in ISO 4217 shipping/value/

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

Request example

{"resourceId":479447789,
"resourceOrderNumber":"455444556222",
"validThrough":"2017-09-25T00:01:00+03:00",
"shortDescription":"Test payment",
"creationTime":"2017-09-20T09:00:00+03:00",
"longDescription":"This is a test payment",
"languageCode":"ru",
"customer":{
"resourceCustomerId":"test33332",
"phone":"375331231231",
"email":"test@test.by",
"name":"tttttt",
"surname":"qqqqqqq"},
"items":[{
"idx":1,
"name":"Товар 1 UTF-8 1",
"quantity":"1",
"price":{
"currency":"BYN",
"amount":130.10}},
{"idx":2,
"name":"Product 2",
"quantity":1,
"price":{
"currency":"BYN",
"amount":40.10}}],
"total":{
"currency":"BYN",
"amount":170.20},
"discounts":[{
"name":"discount",
"promoCode":"promo code",
"type":"type",
"value":{
"amount":10.10,
"currency":"BYN"}}],
"shippings":[{
"name":"shipping",
"value":{
"amount":10.10,
"currency":"BYN"}}],
"urls":{
"resourceReturnUrl":"http://localhost:8080/return11111",
"resourceCancelUrl":"http://localhost:8080/cancel22222",
"resourceNotifyUrl":"http://192.168.44.11:8080/webpay/shop"}}

Description of the response parameters

Name Type Required Description
resourceId String yes Store ID in the WEBPAY system
resourceOrderNumber String yes Order number in the Store`s system
webpayInvoiceId Integer no Order ID in the WEBPAY system
webpayInvoiceNumber String no Unique order number in the WEBPAY system
invoiceURL String no Order URL address

Response of the WEBPAY system upon successful order creation.

Response example

{"resourceId":479447789,
"resourceOrderNumber":"455444556222",
"webpayInvoiceId":77714,
"webpayInvoiceNumber":"735542997",
"webpayOrderId":9736,
"webpayOrderNumber":null,
"shortOrderNumber":"455444556222",
"invoiceUrl":"https://sandbox.webpay.by/?"}

WEBPAY response to an error, for example:

Response example

{"errorCode":"BAD_REQUEST",
"errorMessage":"resourceOrderNumber: The field must be unique"}

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:

Authorization: HmacSHA512 <apiKey>:<nonce>:<digest>

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
Field name Required field Field description
METHOD yes Request method (POST)
RESOURCE yes Resource, to which the request is executed. For example: /woc/order will be the string for signature in https://sand-box.webpay.by/woc/order
QUERYSTRING Нет Request parameters. For example: id=11 will be the string for signature in https://sand-box.webpay.by/woc/order?id=11
CONTENT_TYPE yes Http-header Content-type
APIKEY yes Store`s resource ID number
NONCE yes Randomly generated string. Shoul be uniq for each order
PAYLOAD yes Request body

Code example

<?php
$jsonString =
'{"resourceId":349204746,
"resourceOrderNumber":"ORDER-16",
"validThrough":"2020-06-10T20:16:35+03:00",
"creationTime":"2020-04-13T05:16:09+03:00",
"languageCode":"ru",
"customer":{
"resourceCustomerId":"1",
"phone":null,
"email":"test@test.by"
},"items":[{
"idx":0,
"name":"TEST!",
"quantity":1,
"price":{"currency":"BYN","amount":100.00}}],
"total":{"currency":"BYN","amount":105.00},
"urls":{
"resourceReturnUrl":"https:\/\/test.by",
"resourceCancelUrl":"https:\/\/test.by",
"resourceNotifyUrl":"https:\/\/test.by"},
"shippings":[{"name":"shipping","value":{"amount":5,"currency":"BYN"}}]}';

$nonce = 'Ykw5M85o2iLkTVgDWmz1yPIomi93gvL4AvQN';
$storeid = '349204746';
$secret = '123456';

$stringToSign = "POST\n/woc/order\napplication/json;charset=utf-8\n$storeid\n$nonce\n$jsonString\n";

$digest = hash_hmac('sha512', $stringToSign, $secret, true);
$hmacString = 'HmacSHA512 '.$storeid.':'.$nonce.':'.base64_encode($digest);
//$hmacString
/*
HmacSHA512 349204746:Ykw5M85o2iLkTVgDWmz1yPIomi93gvL4AvQN:/Ef0ipKEy2+ZW6cjtOWKr51o0stKbfWxnsRjLxGgT9s+ua6gklzj2BGLdp4/hTXxEZudpVfdcwyAB/I+eA2jfA==
*/
$headers = array(
  "Authorization: $hmacString",
  "Content-type: application/json;charset=utf-8"
);

$url = 'https://sand-box.webpay.by/woc/order';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonString);
$content = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
print "$content\n";?>

Working without integration

The WEBPAY system provides work without integration with the Store`s website. You can accept payments by creating invoices from your WEBPAY personal cabinet.

Invoice creation from personal cabinet WEBPAY

Forming a new invoice for payment

To create a new invoice, go to "Invoices" section and press the "New invoice" button.

All your invoices are displayed in the "Invoices" menu, where is also located a search window, providing you with ability to search for different criteria: creation date, invoice name, merchant invoice name, invoice ID and account ID.

After pressing the "New invoice" button a pop-up form will appear with special fields that have to be filled. The "Select Account" field is required. In the "Select Account" you can create new account select "New Account" or select a previously created account.

Then you should fill the "First name" – specify a customer`s name to whose you want to file an invoice. Maximum field length is limited by 128 characters, while minimum length is 1 character. You may use any input format. This field is required.

Important!

Please note, that all the fields marked with * are required to fill. Fields that are not marked with * can be skipped.

Forming a new invoice for payment

The "Last name" field is also required. You should specify here a second name of a customer, who will receive your invoice. Maximum field length is limited by 128 characters, while minimum length is 1 character. You may use any input format.

Your invoice will be send to email specified in the "Email". field. This field is required. Maximum field length is limited by 128 characters, while minimum length is 4 characters. You can use only small Latin letters, numbers and "-" or "_" symbols.

The "Invoice name" is required. It is the unique order ID. Maximum field length is limited by 32 characters, while minimum length is 1 character. Any input format is allowed.

Important!

Please, note that for paying for purchase in the AIS "Raschet" (ERIP) system there will be used a number, typed in the "Invoice name" field. Its value MUST NOT start with "0" (zero). Creation of a multiple orders with the same number is PROHIBITED.

The "Currency" field is required. It specifies a currency that will be used for checkout. Currently there are four supported currencies to make payments:

  • belarusian ruble (BYN),
  • euro (EUR),
  • USA dollar (USD);
  • russian ruble (RUB).

The "Language" field is also required. On this stage you must choose a language for an invoice payment form. For now the system supports two languages:

  • russian,
  • english.
Create new invoice

The date till which your invoice needs to be paid is selected in the "Due date" field. This field is required. To select a date you should click on the watches icon, which located in the left part of the field. Pop-up calendar will appear where you can select day, month and year. You can also type payment`s date and time in the fields "Select date" and "Select time" using formats "yyyy-mm-dd" and "hh:mm:ss" accordingly. If you`ve changed your mind about invoice payment date during the form filling you can click on the watches icon again and change invoice payment date.

Next you need to add information about commodities/services to your invoice for which payment will be made. The name of a commodity/service is filled in the field "Product name". This field is required. Maximum field length is limited by 128 characters. Any input format is allowed.

You may skip the "Product code" field which contains product ID in the store. Maximum field length is limited by 32 characters, and minimum length is 1 character. You may use latin letter, numbers and "-"" or "_" symbols.

Choosing the time to pay the invoice

Next you need to fill the required field "Price". It contains a full product price without discount and shipping cost. Maximum field length is unlimited.

Commodities/services quantity is specified in the "Quantity" field. This field is required. Maximum field length is unlimited.

Important!

You can only enter an integer in the "Quantity" field.

You can add several commodities/services to invoice in the same way by clicking on the "Add field" button. You can also remove the commodity/service from invoice by clicking on the red icon "—" to the right of the item position.

The next fields are not required.

Shipping cost can be specified in the "Shipping and Handling" field. Maximum field length is unlimited.

Discount for a commodity/service can be specified in the "Discount" field. Maximum field length is unlimited.

Important!

Please, note, discount is typed without "-" (minus). The system will automatically deduct it from the order`s price. The final cost of the commodity/service with applied discount and shipping cost should not exceed the limit that was set in the Internet acquiring agreement.

If you wish to send payer an info message along with the invoice you can type it into the "Notes" field. Maximum field length is unlimited.

The filled out invoice

After clicking the "Save" button, the created invoice will appear first in the list.

If you click on the invoice card it will uncover the invoice details. You can use the "Edit invoice" button to make changes to an already created invoice.

The "Copy invoice URL" button will automatically copy the link into clipboard. URL allows to open invoice in a new tab and then to pay for purchase. You can send that link to a payer using any convenient way (SMS, email, messenger, etc.).

The "QR code" button allows you to open the code to move to the invoice. The code contains the same URL which can be identified by any mobile device that has a QR scanning function. That feature may be used, for example, for selling commodities in general stores.

Saved invoice

You can view detailed info about the invoiced customer and commodities/services contained in that invoice by clicking the "Show invoice" button. The button "Pay Invoice Now" is also located here.

View detailed info about the invoiced

After the invoice has been formed, the customer will receive an email with notification about new invoice and request to follow the link below to meet an invoice. Here is an example of email.

Example of email about new invoice

Example of notification email to meet an invoice using AIS "Raschet" (ERIP).

Example of email about new invoice using ERIP

Order payment

If a customer follows the provided link he will get on the payment form.

Order info

After clicking the "Pay Invoice Now" button, a customer will get on the WEBPAY payment page:

  • if you have an Internet acquiring connected;Платежная страница при интернет-эквайринге
  • if you have payment receiving through AIS "Raschet" (ERIP) connected;Платежная страница при ЕРИП
  • if you have both payment variants on your billing account (bank card and AIS "Raschet" (ERIP).Платежная страница при интернет-эквайринге и ЕРИП

Invoice creation from personal cabinet WEBPAY for installment cards

It is possible to create new invoices for payment by "MTBank" CJSC (Halva) and "Priorbank" JSC installment cards. If the customer has informed the Store that the payment will be made using an installment card, you can select for the current order the required installment period. If the Store has one installment type and the payment method is not selected, but the customer enters the Halva card, the payment will be made via the Halva installment type. If the Store has two or more installment types and the Store does not select the required terminal during creating new invoice, and the payer enters the Halva installment card, the payment will be rejected.

Invoice creation for installment cards

You will also see information about the terminal to which the invoice is issued, when viewing the detail of invoice.

Information about installments after payment

Payments using the QR code

It is possible to accept payments using a QR code, when entering into an Internet acquiring agreement with JSC "Bank BelVEB". This method does not require integration with the site and can be used for both online and offline payments.

To start accepting payments using the QR code, go to the WEBPAY personal account, the "QR code" section (enabled individually for the account):

Section QR code

The QR code is fixed and individual for a specific legal entity or individual entrepreneur and allows you to issue and pay an unlimited number.

You can use the "Download" and "Print" buttons for the convenience of working with the QR code. There is also a note "To copy QR to clipboard press right mouse button on image → "Copy image".

You will go to the payment form with address https://sales.webpay.by for real environment or https://salessandbox.webpay.by for test after scanning the QR code.

Example of form:

Example of a form for payment using QR code

The following information is displayed on the invoice form:

  • Company name.
  • Company address, contact phone number and email.
  • The field "Amount" with the option to enter the payment amount.
  • The field "Currency" with a drop-down list of available currencies for the company.
  • The field "Product/service name" with the ability to enter information about the paid order.
  • The field "Email" to enter an email address for sending a card receipt for payment.

As a result of clicking the "Go to payment" button the payer will be redirected to the standard WEBPAY payment page, where the buyer can enter the card details for payment and make the payment.

The results of payments and reports can be viewed and / or downloaded in the required format in the WEBPAY personal account in the corresponding section.

Отчет по оплатам, осуществленным по QR-коду

Merchant PCI DSS

For PCI DSS compliant merchants (who works with card data on the website pages or in application directly and want to use Host2Host integration) to make an integration with WEBPAY system, please, follow the instruction below. The formation of a standard POST request (according to Formation of an order for payment) + field wsb_encrypted_data. Also note that with this method of operation, the wsb_email field is required.

Name of the field Required field Description
wsb_encrypted_data yes This field contains encrypted JSON of the format {"cc_pan":"", "cc_exp":"", "cc_cvv":"", "cc_name":""}. Encrypted using the RSA algorithm using a public key from personal account.

Important!

When forming the wsb_signature field (the mechanism for generating of the signature is specified in Electronic signature of an order) the wsb_encrypted_data field is also involved. It is put in the end, before the Secret Key from the billing settings, when parameters are concatenated. Then a standard payment script occurs. The difference is only in the response format. The WEBPAY system gives the answer in JSON format.

Response fields

Fields Description
time The time of request
orderNumber The number of order
invoiceNumber The number of invoice
transaction Transaction Id
authorizationCode Authorization Code
Rrn The unique identifier of a bank transaction
trimPan Card number in the format 123456xxxxxx1234
payee Payment receiver
amount Payment amount
currency Payment currency
acsUrl Link for passing 3D-Secure
PaReq Parameter that is passed to the acs page
TermUrl Link for receiving response from acs page
MD Token for recovery the session after the acs page
tokenName The name of the token for recovery the payment session
token Token value for the recovery a payment session
availableOption The parameter contains possible values for the paymentType field. The list of values depends on the type of card and merchant settings. Possible values:
IpsPayment — ips terminal (default or, with routing turned on, a routed terminal)
halva — terminal of Halva
standard — terminal of Halva+ (payment in Belarusian rubles)
bonus — terminal of halva+ (bonus payment)
paymentType It is used when necessary to choose a payment option for cards. An empty value comes, it must be filled. Possible values for filling are taken from the availableOption field.
responseCode If an error occurs, contains an error code
responseText Contains an error desctiption

For payments by Halva+ card

WEBPAY in the response returns

Response example

{"token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a303458
79566e334b48526e592c","tokenName":"wt","availableOption":"ipsPayment,halva","paymentType":""}

If merchant receives such a response, he need to request a payment type from the client and send to WEBPAY a POST request with the following fields:

Request example

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

For payments with 3D-secure

WEBPAY in the response returns the filled fields acsUrl, PaReq, TermUrl, MD

Response example

{"token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345
879566e334b48526e592c",
"tokenName": "wt",
"acsUrl": "https://aacsw.3ds.verifiedbyvisa.com",
"PaReq":"eJxVUe1ugkAQfBXjA3gfSCtmvQSqrTTB2JbWyD88NoVUAQ9o5e17h1jtbmdvd2Z21kIU4U4f0PZKBQQYFXFnzjIktmQWRa3J1Y5FLB2XEo4BtVlRW5YCM64kAuUHcpmcZ5LSC
WR89fiTGzObs",
"TermUrl": "https://payment.webpay.by:443",
"MD":"d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=547159794b415849646e5242754b35545865694b5766726d62"}

Merchant sends a POST request to the URL that came in the acsUrl field with the parameters PaReq, MD and TermUrl.

Important!

Please, firstly replace the TermUrl field with your URL where the response from acs will be processed. When the response comes to your URL for process the response from acs, you need to send the WEBPAY POST request with the parameters that came from acs (in the response from acs, the PaRes field and MD-token comes by which the WEBPAY system will recover the payment session).

Request example

$params['PaRes'] = "effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c
4d5a30345879566e334b48526e592c";
$params['MD'] = "d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=547159794b415849646e5242754b3555865694b5766726d62";

WEBPAY receives the request, processes it, sends it to processing and returns the answer to the merchant

Response example

{"token":"ffc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444a4f5f39",
"tokenName":"wt",
"time":"2019.09.13 10:18:14",
"orderNumber":"test-1568359081",
"invoiceNumber":"138143506",
"transaction":"760583316",
"authorizationCode":"269412",
"rrn":"269412973762",
"trimPan":"417753xxxxxx1234",
"amount":"6,00",
"currency":"BYN",
"payee":"Test",
"acsUrl":"",
"PaReq":"",
"TermUrl":"",
"MD":"",
"responseCode":"",
"responseText":""}

Payment modules for payouts

General description

This guide describes the process of developing a payment modules for payouts (B2C and W2C) with using the WEBPAY system for Internet resources connected to Internet acquiring. The functionality is available when working through the acquiring Bank of OJSC "Belveb".

For depositing and payouts funds on your website the payer is allowed to using cards of payment systems MASTERCARD, VISA, BELKART issued by any Belarusian bank. Foreign cards are not allowed for payouts according to the rules of payment systems.

Scheme of work

The first refill of the account card binding (assignment token)

  1. The payer initiates the refill of the account.
  2. An Internet resource generates an authorization POST request and redirects the payer to the WEBPAY payment page, where the payer enters his cards (Formation of an order for payment).
  3. After filling in the necessary data by the payer, the WEBPAY system sends request to the acquirer bank for transactions and get a response on the results of passing.
  4. After receiving a response from the acquiring bank, the WEBPAY system sends to the Internet resource a notifier containing information about successful/error transaction. In the case of a successful operation, the notification will include the card token (a binding occurs by wsb_customer_id) and a card in the format 4***********1234).
  5. The Internet resource displays a card in the payer`s personal account in the format 4***********1234 (if it necessary).
  6. On its side, the Internet resource necessarily collects the information about a payer (full name and address).

Subsequent deposits to accounts

  1. If it`s necessary to make a new refill by the same payer, the Internet resource sends a new POST request to the WEBPAY system indicating wsb_customer_id.
  2. The WEBPAY system restores the payer`s card number, cardholder`s name, and expiration date. The payer only needs to enter the CVV/CVC code. Also for each deposit the payer passes 3D-Secure verification.

Payouts of funds from the payer`s account

  1. The payer in his personal account of the Internet resource initiates the payout of funds by selecting a card from the list (the list displays the payer`s cards in the format 4***********1234, from which he previously made a deposit to the account), to which the payout must be made.
  2. The payer indicates the amount he wants to payout funds.
  3. The Internet resource sends a request to the WEBPAY system, where it indicates the card token (any operation that took place for this wsb_customer_id), to which funds must be payout, also the Internet resource sends the information about the payer (full name and address. The fields are described in the table Description of table fields for B2C type of operation) when working with B2C type of operation or sends the information about the receiver and the sender ( Description of table fields for W2C type of operation).
  4. According to the received data, the WEBPAY system finds the payer`s card and makes request for payout to the acquiring Bank. The payer passes the 3D-Secure verification.
  5. The WEBPAY system gets the result of processing the request from the acquiring bank.
  6. After receiving the result from the acquiring bank, the WEBPAY system sends a notifier to the Internet resource containing the result of the payout operation.

The development of payment module

Operation type Documentation
Refill, card binding and subsequent refill Formation of an order for payment,
Simplified payment
Payout funds Service WSBApi (TransactionB2C request for operation type B2C or TransactionW2C for operation type W2C). Before using, you must inform the IP address from which will be sent a transaction request

Refill, card binding and subsequent refill

The Internet resource should send an authorization POST request to the WEBPAY system in accordance with Formation of an order for payment and Simplified payment. The card token is passed in the transaction_id field.

Payout funds

You should use the URL https://sandbox.webpay.by/WSBApi2 and TransactionB2C/TransactionW2C request (Service WSBApi) for testing B2C/W2C.

The addInfo field for operations B2C is a json string consisting of the values represented in the table.

The addInfo field for operations W2C is a json string consisting of the two objects senderData and receiverData with values represented in the table.

Description of table fields for operations type B2C

Tag Type Description Value Format
C1 T First Name ans ...35
C2 T Middle Name ans 1
C3 T Last Name ans ...35
C4 T Street Address ans ...50
C5 T City ans ...25
C6 T State/Province Code ans ...3
C7 T Country ans 3
C8 T Postal Code ans ...10

ans – alphabetic, numeric and special characters.

Code example

<TransactionB2C xmlns= "https://billing.webpay.by/WPPAPI-V0.2/">
  <parameters>
    <store_id>182612154</store_id>
    <login>test_bveb</login>
    <password>25f9e794323b453885f5181f1b624d0b</password>
    <transaction_id>805373075</transaction_id>
    <amount>22</amount>
    <currency>BYN</currency>
    <addInfo>{"C1":"LNAMES","C2":"V","C3":"LNAMES","CC":"00", "C4":"av. POBEDITELEY101","C5":"MINSK","C7":"112","C8":"220019"}</addInfo>
  </parameters>
</TransactionB2C>

Description of table fields for operations type W2C

Description of table fields senderData
Tag Type Description Value Format
C1 T First Name ans ...35
C3 T Last Name ans ...35
C4 T Street Address ans ...50
C5 T City ans ...25
C6 T State/Province Code ans ...3
C7 T Country ans 3

ans – alphabetic, numeric and special characters.

Description of table fields receiverData
Tag Type Description Value Format
C1 T First Name ans ...35
C3 T Last Name ans ...35

ans – alphabetic, numeric and special characters.

You should use a test card for testing, the data of test card you can get by contacting us by support@webpay.by.

The Internet resource should request the status of transaction using the get_transaction method (Payment verification) after receiving a response from the WEBPAY system.

Code example

<TransactionW2C xmlns= "https://billing.webpay.by/WPPAPI-V0.2/">
  <parameters>
    <store_id>182612154</store_id>
    <login>test_bveb</login>
    <password>25f9e794323b453885f5181f1b624d0b</password>
    <transaction_id>805373075</transaction_id>
    <amount>22</amount>
    <currency>BYN</currency>
    <addInfo>{"senderData":{"C1":"Company Name","C3":"IVANOV","C4":"st. Shafarnyanskaya, 11, of. 54","C5":"MINSK","C6":"BY","C7":"112"},"receiverData":{"C1":"IVAN","C3":"IVANOV"}}</addInfo>
  </parameters>
</TransactionW2C>

If multiple payouts are made with the same transaction_id the Internet resource can use the GetTransactionStatus (Service WSBApi).

In this example, the Internet resource should only replace the values in the fields: store_id, login, password, transaction_id.

Code example

$wsdl_url = 'https://sandbox.webpay.by/WSBApi2';
try {
  $soap_client = new SoapClient($wsdl_url, $defaultOptions);
} catch (SoapFault $e) {
  print $e->getMessage();
}
$params = array(
  'store_id'=> 'store_id',
  'login'=> 'login',
  'password'=>'password',
  'transaction_id'=> 'transaction_id',
  'order_num'=> 'order_num'
);
try {
  $r = $soap_client->GetTransactionStatus($params);
  print_r($soap_client);
  print_r($r);
} catch (SoapFault $exception) {
  print_r($soap_client);
  echo $exception;
}

API

Managing operations

The SDK and API description for managing card operations are available at the link https://github.com/WebpayDev/wsb-api-sdk

You can use the documentation to configure operation management yourself Service WSBApi or check the wsdl scheme https://sandbox.webpay.by/WSBApi2.

Important!

You should send a request to the WEBPAY support service at support@webpay.by to specify the IP address from which requests will be made.

Important!

If for any reason no response is received from the WEBPAY system we recommend to repeat the request with an increasing frequency of up to 1 hour. If the WEBPAY system has not returned a response, then mark such operations and send them to support@webpay.by.

Server SDK

Server SDK is a library in PHP for requests to the WEBPAY payment page. There is no need to create html form yourself. The server SDK is located at https://github.com/WebpayDev/payment-json-sdk.

An example request is posted here: https://github.com/WebpayDev/payment-json-sdk/blob/master/examples/simple_request.php.

Requests for reporting

The WEBPAY system provides two ways for receiving API reports from real environment personal account https://merchant.webpay.by:

  1. GET method.
  2. POST method.
When using the GET method the URL is formed according to the following scheme:

payment_module_url/reports/merchants/{reportType}?email=value_email_parameter&reportFormat=value_reportFormat_parameter&startDate=value_startDate_parameter&endDate=value_endDate_parameter

Header Authorization: login:password

When using the POST method the request is made to the following URL:

payment_module_url/reports/get

Important!

RESTRICTION: date range must be less than 3 months or the file must contain less than 100000 entries.

Code example

private String email;
private Integer login;
private String password (md5);
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private Date startDate;
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private Date endDate;


// Request sent by the POST method
{
  "login": "test",
  "password": "3434c7ab03ecfbde62ae697a7c66ae8e",
  "startDate": "2017-11-01",
  "endDate": "2017-12-31",
  "reportType": "RECONCILIATION_REPORT",
  "reportFormat" : "JSON"
}

Description of fields in request

  • payment_module_url — address for receiving the report. Possible value:
  • reportType — type of the report. Possible value:
    • RECONCILIATION_REPORT — reconciliation report,
    • RECEIPT_OF_FUNDS — receipt of funds,
    • ERIP_PAYMENT_RESULTS — ERIP payment results,
    • ERIP_TRANSACTION_LOG — ERIP transaction log.
  • email — email address to which the report can be sent. The report will be received via specified email with a delay (up to 10 minutes) after the required information is downloaded from data base.
  • reportFormat — format of the report. Possible value:
    • JSON — the report will be sent in JSON format,
    • EXCEL — the report will be sent as an .xlsx file.
  • startDate, endDate — range of dates.
  • login — login from personal account.
  • password — password from personal account encrypted in MD5.

Remote identification system IDCHECK

General information

All API requests are sent over the HTTPS POST protocol. The response is returned in json format. Authentication is performed by signing a request based on a personalized api key (api_key), more information about the signing mechanism is specified in the corresponding request parameter.

Example of a Workflow process:

IDCheck workflow

API methods

  • WEBcheck — verification execution in a web application;
  • mobileCheck — verification execution in a mobile application;
  • fileCheck — verification execution by uploading documents via the API;
  • getStatus — getting the verification status;
  • getResult — getting the verification results;
  • getDoc — getting a verified document;
  • unarchiveDocs — request for the return of documents transferred to the archive;
  • testCompleted — complete testing;
  • apiStatus — service operation status.

WEBcheck

Passing the verification via the web form.

Executed by the applicant who should be redirected to the url: <>/request_id. Where request_id and the corresponding form is generated after executing this request.

Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: WEBcheck
3 check_id yes string unique verification ID is determined by the client. Format: [0-9a-zA-Z\-\ _]{1,100}
4 flow_name no string name of the identification scheme. Format: [0-9a-zA-Z\-\ _\+]{1,100}
5 lang no string the language of the form in the format ISO 639-1. Available list of languages: ru, en, et, pt, hu, zh, zh-tw, th, id, es, tr, vi, ar, hi, ms, ur, bn, fa, fl, fr, ja, ko, uk, ro. By default: ru
6 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method+check_id
Response:
# Parameter Required Type Description
1 request_id yes string request ID

Request example

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=WEBcheck&check_id=30&sign=75c8a65f407f7180f6a2a3952a7924d4963cd702d5d80bbe564c"

Response example

{
  "request_id": "b19a6c370693218ef0a4b06308fc0a5de32e86e"
}

mobileCheck

Passing the verification via the mobile application.

The method is necessary to create a verification (applicant) and a primary access token, which is required for initializing the SDK. The token validity period is 1 hour. The token update is present in the SDK. Documentation and access to the SDK (Android & iOS) are issued by agreement.

Proposed mobile application operating schema:

mobile check method
  1. Initializing the mobile SDK and data request (token and, if necessary, flow verification)
  2. Request for a token by the specified applicant ID (request_id)
  3. Getting data (token) by the client's backend
  4. Getting initialization data by a mobile application
  5. Passing the verification by the applicant
Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: mobileCheck
3 check_id yes string unique verification ID is determined by the client. Format: [0-9a-zA-Z\-\ _]{1,100}
4 flow_name no string name of the identification scheme. Format: [0-9a-zA-Z\-\ _\+]{1,100}
5 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method+check_id
Response:
# Parameter Required Type Description
1 request_id yes string request ID
2 token yes string request token (passed to the SDK)

Request example

curl -X POST \ \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=mobileCheck&check_id=31&sign=9e50358233f8af3ae7b005f8d9db8009ea339145bd8309324afd20079b"

Response example

{
  "request_id": "1b0e72851da3f5653edbdada200fa7f1759a",
  "token": "_act-10bd541d-499c-98f3-aa10b64998b50"
}

fileCheck

Sending documents without the participation of the applicant.

This method can be combined with all the methods of creating a request or passing verification. For example, you can upload a document without the participation of the applicant, who will then be offered to pass only a liveliness check (including a check for a match with the document) in the web or mobile sdk.

Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: fileCheck
3 check_id yes string unique verification ID is determined by the client. Format: [0-9a-zA-Z\-\ _]{1,100}
4 flow_name no string name of the identification scheme. Format: [0-9a-zA-Z\-\ _\+]{1,100}
5 doc_file yes binary document file
6 doc_type yes string document type
7 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method+check_id
Possible types of documents:
Document type Description
PROFILE_IMAGE photo of the applicant (usually used in the verification of liveliness)
PASSPORT passport
Response:
# Parameter Required Type Description
1 request_id yes string request ID
2 upload_status yes string file upload status
Possible statuses:
Status Description
ok successful upload
warning the document file has accepted, but a preliminary check revealed problems with the document
error the file has not accepted

Request example

curl -X POST \
  'https://idcheck-sandbox.webpay.by/api/1.0/post/' \
  -H 'Content-Type: multipart/form-data' \
  -F 'method=fileCheck' \
  -F 'client_id=1' \
  -F 'flow_name=Liveness+Photo' \
  -F 'check_id=user10' \
  -F 'doc_type=PROFILE_IMAGE' \
  -F 'sign=56a74f6a2a3952aaddd963cd7502d55d80bb54e564c' \
  -F 'doc_file=@/var/www/docs/10.jpg'

Response example

{
  "request_id": "acc3421448ef083dde332f3a92105066db",
  "upload_status": "ok"
}

getStatus

Getting the verification status.

Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: getStatus
3 request_id yes string request ID
4 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method+request_id
Response:
# Parameter Required Type Description
1 status yes string verification status
Description of possible response statuses:
Status Description
new new verification request
in_progress documents are being checked
completed verification is complete
canceled the check was canceled (all documents were not uploaded or timeout has expired)

Request example

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=getStatus&request_id=b19a6c370693218ef0a4b06308fc0a5de32e86e&sign=g546cbc1268d886edcc300fb05e1550d91b2a06a7c494c4a85899b830b"

Response example

{
  "status": "in_progress"
}

getResult

Getting the verification results.

The results are also sent to the postback, which additionally contains the sign. The request format is formdata (by default) or json at the client's choice.

Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: getResult
3 request_id yes string request ID
4 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method+request_id
Response:
# Parameter Required Type Description
1 check_id yes string verification ID
2 result yes string verification result: GREEN | RED
3 reject_labels no array one or more reasons for reject of verification (reject_labels table)
4 reject_final no int ability to resend documents for verification; 1 — final reject. Values: 0 | 1
5 review_date yes string date and time of passing the verification (ISO 8601 format: YYYY-MM-DDThh:mm:ss±hh:mm)
6 applicant_summary_info no array the applicant's general data collected from possible sources. This data can be set or redefined by the client or the applicant
applicant_summary_info[].firstName no string first name
applicant_summary_info[].firstNameEn no string transliteration of the first name
applicant_summary_info[].lastName no string last name
applicant_summary_info[].lastNameEn no string transliteration of the last name
applicant_summary_info[].middleName no string middle name
applicant_summary_info[].middleNameEn no string transliteration of the middle name
applicant_summary_info[].legalName no string legal name
applicant_summary_info[].gender no string Sex of a person: M | F
applicant_summary_info[].dob no string date of birth (format: YYYY-mm-dd)
applicant_summary_info[].placeOfBirth no string place of birth
applicant_summary_info[].countryOfBirth no string country of birth
applicant_summary_info[].stateOfBirth no string state of birth
applicant_summary_info[].country no string Alpha-3 country code (Wikipedia)
applicant_summary_info[].nationality нет string Alpha-3 country code
applicant_summary_info[].phone no string phone number
applicant_summary_info[].mobilePhone no string mobile phone number
applicant_summary_info[].applicant_platform no string applicant's device
applicant_summary_info[].addresses no array list of addresses
applicant_summary_info[].addresses[].country no string Alpha-3 country code
applicant_summary_info[].addresses[].postCode no string postal code
applicant_summary_info[].addresses[].town no string town or city name
applicant_summary_info[].addresses[].street no string street name
applicant_summary_info[].addresses[].subStreet no string additional street information
applicant_summary_info[].addresses[].state no string state name
applicant_summary_info[].addresses[].buildingName no string building name
applicant_summary_info[].addresses[].flatNumber no string flat or apartment number
applicant_summary_info[].addresses[].buildingNumber no string building number
applicant_summary_info[].addresses[].startDate no string start date of stay in current building (format: YYYY-mm-dd)
applicant_summary_info[].addresses[].endDate no string end date of stay in current building (format: YYYY-mm-dd)
7 docs_data no array extracted document data
docs_data[].idDocType yes string document type (PASSPORT, ID_CARD, DRIVERS, SELFIE, VIDEO_SELFIE)
docs_data[].idDocSubType no string side of the document (FRONT_SIDE, BACK_SIDE or null)
docs_data[].idsDoc yes array array of document file names (an array element is a parameter doc_id of the method getDoc)
docs_data[].country no string 3-letter country code
docs_data[].firstName no string first name
docs_data[].firstNameEn no string transliteration of the first name
docs_data[].lastName no string last name
docs_data[].lastNameEn no string transliteration of the last name
docs_data[].middleName no string middle name
docs_data[].middleNameEn no string transliteration of the middle name
docs_data[].issueAuthority no string the issuing authority of the document
docs_data[].issuedDate no string issued date
docs_data[].validUntil no string valid until date
docs_data[].number no string document number
docs_data[].dob no string date of birth
docs_data[].placeOfBirth no string place of birth
docs_data[].mrzLine1 no string data from the document that is not related to the key group that was recognized
8 is_archived yes int parameter describes the status of transferring documents to the archive. Values: 0 | 1
9 data_deleted yes int the status of the deletion of personal data. If the applicant's personal data has been deleted, the result will not contain the parameters docs_data and applicant_summary_info. Values: 0 | 1
Description of possible statuses reject_labels:
Value Description
FORGERY Forgery attempt has been made
DOCUMENT_TEMPLATE Provided documents are templates, downloaded from the Internet
NOT_DOCUMENT Provided documents are not related to the verification procedure*
SELFIE_MISMATCH User photo (profile image) does not match a photo on the provided documents
ID_INVALID Document that identifies a person (like a passport or an ID card) is not valid*
FOREIGNER There is no residence permit or client does not accept applicants from a different country
DUPLICATE Duplicates are not allowed and this applicant has already been checked
WRONG_USER_REGION When applicants from certain regions/countries are not allowed to be registered
INCOMPLETE_DOCUMENT Some information is missing from the document, or it's partially visible
BLACKLIST User is blacklisted
UNSATISFACTORY_PHOTOS Some information is hidden or the quality of the photo is poor*
DOCUMENT_PAGE_MISSING Some pages of a document are missing*
DOCUMENT_DAMAGED Document is damaged*
REGULATIONS_VIOLATIONS Regulations violations*
INCONSISTENT_PROFILE Gender mismatch (for example, a female name with male documents)
PROBLEMATIC_APPLICANT_DATA Applicant data does not match the data in the documents*
ADDITIONAL_DOCUMENT_REQUIRED Additional documents required*
AGE_REQUIREMENT_MISMATCH Age requirement is not met (e.g. cannot rent a car to a person below 25yo)
EXPERIENCE_REQUIREMENT_MISMATCH Not enough experience (e.g. driving experience is not enough)
CRIMINAL The user is involved in illegal actions
WRONG_ADDRESS The address from the documents doesn't match the address that the user entered*
GRAPHIC_EDITOR The document has been edited by a graphical editor*
DOCUMENT_DEPRIVED The user has been deprived of the document
COMPROMISED_PERSONS The applicant was compromised
FRAUDULENT_PATTERNS Fraudulent behavior was detected
SANCTIONS The user was found on sanction lists
FRONT_SIDE_MISSING Front side of the document is missing*
BACK_SIDE_MISSING Back side of the document is missing*
SCREENSHOTS Screenshots uploaded*
BLACK_AND_WHITE Black-and-white photos of documents have been uploaded*
INCOMPATIBLE_LANGUAGE The user should upload translation of his document*
EXPIRATION_DATE Expired document*
UNFILLED_ID The document without signatures and stamps*
BAD_SELFIE The user uploaded a bad selfie*
BAD_VIDEO_SELFIE The user uploaded a bad video selfie*
BAD_FACE_MATCHING Face check between document and selfie failed*
BAD_PROOF_OF_IDENTITY The user uploaded a bad ID document*
BAD_PROOF_OF_ADDRESS The user uploaded a bad proof of address*
BAD_PROOF_OF_PAYMENT The user uploaded a bad proof of payment*
SELFIE_WITH_PAPER The user should upload a special selfie (e.g. selfie with paper and date on it)*
OTHER Some unclassified reason

* — reject_final=0 you can use the same request_id to re-upload documents by the applicant.

Request example

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=getResult&request_id=b19a6c370693218ef0a4b06308fc0a5de32e86e&sign=456h9f69491724f43fddedfc00750d0efbd540d4ec0538ceaa27d3316bd52"

Response example

{
  "check_id": 30,
  "result": "GREEN",
  "review_date": "2020-01-23T17:36:26+03:00",
  "is_archived": 0,
  "applicant_summary_info": {
    "firstName": "ВЛАДИМИР",
    "firstNameEn": "VLADIMIR",
    "middleName": "АЛЕКСЕЕВИЧ",
    "middleNameEn": "ALEXEYEVICH",
    "lastName": "ПЕТРОВ",
    "lastNameEn": "PETROV",
    "dob": "1986-03-18",
    "gender": "M",
    "placeOfBirth": "REPUBLIC OF BELARUS",
    "country": "BLR",
    "applicant_platform": "Android"
  },
  "docs_data": [
    {
      "idDocType": "PASSPORT",
      "country": "BLR",
      "firstName": "ВЛАДИМИР",
      "firstNameEn": "VLADIMIR",
      "middleName": "АЛЕКСЕЕВИЧ",
      "middleNameEn": "ALEXEYEVICH",
      "lastName": "ПЕТРОВ",
      "lastNameEn": "PETROV",
      "issuedDate": "2018-11-24",
      "validUntil": "2028-11-24",
      "number": "KB00001",
      "additionalNumber": "000001PB2",
      "dob": "1986-03-18",
      "placeOfBirth": "REPUBLIC OF BELARUS",
      "idsDoc": [
        45001,
        27686705
      ]
    },
    {
      "idDocType": "SELFIE",
      "idsDoc": [
        435890
      ]
    }
  ]
}

getDoc

Getting a verified document.

Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: getDoc
3 request_id yes string request ID
4 doc_id yes string document ID
5 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method+doc_id
Response:

The document file, the Content-Type header of the response will describe the mime type.

Request example

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=getDoc&request_id=b19a6c370693218ef0a4b06308fc0a5de32e86e&doc_id=45001&sign=fg546cbc12685486edcc305e1550d91b2a06a7c494c4219b830b"

unarchiveDocs

Return documents from the archive.

After the execution, it will be possible to get the documents again using the methodgetDoc.

Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: unarhiveDoc
3 request_id yes string request ID
4 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method+request_id
Response:
# Parameter Required Type Description
1 status yes string status
Description of possible response statuses:
Status Description
in_progress documents in the process of transferring
completed transfer completed

Request example

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=unarchiveDocs&request_id=b19a6c370693218ef0a4b06308fc0a5de32e86e&sign=fe1080d9642cd761fb6b4506b38e8f2755e0df1da6504a59e55d3aea94"

Response example

{
  "status": "in_progress"
}

testCompleted

Completes the identification with the preset result. Available only in the test environment.

Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: testCompleted
3 request_id yes string request ID
4 test_result yes string with what result to complete the check: GREEN | RED
5 reject_label no string reason for reject the verification failure(RED status) (reject_labels table)
6 reject_final no Int the state of the final value failure: 0 | 1. By default: 1 (final)
7 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method+request_id
Response:
# Parameter Required Type Description
1 status yes string status (done)

Request example

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=testCompleted&request_id=a19a6c370693218ef0a4b06308fc0a5de32e86e&test_result=GREEN&sign=fe1080d9642cd761fb6b4506b38e8f2755e0df1da6504a59e55d3aea94"

Response example

{
  "status": "done"
}

apiStatus

Service operation status.

Request:
# Parameter Required Type Description
1 client_id yes string client ID
2 method yes string API method: apiStatus
3 sign yes hash the request signature is a sha256 hash of a string, which is a concatenation of the values of the following parameters: api_key+method
Response:
# Parameter Required Type Description
1 status yes int service status, static response (200)

Request example

curl -X POST \
  https://idcheck-sandbox.webpay.by/api/1.0/post/ \
  -d "client_id=1&method=apiStatus&sign=33cbc277c9cfe9a91ead1145c1c6670ba4bcddbc0294d13b76f1b69eca1fc5b7"

Response example

{
  "status": "200"
}

Errors

If an error occurs, the response contains the error parameter with the error code.

Errors description:
Error Description
400 Invalid request
401 Authentication error
404 The requested entity was not found
405 Incorrect request method
406 The request cannot be executed with the current conditions
409 Incorrect data was passed for verification
429 Too many requests
503 The service is temporarily unavailable

Test environment

The test environment has the same functionality as the production, except that the documents are not checked. Additionally, the testCompleted method for generating the desired response is presented.