Розширені можливості

Використання номерів замовлень в запитах

Якщо при ініціалізації платіжного віджета не передавати параметр orderId, кожна нова сесія віджета буде створюватися з автоматично згенерованим номером замовлення. Для використання власного номеру замовлення в запиті на ініціалізацію віджета, необхідно передавати відповідне значення, використовуючи параметр orderId. Це також дозволить відобразити вже існуючий платіж, якщо сесія віджета з таким orderId вже була раніше створена.

Приклад ініціалізації віджета з передачею номера замовлення:

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

Обробка івентів

Для обробки івентів платіжного віджета необхідно зареєструвати функцію зворотного виклику. Для цього в код ініціалізації віджета треба додати виклик методу on(eventName, callback) з передачею назви події та функції зворотного виклику.

Приклад ініціалізації віджета з реєстрацією функцій для обробки подій:

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

Платіжний віджет підтримує відправку таких івентів:

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

Передача інформації про продукти

В запиті на ініціалізацію платіжного віджета також можна передати список продуктів. Ці продукти будуть включені до запиту на створення платежу. Наразі список продуктів на самому платіжному віджеті не відображається

Важливо

При фіскалізації платежів за допомогою ПРРО передача в запиті інформації про продукти є обовʼязковою.

Передача інформації про платника

Деякі платіжні шлюзи можуть вимагати передачу додаткової інформації про платника. Цю інформацію можна також додати в запит на ініціалізацію платіжного віджета.

Приклад ініціалізації платіжного віджета з інформацією про продукти, даними платника та усіма івентами:

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

Закриття платіжного віджета

За необхідності платіжний віджет може бути закритий у звʼязку з настанням певної події, про яку отримано зворотний виклик, або за вашою ініціативою.

Приклади використання (отримання зворотного виклику про неуспішну транзакцію ініціює закриття віджета):

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

Підтримувані мови

Платіжний віджет може бути відображений різними мовами з можливістю задати власне значення будь-якому параметру, що відображається платнику.

Управління мовами платіжного віджета здійснюється через параметр locale.

Підтримувані локалі:

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

Якщо в запиті на ініціалізацію платіжного віджета жодне зі значень не передане, то за замовчуванням використовується значення мови браузера платника, що передається у фінгерпринті. Для мов браузера uk або ru - віджет відображається українською. Для всіх інших мов - англійською.

Приклад запиту:

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

Для встановлення власних значень параметрам платіжного віджета слід використовувати блок localization.

Приклад запиту:

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

Перелік UI-компонентів платіжного віджета, яким можна задати власне значення:

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

Використання номерів замовлень в запитах​

Обробка івентів​

Передача інформації про продукти​

Передача інформації про платника​

Закриття платіжного віджета​

Підтримувані мови​