Advanced features

Using order numbers in requests

If the orderId parameter is not passed during payment widget initialization, each new widget session is created with an automatically generated order number. To use your own order number in the widget initialization request, pass the required value in the orderId parameter. This also allows you to display an existing payment if a widget session with the same orderId was already created.

Example of widget initialization with an order number:

<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 payment widget events, register a callback function. To do this, add the on(eventName, callback) method call to the widget initialization code and pass the event name and callback function.

Example of widget initialization with event handling callbacks:

<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 can send 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 product information

You can also pass a list of products in the payment widget initialization request. These products will be included in the payment creation request. At the moment, the product list is not displayed in the payment widget itself.

caution

When payments are fiscalized through a software cash register, product information must be passed in the request.

Passing payer information

Some payment gateways may require additional payer information. You can also add this information to the payment widget initialization request.

Example of payment widget initialization with product information, payer data, and 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>

If needed, the payment widget can be closed when a specific event occurs and a callback is received, or at your own initiative.

Usage example: receiving a callback about a failed transaction closes the widget.

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

Supported languages

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

The payment widget language is managed through the locale parameter.

Supported locales:

Parameter value	Language
`en`	English

If the widget initialization request does not include a language value, the widget is displayed in English by default.

Request example:

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

Use the localization block to set custom values for payment widget parameters.

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 payment widget UI components that can be customized:

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

Using order numbers in requests​

Event handling​

Passing product information​

Passing payer information​

Closing the payment widget​

Supported languages​

Using order numbers in requests

Event handling

Passing product information

Passing payer information

Closing the payment widget

Supported languages