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:

The app's main screen

There is main statistics about your billing account shown on this page. Here you also can 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 except for the sign &.

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. Setting SecretKey

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.

Вход в личный кабинет WEBPAY

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 Invoice section by pressing the "Invoice" 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.
  • 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.

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.

Parameters of WEBPAY Personal Cabinet

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" в меню "Settings" → "Users" menu.

Добавление учетной записи

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;
  • E-mail;
  • 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.

Create 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 "Confirm" 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. hen 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 information

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 E-mail, 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 invoices issued

Additional information will be shown after clicking an invoice:

Additional information about invoices issued

Payments log

All payment attempts, 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 3-D 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.

Transaction log

Accounting for completed payments

To get a report about payment made through AIS "Raschet" (ERIP) and 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 .xls files or in JSON format without entering the system. Please, get acquainted with API for receiving reports to learn how to activate that feature.

Logging 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 Name
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 funds transferring will show up.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 blocked on the payer's card;

Partial authorization reset – Part of the funds is unblocked on the payer's card;

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 An 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 receiving funds to your operating account. 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 The date when funds reception by the Store's operation account was reflected.
Amount to transfer Total amount (minus the commission) that goes to the Store's operation account.
Transfer currency The currency in which funds are credited.
Trader's order number An 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;
Возможности для изменений платежной страницы

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

The list of available fonts will be expanded.

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

Bill 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 "Order amount" 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" type.

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 "Paid" field. The transaction gets the "Completed" type.

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

Voided

Partial refunded – a partial refund to the buyer's card account was initiated. The amount in the "Paid" field is equal to the difference between the order and return amount. The transaction gets the "Refunded" type.

Partial refunded

Refunded - full refund to the buyer's card account was initiated. The amount in the "Paid" eld is equal to zero. The transaction gets the "Refunded" type.

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 "Waiting for payment", "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" либо "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

Test environment URL: https://sandbox.webpay.by
Login: sent via e-mail
Password: sent via e-mail
Unique store ID (wsb_storeid): sent via e-mail

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:

Test https://securesandbox.webpay.by
Real https://payment.webpay.by

IMPORTANT In real environment requests to https://payment.webpay.by must be performed from domain name stated in an 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:

Test https://sandbox.webpay.by
Real https://billing.webpay.by

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 e-mail 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.

Payment module development

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.

Principle of formation of an order and payment for it

  1. Formation of an order. Creation of 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 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 (WEBPAY system will send a notification (Charge announcement);
  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 form with specific fields (fields values and descriptions are presented in the Payment form fields) and redirect a customer to a payment page by POST method. Specify https://securesandbox.webpay.by for testing or https://payment.webpay.by for real transactions.

Payment form fields

Main payment form fields

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 e-mail.
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 standart. 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)

See: Charge announcement.
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.

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="338d1647833079f9353907ad266ec0bb5264c0d9">
  <input type="hidden" name="wsb_tax" value="1050">
  <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>
              
            

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 "-").
wsb_discount_promo_code no Discount promo code value. 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 e-mail 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

IMPORTANT! All text fields must be filled with text in UTF-8 or windows-125 charset.

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.

Example form

            
            
$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_urlfield. 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 (Charge announcement).

Order payment

Charge announcement

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

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.

Successful payment notification receipt

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:

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

order_id Order number in 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

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.

Example form

              
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}
              
            

SOAP tool

For SOAP tool (may be enabled by request) 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.

Example form

              
<?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:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>
              
            

Example of a request in accordance with the scheme

Example form

              
<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:OrderTag>onlinePayment</ns2:OrderTag>
      </ns2:NotifierRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
              
            

Website should check received data in accordance with order execution requirements and answer with code:

Example form

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

Example form

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

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

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

Example form

              
// API Request
$postdata = '*API=&API_XML_REQUEST=''.urlencode('
  <?xml version="1.0" encoding="ISO-8859-1" ?>
    <wsb_api_request>
      <command>get_transaction</command>
      <authorization>
        <username>your_username</username>
        <password>your_md5_password</password>
      </authorization>
      <fields>
        <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;
              
            

