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 to save card information for future use, you have to use the Secure Form.

The 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. This approach ensures optimal protection of customer card data and helps you comply with PCI DSS regulations.

Requirements

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

---

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

Secure Form Examples

Preview

Single Input Window Secure Form Example

HTML

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

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

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

Multiple Input Windows Secure Form Example

HTML

HTML Used in Sample Secure Form with Fields as Separate 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

JavaScript Used in Sample Secure Form with Fields as Separate 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

CSS Used in Sample Secure Form with Fields as Separate 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, add the type definitions:

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

SDK Documentation

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

Loading JS SDK

Add the JS SDK script to every page on which you want to use the Secure Form. Always load it from the PayU server. Do not host it on your own server or bundle it with your application package.

Production

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

Sandbox

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

JS SDK Instance Creation

PayU(posId, options?)

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

Method Parameters

posIdrequiredstring

Point of Sale identifier.

optionsoptionalobject

Instance options.

devboolean

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

Return

PayU instance.

Exceptions

posId.is.empty

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

non.https.integration

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

Example

var payu = PayU('393823')

JS SDK Instance Methods

secureForms(options?)

Creates a SecureForms instance, to which you can add SecureForm elements.

Method Parameters

optionsoptionalobject

SecureForms instance options. For more information about individual options, see the 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 add more than one card form to your page, create a separate JS SDK instance for each of them.

Example

var secureForms = payu.secureForms()

tokenize(type?)

Requests creation of a card token using the SecureForm fields you created.

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 it is charged via REST API.

Return

A Promise that resolves to an object containing the result.

Result Fields Description

Field	Description
status	Tokenization status: SUCCESS - successful tokenization, the result is available in the body field; ERROR - tokenization attempt ended in an error. The errors that occurred can be found in the error field.
body	Only for SUCCESS status. The object contains tokenization information.
error	Only for ERROR status. Object with messages array which contains error information. Details can be found in the 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 the description of the type parameter.

tokenize.not.possible

Tokenization is not possible. A card form or number, date and cvv forms are required.

Example

payu.tokenize()

sendCvv(refReqId)

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

Method Parameters

refReqIdrequiredstring

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

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

Return

A Promise that resolves to an object containing the result.

Returned Fields Description

Field	Description
status	CVV sending status: SUCCESS - CVV was sent successfully (this does not mean that the 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

The refReqId parameter was not specified or is empty.

sendCvv.not.possible

An error occurred while trying to send the CVV. A 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

The extracted refReqId value.

Example

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

SecureForms Instance Methods

add(type?, options?)

Creates a single-use SecureForm instance.

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 the Form Options section.

styleobject

Your own form style.

labelobject

Your own accessibility 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.

langstring

Language.

disabledboolean

Blocks a field.

cardIconboolean

Determines whether the card icon is 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 the description of the type parameter.

secure.form.exist.type [message]

Occurs when trying to add another form of the 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. The element is located using querySelectorAll.

Return

The same SecureForm instance.

Exceptions

element.selector.empty

The selector parameter was not specified or is empty.

element.selector.not.string

The selector parameter is not of the string type.

element.not.exists

The element does not exist on the page.

element.too.many.exists

More than one matching element exists on the page.

element.not.valid

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

element.contains.children

The element contains child elements.

Example

cardNumberForm.render('#cardNumberForm')

update(options)

Updates form options.

Method Parameters

optionsrequiredobject

The options parameter is the same as the options parameter in the add method. New options override the existing ones; omitting an option does not remove its existing value.

Return

The same SecureForm instance.

Example

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

on(event, callback)

Attaches your own callback to an event emitted by the form. For more information about the events, see the Events 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

The same 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

The same SecureForm instance.

Example

cardForm.clear()

focus()

Focuses the form.

Return

The same SecureForm instance.

Example

cardForm.focus()

remove()

Removes form from the page.

Return

The same SecureForm instance.

Example

cardForm.remove()

Options

Secure Forms Instance Options

All parameters are validated for type and value correctness. Unknown and invalid parameters are ignored without an error message.

Secure Forms Instance Params

Parameter	Type	Description
fonts	array	Custom fonts for forms.
lang	string	Two-character language code. Available languages: bg, cs, da, de, el, en, es, et, fi, fr, hr, hu, it, lt, lv, nl, pl, pt, ro, ru, sk, sl, sr, sv, tr, uk. 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

Permitted values: url(URL) format([collection|embedded-opentype|opentype|svg|truetype|woff|woff2])
May contain multiple entries separated by commas.

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("woff")',
      style: 'normal',
      weight: 400,
    },
    {
      family: 'Own Font',
      src: 'url(https://ownulr.com/own_font_bold.woff2) format("woff2")',
      style: 'normal',
      weight: 'bold',
    },
  ]
}

