Basic information

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

Development procedure

Take a close look at present guide.
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.
Get familiar with Sandbox interface and fill in required fields (Company profile).
Proceed with payment module development in accordance with present guide.
Test out your module.
Receive a letter with new parameters for payment module transition from test environment into real payment system (Transition from test into real environment).
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:

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

Secret key installation

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

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.

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.

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.

Important!

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

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

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

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.

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.

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.

To create a new user, click on the "Add User" button in the "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,
email,
country,
state,
ZIP code,
city,
address,
password,
password confirmation.

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

administrator,
buyer,
system account,
guest.

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

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

Press "Save" button to finish account creation.

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

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

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.

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

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

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.

Additional information will be shown after clicking an invoice:

Additional information about issued invoices

Payments log

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

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

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

Accounting for completed payments

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

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

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

Name	Description
Payment status	Payment processing result. Possible values: Successful payment — the WEBPAY system did confirm the payment success; Payment error — the WEBPAY system did NOT confirm the payment success; NOT confirmed by WEBPAY — ERIP reconciliation report contains information about a non-existent operation.
Reconciliation status	WEBPAY data reconciliation status with the data from ERIP reports. Possible values: Not confirmed by the bank (ERIP) — confirmation of a successful transaction in the WEBPAY system has NOT been received from ERIP; Successful reconciliation — confirmation of a successful transaction in the WEBPAY system has been received from ERIP; Reconciliation error — confirmation of a successful transaction in the WEBPAY system has been received from ERIP, but there is a discrepancy in the payment parameters.
Payment time	Date of the payment performed in the WEBPAY system.
Business account	Value that identifies the consumer of a commodity or service.
ERIP request ID	Single identifier for the requests sequence for ERIP payments.
ERIP transaction ID	Operation account number in the ERIP central unit.
Number of service	Service number of the Store.
Settlement agent code	Three last numbers of the settlement agent`s sort code.
Amount	Payment amount in the WEBPAY system.
Currency	Payment currency in the WEBPAY system.
Authorization type	Payment method. Possible values: MS — card with a magnet stripe. BC — BELCARD card. NONE — the payer is not identified. CASH — payment in cash in the Cash Settlement Center. CASHIN — payment in cash in the payment and inquiry terminal.
WEBPAY transaction ID	ERIP identifier in the context of payment requests.
Message dispatcher code	Regional node subscriber`s code.
Message number	ERIP message number.
Message formation date	ERIP message forming date.
Payment document number	ERIP payment document number.
Funds transfer date	Funds transfer date according to ERIP data.
Settlement agent`s business account	Settlement agent`s business account from which was performed the settlement with service provider.
Transferred amount	Amount transferred for the current payment according to the ERIP data.
Currency	Currency of the current ERIP payment.
Transaction date	Transaction date by the ERIP data.
Transaction number in the Account agent	ERIP operation number in the Account agent.
Amount Authorization Tool	Information about payment tool.

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

Service Info,
Transaction Start,
Transaction Result.

Funds refund is performed in two stages:

Storn Start,
Storn Result.

Report fields description