Transaction types

There are following transaction groups by transaction type (payment_type field):

Type Value Value
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 Value
1 Completed Completed
4 Authorized Authorized
10 Recurrent Recurring payment (CoF)

And these are types for refunded payments:

Type Value Value
5 Partial Refunded Partial Refunded
7 Voided Void after authorization
9 Partial Voided Partial Void
11 Refunded 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

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 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, e-mail 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

IMPORTANT! To activate this service, please contact your manager managers@webpay.by

In order to implement "Simplified payments" service provider just needs to make minimal adjustments to POST-request of order form (See: Payment module development). 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.

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.

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="86832487d9996b0f863bcd655023a281ac88727d">
  <input type="hidden" name="wsb_shipping_name" value="Shipping costs">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Discount">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_customer_id" value="1234567">
  <input type="submit" value="Buy">
</form>
              
            

Recurring payment

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.

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.

Requests

Additional fields

For 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 it is obligatory to 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.

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="9418af1d506f8f8da1dc577278a1f0d89eecc66d">
  <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 e-mail 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/BELCARD 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 accoun
recurring_token Card binding token meant for future recurring (CoF) payments executinon
offer_exp_date Card's expiration date in YYYY-MM-DD format (e.g. 2016-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.

Recurring payment (Credential on File)

The following alterations are made to a request form in comparison with a form for initiating 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.

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="d0a6ec427fc2e0b5c90729606ee819e2684b9824">
  <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="Buy">
</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_datefield and this filed is not included into combination for signature calculation.

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

Example form

              
//Response about a successful recurring payment
Content-Type: application/x-www-form-urlencoded
batch_timestamp=1586712564¤cy_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¤cy_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

The request form for unbinding the card from recurring (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.

Example form

              
<!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="Отказ от подписки на рекуррентные платежи">
    </form>
    </body>
</html>
              
            

Notification after unbinding card from the recurrent payments

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

Example form

              
//Exaple 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: Card payments). In advance you should send an inquiry to WEBPAY support to support@webpay.by specifying IP address that will be used to send requests. Dependin 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

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 standard authorization (POST) request in accordance with Payment module development.

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 months 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 don'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 don'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.

Выбор способа оплаты при карет ИКС карта

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="2e45588afe41be5372af7a250628dd03846d8e30">
  <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 Payment module development. 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 Paste 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.

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 VISA/MASTERCARD premium cards (Gold, Platinum, Infinite). If customer wants to use one of the VISA/MASTERCARD 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 VISA or MASTERCARD premium cards on the service provider's side, WEBPAY controls the payment to be made with the specified card type
  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
  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/MASTERCARD Gold gold
VISA/MASTERCARD Platinum platinum
VISA/MASTERCARD Infinite infinite
VISA visa
MASTERCARD (Maestro and BELKART-MAESTRO cards are not included) mastercard

For example, if you choose to pay with a premium VISA/MASTERCARD 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.

Example form

              
<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="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="21.90">
  <input type="hidden" name="wsb_signature"
  value="338d1647833079f9353907ad266ec0bb5264c0d9">
  <input type="hidden" name="wsb_tax" value="1050">
  <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="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 one described in Payment module development 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
MASTERCARD Gold 510116
MASTERCARD Platinum 511278

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 a standard authorization (POST) request (Payment module development). 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.

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

Example form

              
<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="21.90">
  <input type="hidden" name="wsb_signature"
  value="338d1647833079f9353907ad266ec0bb5264c0d9">
  <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;Commodity 1;01.12.2017 16:51:29;1.86;Ivanov Ivan

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

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

  1. Successful invoicing Successful invoicing
  2. Error Error invoicing Notification about a non-unique file

FTP setup

Parameters of our 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:

Пример настроек FTP

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 "E-mail". 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" field can be generated automatically after successful invoice creation. 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". 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;

    Payment page for Internet acquiring
  • If you have payment receiving through AIS "Raschet" (ERIP) connected;

    Payment page for ERIP
  • If you have both payment variants on your billing account (bank card and AIS "Raschet" (ERIP)).

    Payment page for Internet acquiring and 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

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 Payment module development) + field wsb_encrypted_data.

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 a public key from your personal account.

