Skip to main content

Secure Elements

Extending PayU API​

Retrieving Click to Pay Configuration​

To use Click to Pay in the Secure Elements application, first verify that this payment method is available and retrieve its configuration for your POS. To do this, call the Retrieve Payment Methods endpoint, extending the request with an additional features parameter set to clickToPay.

Production env example of retrieving payment methods
curl -X GET https://secure.payu.com/api/v2_1/paymethods?features=clickToPay \
-H "Authorization: Bearer 87ad751f-7ea5-4023-a16f-04b6647a07f5"
-H "Cache-Control: no-cache"

In the response, in the payByLinks array in the card token object ("value"="c"), you will receive an additional clickToPay object containing all the necessary data to configure Click to Pay in the Secure Elements application.

Example of a successful response for retrieving payment methods (HTTP 200) with an additional clickToPay object
{
    "payByLinks":[{
        "value":"c",
        "name":"Card payment",
        "brandImageUrl":"http://static.payu.com/images/mobile/logos/pbl_c.png",
        "status":"ENABLED",
        "minAmount": 50,
        "maxAmount": 100000,
        "features": {
            "clickToPay": {
                "clickToPayBrandImageUrl": "https://static.payu.com/images/mobile/logos/pbl_cpt_on.png",
                "mastercard": {
                  "status": "ENABLED",
                  "dpaId": "mddctp12"
                },
                "visa": {
                    "dpaId": "visctp01",
                    "acquirerBIN": "123456",
                    "acquirerMerchantId": "MERCH01",
                    "status": "ENABLED"
                }
            }
        }
    }]
}

Extending Order Create Request​

To create an order with a selected payment method, you need to add the payMethods section to the standard order request. The description of the payMethods object can be found in our API reference in the Create an Order section.

Using Card Data​

After the process is completed, the Secure Elements application returns an object containing the card token. You need to extract the token from this object and pass it in the value field of the payMethod object, while the type field should be set to CARD_TOKEN.

payMethods Object Example
{
    "payMethods": {
        "payMethod": {
            "type": "CARD_TOKEN",
            "value": "TOKD_1LOQUV5MMRNX70i7UXXXXXXXXX"
        }
    }
}

Using Card with Click to Pay​

After the process is completed, pass the data returned by the Secure Elements application in the payMethod object. Depending on the card brand, fill in the appropriate fields in the clickToPay object:

  • for Visa Click to Pay cards, the srcCorrelationId field is required,
  • for Mastercard Click to Pay cards, the srcCorrelationId and srcDigitalCardId fields are required.
payMethods Object Example for Visa Click to Pay Card
{
    "payMethods": {
        "payMethod": {
            "type": "PBL",
            "value": "c",
            "clickToPay" : {
                "visa": {
                    "srcCorrelationId": "123e4567-e89b-12d3-a456-426614174000"
                }
            }
        }
    }
}
Note that...

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

Javascript SDK​

PayU provides a JavaScript SDK library that runs in the browser. The library contains methods and objects that can help with integrating selected PayU solutions, such as Secure Elements. You can also try the Click to Pay Secure Elements demo shop, where you can test the integration with your own POS data and configure custom styles.

Click to Pay Secure Elements Demo Payment Form​

The payment demo form is a self-service tool that runs in your browser, helping you understand, test, and configure Click to Pay Secure Elements before implementing it in your checkout.

Note that...

You don't need to install this tool in your store. It does not replace the integration described in this guide.

What You Can Test​

The demo shop allows you to:

  • preview Secure Elements inside a sample merchant checkout;
  • customize the appearance of Click to Pay Secure Elements to match your checkout design and brand;
  • test Click to Pay login and trusted-device recognition;
  • display and select cards stored in a Click to Pay wallet;
  • select a stored Click to Pay card or enter a new one;
  • test standard card tokenization when Click to Pay is not used;
  • observe the data returned by the Secure Elements component in the completed or failed event.

Styling Configurator​

