Web SDK

 

 

Judopay's 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 such as:

  • card number (PAN)

  • expiry date

  • CV2 

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

 

Also use our Web SDK to integrate:

 

Creating a 3D Secure 2 Payment with the Web SDK

We have made it a simple implementation for you to upgrade and integrate 3D Secure 2 within your payment flow.

 

Web SDK Version 0.0.29 (and higher) fully supports 3D Secure 2 flows. No additional support is required, the SDK does the rest.
The following guide is a full working example for use with Judopay's Web SDK.

Make sure your account has 3D Secure 2 enabled. Contact ​Customer Support​​ to set this up.

 

When authorising /payments or /preauths it is recommended to use paymentSession.

Payment Flow:

 

 

Step One: Create a paymentSession

Make sure you are using Judopay's API version 6.0.0.0 or higher.

Important to Consider:

  • The paymentSession can be used for up to three transaction attempts for the same transaction.

    • If the block duplicate transactions permission has been applied on your API tokens, the paymentSession can only be used for one transaction attempt.

  • A payment session can be used again to re-submit a failed transaction attempt.

  • Once a transaction attempt is successful, the paymentSession can no longer be used even if there are any remaining attempts available.

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

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

    As soon as the payment session is used for the initial transaction attempt, this will initiate the 30 minute expiry time.

 

Make a HTTP POST Request: /paymentsession

For the full schema details and descriptions, see Transaction API /paymentsession

 

Response Model

Payment-Session - Response Reference:

 

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 and /preauths from your front-end client.
See Step Three: Making a Transaction.

The following parameters need to remain consistent between the /paymentsession requests and the /payments and /preauths requests, otherwise the transaction will fail:

  • YourPaymentReference

  • YourConsumerReference

  • JudoID

  • Currency

  • Amount

This is used to cross reference the validity of the transaction.

 

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.43/judopay.min.js"></script>

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

    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>

    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>

    For more information on all errors that can be returned, see Displaying Payment Form Error Messages.

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

    Make sure you have set:id="submit-payment-button" . This is required to perform form validation where the Pay button will be greyed out until all the information has been entered.

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

    You can apply any css styling you wish to this button.

  2. In your <BODY> define the iFrameConfiguration object. This is used to customise the look and behaviour of the iFrame.

    For more information on customising the iFrame, see Customising your Web SDK Integration.

     

    An example of an iFrameConfiguration object:

The iframe is created in your <SCRIPT> location.

 

See below for more details on the parameters that create the iFrameConfiguration object:

 

Parameter

Description

 

isGeoLocationGatheringAllowed

Boolean

isGeoLocationGatheringAllowed = false

The browser will not ask for the location. 

isChallengeModalCancelButtonVisible

Boolean

isChallengeModalCancelButtonVisible = true

If set to false, the cancel (X) button on the 3D Secure 2 challenge modal will not be shown:

iFrame Parameters: 

language

String

Sets the language of the iFrame.

Values:

  • en (english) (Default)

  • es (spanish)

  • fr (french)

  • pt (portugese)

  • de (german)

 

errorFieldId

String

Set as the class name of the <div> where the errors appear.

For example:

<div class="judopay-errors">Error Location</div> 

showCardTypeIcons

Boolean

showCardTypeIcons = true

The card icons will display when the card entry is recognised.

 

cardTypeIconRight

String

Changes the position of the card icon.

 

cardTypeIconTop

String

Changes the position of the card icon.

 

backgroundColor

String

Sets the background colour of the iFrame.

For example:

  • #FFFFFF

  • Default: white

 

layout

String

Sets the layout of the iFrame payment form.

Values:

  • vertical (default)

  • compact

  • horizontal

 

For the form layout illustrations, see Form Layout

 

defaultCountryCode

String

Sets the country displayed in the country field.

For example:

  • UK

 

isCountryAndPostcodeVisible

Boolean

isCountryAndPostcodeVisible = true

The country and postCode fields will be displayed.

 

isCardHolderNameVisible

Boolean

isCardHolderNameVisible = true

The cardHolderName field will be displayed.

 

enabledPaymentMethods

String [ ]

Array of accepted payment methods.

Values:

  • CARD

  • IDEAL

 

errorsDisplay

String

Formats how errors are displayed to the consumer.

Values:

  • SHOW_ALL

  • HIDE_UNDER_FIELDS

  • HIDE_UNDER_FORM

  • HIDE_ALL

 

shouldAutofocus

Boolean

shouldAutofocus = true

Sets the focus to the cardNumber field when the iFrame appears

 

idealPollingTimeout

Number

Specifies the amount of time the system waits for the IDEAL alternative payment method to respond.

For example: 6000

 

disableUnderline

Boolean

disableUnderline = false

When the consumer enters information into the iFrame, the fields will be underlined and highlighted.

 

allowedCardSchemes

String [ ]

Array of accepted card schemes.

If this field is set, an error will appear if an unsupported card scheme is entered.

Values:

  • amex

  • mastercard

  • maestro

  • visa

  • diners

  • discover

  • jcb

 

styles

Object

A JSON object.

Define further css style customisation for the payment fields.

 

For more information, see Styles Properties.

 

fonts

Object [ ]

An array of JSON objects, each representing a font.

 

For more information, see Form Fonts.

 

 

  1. Create an instance of the Judopay Web SDK: var judo = new JudoPay("yourAPIToken", true); //initialize library

  • Alter yourAPIToken to match your Sandbox API Token

  • The second parameter is called useSandbox

    • Set to true to use the Sandbox environment.

    • Set to false to use the Production environment.

  1. Create the iFrame in the <div> tag: var payment = judo.createCardDetails('payment-iFrame', iFrameConfiguration)

    • 'payment-iFrame': The <div> id where the iFrame will be rendered, in step (2) above.

    • iFrameConfiguration: The object defined to customise the look and behaviour of the iFrame, in step (5) above.

 

Step Three: Making a Transaction

To make a transaction:

  1. Define the paymentConfiguration object for the payment or preAuth:

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

 

See below for more details on the parameters that create the paymentConfiguration object:

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.

 

phoneCountryCode

String

Optional

The country code of the consumer's phone.

Format:

  • Maximum length 3 characters.

  • Only numbers allowed.

  • Do not include special characters or spaces.

Should be set if mobileNumber is set.
If not set, default = 44 

mobileNumber

String

