IPS UCB - Instant Payment Serbia via UniCredit Bank

Prev Next

ips-ucb is the Monri Components payment method for IPS (Instant Payment Serbia), the instant payment system of the National Bank of Serbia (NBS), acquired through UniCredit Bank Serbia (UCB). The buyer pays from the m-banking application of their own bank: on a desktop by scanning a one-time IPS QR code, on a phone by choosing their bank and opening its application. This page follows the structure of IPS - Instant Payment Serbia, which documents the ips-rs method.

ips-rs, ips-ucb and ips-otp are separate methods

ips-rs, ips-ucb and ips-otp are separate payment methods, and your merchant account must have the one you call enabled; otherwise initiate-payment answers 422 with Direct payment type: '<name>' not supported.

method name IPS connection article
ips-rs IPS - Instant Payment Serbia IPS - Instant Payment Serbia
ips-ucb IPS through UniCredit Bank Serbia this page
ips-otp IPS through OTP Bank Serbia IPS OTP

The method name selects the bank connection. Monri confirms the name when IPS is activated on your account. Use the same name in supported_payment_methods on your backend (Step 2) and in components.create() on your frontend (Step 5).

When the name does not match your account, the component's request POST https://ipg.monri.com/v2/uac/<method name>/<client-secret>/initiate-payment (ipgtest.monri.com in the test environment) answers 422:

{ "errors": ["Direct payment type: 'ips-rs' not supported"] }

Change the name to the one enabled on your account; nothing else needs to change.

Setup and integration

Step 1: Include the Monri Components script

The ips-ucb component is part of Monri Components. Include the script directly from monri.com for PCI (Payment Card Industry) compliance:

Test environment:

<script src="https://ipgtest.monri.com/dist/components.js"></script>

Production environment:

<script src="https://ipg.monri.com/dist/components.js"></script>

Step 2: Backend requirements

When generating the client_secret on your backend via the /v2/payment/new endpoint, ensure:

{
  "ch_full_name": "Customer Full Name",
  "supported_payment_methods": [
    "ips-ucb"
  ],
  "amount": 100,
  "currency": "RSD"
}

Critical: If ch_full_name is missing, the client_secret will be invalid and the component will fail to initialize.

Step 3: Initialize Monri and Components

const monri = Monri('<authenticity-token>', {
    locale: 'sr' // Set default language
});
const components = monri.components({clientSecret: '<client-secret>'});

Step 4: Create the payment form container

<div id="ips-ucb-element"></div>

Step 5: Create and mount the component

const ips = components.create("ips-ucb", {
    trx_token: "<client-secret>",
    environment: isTestSystem ? "test" : "prod",
    lang: "sr",  // Set initial language
    style: {
        // See the styling section below
        container: {
            maxWidth: "600px",
            margin: "0 auto"
        }
    }
});

// Mount the component
ips.mount("ips-ucb-element");
option value
trx_token the client_secret from Step 2, the same value you pass to monri.components()
environment "test" loads the component from ipgtest.monri.com and starts the payment there, with your test authenticity token; "prod" uses ipg.monri.com
lang the initial language, one of the codes under Supported languages
style optional styling, see Style configuration object

Mount the component while its container is visible. The component reads the width of your page at mount time and chooses the desktop or the phone layout from it, see What the buyer sees.

Component dimensions and responsive behavior

The IPS payment component automatically adjusts its dimensions based on content and user interactions. Here are the minimum requirements for proper integration:

Minimum dimensions by platform

Mobile devices (≤768px width)

Initial state (no bank selected):

  • Minimum width: 340px
  • Minimum height: 360px

Bank selected state:

  • Minimum width: 340px
  • Minimum height: 420px

Desktop/Web (>768px width)

All states:

  • Minimum width: 400px
  • Minimum height: 250px (dynamically adjusts based on content)

Bank selection logic

On a phone the component first asks whether the buyer pays as an individual or as a legal entity or entrepreneur, then lists the banks that offer an IPS deep link for that payer type.

  • Selecting a bank shows the bank logo, enables the Pay with app button and raises the frame to 420px.
  • The buyer can tick Remember my bank selection. The choice is stored in the browser's local storage and preselected the next time the component mounts on your site.
  • Pay with app opens the selected bank's m-banking application through its deep link.

Auto-resize functionality

  • Component automatically sends RESIZE_IFRAME messages to parent element
  • Height adjustments happen in real-time based on content changes
  • Minimum thresholds are always maintained regardless of content

Integration requirements

Container setup:

Ensure your iframe container can accommodate:

/* Mobile */
@media (max-width: 768px) {
    .payment-iframe {
        min-width: 340px;
        min-height: 420px; /* Allows expansion for bank selection */
    }
}

/* Desktop */
@media (min-width: 769px) {
    .payment-iframe {
        min-width: 400px;
        min-height: 250px;
    }
}