Name	Description
Request ID	Single identifier for the requests sequence for ERIP payments.
Operation status	The result of operation. Possible values: Successful operation — the WEBPAY system did confirm the operation success. Execution error — the WEBPAY system did NOT confirm the operation success. Duplicate operation — the WEBPAY system already contains this operation.
Operation Type	Type of operation in accordance with ERIP protocol: SERVICE_INFO — receiving the order data. TRANSACTION_START — start of the order payment. TRANSACTION_RESULT — order payment result. STORN_START— start of the refund request. STORN_RESULT — refund request result.
Request date	Date of forming the request to ERIP.
ERIP transaction ID	Operation account number in the ERIP central unit.
WEBPAY transaction ID	ERIP identifier in the context of payment requests.
WEBPAY business account	Value that identifies the consumer of a commodity or service.
Number of service	Service number of the Store.
Amount	Payment amount in the WEBPAY system.
Currency	Payment currency in the WEBPAY system.
Authorization type	Type of funds authorization when order is paid.
Settlement agent	Settlement agent`s code.

Accounting for transactions made through Internet-acquiring

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

Report fields description

Name	Description
Invoice status	The result of payment processing. Possible values: Authorization — funds is blocked on the payer`s card. Authorization reset — funds is unblocked on the payer`s card. Partial authorization reset — part of the funds is unblocked on the payer`s card. Completion — funds debited from the payer`s account. Full refund — funds was written-off from the Store`s operation account and returned to the payer`s card. Partial refund — part of the funds was written-off from the Store`s operation account and returned to the payer`s card.
Reconciliation status	WEBPAY data reconciliation status with the data from the bank reports. Possible values: Not confirmed by the bank — confirmation of a successful transaction in the WEBPAY system has NOT been received from the bank. Successful reconciliation — confirmation of a successful transaction in the WEBPAY system has been received from the bank. Reconciliation error — confirmation of a successful transaction in the WEBPAY system has been received from the bank, but there is a discrepancy in the payment parameters.
Merchant ID	Store`s ID in the WEBPAY system.
Merchant`s website	Website connected to the WEBPAY system.
Merchant`s order number	Unique order identifier specified by the Store.
WEBPAY order number	Order number in the WEBPAY system.
Terminal number	Terminal number set by the acquiring bank.
Processing	Acquiring bank processing number.
Transaction amount	The amount of the order in the Store excluding the discount amount and the delivery amount.
Discount amount	The discount amount set by the Store.
Discount name	Description of the discount specified by the Store.
Shipping cost	The shipping cost set by the Store.
Shipping name	Description of the delivery specified by the Store.
Date and time of the authorization	The date of the payment in the WEBPAY system.
Authorization amount	Payment amount in the WEBPAY system.
Currency of the operation	The currency of the payment in the WEBPAY system.
Payment system	The name of the payment system of the payer's bank payment card.
Card description	Payer`s bank payment card level.
Acquiring bank processing RRN	A unique transaction number assigned by the processing center.
Authorization code of the issuing bank	The authorization code assigned by the issuing bank.
Date and time of financial completion	The date of financial completion of the payment in the WEBPAY system.
The amount of financial completion	The amount of financial completion of the payment in the WEBPAY system.
Date of registration of the payment in the bank	The date of reflection of funds in the acquiring bank.
Amount of payment reimbursement	The amount of payment in the WEBPAY system.
Commission amount	Commission fee to the bank.
Currency of payment accounting at the bank	The currency in which the funds are reflected in the bank.
Date and time of cancellation/return	The date and time of cancellation/refund of the payment in the WEBPAY system.
Cancellation/Refund amount	The amount of cancellation/refund of the payment in the WEBPAY system.
The date of registration of the refund in the bank	The date when the refund is reflected in the acquiring bank.
Refund amount in the bank	The amount of reflection of the refund in the acquiring bank.
Commission refund amount	Commission fee to the bank for making a refund.
Merchant`s amount	The amount of debit from the payer`s bank payment card, if the transaction currency in the Store differs from the currency on the payer`s bank payment card.
Merchant`s currency	The currency of the debit from the payer`s bank payment card, if the transaction currency in the Store differs from the currency on the payer`s bank payment card.
Merchant`s currency exchange rate	The conversion rate set by the payment system/acquiring bank, when debiting funds from the payer`s bank payment card, if the transaction currency in the Store differs from the currency on the payer`s bank payment card.
Payer`s address	The address of the payer passed by the Store to the WEBPAY system.
Sender of funds	Information about the payer passed by the Store to the WEBPAY system.
Contract number with the service customer/payer	The number of the contract with the customer of the service/payer passed by the Store to the WEBPAY system.
Purpose of payment	The purpose of the payment passed by the Store to the WEBPAY system.
Payer`s email	The email address specified by the payer during the payment.
Recurring payment	The type of recurrent payment. Possible values: Initiating — the binding of the payer's bank payment card was carried out. Recurring — payment was made using the payer`s previously binded bank payment card.
Issuing bank	The bank that issued the bank payment card of the payer.
Issuing bank country	The country of the bank that issued the bank payment card of the payer.
Payout	Money withdrawal operation. Possible values: Yes — the withdrawal operation has been performed. No — the payer has paid for Store services/goods.
Card number 6x4	Masked number of the bank payment card of the payer.
Authorization Id	The unique identifier of the authorization operation in the WEBPAY system.
Financial completion Id	The unique identifier of the financial completion operation in the WEBPAY system.
Refund Id	The unique identifier of the refund operation in the WEBPAY system.
Void Id	The unique identifier of the void operation in the WEBPAY system.

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

Report fields description

Name	Description
Date of payment registration/refund at the bank	Date of reflection of funds in the acquiring bank.
Amount to transfer	Total amount (minus the commission) that will go to the Store`s operation account.
Transfer currency	The currency in which funds are credited.
Merchant`s order number	Unique order identifier specified by the Store.
Terminal number	Terminal number set by the acquiring bank.
Merchant ID	Store`s ID in the WEBPAY system.
Merchant`s website	Website connected to the WEBPAY system.
Issuing bank	The bank that issued the bank payment card of the payer.
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.
Amount of reimbursement	Payment amount in the WEBPAY system.
Reimbursement commission	Commission fee to the bank.
Date and time of the authorization	Date of payment in the WEBPAY system.
Refund amount	The refund amount reflected in the acquiring bank.
Refund commission	Commission fee to the bank for making a refund.
Payment system	The name of the payment system of the payer's bank payment card.
Card description	Payer`s bank payment card level.
Belonging to a bank	Indicates that the bank payment card of the payer belongs to the Banks of the Republic of Belarus. Possible values: Us — belongs to the Bank of the Republic of Belarus. Not Us — belongs to a foreign Bank.
Transaction amount	The amount of the order in the Store excluding the discount amount and the delivery amount.
Discount amount	The discount amount set by the Store.
Discount name	Description of the discount specified by the Store.
Shipping cost	The shipping cost set by the Store.
Shipping name	Description of the delivery specified by the Store.
Sender of funds	Information about the payer passed by the Store to the WEBPAY system.
Contract number with the service customer/payer	The number of the contract with the customer of the service/payer passed by the Store to the WEBPAY system.
Purpose of payment	The purpose of the payment passed by the Store to the WEBPAY system.
Card type	The type of the payer`s bank payment card (DEBIT, CREDIT, CHARGE CARD).
Payer`s email	The email address specified by the payer during the payment.
Recurring payment	The type of recurrent payment. Possible values: Initiating — the binding of the payer's bank payment card was carried out. Recurring — payment was made using the payer`s previously binded bank payment card.
Issuing bank	The bank that issued the bank payment card of the payer.
Issuing bank country	The country of the bank that issued the bank payment card of the payer.
Payout	Money withdrawal operation. Possible values: Yes — the withdrawal operation has been performed. No — the payer has paid for Store services/goods.
Authorization Id	The unique identifier of the authorization operation in the WEBPAY system.
Financial completion Id	The unique identifier of the financial completion operation in the WEBPAY system.
Refund Id	The unique identifier of the refund operation in the WEBPAY system.
Void Id	The unique identifier of the void operation in the WEBPAY system.