Optional

Consumer’s valid mobile number.

Format:

  • Maximum length 15 characters.

  • Only numbers allowed.

  • Do not include special characters or spaces.

Must be set if phoneCountryCode is set.

 

cardHolderName

String

Optional

The card name of the consumer.

 

If the cardHolderName field is displayed to the user in the payment form (isCardHolderNameVisible: true is set in the iFrame config), the value entered in the payment form will overwrite this value.

 

challengeRequestIndicator

String

Optional

Indicates the type of challenge request you wish to apply.

Set this to one of the following strings:

  • noPreference

  • noChallenge

    • No challenge required.

  • challengePreferred

    • A challenge is preferred for this transaction.

  • challengeAsMandate

    • Must challenge this transaction.

This should not be included in the same configuration object as scaExemption.

 

scaExemption

String

Optional

To apply for an exemption from SCA, for a customer initiated transaction.

Set this to one of the following strings:

  • lowValue

    • Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.

  • secureCorporate

    • Request exemption for payments made using a corporate card.

  • trustedBeneficiary

    • Provides the cardholder the option to add the merchant to their trusted list.

  • transactionRiskAnalysis

    • Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.

This should not be included in the same configuration object as challengeRequestIndicator.

 

initialRecurringPayment

Boolean

Optional

Indicates if this initial payment is part of a recurring payment.

 

billingAddress

Object

Optional

Card holder's billing address.

Properties:

  • address1

    string

  • address2 (optional)

    string

  • town

    string

  • state(only required if country is USA/Canada)

    • Format:

      • string

      • ISO Alpha-2 Code (e.g. California = "CA")

  • country

    • Format:

      • string

      • ISO Numeric Code (e.g. United Kingdom = "826")

  • postCode

    string

 

If the billingAddress is provided, the postcode is required.

 

emailAddress

String

Optional

Consumer’s valid email address.

It is recommended but not required for 3D Secure 2 authentication.

 

primaryAccountDetails

Object

Optional

This is Mandatory for merchants who have an MCC code of 6012

Properties:

  • name

    string

This is the surname.

  • accountNumber

    string

  • dateOfBirth

    string

    • Format: YYYY-MM-DD

  • postCode

    string

 

delayedAuthorisation

Boolean

Optional

For preAuths only.

Set to true to authenticate a card holder with 3D secure, without performing payment authorisation.

When set to true, the 3D Secure authentication status is returned in the response.

 

The payment authorisation is carried out at the stage when you are ready to collect the amount from the consumer.

  • The default value = false

 

 

  1. In a function, add the invokePayment call.

    This will invoke a payment using the paymentSession and paymentConfiguration

 

To invoke a preauth, change the above code to .invokePreauth

  1. To call the function (in step 2 above) to invoke the payment or preauth, add the onclick attribute to the payment button <div>:

    <button id="submit-payment-button" onclick="handlePaymentButtonClick()"> Pay Now </button>

 

Step Four: Handle the Response

Once the authorisation is complete you will receive either:

 

The consumer should be redirected to the outcome screen and the response/error should be handled accordingly.

For example, if the result = SUCCESS redirect the consumer to the Success Page, else ERROR.

 

For more information on the response codes, see Codes.

 

Putting it all together to display the payment form and make a transaction:

 

 

Setting up an Incremental Authorisation

The incremental authorisation feature allows you to increment the value of your original preAuth for scenarios where you need to charge your customer a higher total amount.
By incrementing the preAuth value, you will be able to capture the total amount that you wish to charge your customer when you are ready.

The allow increment flag allows you to set up your initial preAuth so that it can be incremented by an additional amount.

This feature is only available with a limited set of processors - please check with your account manager before you use this feature.

  • allowIncrement is a part of the main JudoPaymentConfiguration config object, and can be set when creating the configuration object.

  • If present = it is automatically applied for preAuth requests.

  • If no value is provided = then false is set by default.

Example:

val configuration: JudoPaymentConfiguration = {
    ...
    allowIncrement: true,
};

const judopay = new JudoPay()
judopay.createCardDetails('jupay-payment-iframe', configuration)

 

Creating a CheckCard Request with the Web SDK

The Web SDK’s Check Card functionality can be used to perform a zero amount pre-authorisation (0 Auth).

Check Card enables you to check the validity of the card, to be used for future payments.

 

Do you have a stored card wallet for existing customers?

If validation is successful, a card token is returned as part of the response object. This token can then be stored and used for a payments/preauths request in the future, using the Web SDK’s Token Payment functionality.

 

Prerequisites

Make sure you are using Web SDK Version 0.0.34 (or higher).

Make sure you have implemented the following prerequisites:

 

Step One: Making a Check Card Request

  1. Define the checkCardConfiguration object.

    Ensure the details used when creating the paymentSession match the values set in the checkCardConfiguration object.

 

See below for more details on the parameters that create the checkCardConfiguration object:

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.

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.

phoneCountryCode

String

Optional

The country code of the consumer's phone.

Format:

  • Maximum length 3 characters.

  • Only numbers allowed.

  • Do not include special characters or spaces.

Should be set if mobileNumber is set.
If not set, default = 44 

mobileNumber

String

Optional

Consumer’s valid mobile number.

Format:

  • Maximum length 15 characters.

  • Only numbers allowed.

  • Do not include special characters or spaces.

Must be set if phoneCountryCode is set.

cardHolderName

String

Optional

The card name of the consumer

 

If the cardHolderName field is displayed to the user in the payment form (isCardHolderNameVisible: true is set in the iFrame config), the value entered in the payment form will overwrite this value.

challengeRequestIndicator

String

Optional

Indicates the type of challenge request you wish to apply.

Set this to one of the following strings:

  • noPreference

  • noChallenge

    • No challenge required.

  • challengePreferred

    • A challenge is preferred for this transaction.

  • challengeAsMandate

    • Must challenge this transaction.

This should not be included in the same configuration object as scaExemption.

scaExemption

String

Optional

To apply for an exemption from SCA, for a customer initiated transaction.

Set this to one of the following strings:

  • lowValue

    • Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.

  • secureCorporate

    • Request exemption for payments made using a corporate card.

  • trustedBeneficiary

    • Provides the cardholder the option to add the merchant to their trusted list.

  • transactionRiskAnalysis

    • Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.

This should not be included in the same configuration object as challengeRequestIndicator.

initialRecurringPayment