Form Options

All parameters are optional and are validated for type and value correctness. Unknown and invalid parameters are ignored without an error message.

Form options

Option Parameters

styleobject

Your own form style.

labelobject

Your own accessibility 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.

frameTitlestring

Your 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: bg, cs, da, de, el, en, es, et, fi, fr, hr, hu, it, lt, lv, nl, pl, pt, ro, ru, sk, sl, sr, sv, tr, uk. The parameter is used when no language was specified in the Secure Forms Instance Options. If no language is specified, it is retrieved from the browser. For unsupported languages, en is used.

disabledboolean

When set to true, the form is blocked; otherwise, it is active.

cardIconboolean

When set to false, the card icon next to the 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: ''
    },
    label: {
        number: 'Card number',
        date: 'Card expiration date',
        cvv: 'CVV/CVC code'
    },
    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

Permitted values: ([1-9]00|normal|bold|lighter|bolder|inherit|initial|unset) font weight

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

Placeholder for the card CVV form.

label (object)

Label Fields

numberstring

Accessibility text (aria-label) for the card number form.

datestring

Accessibility text (aria-label) for the card expiration date form.

cvvstring

Accessibility text (aria-label) for the 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 the form is displayed following a call to the render method.

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: false when the form contains correct data, or an array of objects with errors. Possible error type is validation. Details can be found in the Errors section.
brand	Applies only to forms with the type number. Contains information about the brand of the card. Possible values: visa, mastercard, maestro.
length	Applies only to forms with the type number and when the error field is set to false. Contains information about the length of the card number.

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 the form is active (in focus).
payu-secure-form-invalid	Set when the data entered into the form is invalid.

Errors

The error object contains the messages array of objects with 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"
      }
    ]
  }
}

The highlighted object is one of the elements of the messages array and contains the error details.

Fields Describing Error Objects Inside Messages Array

Field	Description
type	Error type. Possible values: validation - 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 validation type). Possible values: card, number, date, cvv.
message	Error description in the language of the form. For errors of the technical type, the description is always in English.
parameters	Object containing changeable error fragments.

Possible Errors

Error Code	Type	Description
error.validation.card.empty	validation	Empty card number.
error.validation.card.length	validation	Invalid card number length.
error.validation.card.number	validation	Invalid card number.
error.validation.card.unsupported	validation	Card type is not supported. Supported card types: Visa, Mastercard and Maestro.
error.validation.expDate.empty	validation	Empty expiration date.
error.validation.expDate.past	validation	Expiration date is in the past.
error.validation.expDate.value	validation	Incorrect expiration date.
error.validation.cvv.empty	validation	Empty CVV.
error.validation.cvv.value	validation	Invalid CVV.
error.tokenization	technical	Error has occurred 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 occurred while sending CVV. Error information can be found in the parameters object in the error field.
error.network	technical	A network communication error has occurred. Error information can be found in the parameters object in the error field.

FAQ

How do I translate the form into another language?

The translatable elements are placeholder texts and error messages. You can translate both on your own.

Placeholder texts are passed in the placeholder parameter in the form options, e.g.:

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

Error messages are displayed based on 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
  })
}

The browser window was resized or the phone was rotated. How do I change the font size and disable the card brand icon so that the form fits on the page?

When the browser window is resized, use the update method to update the 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])
  }
})