Advanced payment page settings

Important!

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

Possibility of extended payment page settings:

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

Opportunities for changes to the payment page

9.1. Logo

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

9.2. Brand colors

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

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

9.3. Page font

You can choose from five available fonts:

Montserrat,
Roboto,
Segoe UI,
ProximaNova,
Helvetica.

9.4. Card background

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

9.5. Page Background

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

9.6. Change the payment button text

9.7. Typing additional text on the page

Invoice Statuses & Types

Invoice statuses

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

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

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

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

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.

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

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

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

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

Important!

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

Types of operations in the WEBPAY system

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

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

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

Important!

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

Authorization confirmation and cancellation

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

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

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

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

There are two payment processing types in WEBPAY system:

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

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.

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.

Full and partial refund

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

The refund procedure includes the following stages:

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

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

Introduction to Sandbox development environment

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

Test environment parameters

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

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

type: VISA

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

CVV/CVC2: any three numbers

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

Transition from test into real environment

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

Change of payment page address

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

Payment pages URLs:

Name	Description
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 the Internet-acquiring contract. Furthermore, sub-domains are treated as separate domains in accordance with payment systems rules. So if in your contract you specified https://test.by, than redirection to your payment page is also should be happening from https://test.by. In case of redirection from https://bill.test.by transaction will be blocked. Referer URL is regularly checked in accordance with payment systems and acquiring banks. If you are going to use an URL different from the one specified in the contract please contact your personal WEBPAY manager.

Web application interface URL is also changing:

Name	Description
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 email by your personal WEBPAY manager. You must change its value to the one from real environment.

Change of test payment flag

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

Payments integration

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

Card payments

Methods of order formation

The WEBPAY system provides two ways of forming payment orders:

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

Principle of formation of an order and payment for it

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

Formation of an order for payment

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

Payment form fields

Important!

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

Main payment form fields

Name	Required field	Field description	Notes
*scart	yes	Field does not contain value and designates the type of the request.
wsb_storeid	yes	Store ID in WEBPAY system. This ID is created during registration in the system and is sent in the email.
wsb_store	no	Store name that will be shown on the payment form. By default, it is taken from the billing account settings.	Maximum field length of 64 symbols.
wsb_order_num	yes	Unique order ID given by the store.	Maximum field length of 64 symbols. The value can not begin with 0 (zero) when paying via ERIP.
wsb_currency_id	yes	Currency ID. Three-letter code in accordance with ISO4271 standard.	Accepted values: BYN, USD, EUR, RUB
wsb_version	yes	Payment form version.	Current version number: 2
wsb_language_id	no	Payment form language ID.	Accepted values: russian, english. When empty the value is determined by browser settings.
wsb_seed	yes	Random symbol sequence used in electronic signature the order.	See: Electronic signature of an order.
wsb_signature	yes	Control value (electronic signature) of the order is a result of SHA1 function execution (for version 2, see wsb_version field) or MD5, if there is no protocol version specified. This value is a hex sequence.	See: Electronic signature of an order.
wsb_return_url	no	The URL the customer is redirected to if the payment is successful by clicking on the button on the payment result page. In case you need to set an automatic redirect to the URL, you can contact WEBPAY support at support@webpay.by.	Order ID (wsb_order_num) and transaction numbers (wsb_tid) are added to present URL in WEBPAY system.
wsb_cancel_return_url	no	URL a customer is redirected to if the payment was not successful.	Values of order ID (wsb_order_num) are added to present URL.
wsb_notify_url	no	This URL is called independently from the URL specified in wsb_return_url field. The main purpose of this URL is to notify website about successful payment in case user did not click the "Back to the site" button on the payment form. By default, it is taken from the billing account settings. Warning! Sending notifications is only possible to standard ports: 80 (http), 443 (https), 8080 (http_alt), 8443(pcsync-https).	See: Payment notification.
wsb_test	yes	Field that designates whether the payment is real or not. 1 — test payment; 0 — real payment.	In Sandbox test environment the value should be 1.
wsb_3ds_payment_option	no	Allows you to forcibly change the need for the payer to pass 3D-Secure. 3D-Secure management is not available for stores that operate through the acquiring bank Priorbank OJSC. To enable the ability to work with this functionality, you need to contact the personal manager of WEBPAY.	Possible values: auto — the 3D-Secure process is performed by default; force_3ds — forced payment using 3D-Secure. If the card does not support 3D-Secure, the transaction will not pass; force_3ds_only_auth_yes — after authentication using 3D-Secure, the status should be only Y, which guarantees successful authentication of the user, otherwise the transaction will not pass; without_3ds — forcibly disabling 3D-Secure.
wsb_customer_name	no	Customer name.	Maximum field length of 255 symbols.
wsb_customer_address	no	Customer address.	Maximum field length of 255 symbols.
wsb_service_date	no	Effective dates of rendering of services or delivery of goods.	Maximum field length of 255 symbols.