Boolean

Optional

Indicates if this initial payment is part of a recurring payment.

billingAddress

Object

Optional

Card holder's billing address.

Properties:

  • address1

    string

  • address2 (optional)

    string

  • town

    string

  • state(only required if country is USA/Canada)

    • Format:

      • string

      • ISO Alpha-2 Code (e.g. California = "CA")

  • country

    • Format:

      • string

      • ISO Numeric Code (e.g. United Kingdom = "826")

  • postCode

    string

 

If the billingAddress is provided, the postcode is required.

emailAddress

String

Optional

Consumer’s valid email address.

It is recommended but not required for 3D Secure 2 authentication.

 

 

  1. In a function, add the invokeCheckCard call.

    This will make Check Card request using both the paymentSession and checkCardConfiguration.

 

 

  1. To call the invokeCheckCard function (in step 2 above) to make the Check Card request, add the onclick attribute to the payment button <div>:

This is the same button that is used for payments, however you can update the button label to reflect it’s functionality. For example: Check Card instead of Pay Now.

 

Step Two: Handle the Response

Once the Check Card request is complete you will receive either:

The response / error should be handled accordingly.

 

Creating a SaveCard Request with the Web SDK

If you do not want to perform a pre-authorisation check on a customer's account, use this call to tokenise the card information into an encrypted string.

Do you have a stored card wallet for existing customers?

If validation is successful, a card token is returned as part of the response object.

This token can then be stored and used for a payments / preauths request in the future, using the Web SDK’s Token Payment functionality.

 

Prerequisites

 

Step One: Making a Save Card Request

  1. Define the saveCardConfiguration object.

Ensure the details used when creating the paymentSession match the values set in the saveCardConfiguration object.

 

See below for more details on the parameters that create the saveCardConfiguration object:

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.

yourConsumerReference

String

Required

Unique reference to anonymously identify your customer.

Advisable to use GUIDs.

Must be below 40 characters.

currency

String

Optional

The currency of the transaction.

Any ISO 4217 alphabetic currency code:

  • GBP

  • USD

  • EUR

cardHolderName

String

Optional

The card name of the consumer

 

If the cardHolderName field is displayed to the user in the payment form (isCardHolderNameVisible: true is set in the iFrame config), the value entered in the payment form will overwrite this value.

billingAddress

Object

Optional

Card holder's billing address.

Properties:

  • address1

    string

  • address2 (optional)

    string

  • town

    string

  • state(only required if country is USA/Canada)

    • Format:

      • string

      • ISO Alpha-2 Code (e.g. California = "CA")

  • country

    • Format:

      • string

      • ISO Numeric Code (e.g. United Kingdom = "826")

  • postCode

    string

 

If the billingAddress is provided, the postcode is required.

 

 

  1. In a function, add the invokeSaveCard call.

    This will make a Save Card request using the paymentSession and saveCardConfiguration.

 

  1. To call the invokeSaveCard function (in step 2 above) to make the Save Card request, add the onclick attribute to the payment button <div>:

    <button id="submit-payment-button" onclick="handleSaveCardButtonClick()"> Save Card </button>

    This is the same button that is used for payments, however you can update the button label to reflect it’s functionality.

    For example: Save Card instead of Pay Now.

 

Step Two: Handle the Response

Once the Save Card request is complete you will receive either:

The response / error should be handled accordingly.

 

Creating a Token Payment with the Web SDK

Supports token payment and token preAuth.

Do you have a stored card wallet for existing customers, making use of card tokens?

Using our Web SDK, you will also be able to invoke a customer-initiated payment using a card token, to handle:

  • payments

  • preAuths

  • 3D Secure challenges

    on your behalf.

 

Step One: Setting up the Web SDK

To invoke a customer-initiated transaction using a card token, follow the below steps from Creating a 3D Secure 2 Payment with the Web SDK:

The payment form iFrame must be loaded onto the page in order for payments to work. However displaying the form to the consumer is not required for this transaction type.

To hide the payment form iFrame, use: <div id="payment-iframe" style="position:absolute;width:0;height:0;border:0;"></div>

 

Step Two: Making a Token Transaction

To make a token transaction:

  1. Define the tokenConfiguration object for the token payment or token preAuth.

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

 

See below for more details on the parameters that create the tokenConfiguration object:

 

The configuration object for token payments takes the same parameters as the paymentConfiguration object (see Payment Configuration Parameter Descriptions), along with the additional token specific parameters to be included, as listed below:

Parameter

Description

cardToken

String

Required

A randomly generated string linked to the saved card stored in Judopay’s system.

shouldVerifySecurityCode

Boolean

Optional

Indicates if the consumer will be prompted to enter their security code.

Default value = true.

securityCode

String

Optional

The 3/4 digit security code associated with the consumer’s saved card.

 

This value will be overwritten if the user is prompted to enter their own value: (shouldVerifySecurityCode=true).

shouldVerifyCardHolderName

Boolean

Optional

Indicates if the consumer will be prompted to enter their card holder name.

If the user is prompted to enter their card holder name AND you have provided cardHolderName in the config, the config value will be overwritten.

Default value = false *

 

 

  1. In a function, add the invokeTokenPayment call.

    This will invoke a payment using the paymentSession and tokenPaymentConfiguration

 

To invoke a preAuth, change the above code to .invokeTokenPreauth

  1. To customise the style of the Token Details Modal Input, add an extra parameter to the invokeTokenPayment call:

    judo.invokeTokenPayment(paymentSession, tokenConfiguration, tokenDetailsModalStyle)

     

    The tokenDetailsModalStyle is an object defining the style of the modal.

    For example:

    This object has been updated to include the fields: labelTextContent2 and inputPlaceholder2 , which can be used to set the style for the cardHolderName input.

     

    An example of the tokenDetailsModalStyle object:

 

  1. Add a token payment button: <button id="submit-token-payment-button" onclick="handleTokenPaymentButtonClick()"> Pay Now </button>

    When clicked, the function that invokes the token payment or token preAuth is called (in step 2 above).

 

Step Three: Handle the Response

All the Judopay Web SDK transaction methods return a promise.

Once the authorisation is complete, the promise will be either fulfilled or rejected.