Use the visual configurator to adjust the appearance of the component without preparing the entire styling configuration manually. You can change supported properties such as typography, colors, buttons, inputs, borders, and corner radius.

The configurator generates a JSON customization object. Open the JSON Code tab to review or edit the object and copy it for use as the customization option in your Secure Elements integration.

Configuration Required​

You can open the demo using its predefined configuration to preview the basic shopper experience.

To test the demo with your own PayU configuration:

  1. Select the Sandbox or Production environment.
  2. Open the Configuration tab and enter your POS ID.
  3. Optionally enter the buyer's email address.
  4. Enter the Click to Pay DPA name and the required Visa or Mastercard configuration values.
  5. Select Apply changes to reload Secure Elements with the new configuration.
Important Notes
  • The demo does not accept OAuth credentials or retrieve Click to Pay configuration from PayU. Obtain the required configuration through the integration process described in this guide and enter the relevant values in the demo.
  • Use Sandbox credentials and appropriate test data for integration testing. Production testing requires a production-enabled PayU configuration and a valid Click to Pay wallet.
  • Your point of sale must have card payments active and Click to Pay available. If Click to Pay is unavailable for a card scheme, its configuration will not be returned and that scheme cannot be tested.
  • If the buyer's email is omitted, the shopper can enter it during the Click to Pay login flow. If no valid Click to Pay configuration is provided, Secure Elements displays the standard card form.

Usage Example​

Loading JS SDK
Always load the JS SDK from the PayU server. You cannot load it from your own server or bundle it into your build package.
<script type="text/javascript" src="https://secure.payu.com/javascript/sdk"></script>
Creating a SecureElements Instance
SecureElements(options?)
Method Parameters
optionsoptionalobject
Instance options
devboolean
Creates an instance in development mode, which allows it to run on pages that do not use HTTPS.
Returns
A SecureElements instance.
Exceptions
non.https.integration
Occurs when creating a SecureElements instance if the page protocol where the JS SDK is loaded is not https or file, and the page is not loaded from localhost: 127.0.0.1 or 0.0.0.0. During integration work, you can enable development mode using the options parameter.
const secureElements = SecureElements();
SecureElements Instance Methods
render(selector, options)
Renders the application on the page.
Method Parameters
selectorrequiredstring
The selector of the element where the application should be displayed. The element is searched using the querySelectorAll method.
optionsrequiredobject
Application options.
configurationrequiredobject
Application configuration object. More information about each field is available in the Configuration section.
customizationobject
Application customization object. More information about each field is available in the Customization section.
Returns
A SecureElements instance.
Exceptions
element.selector.empty
The selector parameter was not provided or is empty.
element.selector.not.string
The selector parameter is not a string.
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 (it does not implement the appendChild method or it is an input element).
element.contains.children
The element contains child elements.
no.configuration.defined
The configuration option was not provided or has an invalid type.
no.elements.defined
The elements field in the configuration was not provided or has an invalid type.
no.posId.defined
The posId field in the configuration was not provided or has an invalid type.
secureElements.render('#secureElementsApp', {
    configuration: {
        elements: ['cards'],
        posId: '482413',
        clickToPay: {
            dpaName: "Sandbox Test",
            mastercard: {
                dpaId: 'jI8iGo86'
            },
            visa: {
                dpaId: 'jI8iGo86',
                acquirerBIN: "498707",
                acquirerMerchantId: 'jI8iGo86'
            }
        },
        buyer: {
            email: 'test-email@test-domain.com'
        }
    },
    customization: {
        lang: 'pl',
    },
});
on(event, callback)
Attaches your callback function to an event emitted by the application. More information about events is available in the events section.
Method Parameters
eventrequiredstring
Event type
Możliwe wartości
readyEmitted when the application is displayed.
completedEmitted when the payer completes the process in the application.
callbackrequiredfunction
Callback function invoked after the event is emitted.
Returns
The same SecureElements instance.
Exceptions
event.unknown
Unknown event type in the event parameter.
event.callback.not.function
The callback parameter is not a function.
secureElements
    .on('ready', function () {
        // application is ready
    })
    .on('completed', function (body) {
        // payer completed the process in the application
    })