Fields for formation of shopping cart

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

Additional fields

Name	Required field	Field description	Notes
wsb_order_tag	no	Order tag is used to categorize orders, group orders or for other reasons.	Maximum field length of 64 symbols.
wsb_email	no	Customer`s email address.	Value of this field will be automatically put into appropriate field of the payment form.
wsb_phone	no	The customer`s phone number.
wsb_order_contract	no	Number of contract with the customer.
wsb_tab	no	Determining the active tab with the appropriate payment tool (card payment/ERIP).	Possible values: erip, cardPayment. If there is no field the order of tabs is standard — payment by card, then ERIP.
wsb_card_number_short	no	Determination of the possibility of making a payment for the card specified by the payer. The WEBPAY system makes a comparison of the card number data (the first 6 and the last 4 digits) between the transmitted card number in this field and what the payer entered when paying. If the first 6 and last 4 digits of the card number match, the payment is allowed, otherwise the payment attempt is rejected and an error is displayed to the payer.	The value is an integer that consists of the first 6 and last 4 digits of the card number. For example: 1234561234.
wsb_card_halva	no	Determination of the affiliation of the payer`s card to the Halva installment card of MTBank CJSC and the possibility of making payment with this card. This field does not affect the payment with cards other than Halva installment cards of MTBank CJSC.	Possible values: 1 — allow to pay by installments card "Halva" CJSC "MTBank"; 0 — refuse to make payment by installment card "Halva" CJSC "MTBank".

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="The name of your Store">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="1">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_customer_name" value="Ivanov Ivan">
  <input type="hidden" name="wsb_customer_address" value="Minsk Shafarnyanskaya str. 11-54">
  <input type="hidden" name="wsb_service_date" value="Delivery till 1 january 2016 year">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Goods 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Goods 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="31.40">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="266e9c04a24dfb5fc75775c42a831a49488f8303">
  <input type="hidden" name="wsb_tax" value="10.50">
  <input type="hidden" name="wsb_shipping_name" value="Shipping costs">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Discount">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_order_contract" value="Contract №152/12-1 12.01.19">
  <input type="submit" value="Buy">
</form>

Parameters for regulating the payment session

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

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

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

Electronic signature of an order

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

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

In every order form you should fill the following fields:

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

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

wsb_seed
wsb_storeid
wsb_order_num
wsb_test
wsb_currency_id
wsb_total
SecretKey

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

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

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

Payment for an order

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

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

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

Important!

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

Payment notification

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

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

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

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

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

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

Important!

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

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

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

Successful payment notification

There are two ways of receiving notifications about payments:

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

Standard POST request sent from WEBPAY to wsb_notify_url

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

Request fields:

Name	Description
batch_timestamp	Transaction execution time
currency_id	Transaction currency
amount	Transaction amount
payment_method	Transaction methods. Possible values: test — without real processing, cc — card, erip — ERIP apple — Apple Pay payment
order_id	Order number in the WEBPAY system
site_order_id	Order number (name) set by store
transaction_id	Transaction number
payment_type	Transaction type. Successful payments are equal to 1 or 4
rrn	Transaction number in VISA/MASTERCARD/BELCARD system
wsb_signature	Electronic signature (calculated if "Secret key" is set in the billing account options)
action	Payment processing code
rc	WEBPAY operation result internal code
approval	Processing operation code
country_alpha_three_code	Country code of the issuing bank in ISO 3166-1 alpha-3. To include this field in the notifier, you must contact the support@webpay.by
card	The number of the payer`s bank payment card in the format 123456xxxxxx7890, from which the payment was made. The field is included in the notificator when using scenarios when a card is required in the response, for example, when working with recurring payments, PCI DSS merchants, etc. If standard integration is used, but for some reason you need to get card number, you need to contact support@webpay.by to include this field in notificator

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

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

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

application/x-www-form-urlencoded

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

SOAP tool

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

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

batch_timestamp
currency_id
amount
payment_method
order_id
site_order_id
transaction_id
payment_type
rrn
card
SecretKey

Combination order must be preserved.

Important!

SecretKey field is only considered in a real environment.

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

Example of a request in accordance with the scheme

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

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

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

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

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

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

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

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

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

transaction_id
batch_timestamp
currency_id
amount
payment_method
payment_type
order_id
rrn
SecretKey

Combination order must be preserved.

Important!

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

Transaction types

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

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

Important!

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

These are types for successful payments:

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

And these are types for refunded payments:

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

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

Simplified payment

Description of the work process

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

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

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

Initiating payment in the Simplified payment scenario

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

Repeat payment in the Simplified payment scenario

Important!

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

Payments execution

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

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

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

wsb_seed
wsb_storeid
wsb_customer_id
wsb_order_num
wsb_test
wsb_currency_id
wsb_total
SecretKey

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

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

Important!