* 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. We give 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

Example form

              
{"token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=7344
4a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345879566e334b48526
e592c",
"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 us a POST- request with the following fields:

Example form

              
$params['wt'] = "effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05
fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345879566e
334b48526e592c";
$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

Example form

              
{"token":"effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=7344
4a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345879566e334b48526
e592c",
"tokenName": "wt",
"acsUrl": "https://aacsw.3ds.verifiedbyvisa.com",
"PaReq":"eJxVUe1ugkAQfBXjA3gfSCtmvQSqrTTB2JbWyD88NoVUAQ9o5e17h1jtbmdvd2Z21kIU4U
4f0PZKBQQYFXFnzjIktmQWRa3J1Y5FLB2XEo4BtVlRW5YCM64kAuUHcpmcZ5LSCWR89fiTGzObs",
"TermUrl": "https://payment.webpay.by:443",
"MD":"d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=54715979
4b415849646e5242754b35545865694b5766726d62"}
              
            

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

* 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 a WEBPAY POST-request with the parameters that came from acs (in the response from acs, the PaRes field and MD-token comes by which we will recover the payment session).

Example form

              
$params['PaRes'] = "effc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a
05fcf=73444a4f5f39324b764b767476517876622d647372676b49744444534c4d5a30345879566
e334b48526e592c";
$params['MD'] = "d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae
80=547159794b415849646e5242754b3555865694b5766726d62";
              
            

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

Example form

              
{"token":"ffc84c25f202e28dd96b3197d682bfe611dd2e8e67233f46114094940a05fcf=73444
a4f5f39",
"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":""}
              
            

Managing operations

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

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.

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

Example form

              
{"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",
"unit":"ww.",
"quantity":"1",
"price":{
"currency":"BYN",
"amount":130.10}},
{"idx":2,
"name":"Product 2",
"unit":"qt.",
"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.

Example form

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

WEBPAY response to an error

Example form

              
{"errorCode":"BAD_REQUEST",
"errorMessage":"resourceId: Resource not found or disabled"}
              
            

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 – he 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://sandbox.webpay.by/woc/order
QUERYSTRING no 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

Example form

              
<?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+ZW6cj
tOWKr51o0stKbfWxnsRjLxGgT9s+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";?>
              
            

Request structure for getting data reports

Request should be sent to the following URLs:

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

Example form

              
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;
              
            

Reports formats

Report from WEBPAY system may be recieved in two formats:

  • JSON
  • EXCEL-file

The report will be recieved via specified e-mail with a delay (up to 10 minutes) after the required information is downloaded from data base.

Example form

              
// JSON
{
  "login": "test",
  "password": "3434c7ab03ecfbde62ae697a7c66ae8e",
  "startDate": "2017-11-01",
  "endDate": "2017-12-31",
  "reportType": "RECONCILIATION_REPORT",
  "reportFormat" : "JSON"
}

//EXCEL-file
{
  "email": "test@webpay.by",
  "login": "test",
  "password": "3434c7ab03ecfbde62ae697a7c66ae8e",
  "startDate": "2017-11-01",
  "endDate": "2017-12-31",
  "reportType": "RECONCILIATION_REPORT",
  "reportFormat" : "EXCEL"
}
              
            

Reports types

WEBPAY system is capable of sending the following report types:

  • RECONCILIATION_REPORT - reconsiliation report;
  • RECEIPT_OF_FUNDS - receipt of funds;
  • ERIP_PAYMENT_RESULTS - ERIP payment results;
  • ERIP_TRANSACTION_LOG - ERIP transaction log.