Judopay Documentation

Web SDK

Our Web SDK is a JavaScript library which includes a fully customisable hosted iframe solution enabling you to collect sensitive card information.

You will not take on additional PCI scope, as sensitive card information:

  • card number (PAN)

  • expiry date

  • CV2 

will be submitted by your customers into fields hosted by Judopay.

WebSDK.png

How to use the Web SDK

You have two options to create a payment using the Web SDK:

  1. Use paymentSession to complete the whole payment journey (Recommended).

    For more details, see Option One - Create PaymentSession.

  2. Create a One Use Token.

    For more details, see Option Two - Create One Use Token.

Warning

The one-use token is a different field to the cardtoken.

Web SDK Checkout Flow

The complete checkout flow:

WebSDK_Checkout_Flow.png

Step

Description

One.png

An iframe is loaded on your page, including an instance of a JudoPay JavaScript object.

Two.png

Consumer enters card details into the iframe fields:

  • Card number

  • CV2

  • Expiry date

  • Post code Optional

Three.png

Consumer clicks on the Pay button:

  • The createToken function from the JudoPay object is called. 

  • This sends a request to Judopay.

  • Judopay uses the card details to return a one-use token. 

This token will be valid for 30 minutes.

Four.png

You send the one-use token to your backend, to process the transaction.

Five.png

Your backend makes a second call to Judopay.

This call sends the one-use token for the operation such as: Payment or RegisterCard.

Six.png

Judopay returns the Receipt for the operation.

Caution

The one-use token is a different field to the cardtoken.

Web SDK Set Up

To set up the Web SDK on your payment page:

  1. Include Judopay's JavaScript page on your website by adding a script tag in your HTML code:

Note

To automatically receive non-breaking changes, you can pin to the minor version (0.0) rather than the current patch version (0.0.12).

<script 
    src="https://web.judopay.com/js/0.0.14/judopay.min.js">
</script>

  1. Include a div in the iframe page with a unique ID value:

<div id="payment-iframe" width="100%"></div>

  1. Create an instance of the JudoPay object to call the createCardDetails function

  2. Provide the iframe div ID as a parameter. This function will return a reference to the card fields.:

var judo = new JudoPay("api_token", true);
Var payment = judo.createCardDetails('payment-iframe');

Note

The second parameter is called useSandbox. 

Set to true to use the Sandbox environment.

Set to false to use the Production environment.

Note