Options​

Options for the render method.

Configuration​

All parameters are validated for type and for correct values. If an optional parameter is unknown or invalid, it is ignored and a warning is logged in the browser console.

Configuration Parameters
elementsrequiredarray
An array with the list of elements to enable.
Allowed values: cards.
posIdrequiredstring
Payment point identifier, which you can find in the management panel.
Must be a string containing only digits.
clickToPayobject
Click to Pay configuration data.
If this data is not provided, Click to Pay functionality is not available.
buyerobject
Payer information.

The following example uses Sandbox test data.

{
    elements: ['cards'],
    posId: '482413',
    clickToPay: {
        dpaName: "Sandbox Test",
        mastercard: {
            dpaId: 'jI8iGo86'
        },
        visa: {
            dpaId: 'jI8iGo86',
            acquirerBIN: "498707",
            acquirerMerchantId: 'jI8iGo86'
        }
    },
    buyer: {
        email: 'test-email@test-domain.com'
    }
}
clickToPay Object
Click to Pay configuration data.
dpaNamestring
Merchant name that can be displayed on Click to Pay pages. Maximum length is 32 characters.
mastercardobject
Mastercard configuration data obtained from the retrieve payment methods endpoint.
dpaIdstring
dpaId identifier
visaobject
Visa configuration data obtained from the retrieve payment methods endpoint.
dpaIdstring
dpaId identifier
acquirerBINstring
acquirerBIN identifier
acquirerMerchantIdstring
acquirerMerchantId identifier
buyer Object
Payer information.
emailstring
Payer email address. Used by Click to Pay to recognize the user account.

Customization​

All parameters are validated for type and for correct values. If a parameter is unknown or invalid, it is ignored and a warning is logged in the browser console.

