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: 'EUR',
            serverUrl: 'https://myshop.pl/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: 'EUR'
        }
    }).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.

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: 'EUR',
            serverUrl: 'https://myshop.pl/payment/notify',
            products: [
                {
                    name: "Xiaomi fan",
                    price: 199.99,
                    quantity: 2
                }
            ],
            payer: {
                id: '10000123',
                firstName: 'John',
                middleName: '',
                lastName: 'Doe',
                phone: '+123456789',
                email: 'john.doe@mail.com',
                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: 'EUR'
    }
  })
  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

If no language value is specified in the initialization request for the payment widget, the widget defaults to English.

Request example:

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

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: "EUR",
  }
})

List of customizable UI components in the payment widget:

Parameter	Description	Default value
`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
`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
`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.
`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
`redirectRequiredButton`	Button in the embedded payment widget to initiate 3DS verification	Proceed with 3DS Verification
`entityNameLabel`	Recipient name	Name:
`businessRegLabel`	Business registration number/Entrepreneur tax ID	Business ID/Tax ID:
`ibanLabel`	IBAN	IBAN:
`merchantInfoBtn`	Information about the payment recipient	Information about the recipients
`temporaryUnavailable`	Issue with displaying recipient data	Temporary unavailable

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