PayU | Installments

Using PayU Installments, customers have the option to divide the expense of their purchase into monthly payments of equal amounts, spread over a defined period. This approach can render larger purchases more manageable and within reach for customers who might not have the immediate funds to cover the entire cost upfront.

Service Description

• PayU | Installments are available for merchants free of charge.
• PayU | Installments are available for shopping carts worth PLN 100 to PLN 50,000 (depending on the variant).
• The service can be integrated via OpenPayU (REST API).
• The value of payMethod (OpenPayU) or pay_type (NewPayment) parameter is ai.

The process of handling payments through the PayU | Installments service in an online store involves two stages.

1. A buyer places an order on an e-shop webpage.
2. PayU confirms that the payment has been settled correctly.

First Stage - Placing an Order by the Customer

1. The buyer clicks on a button that represents PayU | Installments.
2. If the payMethod.pay_type parameter is set to a value other than ai, and both the first name and last name are not provided, the PayU system will display an order summary page. On this page, the buyer will need to confirm the payment.
3. The PayU system redirects the buyer to the website of a credit partner.
4. The buyer performs the actions required by the credit partner, such as accepting an offer or making a verification transfer.
5. Credit partner confirms to PayU that it has processed the payment and redirects the buyer back to the PayU website.
6. At this stage, a transaction may receive one of three statuses depending on the loan lender's decision or ability to consider the installments request:
   • In the event that the credit partner cannot promptly verify all request details or process the loan request, the transaction status will be marked as PENDING. Subsequently, the buyer will be directed to a PayU webpage containing information about the PENDING status and a button to return to the shop.
   • Should a loan not be granted or the credit partner is unable to process the loan request, the transaction status will be designated as FAIL, prompting the redirection of the buyer to a page specified as a negative URL in the shop configuration.
   • After the credit request undergoes assessment and gains approval, the transaction status will be updated to SUCCESS. This, in turn, will lead to the redirection of the buyer to a page specified in the shop configuration as a positive outcome.
7. The PayU system redirects the buyer to a page in your system that informs the buyer that the order has been successfully placed.

Credit Confirmation

Once the transaction has been confirmed manually (or automatically collected), the buyer is informed about the outcome of loan request processing.

Second Stage (optional) - Payment Settlement

1. The PayU system notifies your system that the status of the payment order has changed.
2. Your system confirms receiving the notification.

Integrating Installments

For PayU | Installments, the standard order request should be extended with payMethods object containing specified payment method.

Request Example with Installments Specified as a Payment Method

curl -v -X POST https://secure.payu.com/api/v2_1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
    "notifyUrl": "https://your.eshop.com/notify",
    "customerIp": "127.0.0.1",
    "merchantPosId": "145227",
    "description": "RTV market",
    "currencyCode": "PLN",
    "totalAmount": "99900",
    "extOrderId":"yrjut2mp63wdzcozq7w0br",
    "buyer": {
        "email": "jan.kowalski@example.com",
        "phone": "654111654",
        "firstName": "Jan",
        "lastName": "Kowalski"
     },
     "payMethods":{
          "payMethod":{
              "type":"PBL",
              "value":"ai"
          }
      },
      "products": [
          {
              "name": "Laptop",
              "unitPrice": "99900",
              "quantity": "1"
          }
       ]
 }'

For details on parameters, please refer to Create an Order section in the Single Platform API Reference.

Notes

Highlighted within the above request are:

• The buyer object, which specifies basic customer information.
• And the payMethods object, which specifies installments (ai) as the payment method.

POS used in the example does not have installments switched on. Consequently, the Buyer won't be directed to the application form; instead, the PayU system will display a summary page.

Automatic Collection

Notes

PayU makes it possible to enable or disable the automatic receipt in a POS.

Unless you disable automatic collection on one of your POS, any transaction created with its credentials will be processed automatically without manual confirmation. If this option is disabled, you will need to manually confirm transactions in the management panel.

Manually Confirming Transaction

To manually confirm a transaction in the Management Panel when Automatic collection is disabled:

1. Go to the Management Panel.
2. Click on the Transactions tab. A list will appear underneath, from which select the "List of transactions" option.
3. In the Status field, select "Waiting for collection". Optionally, set other search parameters.
4. Click on the Show button.
5. To confirm the transaction, in the Action column, click on Collect.
6. Check if data is correct and click on OK button

Notes

Information about transaction support via API is available in the Capture and Cancel section.

How to promote

The objective of every e-business is to provide customers with a comprehensive and innovative offering. With the introduction of PayU | Installments, a store can accomplish this objective by presenting details about the new service in a straightforward and lucid manner.

This section outlines the process of incorporating the following components:

• Elements contributing to graphic identification, including buttons and static banners.
• Installment widget.
• Calculator widget.

These elements provide the following advantages:

• professional approach to e-shop customers;
• relevant amount of information about shopping on installments;
• keeping customers interested, thus increasing the number of successful transactions;
• allowing customers to make quick payments;
• encouraging satisfied customers to return to the e-shop.

Graphic Identification

Sign - “Here you can pay via PayU | Installments”

In order to inform a customer that you offer shopping on installments, we recommend adding the "Here you can pay via PayU | Installments" button on the main page or on other e-shop pages

A customer who clicks on the button is redirected to the informational PDF document about PayU Installments.

To produce this effect on your shop website, enter the following code:

Link Implementation

<a href="http://www.payu.pl/en/payu-installments-for-business"><img src="http://static.payu.com/pl/standard/partners/raty_payu/tu_kupisz_na_raty_payu_blue.png"/></a>

Other graphic versions are available here.

Button - "Transaction"

To draw your customer's attention to quick installment shopping, use the following button:

To produce this effect on your shop website, style the form button using the following code between the <head> tags:

Button Implementation

<style type="text/css">
    form[name='payform'] input[type='submit'] {
        border: 0px;
        height: 35px;
        width: 100px;
        background: url('http://static.payu.com/pl/standard/partners/raty_payu/raty_small.png');
        cursor: pointer;
    }
</style>

Other graphic versions are available here.

Static Banners

We have also designed static graphical ads which you can use to inform customers that PayU | Installments are available in your shop.

Other graphic versions are available here.

Widget Installments

To communicate the minimum installment value for a specific product to customers, we suggest integrating an installment widget within the product list, individual product cards, the shopping cart, and the checkout section. When implementing the widget in the product list, which might involve multiple widgets, it's important to ensure each widget has a distinct identifier. A practical approach would be to assign an "id" corresponding to the product's ID. For instance, for a product with the ID 3241, you can set the "id" as id="installment-mini-3241".

To embed the widget into your website:

1. Open the source code of your website.
2. Paste the following script in the <head> section.
Scripts Needed for Widget
<meta charset="utf-8" />
<script src="https://static.payu.com/res/v2/widget-mini-installments.js"></script>
Warning!

Please refrain from copying this script to your server, as PayU scripts contain specific information about the current installment settings.

3. Paste the following code, after editing creditAmount, posId (enter your data) and key (enter your data) in the <body> section of your source code.
Widget Example
<p><span id="installment-mini"></span></p>
<script type="text/javascript">
    var value = 1234.56
    var options = {
        creditAmount: value, // amount in PLN
        posId: '00000', // point of sale identifier
        key: 'a0', // first two characters of API key
        showLongDescription: true,
    }

    OpenPayU.Installments.miniInstallment('#installment-mini', options)
        .then(function (result) {
            // This fragment of code will be executed after widget is shown
            // parameter ‘result’ contains additional functions and parameters described in 'Additional integration metods' section
        })
        .catch(function (e) {
            console.error(e.toString()) // This snippet writes config errors
            // to developer’s console
        })
</script>
Parameters Available in the Panel.

Parameter	Default value	Required	Description
creditAmount	none	yes	Purchase value should be in correct range – check the range for PayU | Installments payment method on page Installments and Pay later. If amount is out of given range widget will not be presented.
posId	none	yes	Point of sale identifier posId. Identifier contains only digits.
key	none	yes	Key dependent on the point of sale type. Key contains digits or lowercased characters a-f. For: REST API - first characters of 'OAuth protocol - client_secret' Classic API - first two characters of 'Key (MD5)'
showLongDescription	false	no	Once activated, the specific prefix will be added. For languages: pl (default), Rata już od: en, Installment from: It is recommended to iniatiate value with a true value. Regarding future product changes it will be automatically updated.
currencySign	PLN	no	Currency
lang	pl	no	Language used in the component. Available values: en, pl.

4. Save changes.
5. Refresh the website in your browser.

Notes

If you cannot see any changes despite refreshing the page, try to clear cache and verify if the creditAmount is in correct range - check the range for PayU | Installments payment method on page Installments and Pay later.

Additional Integration Methods

OpenPayu.Installments.miniInstallment function returns a Promise with resolved result object. Structure of a result object is presented in a table below.

Result Parameters

Parameter	Type	Required	Description
isWidgetAvailable	boolean	yes	true, when input parameters allow to display widget. Otherwise false, when for example credit amount is out of correct range - check the range for payment method on PayU | Installments page.
element	HTMLElement	available, when isWidgetAvailable = true	DOM element containing text with installment amount and link opening popup with installments details.
openWidget	function	available, when isWidgetAvailable = true	Function displays installment details popup.

Using the element Object

Example of Code Snippet Showing element Object Usage