Important notes

  • Always reserve space for expanded state (420px height on mobile)
  • Component internally handles responsive behavior
  • Minimum widths are enforced to ensure payment form usability
  • Bank selection triggers immediate height recalculation

Language management

Dynamic language switching

The ips-ucb component supports real-time language switching:

// Set language during component creation
const ips = components.create("ips-ucb", {
    trx_token: "<client-secret>",
    environment: "test",
    lang: "sr"  // Serbian
});

// Change language after component is mounted
ips.setLanguage("sr-Cyrl");  // Switch to Serbian (Cyrillic)
ips.setLanguage("en");  // Switch to English

Supported languages

Language Code Language Region
en English International
ba-hr Bosnian-Croatian Bosnia and Herzegovina
hr Croatian Croatia
de German Germany
me Montenegrin Montenegro
sl Slovenian Slovenia
sr Serbian Serbia
sr-Cyrl Serbian (Cyrillic) Serbia
mk Macedonian North Macedonia

Translation keys

All UI text uses these translation keys. The two instruction keys belong to different layouts: the desktop layout shows MBANKING_INSTRUCTION next to the QR code, the phone layout shows DEEP_LINK_INSTRUCTION above the bank list.

Key English Serbian (sr)
MBANKING_INSTRUCTION "Using the mbanking application..." "Mbanking aplikacijom koju imate instaliranu..."
DEEP_LINK_INSTRUCTION "You can pay with IPS by selecting the bank whose mbanking application you have on your device." "Možete platiti IPS-om, izborom banke čiju mbanking aplikaciju imate na svom uređaju."
CLICK_AND_REFRESH "Click and refresh" "Klikni i obnovi"
REFRESH_QR_CODE "Refresh QR code" "Obnovi QR kôd"
INDIVIDUAL_PERSON "Individual" "Fizičko lice"
LEGAL_ENTITY "Legal entity or entrepreneur" "Pravno lice ili preduzetnik"
SELECT_BANK "Select bank..." "Izaberite banku..."
PAY_WITH_APP "Pay with app" "Plati aplikacijom"
REMEMBER_BANK_SELECTION "Remember my bank selection" "Sačuvaj odabir banke za buduća plaćanja"
ENV_NOT_SET "Environment is not set" "Okruženje nije postavljeno"
LANG_NOT_SET "Language is not set" "Jezik nije postavljen"

Styling

CSS custom properties

The component is styled with the same CSS custom properties as ips-rs: more than 100 variables for the container, the loading state, text, logos, the QR code, buttons, form elements, the timer, layout containers, the error state and the mobile breakpoint, all overridable from your page. The full list with default values and three complete theme examples are in IPS - Instant Payment Serbia under Complete CSS Customization Guide. A short example:

:root {
    --ips-container-max-width: 600px;
    --ips-container-margin: 0 auto;
    --pay-button-background-color: #007bff;
    --instruction-text-font-size: 16px;
}

Style configuration object

Instead of using CSS variables, you can also pass styles directly to the component:

const ips = components.create("ips-ucb", {
    trx_token: "<client-secret>",
    environment: "test",
    style: {
        // Use any of these keys for direct styling
        container: { /* CSS properties */},
        loadingWrapper: { /* CSS properties */},
        loadingSpinner: { /* CSS properties */},
        ipsContent: { /* CSS properties */},
        desktopLayout: { /* CSS properties */},
        leftContent: { /* CSS properties */},
        rightContainer: { /* CSS properties */},
        mobileLayout: { /* CSS properties */},
        header: { /* CSS properties */},
        text: { /* CSS properties */},
        logo: { /* CSS properties */},
        qrSection: { /* CSS properties */},
        qrCodeContainer: { /* CSS properties */},
        qrRegenerate: { /* CSS properties */},
        qrRegenerateOverlay: { /* CSS properties */},
        regenerateButton: { /* CSS properties */},
        qrPlaceholder: { /* CSS properties */},
        timer: { /* CSS properties */},
        ifMobile: { /* CSS properties */},
        mobileLabel: { /* CSS properties */},
        userTypeSelection: { /* CSS properties */},
        radioLabel: { /* CSS properties */},
        radioInput: { /* CSS properties */},
        bankSelect: { /* CSS properties */},
        bankLogoContainer: { /* CSS properties */},
        bankLogo: { /* CSS properties */},
        generateQRButton: { /* CSS properties */},
        payButton: { /* CSS properties */},
        actions: { /* CSS properties */},
        error: { /* CSS properties */}
    }
});

Events and the payment outcome

Frame height

The component posts a RESIZE_IFRAME message to your page whenever its height changes, and Monri Components applies the new minimum height to the iframe for you. Listen to it only if your layout needs to react:

window.addEventListener('message', (event) => {
    if (event.data.type === 'RESIZE_IFRAME') {
        console.log('Component height changed to:', event.data.data.minHeight);
    }
});

Payment outcome

