Capturing Card Data

The PayU payment form presents card payments as one of the available options for buyers to complete their transactions. However if you want save card information for future use, you have to use the Secure Form.

Secure Form is a customizable form hosted by PayU that can be integrated into your website through an iframe. When customers enter their card details on the Secure Form, this information is securely transmitted to PayU, where it undergoes tokenization before being returned in the form of a unique token. Utilizing this approach ensures optimal protection for customer card data and helps you comply with PCI DSS regulations.

Requirements

When using Secure Form you should display text provided in the Disclosure Obligations section.

For more details on the tokenization process and how to use tokens effectively, please refer to Card Tokenization section.

Secure Form Examples

Preview
HTML
Javascript
CSS

Single Input Window Secure Form Example

HTML Used in Secure Form with Single Input Window Example
<script
    type="text/javascript"
    src="https://secure.payu.com/javascript/sdk"
></script>
<section class="container">
    <div class="card-container">
        <div class="payu-card-form" id="payu-card"></div>
    </div>
    <button id="tokenizeButton">Tokenize</button>

    <div id="responseTokenize"></div>
</section>

Javascript Used in Secure Form Single Input Window Example
var optionsForms = {
    style: {
        basic: {
            fontSize: '18px',
        },
    },
    lang: 'pl',
}

var renderError = function (element, errors) {
    element.className = 'response-error'
    var messages = []
    errors.forEach(function (error) {
        messages.push(error.message)
    })
    element.innerText = messages.join(', ')
}

var renderSuccess = function (element, msg) {
    element.className = 'response-success'
    element.innerText = msg
}

//initialize the SDK by providing your POS ID and create secureForms object
var payuSdkForms = PayU('393823')
var secureForms = payuSdkForms.secureForms()

//create the form by providing type and options
var card = secureForms.add('card', optionsForms)

//render the form in selected element
card.render('#payu-card')

var tokenizeButton = document.getElementById('tokenizeButton')
var responseElement = document.getElementById('responseTokenize')

tokenizeButton.addEventListener('click', function () {
    responseElement.innerText = ''

    try {
        payuSdkForms.tokenize('SINGLE').then(function (result) {
            //example for SINGLE type token
            result.status === 'SUCCESS'
                ? renderSuccess(responseElement, result.body.token) //pass the token to your back-end and charge it
                : renderError(responseElement, result.error.messages) //check the business error type and messages and display appropriate information to the user
        })
    } catch (e) {
        console.log(e) // technical errors
    }
})

CSS Used in Secure Form Single Input Window Example
.container * {
    font-family: Arial, Helvetica, sans-serif;
    font-size: 14px;
    color: #ffffff;
}

.container {
    text-align: center;
    width: 420px;
    margin: 20px auto 10px;
    display: block;
    border-radius: 5px;
    box-sizing: border-box;
}

.card-container {
    width: 100%;
    margin: 0 auto;
    border-radius: 6px;
    padding: 10px;
    background: rgb(2, 0, 60);
    text-align: left;
    box-sizing: border-box;
}

.payu-card-form {
    background-color: #ffffff;
    padding: 5px;
    border-radius: 4px;
}

button {
    border: none;
    background: #438f29;
    padding: 8px 15px;
    margin: 10px auto;
    cursor: pointer;
}

.response-success {
    color: #438f29;
}

.response-error {
    color: #990000;
}

Preview
HTML
Javascript
CSS

Multiple Input Windows Secure Form Example

HTML Used in sample Secure Form with Fields as Seperate Forms
<script
    type="text/javascript"
    src="https://secure.payu.com/javascript/sdk"
></script>
<section class="container">
    <div class="card-container">
        <aside>Card Number</aside>
        <div class="payu-card-form" id="payu-card-number"></div>

        <div class="card-details clearfix">
            <div class="expiration">
                <aside>Valid Thru</aside>
                <div class="payu-card-form" id="payu-card-date"></div>
            </div>

            <div class="cvv">
                <aside>CVV</aside>
                <div class="payu-card-form" id="payu-card-cvv"></div>
            </div>
        </div>
    </div>
    <button id="tokenizeButton">Tokenize</button>

    <div id="responseTokenize"></div>