Fulfilled

  • You will receive a JSON object response (a Judopay receipt object).

    • For more information and schema on the JSON object, see API Transaction Response.

      This does not mean the transaction was successful.
      Check the result parameter of this response to see the result of the transaction.

  • Depending on the result the consumer should be redirected to the appropriate outcome page.

    • For example, if the result = SUCCESS redirect the consumer to the Success Page.

  • This page should display the necessary transaction information (found in the Judopay receipt object).

Rejected

  • You will receive an error object

  • The consumer should be redirected to an Error Page.

 

 

For more information on the response codes, see Codes.

 

Putting it all together to set up the Web SDK and make a token transaction:

 

Testing your Integration

Follow our Testing your Web SDK Integration test scenarios, to test your integration and generate:

  • Successful payments

  • Declined payments

  • Unexpected errors

 

Customising your Web SDK Integration

 

Form Customisation

The iFrameConfiguration object is key for customising the look and behaviour of the iFrame.

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

 

It is optional to provide the iframeConfiguration object in the createCardDetails call.
If it is not provided, the customisation properties will be set as their default values.

 

 

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 six properties:

  1. Default 

  2. Focus 

  3. Error 

  4. Valid 

  5. cv2 

  6. expiryDate 

 

Each of the above properties has two properties:

  1. Field 

  2. Label 

 

The properties for field and label:

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

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.

 

 

Form Layout

Three layout options are provided:

  • Vertical

  • Compact

  • Horizontal

 

 

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

 

 

Adding a New Language

You can:

  • Add any language you need.

  • Override some or all of the translations of an existing language.

    The Web SDK supports: en, de, fr, es, pt.

 

To add a new language:

  1. Define a dictionary of the language(s) you wish to add or override.

    This is an object of languages, along with their translation keys and values.
    Ensure the keys have no spelling errors, otherwise the translations will not work.

    • To define a new language: Supply all translation keys and values

    • To override an existing language: Supply only the translation key / pair values to override

 

For the purpose of this exercise, the following example dictionary object contains:

  • Translations for a new language: Italian

  • Translations for an existing language: English

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

Error Message strings:

  • The above example dictionary object contains error message strings which contain values {0} and {1}.

  • The {0} and {1} values will be will be swapped for strings at runtime, depending on the current state of the iFrame form.

    For example:

    • {0} will change to the card verification code acronym

      This will be named depending on the card type, for example CVC, or CVV.

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

    Ensure you include {1} or {0} in your translation strings (for appropriate keys), to enable this behaviour.
    For more information on error messages, including these dynamic values, see Displaying Payment Form Error Messages.

 

  1. Set the customLanguages property in your iFrame configuration object to the dictionary object you have defined:

 

 

Changing the Form Language

Judopay's Web SDK supports multiple languages.

The default property is English.

Language

Code

English

en

French

fr

Spanish

es

Portuguese

pt

German

de

You can also add other languages or override an existing language, see Adding a New Language.

Change Form Language at Page Load

  1. Set the language variable in your iFrame configuration object to the alpha-2 country code (above ) for the desired language

 

For the purpose of this exercise, the language is set to Spanish when the iFrame is initially loaded onto the page:

 

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).

 

  1. Call the Web SDK method for updating the language changeIframeLanguage('de')

You can call this method when an event occurs, such when a button is clicked, to dynamically changing the language.

For the purpose of this exercise, the method is called when a button is clicked, and the iFrame language is changed to German:

 

 

Configuration File Example

Below is an example configuration object that customises the payment iFrame.

It is provided as a parameter to the createCardDetails Web SDK call: judo.createCardDetails('payment-iFrame', iFrameConfiguration)

 

Displaying Payment Form Error Messages

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

To display payment form error messages:

  1. 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{1} is not supported

4

Card number required

5

Card is expired

6

Card expiry date is not valid

7

Expiry date required

8

{0} code too short for {1} card

9

{0} code too long for {1} card

10

{0} code can only contain numbers

11

{0} code required for {1} card

12Post/Zip code is invalid
13Sorry, an error has occurred, you have not been charged.
14Cardholder Name is required
15Cardholder Name can't be less than 4 characters
16Cardholder Name can't contain numbers or special characters

For error strings containing {0} and {1}, 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, Diners Club International 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"

 

Web SDK Error Responses

There are 2 possible error formats:

  1. Error responses from our Transaction API (which the Web SDK formats and returns).

    These are caused by the transaction itself, for example incorrect payment credentials | failure of 3D Secure 2.

    For more information on this type of error, see Enhanced Error Messaging for Web SDK

 

  1. Errors thrown by the Web SDK code.

    Examples of causes can be, scripts failing to load | closing of a modal | time-outs.

    For more information on this type of error, see here.

 

Enhanced Error Messaging for Web SDK

For Web SDK Version 0.0.29 (or higher), the error response object has the following additional fields describing the error:

  • name

  • status

  • judoDetails

Not all errors returned from the Web SDK will have the new format described below.
This only refers to errors that originated from our Transaction API (previous to version 0.0.29) having the following interface: {message: string}.

Error Object Response Fields

FieldDescription

message

String

A text description of the error.
name

String

Represents a name for the type of error.
status

Number

A HTTP response status code.

judoDetails

Object

Object giving additional context to the error.

For further details on the interface of the judoDetails object, including examples, see JudoDetails Object.

This field is optional.

Examples of the Enhanced error response

The enhanced error response provides an error object with additional fields to increase the description of the error, for example:

 

Cause of Error: When the amount = 0.00

Enhanced Error Response:

{ 
 message: 'Request failed with status code 400',
 name: "Error", 
 status: 400,
 judoDetails: {
    category: 2,
    code: 1,
    details: [{
        code: 4, 
        fieldName: 'Amount', 
        message: 'Sorry, but the amount specified must be greater than "0".',  
        detail: "Sorry, we're currently unable to process this request."}], 
    message: "Sorry, we're unable to process your request. Please check your details and try again."
  }
}

 

Cause of Error: When card authentication fails

Enhanced Error Response:

{ 
 message: 'Request failed with status code 400', 
 name: "Error",
 status: 400,
 judoDetails: {
    category: 4,
    code: 158,
    message: "Sorry, but your card authentication has failed."
  }
 }

 

JudoDetails Object

The judoDetails object aims to provide additional context around the error.

See below for further information on the optional judoDetails object that is now included in the error response:

JudoDetails Interface

FieldDescription

message

String

A text description of the error.

code

Number

A static numeric code associated with the specific error. 

category

