Skip to main content

Payment form widget

You will need to use the payment form widget to perform payouts if you do not have PCI DSS.

You add the widget to the page, show it to the user, and the user then interacts with the widget, going through all the payment steps from beginning to end. The user first securely enters their card details, and then sees a message telling them that the payment has been successful (or an error message if anything goes wrong).

You need to create a payment session, and the widget does the rest: it will send the payment request, redirect the user to the appropriate address, and show them the screen with the result of the operation.

How to perform a payment through the payment form

What the widget looks like

Regular widget

Payment form widget

With a checkbox for enabling recurrent payments

Automatic payment widget

Code example: a page with a widget

<!DOCTYPE html>

<html lang="ru">
<head>
<meta charset="utf-8" />
<title>Payment form widget</title>

<link href="https://widget.bank131.ru/payment-form.css" rel="stylesheet" />
<script src="https://widget.bank131.ru/payment-form.js" defer></script>
</head>

<body>
<div id="bank131-payment-form"></div>

<script>
document.addEventListener('DOMContentLoaded', function () {
if (!window.Bank131PaymentForm) {
return;
}

const paymentForm = new Bank131PaymentForm('publicToken', {
isCvcMasked: true,
customerInteractionRedirect: {
target: "_blank",
});

paymentForm.render();
});
</script>
</body>
</html>

How to add a widget to a page

<!-- In test environment -->
<link href="https://widget-demo.bank131.ru/payment-form.css" rel="stylesheet" />
<script src="https://widget-demo.bank131.ru/payment-form.js" defer></script>
<!-- For real payments -->
<link href="https://widget.bank131.ru/payment-form.css" rel="stylesheet" />
<script src="https://widget.bank131.ru/payment-form.js" defer></script>

2. Add a container with the widget

<div id="bank131-payment-form"></div>

3. Create an instance of the widget

Once the script is linked to the page, the Bank131PaymentForm class will appear in the global scope. To create the payment form, pass the public token obtained to work with the widget to the constructor.

const paymentForm = new Bank131PaymentForm('public token');

To display the payment form, call the render() method:

paymentForm.render();

Widget API

Bank131PaymentForm

Payment form class constructor.

const paymentForm = new Bank131PaymentForm(publicToken[, options])
ParameterTypeDescription
publicTokenStringMandatory. The public token
optionsObjectAdditional settings object.
options.containerHTMLElementThe container into which the form will be inserted.
The default value is: <div id="bank131-payment-form"></div>

Method: paymentForm.render()

The method displays the form on the page, in the container defined by the options.container parameter.

paymentForm.render([options])
ParameterTypeDescription
optionsObjectAdditional settings object.
options.containerHTMLElementThe container into which the form will be inserted.
The default value is:
<div id="bank131-payment-form"></div>

Event handler: paymentForm.onReady

Handles the event of the form becoming ready for work.

paymentForm.onReady = function () { /* handler */ }

Event handler: paymentForm.onPaymentStart

Handles the event occurring at the start of the payment process.

paymentForm.onPaymentStart = function () { /* handler */ }

Event handler: paymentForm.onPaymentSuccess

Handles the event occurring when the payment process finishes successfully.

paymentForm.onPaymentSuccess = function () {
/* handler */
};

Event handler: paymentForm.onPaymentFail

Handles the event occurring when the payment process finishes unsuccessfully.

paymentForm.onPaymentFail = function (error) { /* handler */ }

Widget customization

Hide CVV/CVC details

You can customize the CVV/CVC field of the widget to make it display only the latest digit entered by customers and mask the others entered before with *. To do this, add the isCvcMasked flag into the widget constructor, as follows:

const paymentForm = new Bank131PaymentForm('publicToken', {
isCvcMasked: true,
});

Open the 3DS window as required

You can choose how to open the 3DS window for the user. Use the target parameter of the customerInteractionRedirect object with the following options:

  • _blank - in a new tab
  • _self - in the same frame
  • _parent - in the next-level frame if the frames are nested in one another
  • _top - outside of all the frames as the top window
    Default: _top.

Note that:

  • We do not recommend using the _self option for security reasons.
  • If you use the _blank option, the user will need to allow pop-ups in the browser or follow the redirection link from the payment widget.

Appearance

You can link your own styles after the library ones and override them, like this:

<link href="https://widget.bank131.ru/payment-form.css" rel="stylesheet" />
<link href="custom-styles.css" rel="stylesheet" />

Or this:

/* custom-styles.css */

.bank131-Field__label {
color: green;
}

You cannot yet change the appearance of the values entered inside the iframe. This functionality will be added later.

Also, you can modify texts of the widget UI elements. Here are what you can change:

  • labels:
  • placeholders;
  • error messages;
  • prompt texts;
  • button names;
  • footer texts.

To do that, you should pass the Options object with UI elements parameters within the Bank131PaymentForm widget constructor.

Widget UI elementParameter nameTypeDefault value
Widget text settingstextsobject
Failed payment messagefailedPaymentScreenstringОшибка
Payment formpaymentFormobject
Payment button namebuttonPayLabelstringОплатить
Cardholder name textcardholderLabelstringВладелец карты
Cardholder name prompt textcardholderNotestringNone
Cardholder name placeholdercardholderPlaceholderstringИМЯ ФАМИЛИЯ
Card numbercardNumberLabelstringНомер карты
Card number prompt textcardNumberNotestringотсутствует
Card number placeholdercardNumberPlaceholderstring0000 0000 0000 0000
CVV/CVC numbercvvLabelstringCVC
CVV/CVC number prompt textcvvNotestringNone
CVV/CVC number placeholdercvvPlaceholderstringCVC
Card expiration dateexpireDateLabelstringСрок действия
Card expiration date prompt textexpireDateNotestringКак на карте
Card expiration date placeholderexpireDatePlaceholderstringММ/ГГ
Recurring payment checkboxrecurrentLabelstringСоглашаюсь на автоплатежи
Terms of agreement
Terms of agreement.
The text within the mandatory {{#link}}{{\/link}} tags is used as a link to the terms of agreement source.
termsAgreementstringНажимая кнопку «Оплатить» вы соглашаетесь с условиями \{\{\#link\}\}пользовательского соглашения\{\{\/link\}\}
Field validation error messagesvalidationErrorsobject
Invalid card numberINVALID_CARD_NUMBERstringНеверный номер карты
Invalid CVV/CVCINVALID_CVVstringКод должен содержать 3 цифры
Invalid card expiration dateINVALID_EXPIRY_DATEstringНеверная дата
Required field value is missingIS_REQUIREDstringОбязательное поле
Payment process pagepaymentProcessScreenobject
Payment processing page textdescriptionstringЭто займет совсем немного времени
Payment process screen headingtitlestringПроисходит оплата...
Redirecting page (3D Secure)redirectionScreenobject
Invitation message to proceed with redirection in case of automatic redirection failure.
The text within the mandatory {{#link}}{{\/link}} tags is used as a link.
followTheLinkstringЕсли этого не произошло, перейдите \{\{\#link\}\}по ссылке\{\{\/link\}\}.
Payment processing page headertitlestringПроисходит оплата...
Automatic redirection warning, includes 3 seconds countdown timer.
The {{countdown}} value is mandatory and will be replaced with the timer.
Use the {{#strong}}{{\/strong}} tags to emphasise the timer in bold.
waitForRedirectToBanksPagestring\"Через {{#strong}}{{countdown}} сек.{{\/strong}} Вы будете перенаправлены на страницу банка-эмитента.\
Successfull payment pagesuccessPaymentScreenobject
Successfull payment page headertitlestringУспешно
Transaction datatransactionDataobject
Transaction amount labelamountLabelstringСумма
Payment type data (card type and masked card number) labelcreditCardLabelstringКарта
Transaction ID labeltransactionIdLabelstringID транзакции
Unknown error messageunknownErrorstringЧто-то пошло не так...
Feedback