If you did not make changes to interaction protocol with WEBPAY program complex, all payments will be executed by default.
In order to be able to add various cards and bind them you need to set wsb_test parameter to 0.
You can use any numbers with 16 characters for VISA or MASTERCARD cards. You can generate such numbers with some help from http://www.getcreditcardnumbers.com.

Recurring payment

Description

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

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.
Credential on File (CoF) — these are payments made on a bound card, in which the frequency of debits is not observed. The initiator of such charges may be:
- Store,
- Cardholder.

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

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

Recurring (Credential on File) payments usage scenario

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

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

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

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

Cardholder ID, card binding options

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

Fields of the payment form for recurrent payments

The WEBPAY system provides two ways of forming payment orders:

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

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

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

Important!

All text fields must use UTF-8 charset.

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

Payment services URLs for requests

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

Initiating payment

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

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

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

Important!

It is possible to make an initiating payment with a zero amount to verify the payment card, when working with the acquiring bank "Priorbank" OJSC. To enable this feature, you need to contact the WEBPAY support service support@webpay.by.

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:

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
Depending on the protocol version (wsb_version) MD5 (if version is not specified) or SHA1 (for version 2) of combined string is calculated.

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

Notification after initiating the payment

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

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

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

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

MD5 of the string is calculated by default.

Important!

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

Recurring payment (Credential on File)

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

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

Parameter wsb_recurring_token is included to a signature after wsb_operation_type:

wsb_seed
wsb_storeid
wsb_customer_id
wsb_order_num
wsb_test
wsb_currency_id
wsb_total
wsb_operation_type
wsb_recurring_token
SecretKey

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

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

Notification after recurring payment

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

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

// Response about a successful recurring payment

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

// Response to a recurring payment error

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

Card unbinding from recurring (Credential on File) payments

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

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

wsb_version
wsb_seed
wsb_storeid
wsb_customer_id
wsb_operation_type
wsb_recurring_token
wsb_signature

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

wsb_seed
wsb_storeid
wsb_customer_id
wsb_operation_type
wsb_recurring_token
SecretKey

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

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

Notification after unbinding card from the recurrent payments

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

// Example of an answer about successful unbinding

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

// Error answer example

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

Complete or partial refund

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

Acquiring bank	Transaction type	Transaction status
"Priorbank" JSC	Initiating	Authorized → Completed
	Recurring	Recurrent
	Credential on File	Authorized → Completed
CJSC "MTBank" JSC "Belagroprombank" JSC "Sber Bank"	Initiating	Authorized → Completed
CJSC "MTBank" JSC "Belagroprombank" JSC "Sber Bank"	Recurring	Authorized → Completed
JSC "Bank Dabrabyt"	Initiating	Authorized → Completed
	Recurring
	Credential on File

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

Acquiring bank	Transaction type	Request type	Transaction status
"Priorbank" JSC	Initiating, Recurring	TransactionCancel (with the specified amount for refund to cardholder)	Voided
"Priorbank" JSC	Credential on File	TransactionCancel (with the specified amount for refund to cardholder)	Voided
CJSC "MTBank" JSC "Belagroprombank" JSC "Sber Bank"	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
	Recurring	TransactionRefund (with the specified amount for refund to cardholder)	Refund
JSC "Bank Dabrabyt"	Initiating, Recurring, Credential on File	TransactionCancel (with the specified amount for refund to cardholder)	Voided

Installment cards

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

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

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

Installment plan type	Terminal number
1 month	90000001
3 month	80000003

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

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

wsb_seed
wsb_storeid
wsb_order_num
wsb_test
wsb_currency_id
wsb_total
wsb_terminal
SecretKey

Features of working with "PriorBank" JSC installment cards

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

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

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

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

Payment page for payment by Halva installment card

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

Selecting the payment method for the X-card

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

Payments with Halva Plus card

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

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

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

Apple Pay Payments

Description

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

Advantages of Apple Pay technology in comparison with card operations:

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

Apple Pay support on devices

Apple Pay payment technology is supported on devices:

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

Payment execution

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

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

Activation

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

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

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

Promo code for the VISA and MASTERCARD discount program usage

VISA/MASTERCARD discount program description

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

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

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

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

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

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

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

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

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

<form action="https://securesandbox.webpay.by/" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_language_id" value="russian">
  <input type="hidden" name="wsb_storeid" value="11111111">
  <input type="hidden" name="wsb_store" value="The name of your Store">
  <input type="hidden" name="wsb_order_num" value="ORDER-12345678">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="1242649174">
  <input type="hidden" name="wsb_customer_name" value="Ivanov Ivan">
  <input type="hidden" name="wsb_customer_address" value="Minsk Shafarnyanskaya str. 11-54">
  <input type="hidden" name="wsb_service_date" value="Shipping till 1 january 2016 year">
  <input type="hidden" name="wsb_return_url" value="http://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="http://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="http://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_email" value="ivanov@test.by">
  <input type="hidden" name="wsb_phone" value="375291234567">
  <input type="hidden" name="wsb_invoice_item_name[0]" value="Goods 1">
  <input type="hidden" name="wsb_invoice_item_quantity[0]" value="2">
  <input type="hidden" name="wsb_invoice_item_price[0]" value="10">
  <input type="hidden" name="wsb_invoice_item_name[1]" value="Goods 2">
  <input type="hidden" name="wsb_invoice_item_quantity[1]" value="1">
  <input type="hidden" name="wsb_invoice_item_price[1]" value="0.5">
  <input type="hidden" name="wsb_total" value="31.40">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="bc8ea3bee19c247d090c79c8bbb7974f9484db96">
  <input type="hidden" name="wsb_tax" value="10.50">
  <input type="hidden" name="wsb_shipping_name" value="Shipping costs">
  <input type="hidden" name="wsb_shipping_price" value="0.98">
  <input type="hidden" name="wsb_discount_name" value="Discount">
  <input type="hidden" name="wsb_discount_price" value="0.58">
  <input type="hidden" name="wsb_order_contract" value="Договор №152/12-1 от 12.01.19">
  <input type="hidden" name="wsb_discount_promo_code" value="gold">
  <input type="submit" value="Buy">