</section>

Javascript Used in sample Secure Form with Fields as Seperate Forms
var optionsForms = {
    cardIcon: true,
    style: {
        basic: {
            fontSize: '24px',
        },
    },
    placeholder: {
        number: '',
        date: 'MM/YY',
        cvv: '',
    },
    lang: 'pl',
}

var renderError = function (element, errors) {
    element.className = 'response-error'
    var messages = []
    errors.forEach(function (error) {
        messages.push(error.message)
    })
    element.innerText = messages.join(', ')
}

var renderSuccess = function (element, msg) {
    element.className = 'response-success'
    element.innerText = msg
}

//initialize the SDK by providing your POS ID and create secureForms object
var payuSdkForms = PayU('393823')
var secureForms = payuSdkForms.secureForms()

//create the forms by providing type and options
var cardNumber = secureForms.add('number', optionsForms)
var cardDate = secureForms.add('date', optionsForms)
var cardCvv = secureForms.add('cvv', optionsForms)

//render the form in selected element
cardNumber.render('#payu-card-number')
cardDate.render('#payu-card-date')
cardCvv.render('#payu-card-cvv')

var tokenizeButton = document.getElementById('tokenizeButton')
var responseElement = document.getElementById('responseTokenize')

tokenizeButton.addEventListener('click', function () {
    responseElement.innerText = ''

    try {
        ////tokenize the card (communicate with PayU server)
        payuSdkForms.tokenize('SINGLE').then(function (result) {
            // example for SINGLE type token
            result.status === 'SUCCESS'
                ? renderSuccess(responseElement, result.body.token) //pass the token to your back-end and charge it
                : renderError(responseElement, result.error.messages) //check the business error type and messages and display appropriate information to the user
        })
    } catch (e) {
        console.log(e) // technical errors
    }
})

CSS Used in sample Secure Form with Fields as Seperate Forms
.container * {
    font-family: Arial, Helvetica, sans-serif;
    font-size: 14px;
    color: #ffffff;
}

.container {
    text-align: center;
    width: 420px;
    margin: 20px auto 10px;
    display: block;
    border-radius: 5px;
    box-sizing: border-box;
}

.card-container {
    width: 100%;
    margin: 0 auto;
    border-radius: 6px;
    padding: 10px;
    background: rgb(2, 0, 60);
    text-align: left;
    box-sizing: border-box;
}

.card-container aside {
    padding-bottom: 6px;
}

.payu-card-form {
    background-color: #ffffff;
    padding: 5px;
    border-radius: 4px;
}

.card-details {
    clear: both;
    overflow: auto;
    margin-top: 10px;
}

.card-details .expiration {
    width: 50%;
    float: left;
    padding-right: 5%;
}

.card-details .cvv {
    width: 45%;
    float: left;
}

button {
    border: none;
    background: #438f29;
    padding: 8px 15px;
    margin: 10px auto;
    cursor: pointer;
}

.response-success {
    color: #438f29;
}

.response-error {
    color: #990000;
}

Typescript

If you use Typescript in your project, just add a types definition to your project.

npm install --save @types/payu-emea-sdk

SDK Documentation

The following description refers to methods and objects available in browser-side JavaScript library, contained in JS SDK.

Loading JS SDK

Add JS SDK script to every page you want to use Secure Form on. It should always be loaded from the PayU server. You mustn't load it from your own server and then attach it to the package that is being built at the moment.

Production
Sandbox

<script type="text/javascript" src="https://secure.payu.com/javascript/sdk"></script>

<script type="text/javascript" src="https://secure.snd.payu.com/javascript/sdk"></script>

JS SDK Instance Creation

PayU(posId, options?)

You will need posId parameter, which can be found in your management panel. In the following example we used test POS identifier from the Sandbox environment.

Method Parameters

posIdrequiredstring

Point of Sale identifier.

optionsoptionalobject

Instance options.

devboolean

Enables instance creation in the developer mode which allows you to operate on a site without HTTPS protocol.