Number

The type of error:

1 - RequestError

2 - ModelError

3 - ConfigError

4 - DuplicationError / ProcessingError

5 - ExceptionError

details

Object

Object giving additional context to the error.

For examples on what this object may look like, see, judoDetails Examples.

This field is optional.

For ModelError:

  • Array of FieldErrors describing one or more attributes.

For DuplicationError:

  • Provides the receiptId and url of the duplicate transaction.

Judodetails Examples

NameCategory 
RequestError1

Example:

{  
    message: "Sorry, but we were unable to authenticate your request.  Please check your details and try again.",  
    code: 403,  
    category: 1 
} 

 

{  
    message: "We've been unable to decrypt the supplied Encrypted payload.  
    Please ensure the message has not been modified.",  
    code: 150,  
    category: 1 
} 

 

ModelError 2

Response will contain one or more FieldErrors in the details block.

Example:

{  
    details: [  
    {      
        code: 50,  
        fieldName: "PostCode",  
        message: "Please supply the postcode"  
        },  
    {  
        code: 33,  
        fieldName: "Cv2",  
        message: "Sorry, the security code entered is invalid.  Please check your details and try again."  
    } 
            ], 
        message: "Sorry, we're unable to process your request.  Please check your details and try again.", 
        code: 1,  
        category: 2 
} 

 

ConfigError3

Example:

{  
    message: "Sorry, but the amount you're trying to collect is greater than the pre-auth.",  
    code: 46,  
    category: 3 
} 

 

{  
    message: "Sorry, but the amount you're trying to refund is greater than the original transaction.",  
    code: 49,  
    category: 3 
} 

 

DuplicationError 4

Example:

{  
    details: 
        { 
            receiptId: 717774858666278912,  
            url: "https://gw1.karatepay-sandbox.com/transactions/717774858666278912"   
        },  
            message: "Sorry, this payment has been stopped as it is a duplicate transaction.",  
            code: 86,  
            category: 4 
} 
ProcessingError4

Example:

{  
    message: "Sorry, but your card authentication attempt was rejected by the issuer.",  
    code: 159,  
    category: 4 
} 

 

ExceptionError5

Example:

{  
    message: "The content-type was not specified or is unsupported for the request   
    made to the Judopay API. Currently supported content-type is limited to application/json.",  
    code: 0,  
    category: 5 
} 

 

 

Apple Pay™ for Web

It is assumed you already have a Judopay account. If you do not, sign up for a sandbox account here.

 

Prerequisites

Make sure you are using Web SDK Version 0.0.18 (or higher).

Make sure you have implemented the following prerequisites:

  • From the Web SDK integration guide, you have completed the following:

    The payment form iFrame must be loaded onto the page in order for payments to work. However displaying the form to the consumer is not required for this transaction type.

    To hide the payment form iFrame, use: <div id="payment-iframe" style="position:absolute;width:0;height:0;border:0;"></div>

     

Direct from Judopay:

  • Judopay JudoID

  • A valid apple-developer-merchantid-domain-association

From the Merchant:      

  • Domain(s) being used for Apple Pay™

  • These are the domain(s) where the Apple Pay™ button will be displayed, for example the checkout page.      

These must be SSL enabled domains, Apple will not allow non-encrypted domains to be used.

  • Account(s) being used for Apple Pay™

 

Integrating Apple Pay™

Step One: Place the Apple Pay™ Button

Using Judopay's Web SDK:

  1. Within your checkout page code, add the following for placement of the Apple Pay™ Button:
    <div id="apple-pay-button-container" width="100%" align="left"></div>  

This <div> tag will be exchanged to display the Apple Pay™ Button.
(On a browser or device that can use Apple Pay™, for example an iPhone, or Safari Browser on a Mac).

 

Step Two: Update the Apple Pay™ Button

  1. Include the following script to create the Apple Pay™ Button:

This sample will call the handleApplePayButtonClick function, when the button is clicked.

Style:

  • black

  • white

Type (Optional):

  • If set to buy:

    • Buy now with Apple, will be displayed.

  • If omitted:

    • The Apple Logo will be displayed.

 

Step Three: Handle the Apple Pay™ Button Click

  1. Include the following script to handle the Apple Pay™ Payment:

Replace the items in {{brackets}} with your values.

 

See below for more details on the parameters that create the applePayConfiguration object:

 

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.

initiativeContext

String

Optional

Your fully qualified domain name associated with your Apple Pay Merchant Identity Certificate.

  • The default is: window.location.hostname

  • For example: initiativeContext ="web.judopay.com"

methodConfiguration

Object

Optional

This parameter contains the following fields:

  • version

    • number

  • supportedNetworks

    • array containing any of the following strings:

      • “amex”

      • “chinaUnionPay”

      • “discover”

      • “masterCard”

      • “visa”

      • “maestro”

      • “jcb”

  • merchantCapabilities

    • array containing any of the following strings:

      • "supports3DS"

      • "supportsCredit"

      • "supportsDebit"

      • "supportsEMV"

  • countryCode

    • string

details

Object

Optional

Provides information about the specific transaction. Use this object to supply the information for recurring payments.

For more information, see Apple Pay™ Recurring Payments

 

See here for more details on the parameter fields,

options

Object

Optional

Enables you to set options to control the behaviour of the user agent.

 

See here for more details on the parameter fields,

onShippingAddressChange

Method

Optional

Dispatched when the user changes their shipping address.

 

See here for more details on this parameter.

onShippingOptionChange

Method

Optional

Dispatched when the user changes a shipping option.

 

See here for more details on this parameter. 

delayedAuthorisation

Boolean

Optional

For preAuths only.

Set to true to authenticate a card holder with 3D secure, without performing payment authorisation.

When set to true, the 3D Secure authentication status is returned in the response.

 

The payment authorisation is carried out at the stage when you are ready to collect the amount from the customer.

  • The default value = false

initialRecurringPayment

Boolean

Optional

Indicates if this initial payment is part of a recurring payment.

For more information, see Apple Pay™ Recurring Payments

 

 

 

  1. Ensure the configuration options for:

  • amount

  • currency

  • yourConsumerReference

  • yourPaymentReference

    match those used when obtaining the valid paymentSession.

     

    This is used to cross reference the validity of the transaction.

 

Step Four: Handle the Response

Once the authorisation is complete you will receive either:

The consumer should be redirected to the outcome screen and the response / error should be handled accordingly.

For example, if the result = SUCCESS redirect the consumer to the Success Page, else ERROR.

 

For more information on the response codes, see Codes.

 

Apple Pay™ Recurring Payments

Apple Pay™ recurring payments enables you to process a standard Apple Pay™ transaction, however by setting the initialRecurringPayment flag in the initial transaction, will result in an Apple Pay™ recurring payment token (also known as a Merchant Primary Account Number, or MPAN) being generated and sent to Judopay.

 

The Apple Pay™ MPAN is stored by Judopay, and an associated Judopay card token is returned in the Apple Pay™ transaction response. This associated Judopay card token can then be used by you for future Merchant Initiated Transactions.

 

You will be responsible for initiating the recurring / MIT transactions, including those generated from an Apple Pay™ Recurring transaction type.
Call Judopay's Transaction API /transactions/payments endpoint directly, including the recurring payment card token, obtained from the initial transaction.

Card tokens generated from Apple Pay™ Recurring transactions can be utilised for both scheduled (recurring MIT) and unscheduled (ad hoc MIT) transactions.
For more information, see the Transaction API Reference documentation.

 

To trigger an initial transaction that allows you to set up an Apple Pay™ recurring payment token for future MITs.:

Define the recurring payment information

Supply the initialRecurringPayment flag in your configuration object (see, Step Three: Handle the Apple Pay™ Button Click).

Supplying the recurring payment information will:

  • Inform Apple Pay™ of future recurring payments.

  • Update the Apple Pay™ UI with the recurring payment information displayed to the consumer.

 

  1. Add the details field to your configuration object (see, Step Three: Handle the Apple Pay™ Button Click), if this is not already supplied.

    For more information on this object’s interface, see PaymentDetailsBase in the W3C Payment Request API Specification.

  1. As part of the details object, include the modifiers field.

    This is an array of objects of the type: PaymentRequestModifier (see, W3C Payment Request API Specification).

  2. Define a PaymentRequestModifier in the array.

    Here, the data field is used to define the Apple Pay™ Recurring Payment Request.

 

An example details object, used to supply recurring payment information:

Ensure you change the values to your own.

 

The above example details object includes all the mandatory fields.
For more information on optional fields, see the Apple Pay™ Documentation.

 

Domain Registration

To get your valid Apple™ domain registration:

  1. Create the following folder on your web server's root domain directory: ./well-known

  1. In the folder, create a web server identity file: apple-developer-merchantid-domain-association

  1. Add the following contents to the web server identity file:

Take care when copying and pasting the contents.