</form>

Testing out VISA/MASTERCARD discount program

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

You must contact WEBPAY technical support support@webpay.by to enable your account to work under the VISA/MASTERCARD discount program.
You need to send wsb_test parameter with 0 values to make different card numbers input available.
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

Visa Offers Platform

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

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

Operations through the AIS "Raschet" (ERIP)

Payment execution scenario through AIS "Raschet" (ERIP)

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

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

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

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

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

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

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.

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

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

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

Notification for later payment ERIP and Internet acquiring

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

Payment notification

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

Invoicing via FTP in AIS "Raschet" (ERIP)

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

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

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

Example: 1234567_250817125700.bill

Example of a uploadable file:

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

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

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

Successful invoicing
Ошибочное

FTP setup

Parameters of WEBPAY FTP:

User name: merchant

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

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

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

An example of filling in the parameters in Total Commander:

Payment of ERIP invoices for an arbitrary amount

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

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

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

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

API for creating an invoice without moving to the payment page

Description of the order creation mechanism

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

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

Description of the request parameters and its example

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

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

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

Description of the response parameters

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

Response of the WEBPAY system upon successful order creation.

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

WEBPAY response to an error, for example:

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

Hmac signature generation mechanism

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

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

Where:

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

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

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

Fields description

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

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

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

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

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

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

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

Working without integration

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

Invoice creation from personal cabinet WEBPAY

Forming a new invoice for payment

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

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

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

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

Important!

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

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

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

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

Important!

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

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

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

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

russian,
english.

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.

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

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

Important!

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

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

The next fields are not required.

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

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

Important!

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

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

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.

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.

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

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