Return

PayU instance.

Exceptions

posis.is.empty

Occurs when a JS SDK instance is created and posId parameter is not specified or empty.

non.https.integration

Occurs on JS SDK instance creation when the protocol of the page, on which SDK is loaded, is not https and file, and the page is not loaded from localhost: 127.0.0.1 or 0.0.0.0. During the implementation process you can enable developer mode in the options parameter.

Example

var payu = PayU('393823')

JS SDK Instance Methods

secureForms(options?)

Creates SecureForms instance. It will be possible to add SecureForm elements on an object created this way.

Method Parameters

optionsoptionalobject

SecureForms Options Instance. More information about individual options in Secure Forms Instance Options section.

fontsarray

Additional fonts for forms.

langstring

Language.

Return

SecureForms instance.

Exceptions

secure.forms.already.exists

Occurs when trying to create another SecureForms instance. If you want to append more than one card form to your page, create a separate instance of JS SDK for each one of them.

Example

var secureForms = payu.secureForms()

tokenize(type?)

Request for card token creation with use of created SecureForm fields.

Method Parameters

typeoptionalstring

Type of the created card token.

Possible Values (default value - SINGLE)
SINGLE	Card not saved - token with short lifespan (11 minutes).
SINGLE_LONGTERM	Card not saved.
MULTI	Card saved - multi-use token will be returned after the it is charged via REST API.

Return

Promise, which resolves to the object containing the result.

Result Fields Description

Field	Description
`status`	Tokenization status: `SUCCESS` - successful tokenization, result is available in body field; `ERROR` - tokenization attempt ended in an error. The errors that occurred can be found in error field.
`body`	Only for `SUCCESS` status. Object contains tokenization information.
`error`	Only for `ERROR` status. Object with `messages` array which contains error information. Details can be found in Errors section.
`correlationId`	Only for `ERROR` status.

Example

{
    "status": "SUCCESS",
    "body": {
        "token": "TOK_1JOQVU5KJNOV4c4O8UbZySwcfBdS",
        "mask": "444433******1111"
    }
}

Exceptions

incorrect.token.type

Incorrect token type. Possible values can be found in type parameter description.

tokenize.not.possible

Tokenization not possible. Required type card form or number, date and cvv type forms.

Example

var secureForms = payu.secureForms();

sendCvv(refReqId)

Sends a request for CVV. Works only when the form type is cvv.

Method Parameters

refReqIdrequiredstring

If during card charging process PayU responds with WARNING_CONTINUE_CVV, you should retrieve refReqId parameter from redirectUri field, from the response. You can use extractRefReqId method to get refReqId from the URL. If you are redirected to the page after 3DS is executed, you can retrieve refReqId parameter from URL.

URL example:
https://address.page/summary/?statusCode=WARNING_CONTINUE_CVV&refReqId=7b09781ee6a3303cc86712fce16fe030

Return

Promise, which resolves to the object containing the result.

Returned Fields Description

Field	Description
`status`	CVV sending status: `SUCCESS` - CVV was sent successfully - it does not mean that CVV is correct, `ERROR` - sending CVV attempt ended in an error. The errors that occurred can be found in the `error` field.
`error`	Only for `ERROR` status. Object containing error information. Details can be found in Errors section.
`correlationId`	Only for `ERROR` status.

Example

{
    "status": "SUCCESS"
}

Exceptions

refReqId.is.empty

refReqId was not specified or is empty.

sendCvv.not.possible

Error has occurred while trying to send CVV. Only cvv form is required.

Example

payu.sendCvv('7b09781ee6a3303cc86712fce16fe030')

extractRefReqId(url)

Auxiliary function used for retrieving refReqId parameter from the URL.

Method Parameters

urlrequiredstring

URL address.

Return

refReqId

Example

var refReqId = payu.extractRefReqId(
    'https://secure.payu.com/cpm/threeds/proxy?refReqId=7b09781ee6a3303cc86712fce16fe030"'
)

SecureForms Instance Methods

add(type?, options?)

Creates single-use instance of SecureForm form.