7B227073704964223A2246464441433543444430383931464146354232334143353735
3632433236384341323233373634383042303444333239354334333746354231334338
30393835222C2276657273696F6E223A312C22637265617465644F6E223A3137313532
30343131363337392C227369676E6174757265223A2233303830303630393261383634
3838366637306430313037303261303830333038303032303130313331306433303062
3036303936303836343830313635303330343032303133303830303630393261383634
3838366637306430313037303130303030613038303330383230336533333038323033
3838613030333032303130323032303831363633346338623065333035373137333030
6130363038326138363438636533643034303330323330376133313265333032633036
3033353530343033306332353431373037303663363532303431373037303663363936
3336313734363936663665323034393665373436353637373236313734363936663665
3230343334313230326432303437333333313236333032343036303335353034306230
6331643431373037303663363532303433363537323734363936363639363336313734
3639366636653230343137353734363836663732363937343739333131333330313130
3630333535303430613063306134313730373036633635323034393665363332653331
3062333030393036303335353034303631333032353535333330316531373064333233
3433303334333233393331333733343337333233373561313730643332333933303334
3332333833313337333433373332333635613330356633313235333032333036303335
3530343033306331633635363336333264373336643730326436323732366636623635
3732326437333639363736653566353534333334326435303532346634343331313433
3031323036303335353034306230633062363934663533323035333739373337343635
3664373333313133333031313036303335353034306130633061343137303730366336
3532303439366536333265333130623330303930363033353530343036313330323535
3533333035393330313330363037326138363438636533643032303130363038326138
3634386365336430333031303730333432303030346332313537376564656264366337
6232323138663638646437303930613132313864633762306264366632633238336438
3436303935643934616634613534313162383334323065643831316633343037653833
3333316631633534633366376562333232306436626164356434656666343932383938
3933653763306631336133383230323131333038323032306433303063303630333535
3164313330313031666630343032333030303330316630363033353531643233303431
3833303136383031343233663234396334346639336534656632376536633466363238
3663336661326262666432653462333034353036303832623036303130353035303730
3130313034333933303337333033353036303832623036303130353035303733303031
3836323936383734373437303361326632663666363337333730326536313730373036
6336353265363336663664326636663633373337303330333432643631373037303663
3635363136393633363133333330333233303832303131643036303335353164323030
3438323031313433303832303131303330383230313063303630393261383634383836
6637363336343035303133303831666533303831633330363038326230363031303530
3530373032303233303831623630633831623335323635366336393631366536333635
3230366636653230373436383639373332303633363537323734363936363639363336
3137343635323036323739323036313665373932303730363137323734373932303631
3733373337353664363537333230363136333633363537303734363136653633363532
3036663636323037343638363532303734363836353665323036313730373036633639
3633363136323663363532303733373436313665363436313732363432303734363537
3236643733323036313665363432303633366636653634363937343639366636653733
3230366636363230373537333635326332303633363537323734363936363639363336
3137343635323037303666366336393633373932303631366536343230363336353732
3734363936363639363336313734363936663665323037303732363136333734363936
3336353230373337343631373436353664363536653734373332653330333630363038
3262303630313035303530373032303131363261363837343734373033613266326637
3737373737326536313730373036633635326536333666366432663633363537323734
3639363636393633363137343635363137353734363836663732363937343739326633
3033343036303335353164316630343264333032623330323961303237613032353836
3233363837343734373033613266326636333732366332653631373037303663363532
6536333666366432663631373037303663363536313639363336313333326536333732
3663333031643036303335353164306530343136303431343934353764623666643537
3438313836383938393736326637653537383530376537396235383234333030653036
3033353531643066303130316666303430343033303230373830333030663036303932
6138363438383666373633363430363164303430323035303033303061303630383261
3836343863653364303430333032303334393030333034363032323130306336663032
3363623236313462623330333838386131363239383365316139336631303536663530
6661373863646239626134636132343163633134653235653032323130306265336364
3064666431363234376636343934343735333830653964343463323238613130383930
6133613164633732346238623463623838383938313862633330383230326565333038
3230323735613030333032303130323032303834393664326662663361393864613937
3330306130363038326138363438636533643034303330323330363733313162333031
3930363033353530343033306331323431373037303663363532303532366636663734
3230343334313230326432303437333333313236333032343036303335353034306230
6331643431373037303663363532303433363537323734363936363639363336313734
3639366636653230343137353734363836663732363937343739333131333330313130
3630333535303430613063306134313730373036633635323034393665363332653331
3062333030393036303335353034303631333032353535333330316531373064333133
3433303335333033363332333333343336333333303561313730643332333933303335
3330333633323333333433363333333035613330376133313265333032633036303335
3530343033306332353431373037303663363532303431373037303663363936333631
3734363936663665323034393665373436353637373236313734363936663665323034
3334313230326432303437333333313236333032343036303335353034306230633164
3431373037303663363532303433363537323734363936363639363336313734363936
6636653230343137353734363836663732363937343739333131333330313130363033
3535303430613063306134313730373036633635323034393665363332653331306233
3030393036303335353034303631333032353535333330353933303133303630373261
3836343863653364303230313036303832613836343863653364303330313037303334
3230303034663031373131383431396437363438356435316135653235383130373736
6538383061326566646537626165346465303864666334623933653133333536643536
3635623335616532326430393737363064323234653762626130386664373631376365
3838636237366262363637306265633865383239383466663534343561333831663733
3038316634333034363036303832623036303130353035303730313031303433613330
3338333033363036303832623036303130353035303733303031383632613638373437
3437303361326632663666363337333730326536313730373036633635326536333666
3664326636663633373337303330333432643631373037303663363537323666366637
3436333631363733333330316430363033353531643065303431363034313432336632
3439633434663933653465663237653663346636323836633366613262626664326534
6233303066303630333535316431333031303166663034303533303033303130316666
3330316630363033353531643233303431383330313638303134626262306465613135
3833333838396161343861393964656265626465626166646163623234616233303337
3036303335353164316630343330333032653330326361303261613032383836323636
3837343734373033613266326636333732366332653631373037303663363532653633
3666366432663631373037303663363537323666366637343633363136373333326536
3337323663333030653036303335353164306630313031666630343034303330323031
3036333031303036306132613836343838366637363336343036303230653034303230
3530303330306130363038326138363438636533643034303330323033363730303330
3634303233303361636637323833353131363939623138366662333563333536636136
3262666634313765646439306637353464613238656265663139633831356534326237
3839663839386637396235393966393864353431306438663964653963326665303233
3033323264643534343231623061333035373736633564663333383362393036376664
3137376332633231366439363466633637323639383231323666353466383761376431
6239396362396230393839323136313036393930663039393231643030303033313832
3031383833303832303138343032303130313330383138363330376133313265333032
6330363033353530343033306332353431373037303663363532303431373037303663
3639363336313734363936663665323034393665373436353637373236313734363936
6636653230343334313230326432303437333333313236333032343036303335353034
3062306331643431373037303663363532303433363537323734363936363639363336
3137343639366636653230343137353734363836663732363937343739333131333330
3131303630333535303430613063306134313730373036633635323034393665363332
6533313062333030393036303335353034303631333032353535333032303831363633
3463386230653330353731373330306230363039363038363438303136353033303430
3230316130383139333330313830363039326138363438383666373064303130393033
3331306230363039326138363438383666373064303130373031333031633036303932
6138363438383666373064303130393035333130663137306433323334333033353330
3338333233313333333533313336356133303238303630393261383634383836663730
6430313039333433313162333031393330306230363039363038363438303136353033
3034303230316131306130363038326138363438636533643034303330323330326630
3630393261383634383836663730643031303930343331323230343230646332313132
3235323239663166633162633065653934636661356438636561336565356133646332
3837396266393566643965666538323730356162346639333030613036303832613836
3438636533643034303330323034343733303435303232313030393964323962383565
3164336435663232663339353235306461653233393533373333663738353239336432
3238383538383264373338353633313366326238303232303561306132643437663762
6631633736653430623163326539326534623761663632303432666235343036633337
333230356565376633346634363037633664303030303030303030303030227D

  1. Complete a web server test:

    1. Make sure the web server identity file is accessible externally from your website.

    2. In a browser go to: https://www.yourdomain.com/.well-known/apple-developer-merchantid-domain-association

    3. Change the location to your website domain.

    4. Ensure that the apple-developer-merchantid-domain-association file is downloadable.

Apple will use this location to check the validity of your domain. It is important this is externally accessible.

  1. Notify Judopay of the following details:

    • JudoID(s)    

      List your JudoIDs you wish enabled for Apple Pay™

    • Domain(s)   

      List your domain URLs you wish enabled for Apple Pay™  

Judopay developer support will enable your account(s) with the Apple Pay™ configuration that will allow you to perform Apple Pay™ transactions from those domains.
Once complete, we will reply to your original request notifying you that this has been actioned.

 

Google Pay™ for Web

The Judopay Web SDK implements our own easy to use Google Wallet handling service which wraps Google's API requirements, making it very easy for our merchants to implement Google Pay™ for Web.
For more information on the Google Pay™ payment flow, see their Developer Guide.

It is assumed you already have a Judopay account. If you do not, sign up for a sandbox account here.

 

Prerequisites

Make sure you are using Web SDK Version 0.0.18 (or higher).

Make sure you have implemented the following prerequisites:

  • From the Web SDK integration guide, you have completed the following:

    The payment form iFrame must be loaded onto the page in order for payments to work. However displaying the form to the consumer is not required for this transaction type.

    To hide the payment form iFrame, use: <div id="payment-iframe" style="position:absolute;width:0;height:0;border:0;"></div>

     

Direct from Judopay:

  • Judopay Account (sandbox and eventually live)

  • Judopay JudoID

Merchant Requirement (Google Requirement):

Prior to going live with Google Pay™ Web Payments, you must have a valid Google verified Live Merchant ID.

To receive your Live Merchant ID:

  1. Follow Google Pay™'s Integration Checklist, to ensure you have completed all the required steps in your integration.

  2. Begin the process to obtain production access from Google, here.

 