If you want to set the focus to the card number field when the card entry screen appears, add: ‘judokit.createCardDetails(’iframe-container-id', {autofocus: true})'

Creating a Payment with the Web SDK

The following guide is a full working example for use with Judopay's Web SDK.

Prerequisite

  • You have installed Judopay's Web SDK.

Option One - Create PaymentSession

Use Judopay's Web SDK to create a payment using paymentSession:

Step One: Create paymentSession

Call the Judopay API to create a paymentSession as an additional way to authenticate a 3D Secure 2 payments or preauths transaction. 

Note

Your backend server should store the paymentSession response reference returned by Judopay's API. Use this reference from the response to populate paymentSession when calling payments or preauths from your front-end client. See Step Three: Making a Transaction.

 

The following parameters need to remain consistent between the webpayment/payment requests and the payments or preauths requests:

  • YourPaymentReference

  • YourConsumerReference

  • JudoID

  • Currency

  • Amount

Caution

Check your API token has 3D Secure 2 enabled.

Request Body

To create the paymentSession:

  1. Create a /webpayments request using your token and secret by calling:

Target endpoint:

https://api-sandbox.judopay.com/webpayments/payments

HTTP Method: POST

{ 
    "judoId": "100915867",
    "amount": 5.10,
    "currency": "GBP",
    "yourConsumerReference": 'your_consumer_reference',
    "yourPaymentReference": 'your_payment_reference'
    }

Parameter

Description

judoId

String

Required

Unique ID supplied by Judopay.

Specific to a merchant and/or location.

Format:

  • 100100100

  • Maximum length 9 characters.

  • Do not include spaces or dashes.

amount

Decimal

Required

The amount to process. 

Format:

  • Two decimal places

For currencies using a different structure please contact Judopay for support.

currency

String

Required

The currency of the transaction.

 Any ISO 4217 alphabetic currency code:

  • GBP

  • USD

  • EUR

yourConsumerReference

String

Required

Unique reference to anonymously identify your customer.

Advisable to use GUIDs.

Must be below 40 characters.

yourPaymentReference

String

Required

Your unique reference for this payment. 

Format:

  • Maximum length 50 characters.

This value should be unique in order to protect your customers against duplicate transactions. 

With a server side integration, if a payment reference is not supplied, the transaction will not be processed.

Response Model
Payment-Session - Response Reference

Store the reference returned, in your backend server:

{
	"payByLinkUrl": "http://DESKTOP-PKKH4HN/pay/8DjXrE",
	"postUrl": "http://DESKTOP-PKKH4HN/pay/v1",
	"reference": "5AcAAAcAAAACAAAAEAAAAIdPHkGp7ByKnlxboSA9WWbujoHGjVMopy-WIWI-IxGB_BXaaA"
}

The paymentSession will expire in 30 minutes, unless an ExpiryDate is set in the /webpayments/payments request body.

The expiry date must be within one year: "ExpiryDate": "2021-10-06T17:43:21+01:00"

Step Two: Add the Payment Form to your Website

Create and customise the Judopay Web SDK iFrame:

  1. Add the code snippet in your web page <HEAD>:

    <script src="https://web.judopay.com/js/0.0.14/judopay.min.js"></script>

    1. This example will use jQuery for a promise, so include the following in your web page <HEAD>:

      <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js></script>

  2. In your <BODY> add a<DIV> tag where you want the iframe to appear:

    <div id="payment-iframe" width="100%"></div>

  3. In your <BODY> add a button call: submit-payment-button for the iframe submission to Judopay.

Note

This example uses the id: payment-frame. You can use whatever id you wish.

  1. In your <BODY> add a <DIV> tag where you want the errors in form entry to appear.

    For the purpose of this exercise, the class is named judopay-errors, and sets a style to be red. You can add any custom style you wish in your .CSS file.

    <div class="judopay-errors" style="color:red">Error Location</div>

  2. In your <BODY> add a button call: submit-payment-button for the iframe submission to Judopay.

  3. Set this to disabled. The iframe will enable it when the input is valid.

  4. You can apply any CSS styling you wish to this button.

    <button id="submit-payment-button" name="submit-payment" disabled> Pay Now </button>

  5. In your <BODY> add the following script for a minimum iframe.

    1. This example names this style configMinimum which is used when calling the iframe:

<script>var configMinimum = {
    iframe: {
    language: "en",
    errorFieldId: 'judopay-errors',
    showCardTypeIcons: true,
    cardTypeIconRight: "10px",
    cardTypeIconTop: "-2px",
    backgroundColor: "#FFFFFF",
    layout: "compact",
    enabledPaymentMethods: ['CARD'],
    isCountryAndPostcodeVisible: false,
    isCardHolderNameVisible: true,
    errorsDisplay: "HIDE_UNDER_FIELDS",
    disableUnderline: false,
    }
}
</script>

For the purpose of this exercise, this sample config sets the following options for the iframe:

  • Default language will be English “en”

  • iframe error field location set to “judopay-errors” as set in (4) above

  • Card Icons will display when the card entry is recognised

  • Background Colour is White “#FFFFFF”

  • Layout set to compact

  • iframe accepts Credit Card Entry “[‘CARD’]”

  • iframe does not show Post Code entry

  • iframe Errors will not display under the fields

  • iframe will underline the fields and highlight during entry

  1. Create the iframe in a <SCRIPT> tag:

var judo = new JudoPay("yourAPIToken", true);
var payment = judo.createCardDetails('payment-iframe',configMinimum);

Note

The iframe is created in your <SCRIPT> location.

  1. Alter yourAPIToken to match your Sandbox API Token.

  2. ‘true’ lets the iframe know it’s running on sandbox.

    1. Set this to ‘false’ when you wish to go live and use a ‘live’ API Token.

  3. ‘payment-iframe’ is where the iframe will load as defined in step (3) above.

  4. ‘configMinimum’ uses the style called configMinimum as defined in step (5(a)) above.

iFrame.png

Complete customisation of the iframe settings and styles can be found here.

Step Three: Making a Transaction

When the Web SDK Pay Button is clicked, the createPayment method will be called from the Web SDK.

The following parameters need to remain consistent between the webpayment/payment requests and the payments or preauths requests:

  • YourPaymentReference

  • YourConsumerReference

  • JudoID

  • Currency

  • Amount

Caution

For 3D Secure 2 transactions: billingAddress, mobileNumber and emailAddress are mandatory fields.

To make a transaction:

  1. The details of the configuration object needs to be set:

    Note

    Ensure the details used when creating the paymentSession match the values set in the following configuration:

{
    "judoId": "100915867", 
    "amount": 5.10,
    "currency": "GBP",
    "yourConsumerReference": " your_consumer_reference",
    "yourPaymentReference": "your_payment_reference",
    "billingAddress":{
        "address1": "My house", 
        "address2": "My street", 
        "town": "My town", 
        "postcode": "TR14 8PA", 
        "countryCode": 826 
            }, 
    "mobileNumber": "xxxxxxxx", 
    "emailAddress": "example@gmail.com", 
}

Parameter

Description

judoId

String

Required

Unique ID supplied by Judopay.

Specific to a merchant and/or location.

Format:

  • 100100100

  • Maximum length 9 characters.

  • Do not include spaces or dashes.

amount

Decimal

Required

The amount to process. 

Format:

  • Two decimal places

For currencies using a different structure please contact Judopay for support.

currency

String

Required

The currency of the transaction. 

Any ISO 4217 alphabetic currency code:

  • GBP

  • USD

  • EUR

yourConsumerReference

String

Required

Unique reference to anonymously identify your customer.

Advisable to use GUIDs.

Must be below 40 characters.

yourPaymentReference

String

Required

Your unique reference for this payment. 

Format:

  • Maximum length 50 characters.

This value should be unique in order to protect your customers against duplicate transactions. 

With a server side integration, if a payment reference is not supplied, the transaction will not be processed.

billingAddress

Object

Required

Card holder's billing address.

mobileNumber

String

Required

Consumer’s valid UK mobile number.

emailAddress

String

Required

Consumer’s valid email address.

  1. Invoke a payment or preauth transaction using the paymentSession and configuration:

const judopay = new JudoPay()
   // Invoke payment method
        judopay
        .invokePayment(paymentSession, configuration)
        .then(handleSuccess)
        .catch(handleError)
Step Four: Handle the Response

The response will determine whether the consumer is challenged for additional information in order to process the transaction. If the consumer is challenged, the Web SDK takes over and automatically presents the 3D Secure 2 challenge screen to the consumer.

The consumer will enter the required additional information, for example a code or password.

Once the authorisation is complete, the consumer is redirected to the outcome screen. For example, if the result = SUCCESS redirect the consumer to the Success Page, else ERROR.

 

Sample Success Response: 

const handleSuccess = (result) => {
    console.info(result)
}
Frictionless Response

Parameter

Description

receiptId

String

Judopy's reference for the transaction.

Used to process refunds or collections.

yourPaymentReference

String

Your unique reference for this payment. 

This value should be unique in order to protect your customers against duplicate transactions. 

With a server side integration, if a payment reference is not supplied, the transaction will not be processed.

type

String

Type of transaction:

  • Payment

  • Refund

  • PreAuth

  • Collection

createdAt

Date

An ISO8601 formatted date and time.

Includes time zone offset.

result

String

Result of transaction.

message

String

Message detailing the outcome.

judoId

String

Unique ID supplied by Judopay. 

Specific to a merchant and/or location.

Format:

  • 100-100-100

merchantName

String

Merchant's trading name.

appearsOnStatementAs

String

How the Merchant appears on the consumer's statement.

Note: The value will be populated from the dynamicDescriptor field in the /payments or /preauths request.

originalAmount

String

Amount of transaction.

Note: This field will not be included for Refund and PreAuth transaction types.

netAmount

String

The remaining balance of the transaction after a refund.

You cannot refund more than the original transaction amount.

amount

Decimal

The amount to process. 

Format:

  • Two decimal places

For currencies using a different structure please contact Judopay for support.

currency

String

The currency of the transaction.

Any ISO 4217 alphabetic currency code:

  • GBP

  • USD

  • EUR

cardDetails

String

Information on the card used in this transaction.

consumer

String

Details of the consumer.

Used for repeat transactions.

device

String

Specific device details to identify a consumer.

threeDSecure

String

For any 3DSecure requests.

Includes the result of the authentication process.

risks

String

Risks

acquirerTransactionId

String

The unique ID of a transaction set by the acquirer.

externalBankResponseCode

String

Reason code provided by the bank for declined transactions.

cardAddress

String

Cardholder's address.

Sample Error Response:

const handleError = (error) => {
    console.error(error)
}
{
    category: 1
    code: 0
    message: "Sorry, an error has occurred. Please try again later."
}

Option Two - Create One Use Token

Use Judopay's Web SDK to create a payment using a One Use Token:

Caution

The one-use token is a different field to the cardtoken.

Creating a One Use Token

Warning

The one-use token does not authorise any transactions but generates a oneTimeUse token for you to issue a payment request to our API endpoints, or to use our Server SDKs to request payment.

To create a one-use token:

  1. Your consumer clicks the Pay button on your website.

  2. Use your JudoPay instance to generate a one-use token from the card details fields: judo.createToken(payment);

    1. An encrypted Payload is generated (Judopay will decrypt the payload).

A sample success response:

{    
"oneUseToken": "2uhOsi...8KZcn=",    
 "cardLastfour": "3436",    
   "endDate": "12/20",    
    "cardScheme": "Visa",    
      "cardFunding": "Debit",    
        "error": false,     
   "clientDetails": 0 }

A sample error response:

{
    "error": 
    {
        "message": "Sorry, we're unable to process your request. Please check your details and try again."
    }
}

  1. The one-use token will be valid for 30 minutes .

  2. Use this token to call our Payment API and process a transaction.

  3. You will need to include the one-use token as part of an encrypted card model instance.

Registering a Card for a One Use Token

  1. Using your Judopay API client instance, create a RegisterEncryptedCardModel to save the consumer's card to Judopay’s card vault:

var encryptedCard = new RegisterEncryptedCardModel
{
    OneUseToken = oneUseToken,
    JudoId = judoId,
    YourConsumerReference = yourConsumerReference,
};

var response = client.RegisterCards.Create(encryptedCard);
var receipt = response.Response as PaymentReceiptModel;

if(receipt.Result === "Success") {
    var cardToken = receipt.CardDetails.CardToken;  
}

  1. The response will include a card token, which does not expire.

  2. The card token can be used in a TokenPaymentModel for the next transaction.

Making a Transaction with a One Use Token

  1. Using your Judopay API client instance, create a OneTimePaymentCardModel and immediately process a payment with the one-use token.

  2. The response includes a Card token:

    var oneTimePayment = new OneTimePaymentModel
{
    OneUseToken = oneUseToken,
    JudoId = judoId,
    YourConsumerReference = yourConsumerReference,
    YourPaymentReference = yourPaymentReference,
    Amount: 1.0,
    Currency: "GBP"
};

var response = client.Payments.Create(oneTimePayment);
var receipt = response.Response as PaymentReceiptModel;

if(receipt.Result === "Success") {
    var cardToken = receipt.CardDetails.CardToken;  
}

  3. Save the card token for the next transaction

  4. If 3D Secure is enabled, the response message = Requires 3D Secure 

All fields required to run the 3D Secure check will be available in the receipt:

  • acsUrl

  • PaReq

  • MD

{
    "receiptId": "415874660497166336",
    "result": "Requires 3D Secure",
    "message": "Issuer authentication required",
    "acsUrl": "https://gw1.paymentsensegateway.com:4430/ACS/Default.aspx",
    "md": "1902...2484",
    "paReq": "eJxd...kqXcvg=="
}

To complete the transaction the 3D Secure form needs to be displayed to the consumer.

This can be achieved in any of the following ways: 

  • a redirect

  • pop-up window

  • iframe

Customising your Web SDK Integration

Form Customisation

The configuration file is key for customising the behaviour and look of the Iframe.

You can change the appearance, behaviour and language by passing a configuration JSON object into createCardDetails.

Tip

Wrap up your configuration in a separate js file and include it on your page.

Example 1. Passing your configuration into createCardDetails:
var styleOptions = {
    iframe {
        ...
    }
}
var judo = new JudoPay('Your Token', true);
var paymentFrame = judo.createCardDetails('', styleOptions)


Form Customisation Top Level Properties

The Web SDK has a default setting for all properties, you override these in the config file. 

The config file is a simple JSON object containing the following properties:

Property Name

Values

Default

language

language from supported list

en

showCardTypeIcons

boolean

true

backgroundColor

HTML colour ('red') or

Hex color ('#FF0000')

white

layout

vertical, horizontal or compact

vertical

styles

JSON object which is defined below

specified below

fonts

JSON array which is defined below

specified below

The configuration file is optional.

Styles Properties

Configuration to style fields is within the Styles object. 

Styles can be applied to all fields by placing the style attribute in the default object inside Styles. You can also apply styles individually to fields, directly to the field name.

The styles object has 6 properties:

  1. Default 

  2. Focus 

  3. Error 

  4. Valid 

  5. cv2 

  6. expiryDate 

Each of these properties has three properties:

  1. Field 

  2. Label 

  3. Container

The properties for field and label:

  • Mapped to the style objects of the input and label HTML elements. 

The properties for container:

  • Mapped to the div that contains both the input and label.

The properties for focus, error and valid:

  • Mapped on state transition allowing the functionality to be consistent with other forms on your site.

Any property defined in default will be applied to all the fields.

Any property defined in a field will take priority over a default property, the fields are expiryDate and cv2.

All valid style properties are supported and take the form of camel cased CSS properties, eg padding-bottom becomes paddingBottom.

styles: {
            default: {
                field: {
                    backgroundColor: '#0a0a0a',
                    color: '#EEE',
                    padding: '10px',
                    margin: '0 20px',
                    width: '90%',
                    borderRadius: '4px',
                    boxShadow: 'rgba(255, 255, 255, 0.8) 0px 0px 10px inset'
                },
                label: {
                    color: '#EEE',
                    padding: '10px 10px 0 25px',
                    fontWeight: 'bold',
                    textTransform: 'capitalize'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#2a2a2a',
                    color: '#EEE'
                },
            },
            error: {
                field: {
                    backgroundColor: '#1a0a0a',
                    color: '#990000'
                }
            },
            valid: {
                field: {
                    color: '#CFC'
                }
            },
            cv2: {
                field: {
                    margin: "0 20px 10px;"
                },
                container: {
                    width: '47%',
                    paddingBottom: "20px"
                }
            },
            expiryDate: {
                field: {
                    marginBottom: "10px;"
                },
                container: {
                    width: '47%',
                    paddingBottom: "20px"
                }
            }

Form Layout

Three layout options are provided:

  • Vertical

  • Compact

  • Horizontal

WebSDK_Layout.png

Form Fonts

An array of JSON objects each representing a font, are added to the page.

They can be referenced from the Style object.

Each object can have the following properties:

Property Name

Values

Example Value

family

Specifies the name of the font face value properties.

Roboto

src

Specifies the resource containing the font data.

"/fonts/OpenSans-Regular-webfont.woff2"

display

Determines how a font face is displayed.

Based on whether and when it is downloaded and ready to use.

auto

style

Specifies the font styles.

italic

unicodeRange

The range of font Unicode code points to be used.

U+0025-00FF, U+4??

weight

Specifies the font weight, or boldness.

400

The following example loads Roboto from Google fonts and assigns it:

fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange: 'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: "'Roboto', sans-serif",
                },
                label: {
                    fontFamily: "'Roboto', sans-serif",
                }
            },