Method Parameters

typeoptionalstring

Form type.

Possible Values (default value - card)
card	Complete card data form (card number, expiration date, CVV).
number	Card number form.
date	Card expiration date form.
cvv	CVV form.

optionsoptionalobject

Form options. For more information about individual options see Form Options section.

styleobject

Your own form style.

labelobject

Your own accessability text (aria-label) for the form fields.

placeholderobject

Your own placeholder text in fields of the form.

frameTitlestring

Your own iframe title for the form fields.

langboolean

Language

disabledboolean

Blocks a field.

cardIconboolean

Should card icon be displayed next to the card number input field.

Return

SecureForm Instance.

Exceptions

secure.form.incorrect.type

Invalid form type. Possible values can be found in type parameter description.

secure.form.exist.type [message]

Occurs when trying to add another form of specified type. message array contains details about errors.

secure.form.exist.other.type [message]

Occurs when trying to add form with type card when another number, date or cvv form was already added. It also occurs in the opposite situation while trying to add number, date or cvv form when card form was already added. message array contains details about errors.

Example

var cardNumberForm = secureForms.add('number')

SecureForm Instance Methods

render(selector)

Displays the form on the page.

Method Parameters

selectorrequiredstring

Selector of the element in which the form will be displayed. Searching for element is done by querySelectorAll.

Return

Its own Secure Form instance.

Exceptions

element.selector.empty

selector parameter was no specified or is empty.

element.selector.not.string

selector parameter is not of the string type.

element.not.exists

Element do not exists on the page.

element.too.many.exists

There is more than one element on the page.

element.not.valid

Invalid element (appendChild method is not implemented or it is an input element).

element.contains.children

Element contains secondary items.

Example

cardNumberForm.render('#cardNumberForm')

update(options)

Updates form options.

Method Parameters

optionsrequiredobject

options parameter is the same as options parameter in the add method. New options are overriding the existing ones, lack of an option does not remove existing one.

Return

Its own SecureForm instance.

Example

cardNumberForm.update({ lang: 'en' })

on(event, callback)

Attaching your own callback to the event emitted by the form. You can find more information about the events in the event section.

Method Parameters

eventrequiredstring

Event type.

Possible Values
ready	Emitted when the form is displayed.
focus	Emitted when the form gains focus.
blur	Emitted when the form loses focus.
change	Emitted when the value of the form is changed.

callbackrequiredfunction

Callback called after event is emitted.

Return

SecureForm instance

Exceptions

event.unknown

Unknown event type in event parameter.

event.callback.not.function

callback parameter is not a function.

Example

cardNumberForm
    .on('ready', function () {
        // form ready
    })
    .on('focus', function () {
        // form activated
    })
    .on('blur', function () {
        // form deactivated
    })
    .on('change', function (body) {
        // value of the form has changed
    })

clear()

Removes data entered in the form.

Return

Its own SecureForm instance

Example

cardForm.clear()

focus()

Focuses the form.

Return

Its own SecureForm instance

Example

cardForm.focus()

remove()

Removes form from the page.

Return

Its own SecureForm instance

Example

cardForm.remove()

Options

Secure Forms Instance

All parameters are checked for their type and values correctness. Unknown and invalid parameters are ignored without information about error.

Secure Forms Instance Params

Parameter	Type	Description
fonts	`array`	Custom fonts for forms.
lang	`string`	Two-character language code. Available languages: `pl`, `en`, `cs`, `sk`. If there is no language specified, it is retrieved from the browser. In the case of an unsupported language, the `en` value is used.

option - fonts (array)

fonts

Custom fonts for forms.

Attributes

Below is a list of the objects defining additional fonts, which will be added to every form using @font-face.

familyrequired

Permitted values: [-_a-zA-Z0-9 ]+

srcrequired

displayoptional

Permitted values: (auto|block|swap|fallback|optional)

styleoptional

Permitted values: (normal|italic|oblique)

weightoptional

Permitted values: ([1-9]00|normal|bold)

Example