Integrating Google Pay™

Step One: Displaying the Google Pay™ Button

 

See below for more details on the parameters that create the googlePayConfiguration object:

 

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.

paymentSession

String

Required

A unique string that references the payment session of this transaction.

The paymentSession will expire in 30 minutes, unless an expiryDate is set in the /paymentsession request body.

 

To get the reference:

  1. Use any Google Merchant ID when creating a Google Pay™ transaction request in sandbox.

Use your verified Live Merchant ID when creating a live Google Pay™ transaction request.

  1. Choose from the following transaction modes:

    • payment

    • pre_auth

  2. Use the paymentSession response reference to populate this field.

transactionMode

String

Required

Represents type of transaction.

Values:

  • payment

  • pre_auth

onSuccess

Function

Required

Set as the function you want called when the transaction is successful.

The response object will be passed as a parameter.

 

For more information on how to handle the response, see Step Two: Handle the Response.

onError

Function

Required

Set as the function you want called when there is an error.

The error object will be passed as a parameter.

 

For more information on how to handle the response, see Step Two: Handle the Response.

paymentRequest

Object

Required

Use this to configure your site's support for the Google Pay™ API. For more information on this parameter and the fields it can contain, see PaymentDataRequest.

(For example, if you Include the optional flags, such as emailRequired (default=true), this will affect whether the related information (e.g. the Google Pay email) is available in the result object, which is returned when the transaction is complete).

 

You are required to provide the following mandatory fields:

  • merchantInfo

    • To process payments, set the merchantId attribute in this object.

      • Use the merchantId provided after registering with Google Pay™.

        This is a requirement for processing a Google Pay™ payment in PRODUCTION.

  • allowedPaymentMethods[ ]

    • The only mandatory attribute to be provided: parameters.allowedCardNetworks

  • transactionInfo

 

The example paymentRequest object snippet in Step One, shows the fields that must be provided. (Judopay will provide the other required fields).

environment

String

Optional

Represents the environment type Google Pay™ will run in.

Values:

  • PRODUCTION

  • TEST

buttonStyle

Object

Optional

Change the style of the Google Pay™ Button.

 

For more details on the fields you can set, see Google Pay™ Button Style

onPaymentDataChanged

Function

Optional

Used when payment data changes in the payment form, for example:

  • shipping address

  • shipping options

 

For more information on this parameter, see onPaymentDataChanged.

onPaymentAuthorized

Function

Optional

Used when a payment is authorized in the payment form.

 

For more information on this parameter, see onPaymentAuthorized.

onReadyToPayChange

Function

Optional

Used when the consumer's isReadyToPay state changes.

Change the application's behaviour, based on whether or not the consumer is ready to pay.

 

When existingPaymentMethodRequired = true, inspect both result.isReadyToPay and result.paymentMethodPresent to determine if the consumer isReadyToPay and has a paymentMethodPresent.

 

Alternatively:

  • result.isButtonVisible can be used to determine whether or Google Pay™ button will be displayed.

  • existingPaymentMethodRequired is taken into account with result.isButtonVisible.

  • Also raised as event "readytopaychange".

 

For more information on this parameter, see button-element.

challengeRequestIndicator

String

Optional

Indicates the type of challenge request you wish to apply.

Set this to one of the following strings:

  • noPreference

  • noChallenge

    • No challenge required.

  • challengePreferred

    • A challenge is preferred for this transaction.

  • challengeAsMandate

    • Must challenge this transaction.

This should not be included in the same configuration object as scaExemption.

scaExemption

String

Optional

To apply for an exemption from SCA, for a customer initiated transaction.

Set this to one of the following strings:

  • lowValue

    • Transactions up to €45 do not require SCA, up to a maximum of five consecutive transactions, or a cumulative limit of €100.

  • secureCorporate

    • Request exemption for payments made using a corporate card.

  • trustedBeneficiary

    • Provides the cardholder the option to add the merchant to their trusted list.

  • transactionRiskAnalysis

    • Allows for certain remote transactions to be exempt from SCA, provided a robust risk analysis is performed.

This should not be included in the same configuration object as challengeRequestIndicator.

delayedAuthorisation

Boolean

Optional

For preAuths only.

Set to true to authenticate a card holder with 3D secure, without performing payment authorisation.

When set to true, the 3D Secure authentication status is returned in the response.

 

The payment authorisation is carried out at the stage when you are ready to collect the amount from the customer.

  • The default value = false

initialRecurringPayment

Boolean

Optional

Indicates if this initial payment is part of a recurring payment.

 

 

Google Pay™ Button Style

To help you implement Google Pay™ within your apps, see their Brand Guidelines*.

* The Google Pay™ button guidelines have been updated as follows:
- Buttons have rounded edges.
- The color of the button can no longer be set. (If you do set this, it will not break anything, but will no longer have any effect).
- The long and short button types have been deprecated and replaced with types buy and plain.

 

You can set the following parameters in the buttonStyle object (defined in the Google Pay Configuration Parameter Descriptions):

ParameterDescription

 

type

String

buy

  • If set to buy:

    • If the consumer is not logged into their Google Pay™ account Buy with G Pay will be displayed.

       

    • If the consumer is logged into their Google Pay™ account, the details of their selected card will be displayed.

 

 

donate

  • If set to donate, Donate with G Pay will be displayed.

plain

  • If set to plain, the G Pay logo will be displayed.

book

  • If set to book, Book with G Pay will be displayed.

checkout

  • If set to checkout, Checkout with G Pay will be displayed.

order

  • If set to order, Order with G Pay will be displayed.

pay

  • If set to pay, Pay with G Pay will be displayed.

subscribe

  • if set to subscribe, Subscribe with G Pay will be displayed.

sizeMode

String

  • Static

  • Fill

height

String

Sets the button height in pixels

width

String

Sets the button width in pixels

locale

String

Sets the localised language versions of the Buy with text

 

Step Two: Handle the Response

Once the authorisation is complete you will receive either:

The consumer should be redirected to the outcome screen and the response / error should be handled accordingly.

For example, if the result = SUCCESS redirect the consumer to the Success Page, else ERROR.

 

For more information on the response codes, see Error Codes and Descriptions.

 

Testing your Wallet Payment Integration

Wallet Payment Scenarios (via Web SDK Integration):

For more information see, Testing your Wallet Payment Integration.