Adding a New Language

You can add any language you need.

To add a new language:

  1. Add the language in a customLanguages property in your Judopay configuration file. 

    This property can either be a single dictionary for one language, or an array of dictionaries for multiple languages. 

For the purpose of this exercise, the example shows how to add Romanian:

var customStyle = {
    iframe1 : {
        language : "ro",
        customLanguages : 
            {
                "ro" : {
                    fieldLabels: {
                        cardNumberLabel: "Număr de card",
                        expiryDateLabel: "Data Expirarii",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "Număr de card",
                        expiryDatePlaceholder: "LL / AA ",
                        cardVerificationCodePlaceholder: "CVC"
                    },
                    errors : {
                        0: "Numărul cardului poate conține numai numere",
                        1: "Numărul cardului nu este valid",
                        2: "Tipul de card nu este recunoscut, verificați din nou numărul dvs",
                        3: "Numarul cardului este necesar",
                        4: "Cardul a expirat",
                        5: "Data expirării cardului nu este validă",
                        6: "Data expirării necesară",
                        7: "Codul {0} este prea scurt pentru cartea de {1}",
                        8: "Codul {0} este prea lung pentru carte de {1}",
                        9: "Codul {0} poate conține numai numere",
                        10: "Codul {0} necesar pentru cartea de {1}"
                    }
                }
            },
           ...
    }
};