{
    fonts: [
        {
            family: 'Own Font',
            src: 'url(https://ownulr.com/own_font_normal.woff2) format("woff2"), url(https://ownulr.com/own_font_normal.woff) format("woff2)',
            style: 'normal',
            weight: 400,
        },
        {
            family: 'Own Font',
            src: 'url(https://ownulr.com/own_font_bold.woff2) format("woff2")',
            style: 'normal',
            weight: 'bold',
        },
    ]
}

Form

All parameters are optional and are checked for their type, and values correctness. Unknown and invalid parameters are ignored without information about error.

Form options

Option Parameters

styleobject

Your own form style.

labelobject

You own accessability label (aria-label) for the form fields. If the parameter is missing, the text is added according to the current language.

placeholderobject

Your own placeholder text in the form input fields.

placeholderobject

You own iframe title. If the parameter is missing, the title is added according to the current language.

langstring

Two-character language code. Available languages are: pl en cs sk. Parameter is used when the language was not specified in the Secure Forms Instance. If language is not specified, it is retrieved from the browser. For languages that are not supported, en is used.

disabledboolean

When set to true form will be blocked, otherwise it will be active.

cardIconboolean

When set to false, card icon, next to card number input field, is not displayed, otherwise it is displayed.

Example

{
    style: {
        basic: {
            fontColor: '#0000FF'
            fontSize: '26px'
            fontWeight: '700'
        },
        invalid: {
            fontColor: '#990000'
        },
        placeholder: {
            fontColor: '#aaaaaa'
        }
    },
    placeholder: {
        number: '',
        date: 'MM / YY',
        cvv: ''
    },
    cardIcon: true,
    lang: 'en',
    disabled: false
}

style (object)

Groups styles for different form behaviours in objects. Each group has its permitted styles.

Style Groups

basic

Permitted styles: fontColor fontSize fontFamily fontWeight letterSpacing

Form styles.

invalid

Permitted styles: fontColor fontWeight

Styles for the form with invalid values.

focus

Permitted styles: fontColor fontWeight

Style for the form with active focus.

placeholder

Permitted styles: fontColor fontWeight

Styles for the form placeholders.

disabled

Permitted styles: fontColor fontWeight

Styles for the disabled form.

Permitted Styles

fontColor

Permitted values: #[0-9a-f]{6} font color

fontSize

Permitted values: (\d+|\d*.\d+)(px|em|%) font size

fontFamily