<p><span id="installment-mini"></span></p>
<script type="text/javascript">
    var value = 1234.56
    var options = {
        creditAmount: value, /// amount in PLN
        posId: '00000', // point of sale identifier
        key: 'a0', // first two characters of API key
        showLongDescription: false,
    }
    OpenPayU.Installments.miniInstallment('', options) // selector is not required
        .then(function (result) {
            if (result.isWidgetAvailable) {
                // check if widget is available
                const customText = document.createElement('span')
                customText.innerText = 'PayU installments from: '
                document.getElementById('installment-mini').append(customText)
                document
                    .getElementById('installment-mini')
                    .append(result.element) // element can be appended to any html element on page
            }
        })
        .catch(function (e) {
            console.error(e.toString()) // This snippet writes config errors
            // to developer’s console
        })
</script>

Notes for the element Object:

• Upon calling the OpenPayU.Installments.miniInstallment('', options) function, you can utilize the element object within a Promise callback. This element object represents a DOM element containing text that displays the installment amount and a link that, when clicked, opens a popup containing installment details.
• element object is also available when selector argument in OpenPayU.Installments.miniInstallment function is empty (undefined, null or ""). In that case you need to display element in your own scripts.
• element object is available only when isWidgetAvailable equals true. Before object usage check if condition is fulfilled.
• It's considered a good practice to hide all HTML elements that rely on the widget's availability, especially when the isWidgetAvailable parameter is set to false.

Displaying Installment Details Popup Manually

Example of a Code Snippet Allowing to Open Widget Popup

<img
    id="payuLogo"
    src="https://poland.payu.com/wp-content/themes/global-website/assets/src/images/payu-logo.svg"
    hidden
/>
<script>
    var options = { creditAmount: 2200, posId: '00000', key: 'a0' }
    window.OpenPayU.Installments.miniInstallment('', options)
        .then(function (result) {
            if (result.isWidgetAvailable) {
                document.querySelector('#payuLogo').removeAttribute('hidden') // display element
                document.querySelector('#payuLogo').onclick = function () {
                    result.openWidget()
                } // handle onclick action
            }
        })
        .catch(function (e) {
            console.error(e.toString())
        })
</script>

Notes for openWidget() Function:

• Upon invoking the OpenPayU.Installments.miniInstallment('', options) function, you can access the openWidget() function within a Promise callback. This function enables you to present a popup displaying installment details.
• openWidget() function is available when isWidgetAvailable equals true. Before function invocation check if condition is fulfilled.
• A recommended approach is to hide all HTML elements that will have the openWidget() function attached to them, in situations where the isWidgetAvailable parameter is set to false.
• If you don't need to present installment amount, pass empty selector (undefined, null or "") to OpenPayU.Installments.miniInstallment function.

FAQ

After adding the code to the website, a blank page is displayed.

While modifying the code, the HTML file structure may have been damaged, causing the webpage to function improperly or not at all (resulting in a blank screen). An HTML file is a structured document that must maintain the correct format.

After adding the code to the website, I don't see any changes; the widget is not visible.

• The amount is not within the correct range – refer to the amount ranges for the PayU Installments payment method.
• Check if the widget is not visible at the bottom of the page. If the widget is visible on the page (but in the wrong location), refer to point 3.
• Verify whether there are any configuration validation errors for the widget. These errors are logged to the browser console.
• Ensure that the backend code (e.g., PHP) is correctly inserted into the HTML page.
• The widget consists of three elements: a link to our script (in the head tag), an HTML tag with the widget (in the body tag), and code executing the JavaScript function. It is likely that one of these elements is missing from the page.
• For each product on the product list, the widget needs to be added.

The widget is displaying, but in the wrong location.

You need to locate an element on the page, likely associated with the price, beneath which the mini installment widget should appear, and move the HTML tag to that location.

The widget is displaying incorrect data.

• The correct codes have been added in the right places; however, an incorrect amount was passed to the widget.
• There are HTML tags on the page with duplicated identifiers (id).

On which pages is it worth placing the widget?

• Product description/product card
• Product list – for each product, a separate widget. Be careful to ensure that each widget has a unique ID (e.g., id="installment-mini-2903", next one could be id="installment-mini-2821").
• Cart
• Checkout – order finalization

Where can I find the POS_ID and KEY?

• In the widget installation instructions, certain data indicated in the HTML code are examples, and you should replace them with your own data. These include, for example, POS_ID and KEY.
• Log in to the management panel.
• Choose My Stores.
• Select the payment point in the chosen store.
• Click on the relevant payment option.
• A green frame with data will appear.
• POS_ID consists only of digits.
• The entire key shown in the management panel (under the name OAuth Protocol – client_secret or, if absent, Second key (MD5)) consists of 32 characters (digits or lowercase letters a-f). Only the first two characters of the key are required.

I am using a so-called boxed system. Will the widget work for me?

• To make the widget work, a change in the page's source code is required. For some boxed systems, modifying the code may be challenging. In such cases, contact your software provider. If you are using PrestaShop, you don't need to install the widget - PayU provides an official PrestaShop plugin with the option to promote installment payments, including the installment widget.
• The recommended version of the PrestaShop plugin is at least 3.1.14. If you are using an older version, we recommend updating the plugin.