Quick Start

 

Quickly integrate and perform a test payment with Judopay.

The following example takes you through the steps to quickly integrate and perform a test card payment using Judopay’s Web SDK.

The sample code uses PHP to directly call our API, however this can also be used as a guide in understanding how to call our API's by other methods.

 

Start Integrating with Judopay

To start integrating with Judopay:

Step One: Sign up for your Judopay Sandbox Account

You need your sandbox account so you can process test transactions while developing your app.

An app is a Judopay term and relates to your API credentials.

Once signed up, you will receive your:

  • TokenSecretAuth

    • The token and secret pair

    • Specify your token in Username and secret in Password

  • JudoId

Ensure Judopay has enabled 3D Secure in your sandbox account. If this is not enabled the test transaction may appear successful without following the correct payment flow.
Contact ​Customer Support​​ to set this up.

 

Step Two: Get Access to your Judopay Dashboard

Get access to your dashboard in the Judopay Portal where you can create your app.

For more details, see Creating your App

 

Perform a Test Payment

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

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

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

    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

  • address3(optional)

    string

  • town

    string

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

    • Format:

      • string

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

  • country

    • Format:

      • number

      • 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:

 

Testing and Customising your Integration

For more information, see Testing your Integration.

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