Warning

It is important the language dictionary follows this structure with inner dictionaries and strings, so the translations can be applied.

Now all strings used in the application will be taken from the new language set.

As well as adding any language into the customLanguages property, also set the language for the error code (ro). 

It is recommended to copy this example and change the strings when defining your new language.

Language Translations

Judopay's Web SDK supports multiple languages.

Tip

The default property is English.

Language

Code

English

en

French

fr

Spanish

es

Portuguese

pt

German

de

Changing the Form Language

To change the language of the form:

1. Set a language variable in your configuration file. 

2. Pass in the language code as a string:

var customStyle = {
    iframe1 : {
        language : "es"
        ...
    }
}

3. For the purpose of this exercise, the iframe will now load using Spanish translations.

Change Form Language at Runtime

You can change the language used in the form at run time. This is useful for consumers running a Single Page Application (SPA).

The JudoPay object which initialises the form provides a method for updating a language. You can hook this method up to a button/event of your choice for dynamically changing the language. 

In the example below, a method is added to an anchor element on the checkout page, which will change the language used after the iframe is already initialised.

<script>
    var judo = new JudoPay('Your Token', true);
</script>
<a href="javascript:judo.changeIframeLanguage('de');">de</a>

Configuration Example

Below is an example config file which sets the styles for:

  • Layout

  • Background colour

  • Inputs

  • Labels