Permitted values: [0-9a-z-\s,"']{1, 150} font family

fontWeight

letterSpacing

Permitted values: normal|(-?)(\d+|\d*.\d+)(px|em|%) spacing between letters

placeholder (object)

placeholder fields

numberstring

Placeholder text for the card number form.

datestring

Placeholder for the card expiration date form.

cvvstring

Placeholderfor the card CVV form.

Events

Forms emit events to which you can attach your own callback using the on method.

Event ready

This event is emitted after calling render method after the form is displayed.

Event focus

This event is emitted when the form is activated.

Event blur

This event is emitted when the form is deactivated.

Event change

This event is emitted when the value of the form is changed. Callback is called with one object parameter with the following structure:

Available Fields for the change Event

Field	Description
`empty`	Indicates if the form is empty. Possible values: true, false.
`error`	Indicates if the data entered in the form is correct. Possible values: true, false when the form contains correct data or array of objects with errors. Possible error type is `validation`. Details can be found in Errors section.
`brand`	Only for form with the type `number`. Contains information about the brand of the card. Possible values: visa, mastercard, maestro.

Dynamic Classes

Dynamic classes are added to the element in which the form is displayed.

Available Dynamic Classes

Class	Description
`payu-secure-form-empty`	Set when form is empty.
`payu-secure-form-focus`	Set when for is active (in focus).
`payu-secure-form-invalid`	Set when data entered into the form are invalid.

Errors

error object contains an array of objects (messages), which contain detailed information about the errors.

Error Object Example

{
    "status": "ERROR",
    "correlationId": "",
    "error": {
        "messages": [
            {
                "type": "validation",
                "code": "error.validation.expDate.value",
                "parameters": {},
                "message": "Card expiration date is invalid"
            },
            {
                "type": "validation",
                "code": "error.validation.cvv.empty",
                "parameters": {},
                "message": "Empty CVV"
            }
        ]
    }
}

Highlighted above is one of the objects inside the messages array with the error details.

Fields Describing Error Objects Inside Messages Array

Field	Description
`type`	Error type. Possible values: `validate` - when the source of the error is the validation of the form fields values, `technical` - for other errors.
`code`	Error code.
`source`	Element with possible error (only for errors with `validate` type). Possible values: `card`, `number`, `date`, `cvv`.
`message`	Error description in the languageof the form. In case of the `technical` type errors, description in always in english.
`parameters`	Object containing changeable error fragments.

Possible Errors

Error Code	Type	Description
`error.validation.card.empty`	`validate`	Empty card number.
`error.validation.card.length`	`validate`	Invalid card number length.
`error.validation.card.number`	`validate`	Invalid card number.
`error.validation.card.unsupported`	`validate`	Card type is not supported. Supported card types: Visa, Mastercard and Maestro.
`error.validation.expDate.empty`	`validate`	Empty expiration date.
`error.validation.expDate.past`	`validate`	Expiration date is in the past.
`error.validation.expDate.value`	`validate`	Incorrect expiration date.
`error.validation.cvv.empty`	`validate`	Empty CVV.
`error.validation.cvv.value`	`validate`	Invalid CVV.
`error.tokenization`	`technical`	Error has occured while trying to tokenize the card. Error information can be found in the `parameters` object in the `error` field.
`error.send.cvv`	`technical`	Error has occured while sending CVV. Error information can be found in the `parameters</code object in the error`
`error.network`	`technical`	A network communication error has occured. Error information can be found in the `parameters` object in the `error` field.

FAQ

I need translation into xx language.

Elements that are translated are placeholder texts and error messages. Both elements you can translate freely on your own.

In case of placeholder elements we passed them in the placeholder parameter in the form options e.g.

{
    "placeholder": {
        "number": "Kartennummer",
        "date": "MM / JJ",
        "cvv": "CVV"
    }
}

In case of errors, we display message based on the error codes e.g.

var errors = {
    messages: [
        {
            type: 'validation',
            code: 'error.validation.card.number',
            parameters: {},
            message: 'Nieprawidłowy numer karty',
        },
    ],
}

var translations = {
    'error.validation.card.number': 'Ungültige Kartennummer',
}

var showError = function () {
    errors.messages.forEach(function (message) {
        console.log(translations[message.code]) // show error message
    })
}

Someone has resized the browser window or flipped the phone. I want to change the font size and disable the card brand icon, so that the form fits completely on the page.

While resizing the browser window you should use the update method to update form options e.g.

// initializing code of JS SDK and SecureForms has been omitted
var cardNumber = secureForms.add('number')
var options = {
    current: 'gt500',
    profiles: {
        gt500: {
            style: {
                basic: {
                    fontSize: '18px',
                },
            },
            cardIcon: true,
        },
        lt500: {
            style: {
                basic: {
                    fontSize: '14px',
                },
            },
            cardIcon: false,
        },
    },
}

// window size change
window.addEventListener('resize', function () {
    var newProfile = window.innerWidth > 500 ? 'gt500' : 'lt500'
    if (newProfile !== options.current) {
        options.current = newProfile
        // form options update
        cardNumber.update(options.profiles[options.current])
    }
})

Secure Form Examples​

Typescript​

SDK Documentation​

Options​

Secure Forms Instance​

Form​

Events​

Dynamic Classes​

Errors​

FAQ​

I need translation into xx language.​

Someone has resized the browser window or flipped the phone. I want to change the font size and disable the card brand icon, so that the form fits completely on the page.​

On this page

Secure Form Examples

Typescript

SDK Documentation

Options

Secure Forms Instance

Form

Events

Dynamic Classes

Errors

FAQ

I need translation into xx language.

Someone has resized the browser window or flipped the phone. I want to change the font size and disable the card brand icon, so that the form fits completely on the page.