Customization Parameters
langstring
Two-letter language code. Available languages: en, pl. If not provided, the language is detected from the browser settings. If the language is not supported, en is used.
optionsobject
Additional customization options.
stylesobject
Custom styles that let you adjust the application's appearance to match your website. If not provided, the default styles are used.
{
    lang: 'pl',
    options: {
        enableCardFormFieldsAutoJump: false
    },
    styles: {
        body: {
            margin: '10px'
        }
    }
}
options Object
Customization options.
enableCardFormFieldsAutoJumpboolean
Automatically moves between card form fields after entering a valid value. Default value: true.
showCardNumberBrandIconboolean
Shows card brand icon in card number input. Default value: true.
skipStyleDefaultsboolean
Skips default styles for the application. Default value: false.
darkModeboolean
Enables dark mode for the application. Default value: false.
styles Object
Custom styles.
baseobject
Base properties.
fontSizeLengthString
Base font size.
fontFamilystring
Base font family.
Maximum length: 150 characters. Allowed characters: 0-9a-z-\s,"'
fontWeightFontWeightValue
Base font weight.
lineHeightLengthString
Base line height.
gapLengthString
Base gap between site elements. This base value will be used to calculate all gaps in the application.
fontsarray
Additional fonts to load.
familyrequiredstring
Font family name.
Maximum length: 150 characters. Allowed characters: -_ a-zA-Z0-9
srcrequiredarray
List of sources.
urlrequiredstring
Font file URL.
Must be a valid URL.
formatrequiredstring
Font format.
Allowed values: "collection", "embedded-opentype", "opentype", "svg", "truetype", "woff", "woff2"
stylestring
Font style.
Allowed values: "normal", "italic", "oblique"
weightstring
Font weight.
Allowed values: "normal", "bold", "lighter", "bolder", "inherit", "initial", "unset", 100, 200, 300, 400, 500, 600, 700, 800, 900
stretchstring
Font stretch.
Allowed values: "normal", "condensed", "expanded", "ultra-condensed", "extra-condensed", "semi-condensed", "semi-expanded", "extra-expanded", "ultra-expanded"
unicodeRangestring
Unicode range covered by the font.
Must be a valid Unicode range definition and match: U+([0-9a-f?]{1,6}|[0-9a-f]{1,6}-[0-9a-f]{1,6})(,U+([0-9a-f?]{1,6}|[0-9a-f]{1,6}-[0-9a-f]{1,6}))*
bodyobject
Styles for the body element.
Includes all properties from: MarginStyles
buttonobject
primaryobject
defaultButtonStyles
Styles of primary button element in default state.
hoverButtonStyles
Styles of primary button element in hovered state.
focusButtonStyles
Styles of primary button element in focus state.
activeButtonStyles
Styles of primary button element in active/pressed state.
disabledButtonStyles
Styles of primary button element in disabled state.
loadingButtonStyles
Styles of primary button element in loading state.
secondaryobject
defaultButtonStyles
Styles of secondary button element in default state.
hoverButtonStyles
Styles of secondary button element in hovered state.
focusButtonStyles
Styles of secondary button element in focus state.
activeButtonStyles
Styles of secondary button element in active/pressed state.
disabledButtonStyles
Styles of secondary button element in disabled state.
loadingButtonStyles
Styles of secondary button element in loading state.
inputobject
defaultInputStyles
Styles of input element in default state.
errorInputStyles
Styles of input element in error state.
focusInputStyles
Styles of input element in focus state.
disabledInputStyles
Styles of input element in disabled state.
placeholderInputStyles
Styles of input placeholder.
selectobject
defaultSelectStyles
Styles of the select element in default state.
errorSelectStyles
Styles of the select element in error state.
focusSelectStyles
Styles of the select element in focus state.
disabledSelectStyles
Styles of the select element in disabled state.
menuSelectStyles
Styles of select menu.
optionSelectStyles
Styles of select menu option.
placeholderSelectStyles
Styles of select placeholder.
radioobject
defaultRadioStyles
Styles of radio element in default state.
focusRadioStyles
Styles of radio element in focus state.
labelTypographyStyles
Styles of radio element label.
checkboxobject
defaultCheckboxStyles
Styles of checkbox element in default state.
focusCheckboxStyles
Styles of checkbox element in focus state.
labelTypographyStyles
Styles of checkbox element label.
helperTextTypographyStyles
Styles of checkbox element helper text.
headerTypographyStyles
Styles of headers.
paragraphTypographyStyles
Styles of paragraphs.
labelTypographyStyles
Styles of labels.
helperTextTypographyStyles
Styles of helper texts.
errorTypographyStyles
Styles of error messages.
Basic Objects
Basic objects that can be used in styles definition.
LengthStringstring
Length value as a string.
Matching pattern: (\d{1,4}(.\d+)?|.\d+)(px|em|rem|%)
ColorStringstring
Color value as a string.
Matching pattern: #([0-9a-f]3|[0-9a-f]4|[0-9a-f]6|[0-9a-f]8)
Examples: #FFF, #abcdef, #AAA8, #88888810
FontWeightValuestring or number
Font weight value.
Allowed values: "normal", "bold", "lighter", "bolder", "inherit", "initial", "unset", 100, 200, 300, 400, 500, 600, 700, 800, 900
ButtonStyles Object
Object describing all button properties.
Contains all properties from: MarginStyles, PaddingStyles, BorderStyles, FontStyles, BackgroundStyles, ShadowStyles, OutlineStyles
InputStyles Object
Object describing all input properties.
Contains all properties from: MarginStyles, PaddingStyles, BorderStyles, FontStyles, BackgroundStyles, OutlineStyles
SelectStyles Object
Object describing all select properties.
Contains all properties from: MarginStyles, PaddingStyles, BorderStyles, FontStyles, BackgroundStyles, OutlineStyles, and the following:
iconColorColorString
Color of select icon.
CheckboxStyles Object
Object describing all checkbox properties.
Contains all properties from: MarginStyles, PaddingStyles, FontStyles, OutlineStyles, and:
iconColorColorString
Color of checkbox icon.
RadioStyles Object
Object describing all radio properties.
Contains all properties from: MarginStyles, PaddingStyles, FontStyles, OutlineStyles, and:
iconColorColorString
Color of radio icon.
TypographyStyles Object
Object describing all typography properties.
Contains all properties from: MarginStyles, PaddingStyles, BorderStyles, FontStyles, OutlineStyles.
MarginStyles Object
marginLengthString
Margin property.
marginLeftLengthString
Left margin property.
marginRightLengthString
Right margin property.
marginTopLengthString
Top margin property.
marginBottomLengthString
Bottom margin property.
PaddingStyles Object
paddingLengthString
Padding property.
paddingLeftLengthString
Left padding property.
paddingRightLengthString
Right padding property.
paddingTopLengthString
Top padding property.
paddingBottomLengthString
Bottom padding property.
BorderStyles Object
borderRadiusstring
Border radius property.
borderSingleBorderStyles
Border property.
borderLeftSingleBorderStyles
Left border property.
borderRightSingleBorderStyles
Right border property.
borderTopSingleBorderStyles
Top border property.
borderBottomSingleBorderStyles
Bottom border property.
SingleBorderStyles Object
widthLengthString
Border width.
stylestring
Border style.
Allowed values: "dotted", "dashed", "solid"
colorColorString
Border color.
FontStyles Object
fontFamilystring
Font family.
Maximum length: 150 characters. Allowed characters: 0-9a-z-\s,"'
fontColorColorString
Font color.
fontSizeLengthString
Font size.
fontWeightFontWeightValue
Font weight.
lineHeightLengthString
Line height.
letterSpacingLengthString
Letter spacing.
textDecorationstring
Text decoration.
Allowed values: "none", "underline", "overline", "line-through"
textAlignstring
Text alignment.
Allowed values: "left", "right", "center", "justify", "start", "end"
BackgroundStyles Object
backgroundColorColorString
Background color.
ShadowStyles Object
boxShadowobject
Box shadow.
offsetXLengthString
Shadow offset X.
offsetYLengthString
Shadow offset Y.
blurRadiusLengthString
Shadow blur radius.
spreadRadiusLengthString
Shadow spread radius.
colorColorString
Shadow color.
OutlineStyles Object
outlineBorderStyles
Outline property.
outlineOffsetLengthString
Outline offset.