It also modifies the error and UI strings for the default language: English.

var exampleConfig = {
    iframe: {
        language: 'en',
        errorFieldId: 'judopay-errors-2',
        showCardTypeIcons: true,
        cardTypeIconRight: '10px',
        cardTypeIconTop: '-2px',
        backgroundColor: '#e5e5e5',
        layout: "compact",
        fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange:
                'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: "'Roboto', sans-serif",
                    fontSize: '17px',
                    backgroundColor: '#e5e5e5',
                    borderTop: 'none',
                    borderRight: 'none',
                    borderLeft: 'none',
                    boxShadow: 'none',
                    margin: '-10px 0 -5px',
                    padding: '6px 0'
                },
                label: {
                    color: '#F77',
                    fontFamily: "'Roboto', sans-serif",
                    opacity: '0',
                    height: '15px',
                    fontSize: '8px',
                    display: 'inline-block',
                    transition: 'opacity 0.6s',
                    marginLeft: '5px',
                    position: 'relative',
                    bottom: '-10px',
                    zIndex: '100'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#F0F0F0',
                    color: 'rgb(130, 130, 130)',
                    padding: '12px 6px 0',
                    fontSize: '16px',
                },
                label: {
                    opacity: "1",
                    color: 'rgb(130, 130, 130)'
                }
            },
            error: {
                field: {
                    backgroundColor: '#e5ecff',
                    padding: '12px 6px 0',
                },
                label: {
                    opacity: "1"
                }
            },
            valid: {
                field: {
                    backgroundColor: '#e5ffec',
                    color: 'green',
                    padding: '12px 6px 0',
                },
                label: {
                    color: 'green',
                    opacity: "1"
                }
            },
            customLanguages: {
                "en": {
                    fieldLabels: {
                        cardNumberLabel: "Credit Card Number",
                        expiryDateLabel: "Expiration Date",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "xxxx xxxx xxxx xxxx",
                        expiryDatePlaceholder: "MM / YY ",
                        cardVerificationCodePlaceholder: "xxx"
                    },
                    errors: {
                        0: "Card number must be numeric",
                        1: "Card number not valid",
                        2: "Card type not recognised",
                        3: "Card number required",
                        4: "Card is expired",
                        5: "Invalid expiry date",
                        6: "Expiry date required",
                        7: "{0} code too short",
                        8: "{0} code too long",
                        9: "{0} code must be numeric",
                        10: "{0} code required"
                    }
                }
            }
        }
    }
}