The buyer confirms an IPS payment in their bank's application. Monri reports the outcome to your server and, on a phone, returns the buyer to your site:

  • Callback. For an approved payment Monri sends a POST with the transaction parameters to your callback URL (the callback_url_override from /v2/payment/new, or the Callback URL in your merchant profile). An approved IPS UCB payment carries status: "approved" and acquirer: "Uac-Ips-Ucb". See Responses And Notifications.
  • Return of the buyer. On a phone the bank application returns the buyer to Monri, which redirects them to your success URL: the success_url_override from /v2/payment/new, or the Success URL in your merchant profile with redirect to success URL enabled. On a desktop the buyer stays on your page after scanning the QR code; show the outcome there once your server has received the callback, or query it as described under Checking payment status in the Integration Knowledge Base.

What the buyer sees

  • Desktop (page wider than 768px): the IPS instruction text, the IPS logo and a one-time QR code with a countdown of 3 minutes 15 seconds. The buyer scans the code with the m-banking application (IPS Skeniraj) and confirms the payment there. While the countdown runs the buyer can click Refresh QR code; after it expires a Click and refresh overlay covers the code, and a click shows it again with a new countdown.
  • Phone (768px or narrower): no QR code. The instruction reads "You can pay with IPS by selecting the bank whose mbanking application you have on your device." (Serbian: "Možete platiti IPS-om, izborom banke čiju mbanking aplikaciju imate na svom uređaju."). The buyer picks individual or legal entity, selects their bank, optionally ticks Remember my bank selection and taps Pay with app; the bank's m-banking application opens through its deep link and the payment is confirmed there.

The layout follows the width of the page that mounts the component, measured when it mounts. A checkout shown inside a modal or iframe 768px wide or narrower gets the phone layout.

National Bank of Serbia (NBS) requirements for your checkout

The National Bank of Serbia sets these conditions for IPS on internet points of sale. These items are on your site.

  1. Method label. Show the method as "IPS Skeniraj" in your list of payment methods, preferably with the IPS Skeniraj logo.
  2. Footer marks. Show the IPS marks ("IPS" and "IPS Skeniraj") in your site footer.
  3. Outcome wording. On your own result page, show a successful IPS payment as executed ("Plaćanje izvršeno"), not "Odobreno". For an unsuccessful payment use "Plaćanje nije izvršeno" or "Neuspešno plaćanje". Monri's own pages follow the same rule: the hosted payment form's result page and the buyer's e-mail show an approved IPS UCB payment as Executed (Izvršeno).
  4. Return page. When the bank app sends the buyer back, your page must show the outcome. Set your success URL (success_url_override in /v2/payment/new, or the Success URL in your merchant profile) to a page that does.

Integration example

Basic integration with responsive styling

<!DOCTYPE html>
<html>
<head>
    <title>IPS UCB Integration</title>
    <script src="https://ipgtest.monri.com/dist/components.js"></script>
    <style>
        /* Required iframe container styling */
        .payment-container {
            width: 100%;
            max-width: 600px;
            margin: 0 auto;
        }

        /* Mobile */
        @media (max-width: 768px) {
            .payment-iframe {
                min-width: 340px;
                min-height: 240px;
                max-height: 380px;
                width: 100%;
                border: none;
            }
        }

        /* Desktop */
        @media (min-width: 769px) {
            .payment-iframe {
                min-width: 400px;
                min-height: 260px;
                width: 100%;
                border: none;
            }
        }

        /* Custom IPS styling */
        :root {
            --ips-container-max-width: 600px;
            --ips-container-margin: 0 auto;
            --pay-button-background-color: #007bff;
            --instruction-text-font-size: 16px;
        }
    </style>
</head>
<body>
<div class="payment-container">
    <h2>Complete Your Payment</h2>
    <div id="ips-ucb-element"></div>

    <!-- Language switcher -->
    <div class="language-switcher">
        <button onclick="changeLanguage('sr')">Srpski</button>
        <button onclick="changeLanguage('sr-Cyrl')">Српски</button>
        <button onclick="changeLanguage('en')">English</button>
    </div>
</div>

<script>
    let ipsComponent;

    // Initialize component
    function initializeIPS() {
        const monri = window.Monri('<authenticity-token>', {
            locale: 'sr'
        });

        const components = monri.components({
            clientSecret: '<client-secret>'
        });

        ipsComponent = components.create('ips-ucb', {
            trx_token: '<client-secret>',
            environment: 'test',
            lang: 'sr'
        });

        ipsComponent.mount('ips-ucb-element');
    }

    // Language switching function
    function changeLanguage(langCode) {
        if (ipsComponent) {
            ipsComponent.setLanguage(langCode);
        }
    }

    // Handle resize events
    window.addEventListener('message', (event) => {
        if (event.data.type === 'RESIZE_IFRAME') {
            console.log('Component resized to:', event.data.data.minHeight);
        }
    });

    // Initialize when page loads
    document.addEventListener('DOMContentLoaded', initializeIPS);
</script>
</body>
</html>