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.
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).
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 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 &.
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:
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.
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.
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:
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.
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:
To change the other data (company name, company website, legal body name) you`ll have to contact your personal WEBPAY manager.
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:
In the "Groups" list you should also specify the rights for account owner:
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.
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.
In the "Payments" menu you can view all payments received for the benefit of your company and paid by credit card online.
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:
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:
Additional information will be shown after clicking an invoice:
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:
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.
The Errors section in your WEBPAY personal cabinet allows you to track and analyze errors that occur during the payment process of your payers. Using this information, you can quickly identify and eliminate the causes of errors to help your customers solve payment problems, improve the quality of service to your customers and increase the efficiency of your processes.
This section displays all subsections corresponding to the abbreviated names of the acquiring banks' processing centres through which you work. To go to a particular subsection, just click on the name of the subsection and you will see the table with errors.
For each processing bank there is a table with errors, which consists of the following columns:
To use the Errors section, perform the following actions:
If you encounter an error that you cannot find in the Errors section, or you are unable to fix the error yourself, please let us know. We will help you to fix the error and solve any other problems related to payment.
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.
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.
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. |
Cost of goods/services | The total cost of all goods/services in the Store. |
Shipping | Shipping fee set by the Store. |
Discount | The amount of the discount set by the Shop. |
Amount | The amount of payment in the WEBPAY system including the cost of goods/services, delivery and discount amount. |
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:
Funds refund is performed in two stages:
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. |
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.
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.
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. |
To brand a payment page contact your manager managers@webpay.by
Possibility of extended payment page settings:
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:
9.3. Page font
You can choose from five available fonts:
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
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.
Please note, when you perform payment through AIS "Raschet" (ERIP), the invoices will be getting only the "Pending", "Paid" and "Not paid" statuses.
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.
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.
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:
Authorized payments in the WEBPAY system can be financially completed or cancelled.
The payment cancellation procedure includes the following stages:
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.
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:
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.
To ensure security and reduce the risks of fraudulent transactions, acquiring banks set individual transaction limits for each merchant's payment terminal, both in terms of the number of transactions and total amounts for a certain period of time.
After the Internet acquiring is connected, the acquiring bank transfers the necessary limits to WEBPAY. WEBPAY sets them in the system when creating and setting up a personal account for the merchant.
In the process of work there may be situations when the merchant needs to change the limits. In this case, the new limits are agreed with the acquiring bank and changed in the WEBPAY system.
After changing the limits, a notification is sent to the email specified in the Company Profile with the following information:
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.
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.
Please note that a bunch of requirements must be met in order to move from test environment into a real one.
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 |
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 |
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.
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.
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.
The WEBPAY system provides two ways of forming payment orders:
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.
All text fields must be filled with text in UTF-8.
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. |
wsb_show_wt | no | Payment session token. Used to restore the payment session in case the script was interrupted. |
Possible values: 1 — enable token transfer of the payment session; 0 — disable token transfer of the payment session. The rule for forming the link by which the payer should be directed: https://URL_адрес_платежной_страницы/{wsb_show_wt} |
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. |
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>
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 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:
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
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.
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).
This functionality allows the Internet resource to display the result of the payment on its side. Immediately after the payment is made, the payer will be redirected to the URL specified by the Internet resource without displaying the payment result on the WEBPAY payment page.
To activate this functionality you need to send a request to WEBPAY support service at support@webpay.by, specifying wsb_storeid (Billing Id) from which requests will be made.
In order for WEBPAY system to redirect the payer to the page of the Internet resource, you should add the following fields to the request to form an order for payment (HTML-form or JSON API):
After the payer has paid for the order, WEBPAY system will redirect him to the URL specified by the Internet resource in the field wsb_return_url — in case of successful payment or wsb_cancel_return_url — in case of unsuccessful payment. WEBPAY system will also send the following parameters with the result of payment to the Internet resource in JSON format:
Name | Description |
---|---|
orderNumber | Unique order ID given by the store |
invoiceNumber | Unique order number in the WEBPAY system |
rrn | Transaction number in VISA/MASTERCARD/BELCARD system |
trimPan | The number of the payer`s bank payment card in the format 123456xxxxxx7890, from which the payment was made |
responseCode | WEBPAY operation result internal code |
responseText | Text message about the result of the operation |
{
"orderNumber":"ORDER-12345678",
"invoiceNumber":"123456789",
"rrn":"123456789123",
"trimPan":"123456xxxxxx1234",
"responseCode":"W0545",
"responseText":"Недостаточно средств"
}
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.
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.There are two ways of receiving notifications about payments:
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:
|
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:
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¤cy_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}
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:
Combination order must be preserved.
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.
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.
<?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>
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:
|
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 order must be preserved.
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.
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 |
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 is a method of payment with bank card without need for input of all card details to fill in customer`s information when paying to the same service/goods provider. Complete card details are only required for the first time to initiate service binding to that card. In order to make simplified payments possible you should contact WEBPAY technical support support@webpay.by and make some adjustments to interaction scenario between service provider and WEBPAY program complex. This option will make payments more convenient for customers which will increase appeal of a website.
Here by customer stands for a cardholder that passed authorization on a seller`s website. Authorization is crucial here because it allows to associate that person with some unique number.
Card binding is performed on WEBPAY program complex side. Customer data (card number mask, cardholder`s name, expiration date, email and phone number) are stored in relation to customer`s number. New card can be bound by customer in one click after first successful payment to a service provider.
Activated "Simplified payment" feature will help to avoid needless input of information. Customer can just choose a card from a list only need to enter CVV/CVC.
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.
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:
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>
There are two ways in the WEBPAY system to make a payment without participation of the 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.
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 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.
The WEBPAY system provides two ways of forming payment orders:
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.
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:
|
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. |
In order to perform recurring (CoF) inquiries use https://securesandbox.webpay.by for test environment and https://payment.webpay.by for real payments.
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.
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.
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:
<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>
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:
MD5 of the string is calculated by default.
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:
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>
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¤cy_id=BYN&amount=15&payment_method=cc&order_id=294088281&site_order_id=ORDER-15&transaction_id=650449721&
payment_type=10&rrn=210476022664&wsb_signature=66e6be413ea2d8638174e3b69f1ffd32&action=0&rc=W0001%2800%29&approval=210476&
rc_text=Операция завершена успешно&card=516052xxxxxx9495&customer_id=test_1&operation_type=recurring_pay&recurring_token=650449721
// Response to a recurring payment error
Content-Type: application/x-www-form-urlencoded
batch_timestamp=1586714748¤cy_id=BYN&amount=35&payment_method=cc&order_id=0&site_order_id=ORDER-16&transaction_id=0&payment_type=2&
rrn=&wsb_signature=25ac063bbf766c4401858439f3fbd61c&action=4&rc=W0319&approval=&rc_text=Ошибка&card=516052xxxxxx9495&customer_id=test_1&
operation_type=recurring_bind&recurring_token=0&offer_exp_date=2022-10-31
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:
Parameter wsb_signature calculated by combining the following fields into 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.
<!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>
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"}
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 |
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 |
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 | |
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 |
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:
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.
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.
The payment scenario will start after sending the request. In this scenario only the "MTBank" CJSC (Halva or X-card where the Halva installment card is binding to) installment card is allowed to be entered for payment. When working with only one installment plan type, the Store doesn`t need to pass the wsb_terminal field. The WEBPAY system will determine the card entered by the payer and based on it, the payment will be made at the appropriate terminal.
If the Store is enabled to accept payments by installment cards of "MTBank" CJSC (Halva), a page with a block of information for payment will be displayed.
When the customer enters X-card (the product of "MTBank" CJSC) and click the "Pay" button, the payer will be offered a choice of payment methods available for this product.
<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>
To make payments with Halva Plus card it is enough to form standard authorization request in accordance with Formation of an order for payment. When filling in Halva Plus card details and with allowance to pay with accumulated bonuses customer will see a separate page with payment type choice. On this page he will be able to choose the way he wants to pay for an order.
If payment with accumulated bonuses is not allowed, a separate page with payment type choice will not be shown and payment will be automatically made with BYN charged from Halva Plus card
Apple Pay 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:
Apple Pay payment technology is supported on devices:
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.
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:
You can contact your WEBPAY manager to solve your issue or to activate Apple Pay payments for your store with necessary steps.
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 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>
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:
Card type | BIN card |
---|---|
VISA Gold | 480066 |
VISA Platinum | 417685 |
VISA Infinite | 455674 |
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.
To perform a payment with ability to pay for purchase through AIS "Raschet" (ERIP) it is necessary to form JSON API request or a standard authorization request (Formation of an order for payment). For test environment, please, use this address https://securesandbox.webpay.by, and for making real payments this: https://payment.webpay.by.
If you need to create an invoice with ability to pay for purchase until a certain date, you need to pass the wsb_due_date field in authorization request. The value of this field must contain a timestamp in the Unix Timestamp format, until which the invoice will be available for payment.
After finishing the request a page with payment details will be displayed.
If the client is connected to receive payments for orders only through AIS "Raschet" (ERIP), a page with payment information block will be displayed.
If the client has an ability to pay for purchase not only through ERIP, but also by using a bank card, then payment page will show additional info block to enter card details.
You can also define an active tab with a payment instrument (card Payment / Payment through ERIP). When passing the wsb_tab field with the value erip in the POST request, the active tab will be "Payment through ERIP".
The payer has an ability to save order info to perform a payment later. To do this he needs to click the "Pay later" button. As a result, order information will be sent to the specified email.
Here are examples of emails with order details that will be sent to the payer.
If the client have set up an ability to receive payments only through AIS "Raschet" (ERIP).
If the client have set up an ability to pay for purchases with a bank card or through AIS "Raschet" (ERIP).
<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>
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.
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:
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:
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 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.
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/ |
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"}}
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"}
To fulfill an invoice creation request you must add a signature to the request using the Hmac algorithm. The signature is formed as follows — the Authorization http-header is added to the request. It has the following form:
Where:
The following http-request fields are used in the signature:
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";?>
The WEBPAY system provides work without integration with the Store`s website. You can accept payments by creating invoices from your WEBPAY personal cabinet.
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.
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.
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:
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:
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.
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.
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).
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:
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.
If you need to make changes to an invoice that has already been generated, you can use the "Edit Invoice" button.
After clicking on the button, the invoice you created will be displayed with the possibility to edit all fields:
After you save a modified invoice, in the "Invoices" tab, clicking on the invoice card will open it and you will be able to see the information on the invoice. If you click on the "Invoice history" button, you will see the history of all the changes that were made while editing the invoice.
QR code payments are a method of accepting payments using a QR code image. To start accepting payments using a QR code, it is necessary to conclude an Internet acquiring agreement with WEBPAY partner bank that supports this payment method.
QR code payments are a convenient and easy way to accept payments for legal entities and individual entrepreneurs. Their use does not require integration with the website, and they can also 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:
The following information is displayed on the invoice form:
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 Code - a unique subdomain - is a ready-made resource that allows you to accept payments both online and offline, without the need to create your own website. This resource fully complies with the requirements of payment systems.
To start accepting payments by QR code, log in to the WEBPAY personal account, section "QR Code" (enabled individually for the account).
To work with the QR code, you can use the "Download" and "Print" buttons. ТYou can also copy the QR code image to the clipboard by right-clicking on the image → "Copy Image"..
Scanning the QR code leads to a payment form that will have an address like: https://shop_name.w-p.by
Example form:
The following information will be displayed on the QR page:
If you press the "Payment information" button, general information about how the payment is made will be displayed.
After the payer fills in all the necessary fields, he clicks on the "Go to the payment" button and makes the payment by entering the data of his bank card.
You can view and/or download the payment results and report in the required format in your personal WEBPAY account in the "Reports → QR reports" section. The column Additional data will display the data specified by the payer when making the payment.
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.
In order to integrate with the WEBPAY system for PCI DSS merchants who work with card data on their websites or directly in their applications and want to use Host2Host integration, please follow the instructions below:
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. |
When forming the wsb_signature field (the signature formation mechanism is specified in the Electronic signature of an order), the wsb_encrypted_data field also participates in concatenation of parameters and is placed at the end before SecretKey. Then the standard payment scenario takes place.
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 |
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 */
Generate a POST request as described in Formation of a payment and send it to https://payment.webpay.by/api/v1/payment for the real environment or to https://securesandbox.webpay.by/api/v1/payment for the test environment.
{
"wsb_storeid":"123456789",
"wsb_currency_id":"BYN",
"wsb_version":2,
"wsb_seed":"1242649174",
"wsb_test":0,
"wsb_invoice_item_name":["test"],
"wsb_invoice_item_price":["0.1"],
"wsb_invoice_item_quantity":["1"],
"wsb_operation_type":"",
"wsb_customer_id":"41432",
"wsb_encrypted_data":"VYs5XZYA79BORvcPW4LbBM6x4B36lBnQskF7j61UVlsH4ENPrPCs1exkJdCF6fX9nyENvrC434w3tL6HBtY7mxFXFvMBbsNoDbF4OC4lJEPVSSoBASLZH/9M1hBtavKjjDyKWXsCd5HYihp6PRTs3rMtw9+6Dao8hyfucMxyGpzDU/fW7DZdZ1GY3RIRKXJgPOP/AWv1YORy22BtyNs461CKuyXVY5AdeLO7WmV2x9kxexKNncKO4o0voy9KjW/nYj7R1YCQAZ4k1G2ZuXku90+yeo/AVBCXVTOEejwfplw9dFARes6OtQcW10kQmTdMi9200bf3sY2lQ1UZSbNMRw==",
"wsb_order_num":"ORDER-de35",
"wsb_total":"0.1",
"wsb_signature":"87943d79649e10970b23dfd41194e5a503292bba",
"wsb_tax":"0",
"wsb_shipping_name":"Стоимость доставки",
"wsb_shipping_price":"0",
"wsb_discount_name":"Скидка на товар",
"wsb_discount_price":"0",
"wsb_email":"test@test.com",
"wsb_phone":"",
"wsb_return_url":"https://test.com/return",
"wsb_cancel_return_url":"https://test.com/cancel",
"wsb_notify_url":"https://test.com/",
"wsb_3ds_payment_option":"auto",
"*scart":""
}
After sending a request to the specified URL, WEBPAY will return in response filled fields acsUrl, PaReq, TermUrl, MD.
{
"data":{
"token":"92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c",
"tokenName":"wt",
"time":"",
"orderNumber":"",
"invoiceNumber":"",
"transaction":"",
"authorizationCode":"",
"rrn":"",
"trimPan":"",
"payee":"",
"amount":"",
"currency":"",
"responseCode":"",
"responseText":"",
"acsUrl":"https:\/\/ucas.npc.by:8443\/pareq\/194978586\/ceb25c48-69f4-4aec-a069-6f5a8f65cd0d\/",
"PaReq":"eJxVUctSwkAQvPsVFB\/AvmBJqGEpNJZyMKBiWXpbNlOQkoSQhwa+3t0QBG\/dvTM9Oz0wqZNt5xvzIt6l4y7r0e5E3cBykyMGr2iqHBU8YVHoNXbiyFZ4xhdGeN5wIKX2GDNU+1x4EdWR56M0\/mAoqWZdBYvpC+4VtObKevc4kDO1rrnZ6LRUoM3+dhYqnzHOBJCWQoL5LFBccs6temKQ6gTVO64yfQDSEDC7Ki3zg7LtQM4EqnyrNmWZjQj5acp7K9vhVCCX0YvKocK61HGkwmDKPpP7fnjcfs2Dt2P48Fx\/LNf9eTAbA3EVEOkSFadcUMllh\/ERlSPhA2l00Ikbryijdo0ThsyNmF49XAtgE84xNQflC7vkHwOss12KtsLu9IchwsIQu8Dl23ePLj9T2mwY9RilnLsEG8GZxDYLPqSicXEEiGsh7XFIe1uL\/t38FyiprZE=",
"MD":"92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c",
"TermUrl":"https:\/\/payment.webpay.by\/?wt=48957735ca99cdb589ef07753ebaaef5=5255737a5a5539684b335a484f456c594b326b34537a6c59566c6c6e5233684d5a314a6b656b355159335934555734776447313662584e4555325645544459305430396c6545394b543152694c3273344d6b6b3454412c2c"
}
}
Next, to continue the session, you need to send the received parameters to the URL, which is contained in the response in the acsUrl field. The request is sent by
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://ucas.npc.by:8443/pareq/194978586/ceb25c48-69f4-4aec-a069-6f5a8f65cd0d/',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => array('PaReq' => 'eJxVUctSwkAQvPsVFB\\/AvmBJqGEpNJZyMKBiWXpbNlOQkoSQhwa+3t0QBG\\/dvTM9Oz0wqZNt5xvzIt6l4y7r0e5E3cBykyMGr2iqHBU8YVHoNXbiyFZ4xhdGeN5wIKX2GDNU+1x4EdWR56M0\\/mAoqWZdBYvpC+4VtObKevc4kDO1rrnZ6LRUoM3+dhYqnzHOBJCWQoL5LFBccs6temKQ6gTVO64yfQDSEDC7Ki3zg7LtQM4EqnyrNmWZjQj5acp7K9vhVCCX0YvKocK61HGkwmDKPpP7fnjcfs2Dt2P48Fx\\/LNf9eTAbA3EVEOkSFadcUMllh\\/ERlSPhA2l00Ikbryijdo0ThsyNmF49XAtgE84xNQflC7vkHwOss12KtsLu9IchwsIQu8Dl23ePLj9T2mwY9RilnLsEG8GZxDYLPqSicXEEiGsh7XFIe1uL\\/t38FyiprZE=','TermUrl' => 'https:\\/\\/payment.webpay.by\\/?wt=48957735ca99cdb589ef07753ebaaef5=5255737a5a5539684b335a484f456c594b326b34537a6c59566c6c6e5233684d5a314a6b656b355159335934555734776447313662584e4555325645544459305430396c6545394b543152694c3273344d6b6b3454412c2c','MD' => '92a9c54404799d7a08634b0edf224f4d=634574725331424c6454684e57574a574e6c5669523068794e3352545a5339355756564f646e4a704d47356b5548686b595664794e79394e55444245526e4934646b355957697448574642686355394d6479394864512c2c'),
CURLOPT_HTTPHEADER => array(
'Content-Type: multipart/form-data'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
After sending the request, you will receive a form where the payer must enter the 3D-Secure code received via SMS to the cell phone number to which his bank card is linked.
After the payer has entered the 3D-Secure sms-code and clicked the Confirm button, your URL for processing the response from acs, specified earlier in the TermUrl field, will receive the parameters — token, PaReq, MD — necessary to restore the session in WEBPAY.
{
"token":"e801cb1e1b80685bb6fd81ec0617233b=5a6a6c596130xxxxxx5535545731764f586c49536e46795a47524c4e5568544b7a67724c32525461574e6f6446685a63334e514d47746f5931453051305a4c52566848546c424764xxxxxx4554a754e47704f5a772c2c",
"PaReq":"eJxVUe1ugkAQfBXjA3gfSCtmvQSqrTTB2JbWyD88NoVUAQ9o5e17h1jtbmdvd2Z21kIU4U4f0PZKBQQYFXFnzjIktmQWRa3J1Y5FLB2XEo4BtVlRW5YCM64kAuUHcpmcZ5LSC WR89fiTGzObs",
"MD":"d7781ea7482f6f0df17afc7df2abdfc1199b6d460a42279855a4369e3828ae80=547159794b415849646e5242754b35545865694b5766726d62"
}
You need to send a POST request to WEBPAY with the parameters that came from acs in step 2.
To restore the session in WEBPAY you should send POST-request to https://payment.webpay.by/api/v1/payment?wt={token} — for real environment or to https://securesandbox.webpay.by/api/v1/payment?wt={token} — for test environment, where:
The request body should contain MD and PaReq parameters, also received from acs at step 2.
WEBPAY receives your request from step 3, processes it, sends it to the processing and returns to you the response in JSON format. Note that the response comes from the WEBPAY service in the data field.
{
"data":{
"token":"e801cb1e1b80685bb6fd81ec0617233b=5a6a6c596130xxxxxx5535545731764f586c49536e46795a47524c4e5568544b7a67724c32525461574e6f6446685a63334e514d47746f5931453051305a4c52566848546c424764xxxxxx4554a754e47704f5a772c2c",
"tokenName":"wt",
"time":"2023.06.26 13:25:58",
"orderNumber":"ORDER-de35",
"invoiceNumber":"796529012",
"transaction":"608120887",
"authorizationCode":"885415",
"rrn":"001783883631",
"trimPan":"512722xxxxxx8665",
"payee":"\u041e\u041e\u041e \u00ab\u0412\u0415\u0411 \u041f\u042d\u0419\u00bb",
"amount":"0.10",
"currency":"BYN",
"responseCode":"",
"responseText":"",
"acsUrl":""
}
}
To integrate PCI DSS payment for 3D-Secure 2.0, follow the instructions below:
{
"wsb_storeid":"123456789",
"wsb_currency_id":"BYN",
"wsb_version":2,
"wsb_seed":"1242649174",
"wsb_test":0,
"wsb_invoice_item_name":["test"],
"wsb_invoice_item_price":["0.1"],
"wsb_invoice_item_quantity":["1"],
"wsb_operation_type":"",
"wsb_customer_id":"41432",
"wsb_encrypted_data":"LxWN6haDcxu7K2prY2t4P7enfuejEsU7lbD2xvaa8lwQcLQAhchW8xvUXPZWPiYpWuMKtaC3emwALfw9wcB388Gj86Kh7pVSGyljckcFY69tSmvUrUCJYvpNIvYLcBALotXRQCZiijn+ryaXyS0Ymu8G6S6sahWH2UkIEsZJrmMdq2N5fy4sB6fFmDZCtJdCpZHgpCiK9GjX1gvwiB7pOu4vJEwxVmPdheeYsYQiruk+be9U+ENK0EqRA7rZQlrM80lOxw2j2dF2KZYeVbdo5BiYX11bcHNZcgfTbu2zGTQF6MRkV/VPjUuJ+hkMTYPl9XeUYLq8+fMk3QauP/+AXg==",
"wsb_order_num":"ORDER-de35",
"wsb_total":"0.1",
"wsb_signature":"87943d79649e10970b23dfd41194e5a503292bba",
"wsb_tax":"0",
"wsb_shipping_name":"Стоимость доставки",
"wsb_shipping_price":"0",
"wsb_discount_name":"Скидка на товар",
"wsb_discount_price":"0",
"wsb_email":"test@test.com",
"wsb_phone":"",
"wsb_return_url":"https://test.com/return",
"wsb_cancel_return_url":"https://test.com/cancel",
"wsb_notify_url":"https://test.com/",
"wsb_3ds_payment_option":"auto",
"*scart":"",
"wsb_tds_notification_url":"https://companyname.com/test/"
}
After sending a request to the specified URL, WEBPAY will return in response filled fields token, acsUrl, creq.
When passing 3D-Secure verification by Frictionless flow (3D-Secure authentication process without the the cardholder's participation. The issuing bank independently collects data about the transaction, including the device from which it is made, and assesses the possible level of fraud. If no threats are detected, the payment confirmation goes unnoticed by the payer), the request from step 1 will receive a response from step 3.
{
"data":{
"token":"17efa805408c3d0496476f7ef66d5a8f=62554e714f44564b4d30524f4f553148526a527263466c775748687861545a765758466e53476833516d6f3353457458565564595345643157585242636e6c5056573956516e4275575652564e475a4564544a7753672c2c",
"tokenName":"wt",
"time":"",
"orderNumber":"",
"invoiceNumber":"",
"transaction":"",
"authorizationCode":"",
"rrn":"",
"trimPan":"",
"payee":"",
"amount":"",
"currency":"",
"responseCode":"",
"responseText":"",
"acsUrl": "https:\/\/emvacs.qiwi.com\/acs\/api\/3ds2\/creqbrw",
"threeDSSessionData":"",
"creq":"eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhkYjQ3Njc4LTMxMGMtNDg1MS04MTA0LTEyYWFjZTVkY2M4ZSIsImFjc1RyYW5zSUQiOiJkODY4NjJkYi0zYWUwLTQ3ZjMtODdjYi02OTBlNmIxZTEzNjEiLCJkc1RyYW5zSUQiOiI2ODk5YzZmMy03N2JhLTRmNzAtYWY5NS0yNDkyZjQwNjZlMjQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0="
}
}
Next, to continue the session, you need to send the received parameters to the URL, which is contained in the response in the acsUrl field. The request is sent by
POST /acs/api/3ds2/creqbrw HTTP/1.1
Host: emvacs.qiwi.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 327
creq=eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjhkYjQ3Njc4LTMxMGMtNDg1MS04MTA0LTEyYWFjZTVkY2M4ZSIsImFjc1RyYW5zSUQiOiJkODY4NjJkYi0zYWUwLTQ3ZjMtODdjYi02OTBlNmIxZTEzNjEiLCJkc1RyYW5zSUQiOiI2ODk5YzZmMy03N2JhLTRmNzAtYWY5NS0yNDkyZjQwNjZlMjQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0%3D
After sending the request, you will receive a form where the payer must enter the 3D-Secure code received via SMS to the cell phone number to which his bank card is linked.
After the payer has entered the 3D-Secure sms-code and clicked the Confirm button, the payer will be redirected to the URL you specified in step 1 in the wsb_tds_notification_url field also to the specified URL will be sent parameters with the result of the 3D-Secure session, necessary to restore the session in WEBPAY.
To restore a session in WEBPAY you should send POST-request with the header Content-Type: application/x-www-form-urlencoded to https://payment.webpay.by/api/v1/payment?wt={token} — for a real environment or to https://securesandbox.webpay.by/api/v1/payment?wt={token} — for a test environment, where:
The request body should contain the parameters received from acs in step 2 (there can be several parameters, for example, CRes and threeDSSessionData).
POST /?wt=92a2b7aefffcf9d7291e2a068bb0346c%3D526b5a5252557073596e497264314e4c56336c6c64475253556e4e7556474e3565574572596d523156545a48616d6377544752574f486432556d7830526e686155486c495a456f774d484e506432396a5557706859772c2c HTTP/1.1
Host: payment.webpay.by
Content-Type: application/x-www-form-urlencoded
Content-Length: 324
cres=ewogICJ0aHJlZURTU2VydmVyVHJhbnNJRCIgOiAiNjcyMDYxNmItYjJkNy00MjE2LTljM2EtNzcyNzZjN2Q0OWM3IiwKICAibWVzc2FnZVR5cGUiIDogIkNSZXMiLAogICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICJhY3NUcmFuc0lEIiA6ICJiYTA4NjMxZi0yZjRkLTQ2MDgtODU3Yi1jMGM5ZmVjYWQ5NDEiLAogICJjaGFsbGVuZ2VDb21wbGV0aW9uSW5kIiA6ICJZIiwKICAidHJhbnNTdGF0dXMiIDogIlkiCn0
WEBPAY receives your request, processes it, sends it to the processing and returns to you the response in JSON format.
{
"time": "2023.07.14 11:59:03",
"orderNumber": "ORDER-d213e35",
"orderNote": "",
"invoiceNumber": "181060384",
"transaction": "909062398",
"authorizationCode": "KDNVSQ",
"rrn": "319511005218",
"trimPan": "220073xxxxxx8210",
"payee": "ООО «ВЕБ ПЭЙ»",
"customerName": "",
"customerAddress": "",
"serviceDate": "",
"pdfUrl": "https://billing.webpay.by/?kjBNq4f1l1qbIoUeyp7Zpjo6yFeuB%2BPKpl6r1PEBFyzKalsJb84uIMYjM3lYKbn3s1pNEnXRZLqTRKSvomJUVHOd9lnQ3y0zleHOx4VN1ab%2FWQ%3D%3D",
"language": "ru",
"items": [
{
"name": "test",
"quantity": 1,
"price": "0.10",
"totalAmount": "0.10",
"commission": "0.00"
}
],
"amount": "0.10",
"currency": "BYN"
}
The PCI DSS merchant should study the standard work with recurrent payments to make recurrent (CoF) payments and make minimal changes to requests.
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.
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:
The request to unbind the card from recurrent (CoF) payments does not change and is carried out according to the standard scheme.
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:
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".
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.
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 |
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.
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.
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>
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.
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;
}
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 WEBPAY system provides two ways of forming payouts using the P2P type
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 |
When forming the wsb_signature field (the mechanism for generating of the signature is specified in Electronic signature of an order) the wsb_encrypted_data field is also involved. It is put in the end, before the Secret Key from the billing settings, when parameters are concatenated. Then a standard payment script occurs. The difference is only in the response format. The WEBPAY system gives the answer in JSON format.
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.
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.
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 WEBPAY system provides two ways of forming payouts using the P2P type
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:
In the response will be transaction_id parameter for further realization payout on it.
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. |
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:
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/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>
You can use the documentation to configure operation management yourself:
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.
If for any reason no response is received from the WEBPAY system we recommend to repeat the request with an increasing frequency of up to 1 hour. If the WEBPAY system has not returned a response, then mark such operations and send them to support@webpay.by.
Server SDK 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.
The WEBPAY system provides two ways for receiving API reports from real environment personal account https://merchant.webpay.by:
{url_платежного_модуля}/reports/merchants/{reportType}?email={email}&reportFormat={reportFormat}&startDate={startDate}&endDate={endDate}&startFinancialCompletionDate={startFinancialCompletionDate}&endFinancialCompletionDate={endFinancialCompletionDate}&startReversalDate={startReversalDate}&endReversalDate={endReversalDate}
Header Authorization: login:password
Example
https://sander.webpay.by/reports/merchants/RECONCILIATION_REPORT?email=test@webpay.by&reportFormat=JSON&startDate=2019-12-20&endDate=2019-12-30&startFinancialCompletionDate=2019-12-20&endFinancialCompletionDate=2019-12-30&startReversalDate=2019-10-01&endReversalDate=2019-12-30
{payment_module_url}/reports/get
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;
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private Date startFinancialCompletionDate;
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private Date endFinancialCompletionDate;
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private Date startReversalDate;
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd")
private Date endReversalDate;
// Request sent by the POST method
{
"login": "test",
"password": "3434c7ab03ecfbde62ae697a7c66ae8e",
"startDate": "2019-12-20",
"endDate": "2019-12-30",
"reportType": "RECONCILIATION_REPORT",
"reportFormat" : "JSON",
"startFinancialCompletionDate" : "2019-12-20",
"endFinancialCompletionDate" : "2019-12-30",
"startReversalDate" : "2019-12-20",
"endReversalDate" : "2019-12-30"
}