Overriding an Existing Language

You can also modify the language to change the phrasing, words and dialects used

For the purpose of this exercise, the Romanian language is added in this example, to illustrate how multiple dictionaries can be added if customLanguages is defined as an array:

var customStyle = {
    iframe1 : {
        language : "en",
        customLanguages : [
        {
                "en" : {
                    fieldLabels: {
                        cardNumberLabel: "Credit Card Number",
                        expiryDateLabel: "Expiration Date",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "xxxx xxxx xxxx xxxx",
                        expiryDatePlaceholder: "MM / YY ",
                        cardVerificationCodePlaceholder: "xxx"
                    },
                    errors : {
                        0: "Card number must be numeric",
                        1: "Card number not valid",
                        2: "Card type not recognised",
                        3: "Card number required",
                        4: "Card is expired",
                        5: "Invalid expiry date",
                        6: "Expiry date required",
                        7: "{0} code too short",
                        8: "{0} code too long",
                        9: "{0} code must be numeric",
                        10: "{0} code required"
                    }
                }
            },
            {
                "ro" : {
                    fieldLabels: {
                        cardNumberLabel: "Număr de card",
                        expiryDateLabel: "Data Expirarii",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "Număr de card",
                        expiryDatePlaceholder: "LL / AA ",
                        cardVerificationCodePlaceholder: "CVC"
                    },
                    errors : {
                        0: "Numărul cardului poate conține numai numere",
                        1: "Numărul cardului nu este valid",
                        2: "Tipul de card nu este recunoscut, verificați din nou numărul dvs",
                        3: "Numarul cardului este necesar",
                        4: "Cardul a expirat",
                        5: "Data expirării cardului nu este validă",
                        6: "Data expirării necesară",
                        7: "Codul {0} este prea scurt pentru cartea de {1}",
                        8: "Codul {0} este prea lung pentru carte de {1}",
                        9: "Codul {0} poate conține numai numere",
                        10: "Codul {0} necesar pentru cartea de {1}"
                    }
                }
            }
    ],
        ...        
    }
};