Events​

The application emits events to which you can attach your own callback function using the on method.

ready Event
This event is emitted after calling the render method, when the application is displayed.
completed Event
Emitted when the payer completes the process in the application. The callback function attached to this event receives one parameter: an object containing result information. The contents of this object differ depending on whether the payer used a card number or a saved card from the Click to Pay wallet.
Result object
FieldDescription
type
Response type:
  • cardToken - when the payer used a card number.
  • clickToPay - when the payer used a card from Click to Pay.
details
Object containing detailed response data.
Result details - details object
FieldDescriptionOnly for
brand
Selected card type: visa or mastercard.
panLastFour
Last 4 digits of the card number.
panExpirationMonth
Card expiration month
panExpirationYear
Card expiration year
token
Card token.
Use this token to complete the payment.
cardToken
artUri
Optional parameter. Contains the URL of the card image.
clickToPay
srcDigitalCardId
Card identifier in Click to Pay.
Use this identifier to complete the payment.
clickToPay
srcCorrelationId
Transaction identifier in Click to Pay.
Use this identifier to complete the payment.
clickToPay

The following example contains test data.

{
    "type": "cardToken",
    "details": {
        "brand": "visa",
        "panLastFour": "1111",
        "panExpirationMonth": "02",
        "panExpirationYear": "2029",
        "token": "TOKD_1LOQUV5MMRNX70i7UXXXXXXXXX"
    }
}

On this page