Advanced usage

Incorporating order IDs in requests

If the orderId parameter is not passed during the payment widget initialization, a new widget session will be created with an automatically generated order ID. To use your custom order ID in the widget initialization request, ensure you pass the desired value using the orderId parameter. This also allows you to display an existing payment if a widget session with that specific orderId has been created previously.

Example of widget initialization with the passing of an order ID:

<script>
    const widget = PaymentWidget.init({
        apiKey: 'YOUR_API_KEY',
        mode: 'popup',
        payment: {
            type: 'hold',
            orderId: '1002289582',
            description: 'Payment #1002289582',
            amount: 1.99,
            currency: 'UAH',
            serverUrl: 'https://myshop.ua/payment/notify'
        }
    });
</script>

Event handling

To handle events triggered by the payment widget, it is necessary to register a callback feature. This can be achieved by incorporating a call to the on(eventName, callback) method within the widget initialization code, specifying the event name and the corresponding callback function.

Example of widget initialization with the registration of a function for event processing:

<script>
    PaymentWidget.init({
        apiKey: 'YOUR_API_KEY',
        mode: 'popup',
        payment: {
            type: 'hold',
            amount: 1.99,
            currency: 'UAH'
        }
    }).on('widget.ready', function(data){
      // ready
    }).on('widget.error', function(data){
      // error
    }).on('payment.success', function(data){
      // success
    }).on('payment.failed', function(data){
      // failed
    });
</script>

The payment widget supports the following events:

Event Name	Description
`widget.ready`	Payment widget has been successfully initiated
`widget.error`	An error occurred during the initialization of the payment widget
`payment.success`	Payment has been successfully completed
`payment.failed`	Payment has failed

Passing information on products

You can include a list of products in the payment widget initialization request, and these products will be incorporated into the corresponding payment. Please note that, at present, the product list is not visible on the payment widget.

caution

For taxation purposes when using PRRO, it is mandatory to include information about products in the request.

Transmitting data on payer

Some payment gateways may necessitate the inclusion of extra details about the payer. You can include this additional information in the payment widget initialization request.

Example of initializing a payment widget with product details, payer information, and handling all events:

<script>
    const widget = PaymentWidget.init({
        apiKey: 'YOUR_API_KEY',
        mode: 'embedded',
        selector: '#widget',
        payment: {
            type: 'hold',
            orderId: '1002289582',
            description: 'Payment #1002289582',
            amount: 399.98,
            currency: 'UAH',
            serverUrl: 'https://myshop.ua/payment/notify',
            products: [
                {
                    name: "Xiaomi fan",
                    price: 199.99,
                    quantity: 2
                }
            ],
            payer: {
                id: '10000123',
                firstName: 'John',
                middleName: '',
                lastName: 'Doe',
                phone: '+123456789',
                email: '[email protected]',
                birthDate: '1990-01-01',
                billingAddress: {
                    line1: '',
                    line2: '',
                    city: 'LA',
                    country: 'US',
                    state: 'CA',
                    postalCode: '90001'
                }
            }
        }
    });
    widget
        .on('widget.ready', function(data){})
        .on('widget.error', function(data){})
        .on('payment.success', function(data){})
        .on('payment.failed', function(data){});
</script>

The payment widget can be programmatically closed in response to specific events. This feature enables you to either respond to callbacks received (e.g., transaction failures) or initiate closure proactively at your request.

Request example (the widget will be closed upon receiving a callback indicating a failed transaction):

</script>
  const widget = PaymentWidget.init({
    apiKey: 'YOUR_API_KEY',
    mode: 'popup',
    payment: {
      type: 'hold',
      amount: 1.99,
      currency: 'UAH'
    }
  })
  widget.on('payment.failed', function(data){
    // failed
    widget.close()
  });
</script>

Locales

The payment widget can be displayed in various languages, and you have the flexibility to set custom values for any parameter shown to the payer.

The languages for the payment widget are configured using the locale parameter.

Supported locales include:

Parameter value	Language
`en`	English
`uk`	Ukrainian
`ru`	Russian

If no language values are specified in the initialization request for the payment widget, the default language used will be determined by the payer's browser settings, as indicated by the browser's fingerprint. If the browser language is set to uk or ru, the widget will display in Ukrainian. For all other languages, it will default to English.

Request example:

PaymentWidget.init({
  apiKey: "test_E3PALDNAQ11OV9D0141MKB3I9RJRJDR2MJPP",
  mode: "embedded",
  selector: '#widget',
  locale: 'en',
  payment: {
    type: "pay",
    amount: 2.99,
    currency: "UAH",
  }
})

To customize the parameters of the payment widget, use the localization object.

Request example:

PaymentWidget.init({
  apiKey: "test_E3PALDNAQ11OV9D0141MKB3I9RJRJDR2MJPP",
  mode: "embedded",
  selector: '#widget',
  locale: 'en',
  localization: {
    "en": {
      "submit": "Donate",
    },
    "fr": {
      ...
    },
  },
  payment: {
    type: "pay",
    amount: 2.99,
    currency: "UAH",
  }
})

List of customizable UI components in the payment widget:

Parameter	Description	Default value EN	Default value UK	Default value RU
`chooseAnother`	Section to pay using a card	or enter card details	або введіть дані картки	или введите данные карты
`orderNum`	Order number	Order No.	Замовлення	Номер заказа
`optional`	Optional field indicator	Optional	Опціонально	опционально
`cardNumber`	Input field for the card number	Card number	Номер карти	Номер карты
`cardExpDate`	Input field for the card expiration date	Card expiry	Термін дії картки	Срок действия
`cvv`	Input field for card verification value/code	CVV2/СVC2	CVV2/СVC2	CVV2/СVC2
`submit`	Payment button for the card option	Pay	Сплатити	Оплатить
`errorCardNumberField`	Error message for the card number field	Card number is not valid	Номер картки недійсний	Номер карты недействителен
`errorExpDateField`	Error message for the card expiration date field	Expiration date is not valid	Дата закінчення терміну дії картки недійсна	Дата истечения срока карты недействительна
`errorCvvField`	Error message for the card verification value/code field	CVV is not valid	CVV недійсний	CVV недействителен
`errorRequiredField`	Error message for a mandatory field	Required field	Обов'язкове поле	Обязательное поле
`successPayment`	Notification of successful payment	Your payment is successful!	Ваш платіж успішний!	Ваш платеж успешный!
`failedPayment`	Notification of failed payment	Your payment is unsuccessful!	Ваш платіж неуспішний!	Платёж не отправлен
`paymentIsNotCompleted`	Notification when payment is in process	Processing payment	Опрацьовуємо платіж	Обрабатываем платёж
`pendingExpired`	Notification for transactions lacking a confirmed final status	If funds have already been withdrawn from your card, please wait up to 5 minutes for payment confirmation.	Якщо кошти вже були списані з картки, будь ласка, зачекайте до 5 хвилин для отримання фінального статусу платежу.	Если средства уже были списаны с карты, пожалуйста, подождите до 5 минут, чтобы получить окончательный статус платежа.
`wait`	Button to request the current status of transactions	Wait	Зачекати	Подождать
`redirectRequiredTitle`	Notification in the embedded payment widget advising customers to undergo 3DS verification	Click to Open 3DS Verification Window	Натисніть, щоб відкрити вікно підтвердження 3DS	Нажмите, чтобы открыть окно подтверждения 3DS
`redirectRequiredButton`	Button in the embedded payment widget to initiate 3DS verification	Proceed with 3DS Verification	Продовжити з перевіркою 3DS	Продолжить с проверкой 3DS

Incorporating order IDs in requests​

Event handling​

Passing information on products​

Transmitting data on payer​

Configurable payment widget closure​

Locales​

Incorporating order IDs in requests

Event handling

Passing information on products

Transmitting data on payer

Configurable payment widget closure

Locales