Configuration File Example

Below is an example configuration file which sets the:

  • Layout

  • Background colour

  • Input and label styles

  • defaultCountryCode

    For the purpose of this exercise, US is set as the default country code.

It also modifies the error and UI strings for the default language: English.

Example 2. Configuration File
var exampleConfig = {
    iframe: {
        language: "en",
        errorFieldId: 'judopay-errors',
        cardTypeIconRight: "-400px",
        cardTypeIconTop: "-50x",
        backgroundColor: "#EAECEF",
        showCardTypeIcons: true,
        layout: "vertical",
        enabledPaymentMethods: ['CARD'],
        defaultCountryCode: 'US',
        isCountryAndPostcodeVisible: false,
        isCardHolderNameVisible: false,
        disableUnderline: true,
        errorsDisplay: "HIDE_UNDER_FIELDS",
        disableUnderline: true,
        shouldAutofocues: false,
        fonts: [
            {
                family: 'Roboto',
                src: 'https://fonts.gstatic.com/s/roboto/v18/KFOmCnqEu92Fr1Mu72xKOzY.woff2',
                display: 'auto',
                style: 'normal',
                unicodeRange:
                'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
                weight: '400'
            }
        ],
        styles: {
            default: {
                field: {
                    fontFamily: "'Roboto', sans-serif",
                    fontSize: '17px',
                    backgroundColor: '#e5e5e5',
                    borderTop: 'none',
                    borderRight: 'none',
                    borderLeft: 'none',
                    boxShadow: 'none',
                    margin: '-10px 0 -5px',
                    padding: '6px 0'
                },
                label: {
                    color: '#F77',
                    fontFamily: "'Roboto', sans-serif",
                    opacity: '0',
                    height: '15px',
                    fontSize: '8px',
                    display: 'inline-block',
                    transition: 'opacity 0.6s',
                    marginLeft: '5px',
                    position: 'relative',
                    bottom: '-10px',
                    zIndex: '100'
                }
            },
            focus: {
                field: {
                    backgroundColor: '#F0F0F0',
                    color: 'rgb(130, 130, 130)',
                    padding: '12px 6px 0',
                    fontSize: '16px',
                },
                label: {
                    opacity: "1",
                    color: 'rgb(130, 130, 130)'
                }
            },
            error: {
                field: {
                    backgroundColor: '#e5ecff',
                    padding: '12px 6px 0',
                },
                label: {
                    opacity: "1"
                }
            },
            valid: {
                field: {
                    backgroundColor: '#e5ffec',
                    color: 'green',
                    padding: '12px 6px 0',
                },
                label: {
                    color: 'green',
                    opacity: "1"
                }
            },
            customLanguages: {
                "en": {
                    fieldLabels: {
                        cardNumberLabel: "Credit Card Number",
                        expiryDateLabel: "Expiration Date",
                        cardVerificationCodeLabel: "CVC"
                    },
                    fieldPlaceholders: {
                        cardNumberPlaceholder: "xxxx xxxx xxxx xxxx",
                        expiryDatePlaceholder: "MM / YY ",
                        cardVerificationCodePlaceholder: "xxx"
                    },
                    errors: {
                        0: "Card number must be numeric",
                        1: "Card number not valid",
                        2: "Card type not recognised",
                        3: "Card number required",
                        4: "Card is expired",
                        5: "Invalid expiry date",
                        6: "Expiry date required",
                        7: "{0} code too short",
                        8: "{0} code too long",
                        9: "{0} code must be numeric",
                        10: "{0} code required"
                    }
                }
            }
        }
    }
}