if you have an Internet acquiring connected;
if you have payment receiving through AIS "Raschet" (ERIP) connected;
if you have both payment variants on your billing account (bank card and AIS "Raschet" (ERIP).

Invoice creation from personal cabinet WEBPAY for installment cards

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

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

Information about installments after payment

Payments using the QR code

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

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

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

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

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

Example of form:

Example of a form for payment using QR code

The following information is displayed on the invoice form:

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

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

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

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

Products (payments by the link)

If you sell only a few products or services with different prices, the WEBPAY system provides the opportunity to form a single link to pay for a product/service with a single price in the section "Products" of the WEBPAY personal account.

You can use "Products" without integration with your website or mobile app.

To create a product, click on "+" button on the right, then the interface for creating a product or service will be displayed. In the field "Product name" enter the name of the product/service. Fill in the field "Product code" with an additional value that identifies the product in the search. In the field "Price" enter the price of the product/service. The checkbox "Active" allows you to make payment available to your customers.

After creating a product, information about it will be displayed in the list of created Products.

An additional menu on the right allows you to copy the product link to the clipboard, view the product link as a QR code, delete the product or edit it:

The link can be used for placement on the site in a certain section for payment or under the corresponding button, can be sent to the buyer by email, in Telegram or other messengers, and can also be used as a QR code.

The results of such payments will be displayed in the corresponding section of the WEBPAY personal account.

Merchant PCI DSS

Formation of a payment

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:

Create a standard POST request (section Formation of an order for payment).
Add the wsb_encrypted_data field to the request.
Add the wsb_email field to the request. This is a mandatory field for this type of the request.
Additionally, you can add the wsb_return_format field to specify the format of the response from our system.

Name of the field	Required field	Description	Notes
wsb_encrypted_data	yes	This field contains encrypted JSON of the format {"cc_pan":"", "cc_exp":"", "cc_cvv":"", "cc_name":""}.	Encrypted using the RSA algorithm using a public key from personal account.
wsb_email	yes	Customer`s email address.
wsb_return_format	no	Output format of the result.	Possible value: json.

Important!

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

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

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

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

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

For payments with 3D-secure 1

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

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

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

Important!

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

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

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

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

For payments with 3D-Secure 2

WEBPAY returns the following fields in the response:

if the threeDSSessionData parameter is present in the response, then: acsUrl, threeDSSessionData, creq are returned;
if the script is frictionless: acsUrl and threeDSMethodData.

Merchant sends a POST request to the URL that came in the acsUrl field with the parameters received from WEBPAY.

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

{"token":"f0c2d69feaf8f08bd3ae048e3e5d7a47=4e5564425432704d5a5752696344466a544574545a6b56574e316334575670454e6b784452575a6e64576459516b68724d3164764d334a7459545255613349775656457263314a6d6432497859304d796354564261512c2c",
"tokenName":"wt",
"time":"2023.01.12 12:14:08",
"orderNumber":"ORDER-9589",
"invoiceNumber":"",
"transaction":"",
"authorizationCode":"142359",
"rrn":"3012WP000129",
"trimPan":"520813xxxxxx5892",
"payee":"test",
"amount":"13.00",
"currency":"BYN",
"responseCode":"",
"responseText":"",
"acsUrl":""}

Recurrent (Credential on File) payment for PCI DSS merchants

The PCI DSS merchant should study the standard work with recurrent payments to make recurrent (CoF) payments and make minimal changes to requests.

Initiating payment

The algorithm for generating the signature for the order is changed by adding the field wsb_encrypted_data (the rule for the formation of this field can be found here) before the parameter SecretKey, when creating the initiating payment for PCI DSS merchants. The electronic signature wsb_signature must be formed according to the following rule from the values of the following fields:

wsb_seed
wsb_storeid
wsb_customer_id
wsb_order_num
wsb_test
wsb_currency_id
wsb_total
wsb_operation_type
wsb_encrypted_data
SecretKey

Recurring payment (Credential on File)

When forming a request for recurrent (CoF) payments, the field wsb_signature can be formed according to the standard scheme or with the addition of the field wsb_encrypted_data (the rule for the formation of this field can be found here) before the parameter SecretKey:

wsb_seed
wsb_storeid
wsb_customer_id
wsb_order_num
wsb_test
wsb_currency_id
wsb_total
wsb_operation_type
wsb_recurring_token
wsb_encrypted_data
SecretKey

Card unbinding from recurring (Credential on File) payments

The request to unbind the card from recurrent (CoF) payments does not change and is carried out according to the standard scheme.

Payment using previously binded cards in another PSP

If you have payment cards previously binded by your payer from another PSP provider and you want the subsequent recurrent payment will be completed through WEBPAY, then you need to do the following:

Create a request for a recurring payment
In the field wsb_encrypted_data (the rule for the formation of this field can be found here), pass the data of your payer's payment card, except for the field cc_cvv. The fields cc_pan, cc_exp, cc_name contain cardholder data, and the field cc_cvv is left empty.

Payment modules for payouts

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

B2C/W2C (BelVEB Bank)

General description

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

Scheme of work

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

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

Subsequent deposits to accounts

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

Payouts of funds from the payer`s account

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

The development of payment module

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

Refill, card binding and subsequent refill

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

Payout funds

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

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

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

Description of table fields for operations type B2C

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

ans – alphabetic, numeric and special characters.

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

Description of table fields for operations type W2C

Description of table fields senderData

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

ans – alphabetic, numeric and special characters.

Description of table fields receiverData

Tag	Type	Description	Value Format
C1	T	First Name	ans ...35
C3	T	Last Name	ans ...35

ans – alphabetic, numeric and special characters.

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

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

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

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

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

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

P2P (BelVEB Bank)

General description

For payout funds on your website the payer is allowed to use MASTERCARD, VISA, BELKARD payment systems issued by any Belarusian bank. The types of cards to which funds can be payout are determined by the acquiring bank. Foreign cards are not allowed for payouts according to the rules of payment systems.

The payout of funds is carried out from the corporate card of your organization.

The development of payment module

The WEBPAY system provides two ways of forming payouts using the P2P type

JSON API.
Creation of standard POST request.

Creation of standard POST request

To make a P2P payouts of funds, it is necessary to form a standard POST request (according to Formation of an order for payment), to which the following fields are additionally passed:

Name of the field	Required field	Description
wsb_encrypted_data	yes	This field contains encrypted JSON of the format {"cc_pan":"", "cc_exp":"", "cc_cvv":"", "cc_name":""}. Encrypted using the RSA algorithm using a public key from personal account.
wsb_output_via_corpocard	no	Possible values: true, false The default value false true – used to payout funds, false – used for depositing funds

Name of the field

Required field

Description

wsb_encrypted_data

yes

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

wsb_output_via_corpocard

Possible values: true, false

The default value false

true – used to payout funds, false – used for depositing funds

Important!

When forming a P2P request for payout of funds (in the field wsb_output_via_corpocard the value true is passed) the fields wsb_invoice_item_name, wsb_invoice_item_quantity, wsb_invoice_item_price are optional.

<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_storeid" value="240869199">
  <input type="hidden" name="wsb_order_num" value="ORDER-1234567822223">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="dfdasf3i232m13ijdsmcvm">
  <input type="hidden" name="wsb_output_via_corpocard" value="true">
  <input type="hidden" name="wsb_encrypted_data" value="bhch48Wu4Esi3Y7jVq/d+0A3VqdzBsRvobhDxLrWsQyl6+ogVSIxMxM8S/4EVyGeNXO6VR/FA1UnvzLvehhDWMeEZFv04SAktt5BTABXcjgWm7ZJ3tiXEv1c1UuMDCk88xhDDyfSaPaCJMxnQhA3Wo9qfXhFebDwtIUljP7MCs41woxAQx8v9f8fm3FHS2+RnrN+HRAhgM34hR3OwYx/1llgu0L78++Ovrf6ZjQqYArv8YoV8E9y5cWrGYdUp2ogmfOkvGX/wI+wZ0FoAIuwAWiUknca7zClbwfgshw4wV4p0w==">
  <input type="hidden" name="wsb_return_url" value="https://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="https://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="https://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_total" value="1.00">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="04c0129511a4df53e74676f0cb18ac2a1d34a8e2">
  <input type="submit" value="Pay out">
</form>

After sending the request, the payer redirected to the WEBPAY payment page to enter the card number to which funds will be payout from your corporate card.

Payment notification

Upon successful payout of funds, the WEBPAY system notifies the Internet resource about the operation at the address 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 p2p 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.

P2P (MTBank)

General description

For depositing and payout funds on your website the payer is allowed to use MASTERCARD, VISA, BELKARD payment systems. The types of cards to which funds can be payout are determined by the acquiring bank.

The development of payment module

The WEBPAY system provides two ways of forming payouts using the P2P type

JSON API.
Creation of standard POST request.

Creation of standard POST request

Important!

All payouts operations are implemented with required binding to the input operation.

To execute the operation of depositing funds and binding the card, it is necessary to form one of the following types of requests:

Simplified payment;
Recurring payment.

In the response will be transaction_id parameter for further realization payout on it.

Payouts of funds

To make a P2P payouts of funds, it is necessary to form a standard POST request (according to Formation of an order for payment) to the address https://securesandbox.webpay.by/output/mtb for a test environment or https://payment.webpay.by/output/mtb for a real environment, to which the following fields are additionally passed:

Name of the field	Required field	Description
wsb_token_p2p	yes	The value of this field corresponds to the value of the transaction_id field transmitted in the notification after the card was entered and binded.
wsb_output_via_corpocard_mtb	yes	The field always contains the value true and indicates the payout of funds.
wsb_customer_id	yes	Unique user ID in the Store.

Important!

When forming a P2P request for payout of funds the fields wsb_invoice_item_name, wsb_invoice_item_quantity, wsb_invoice_item_price are optional.

Electronic signature wsb_signature to execute a P2P request for the payout of funds 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

<form action="https://securesandbox.webpay.by/output/mtb" method="post">
  <input type="hidden" name="*scart">
  <input type="hidden" name="wsb_version" value="2">
  <input type="hidden" name="wsb_storeid" value="240869199">
  <input type="hidden" name="wsb_order_num" value="ORDER-1234567822223">
  <input type="hidden" name="wsb_test" value="0">
  <input type="hidden" name="wsb_currency_id" value="BYN">
  <input type="hidden" name="wsb_seed" value="dfdasf3i232m13ijdsmcvm">
  <input type="hidden" name="wsb_token_p2p" value="164941648452655">
  <input type="hidden" name="wsb_output_via_corpocard_mtb" value="true">
  <input type="hidden" name="wsb_customer_id" value="164968">
  <input type="hidden" name="wsb_return_url" value="https://yoursiteurl.com/success.php">
  <input type="hidden" name="wsb_cancel_return_url" value="https://yoursiteurl.com/cancel.php">
  <input type="hidden" name="wsb_notify_url" value="https://yoursiteurl.com/notify.php">
  <input type="hidden" name="wsb_total" value="1.00">
  <!-- In the example SecretKey equal 1 -->
  <input type="hidden" name="wsb_signature" value="c6e16f9fa0837eff0585b1046431a134839fbc14">
  <input type="submit" value="Pay out">
</form>

API

Managing operations

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

You can use the documentation to configure operation management yourself:

Service WSBApi or check the wsdl scheme https://sandbox.webpay.by/WSBApi2.
JSON API.

Important!

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

Important!

Server SDK

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

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

Requests for reporting

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

GET method.
POST method.

When using the GET method the URL is formed according to the following scheme:

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

Header Authorization: login:password

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

payment_module_url/reports/get

Important!

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

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


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

Description of fields in request

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

Basic information

Development procedure

Web application interface

Application home page

Secret key installation

Financial operations overview

Login into WEBPAY Personal Cabinet

Important!

Filling parameters of WEBPAY Personal Cabinet ("Company")

Accounts creation ("Users")

Payment information viewing

Payments log

Accounting for completed payments

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

Report fields description

Report fields description

Accounting for transactions made through Internet-acquiring

Report fields description

Report fields description

Advanced payment page settings

Important!

Invoice Statuses & Types

Invoice statuses

Important!

Types of operations in the WEBPAY system

Important!

Authorization confirmation and cancellation

Full and partial refund

Introduction to Sandbox development environment

Test environment parameters

Transition from test into real environment

Change of payment page address

Important!

Change of store ID

Change of test payment flag

Payments integration

Card payments

Methods of order formation

Principle of formation of an order and payment for it

Formation of an order for payment

Payment form fields

Important!

Main payment form fields

Fields for formation of shopping cart

Additional fields

Code example

Parameters for regulating the payment session

Code example

Electronic signature of an order

Code example

Payment for an order

Important!

Payment notification

Important!

Successful payment notification

Standard POST request sent from WEBPAY to wsb_notify_url

Code example

SOAP tool

Important!

Code example

Code example

Code example

Code example

Payment verification

Request example

Important!

Transaction types

Important!

Simplified payment

Description of the work process

Important!

Payments execution

Code example

Important!

Recurring payment

Description

Recurring (Credential on File) payments usage scenario

Cardholder ID, card binding options

Fields of the payment form for recurrent payments

Important!