Web SDK Errors

The Web SDK is designed to provide feedback quickly and clearly to the consumer.

To display error messages:

Add a div with the id judopay-errors on your page, ideally below the iframe:

<div class="judopay-errors"></div>;

 

The table below displays all errors that can be returned:

ID

Error String

0

Card number can only contain numbers

1

Card number not valid

2

Card type not recognised, please recheck your number

3

Card number required

4

Card is expired

5

Card expiry date is not valid

6

Expiry date required

7

{0} code too short for {1} card

8

{0} code too long for {1} card

9

{0} code can only contain numbers

10

{0} code required for {1} card

For errors 7-10; the numbers appear in curly brackets. These will be changed into values depending on the current state of the iframe form.

For example:

{0} will change to the card verification code acronym. This is named differently depending on the card type (e.g. CVC, CVV).

{1} will refer to the detected card type, for example Visa, Mastercard or Discover.

 

If the iframe has detected a Visa number, the following error message transform would occur:

{0} code too long for {1} card" -> "CVC code to long for Visa card

A similar error with an American Express card, the message would appear as:

"CID code too long for American Express card"

See also:

Judopay’s core API for processing transactions.

A card token is a randomly generated string linked to the saved card in Judopay’s systems.

It can be stored in your database without worrying about PCI compliance issues.

This card token can only be used with the associated consumer token.