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.

Also use Judopay's Web SDK to integrate:

 

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 a paymentSession.

 

  1. Create a One Use Token

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

 

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

 

Authenticating via Web SDK

To authenticate a 3D Secure 2 transaction to allow for the provision of additional information required for compliance with SCA, Judopay has created:

 

Challenge Screen:

If the consumer is challenged for additional information (for example a code or password), the Web SDK will automatically present the 3D Secure 2 challenge screen.

 

 Authentication Using paymentSession:

It is recommended to use paymentSession to authenticate your requests, as this flow supports the full payment flow handling Customer Initiated Transactions for alternative payment methods and 3D Secure transactions.

This method of authentication ensures that any intermediate steps are handled automatically by Judopay.

 

We also recommend using paymentSession when authorising /payments or /preauths for 3D Secure 2 transactions for the same reason.

 

Store the reference returned in the response in your backend server. Then Invoke a /payment or /preauth transaction using the paymentSession reference.

To authenticate a transaction via the Web SDK, see Creating a Payment with the Web SDK.

 

3D Secure 2 (EMV 3D Secure) Authentication Flow

 

Web SDK Checkout Flow

The complete checkout flow:

 

Step

Description

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

Consumer enters card details into the iframe fields:

  • Card number

  • CV2

  • Expiry date

  • Post code Optional

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.

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

Your backend makes a second call to Judopay.

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

Judopay returns the Receipt for the operation.

 

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:

     

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

 

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

 

  1. Include a div in the iframe page with a unique ID value: <div id="payment-iframe" width="100%"></div>

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

  3. 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');

 

The second parameter is called useSandbox
Set to true to use the Sandbox environment.
Set to false to use the Production environment.

 

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.

 

Option One - Create a paymentSession

Call the Judopay API to create a paymentSession.

 

When authorising /payments or /preauths for 3D Secure 2 transactions, it is recommended to use paymentSession.
Check your API token has 3D Secure 2 enabled.

 

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.

 

For more information, see Transaction API /paymentSession

 

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.

 

To create a paymentSession:

Prerequisite

You are using Judopay's API version 6.0.0.0 or higher.

 

  1. Call the Judopay Transaction API to create a paymentSession.

    Target endpoint: /paymentSession

    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

 

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": "2022-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.25/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></scrip

  1. In your <BODY> add a <DIV> tag where you want the iframe to appear: div id="payment-iframe" width="100%"></div>

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

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>

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

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

  3. You can apply any CSS styling you wish to this button. button id="submit-payment-button" name="submit-payment" disabled> Pay Now </button>

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

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 (8(a)) above.

 

Complete customisation of the iframe settings and styles can be found here: Customising your Web SDK Integration.

 

Step Three: Making a Transaction

When the Web SDK Pay Button is clicked, the invokePayment, or invokePreauth method will be called from the Web SDK.

 

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

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

 

To make a transaction:

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

 

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

{
    "judoId": "100915867", 
    "amount": 5.10,
    "currency": "GBP",
    "phoneCountryCode": "44",
    "challengeRequestIndicator": "ChallengePreferred",
    "scaExemption": "SecureCorporate",
    "initialRecurringPayment": "false",
    "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", 
    "primaryAccountDetails": { 
          "Name": "Smith",
          "AccountNumber": "9999999",
          "DateOfBirth": "1989-09-19",
          "PostCode": "NW1 1UE"
  },
}

 

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

phoneCountryCode

String

Required

The country code of the consumer's phone.

challengeRequestIndicator

String

Optional

Indicates the type of challenge request you wish to apply.

Values:

  • NoPreference

  • NoChallenge

    • No challenge required.

  • ChallengePreferred

    • A challenge is preferred for this transaction.

  • ChallengeAsMandate

    • Must challenge this transaction.

scaExemption

String

Optional

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

Values:

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

initialRecurringPayment

Boolean

Optional

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

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.

primaryAccountDetails

Object

Optional

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

Primary Account Holder Details:

  • Name

This is the surname.

  • AccountNumber

  • DateOfBirth

    • Format: YYYY-MM-DD

  • PostCode

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

 

 

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

 

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

 

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

 

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 Transaction 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

Using your Judopay API client instance:

  1. 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;  
}
  1. Save the card token for the next transaction

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

 

Configuration File Example

Below is an example configuration file which sets the:

  • Layout

  • Background colour

  • Input and label styles

  • defaultCountryCode

     

For example, US = default country code, and modifies the error and UI strings for the default language: English.
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:

  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

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, 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"

 

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 have implemented the following prerequisites:

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™

Web SDK Version:

  • Web SDK Version 0.0.18 (or higher).

 

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.

Copy
7B227073704964223A22464644414335434444303839314641463542323341433537
35363243323638434132323337363438304230344433323935433433374635423133
433830393835222C2276657273696F6E223A312C22637265617465644F6E223A3135
38323234343132383531332C227369676E6174757265223A22333038303036303932
61383634383836663730643031303730326130383033303830303230313031333130
66333030643036303936303836343830313635303330343032303130353030333038
30303630393261383634383836663730643031303730313030303061303830333038
32303365333330383230333838613030333032303130323032303834633330343134
39353139643534333633303061303630383261383634386365336430343033303233
30376133313265333032633036303335353034303330633235343137303730366336
35323034313730373036633639363336313734363936663665323034393665373436
35363737323631373436393666366532303433343132303264323034373333333132
36333032343036303335353034306230633164343137303730366336353230343336
35373237343639363636393633363137343639366636653230343137353734363836
66373236393734373933313133333031313036303335353034306130633061343137
30373036633635323034393665363332653331306233303039303630333535303430
36313330323535353333303165313730643331333933303335333133383330333133
33333233353337356131373064333233343330333533313336333033313333333233
35333735613330356633313235333032333036303335353034303330633163363536
33363332643733366437303264363237323666366236353732326437333639363736
65356635353433333432643530353234663434333131343330313230363033353530
34306230633062363934663533323035333739373337343635366437333331313333
30313130363033353530343061306330613431373037303663363532303439366536
33326533313062333030393036303335353034303631333032353535333330353933
30313330363037326138363438636533643032303130363038326138363438636533
64303330313037303334323030303463323135373765646562643663376232323138
66363864643730393061313231386463376230626436663263323833643834363039
35643934616634613534313162383334323065643831316633343037653833333331
66316335346333663765623332323064366261643564346566663439323839383933
65376330663133613338323032313133303832303230643330306330363033353531
64313330313031666630343032333030303330316630363033353531643233303431
38333031363830313432336632343963343466393365346566323765366334663632
38366333666132626266643265346233303435303630383262303630313035303530
37303130313034333933303337333033353036303832623036303130353035303733
30303138363239363837343734373033613266326636663633373337303265363137
30373036633635326536333666366432663666363337333730333033343264363137
30373036633635363136393633363133333330333233303832303131643036303335
35316432303034383230313134333038323031313033303832303130633036303932
61383634383836663736333634303530313330383166653330383163333036303832
62303630313035303530373032303233303831623630633831623335323635366336
39363136653633363532303666366532303734363836393733323036333635373237
34363936363639363336313734363532303632373932303631366537393230373036
31373237343739323036313733373337353664363537333230363136333633363537
30373436313665363336353230366636363230373436383635323037343638363536
65323036313730373036633639363336313632366336353230373337343631366536
34363137323634323037343635373236643733323036313665363432303633366636
65363436393734363936663665373332303666363632303735373336353263323036
33363537323734363936363639363336313734363532303730366636633639363337
39323036313665363432303633363537323734363936363639363336313734363936
66366532303730373236313633373436393633363532303733373436313734363536
64363536653734373332653330333630363038326230363031303530353037303230
31313632613638373437343730336132663266373737373737326536313730373036
63363532653633366636643266363336353732373436393636363936333631373436
35363137353734363836663732363937343739326633303334303630333535316431
66303432643330326233303239613032376130323538363233363837343734373033
61326632663633373236633265363137303730366336353265363336663664326636
31373037303663363536313639363336313333326536333732366333303164303630
33353531643065303431363034313439343537646236666435373438313836383938
39373632663765353738353037653739623538323433303065303630333535316430
66303130316666303430343033303230373830333030663036303932613836343838
36663736333634303631643034303230353030333030613036303832613836343863
65336430343033303230333439303033303436303232313030626530393537316665
37316531653733356235356535616661636234633732666562343435663330313835
32323263373235313030326236316562643666353530323231303064313862333530
61356464366464366562313734363033356231316562326365383763666133653661
66366362643833383038393064633832636464616136333330383230326565333038
32303237356130303330323031303230323038343936643266626633613938646139
37333030613036303832613836343863653364303430333032333036373331316233
30313930363033353530343033306331323431373037303663363532303532366636
66373432303433343132303264323034373333333132363330323430363033353530
34306230633164343137303730366336353230343336353732373436393636363936
33363137343639366636653230343137353734363836663732363937343739333131
33333031313036303335353034306130633061343137303730366336353230343936
65363332653331306233303039303630333535303430363133303235353533333031
65313730643331333433303335333033363332333333343336333333303561313730
64333233393330333533303336333233333334333633333330356133303761333132
65333032633036303335353034303330633235343137303730366336353230343137
30373036633639363336313734363936663665323034393665373436353637373236
31373436393666366532303433343132303264323034373333333132363330323430
36303335353034306230633164343137303730366336353230343336353732373436
39363636393633363137343639366636653230343137353734363836663732363937
34373933313133333031313036303335353034306130633061343137303730366336
35323034393665363332653331306233303039303630333535303430363133303235
35353333303539333031333036303732613836343863653364303230313036303832
61383634386365336430333031303730333432303030346630313731313834313964
37363438356435316135653235383130373736653838306132656664653762616534
64653038646663346239336531333335366435363635623335616532326430393737
36306432323465376262613038666437363137636538386362373662623636373062
65633865383239383466663534343561333831663733303831663433303436303630
38326230363031303530353037303130313034336133303338333033363036303832
62303630313035303530373330303138363261363837343734373033613266326636
66363337333730326536313730373036633635326536333666366432663666363337
33373033303334326436313730373036633635373236663666373436333631363733
33333031643036303335353164306530343136303431343233663234396334346639
33653465663237653663346636323836633366613262626664326534623330306630
36303335353164313330313031666630343035333030333031303166663330316630
36303335353164323330343138333031363830313462626230646561313538333338
38396161343861393964656265626465626166646163623234616233303337303630
33353531643166303433303330326533303263613032616130323838363236363837
34373437303361326632663633373236633265363137303730366336353265363336
66366432663631373037303663363537323666366637343633363136373333326536
33373236633330306530363033353531643066303130316666303430343033303230
31303633303130303630613261383634383836663736333634303630323065303430
32303530303330306130363038326138363438636533643034303330323033363730
30333036343032333033616366373238333531313639396231383666623335633335
36636136326266663431376564643930663735346461323865626566313963383135
65343262373839663839386637396235393966393864353431306438663964653963
32666530323330333232646435343432316230613330353737366335646633333833
62393036376664313737633263323136643936346663363732363938323132366635
34663837613764316239396362396230393839323136313036393930663039393231
64303030303331383230313863333038323031383830323031303133303831383633
30376133313265333032633036303335353034303330633235343137303730366336
35323034313730373036633639363336313734363936663665323034393665373436
35363737323631373436393666366532303433343132303264323034373333333132
36333032343036303335353034306230633164343137303730366336353230343336
35373237343639363636393633363137343639366636653230343137353734363836
66373236393734373933313133333031313036303335353034306130633061343137
30373036633635323034393665363332653331306233303039303630333535303430
36313330323535353330323038346333303431343935313964353433363330306430
36303936303836343830313635303330343032303130353030613038313935333031
38303630393261383634383836663730643031303930333331306230363039326138
36343838366637306430313037303133303163303630393261383634383836663730
64303130393035333130663137306433323330333033323332333133303330333133
35333233383561333032613036303932613836343838366637306430313039333433
31316433303162333030643036303936303836343830313635303330343032303130
35303061313061303630383261383634386365336430343033303233303266303630
39326138363438383666373064303130393034333132323034323061643565343661
35653561663738663864643935616635393038616136336666636663343139316666
31353163653866616265323933396333353835643761363330306130363038326138
36343863653364303430333032303434373330343530323230303737346461363466
66373232363664646264303333613835643934313561353937396564303731366337
35666534353232306565353437313830303065613130323231303064666163663134
34326362353863323834666439666662313264396163643730326636313865613931
38343833343630323663613765636166633836343066313030303030303030303030
30227D
  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.

Once this has been confirmed you can move onto the integration steps to continue: Step 1: Obtain a Payment Session.

 

Integration

Step 1: Obtain a Payment Session

To use Apple Pay™ with Judopay's Web SDK to create a payment or preauth, you must first obtain a valid paymentSession. This is used to complete the Apple Pay™ Transaction.  

Judopay's Web SDK now supports paymentSession for Card and alternative payment methods, in order to ensure the security and authenticity of the transaction being requested.

It is recommended to use paymentSession to authenticate your requests, as this flow supports the full payment flow handling Customer Initiated Transactions for alternative payment methods and 3D Secure transactions.

This method of authentication ensures that any intermediate steps are handled automatically by Judopay.

 

We also recommend using paymentSession when authorising /payments or /preauths for 3D Secure 2 transactions for the same reason.

 

Prerequisite

You are using Judopay's API version 6.0.0.0 or higher.

 

  1. Call the Judopay Transaction API to create a paymentSession.

    Target endpoint: /paymentSession

    HTTP Method: POST

{  
"JudoId": "yourJudoID",  "amount": 1.01,  
"yourConsumerReference": "yourConsumerReference",  
"yourPaymentReference": "yourUniquePaymentReference",  
"Currency":"GBP"
}

These are live endpoints as Apple Pay™ only works on live transactions. You can create the Apple Pay™ Button on Sandbox, but you will not be able to complete an Apple Pay™ Transaction on Sandbox accounts.
(Apple Wallet holds live credit card data, and it is this that is used to perform the transaction payment).

  1. You should receive the following response:


  "payByLinkUrl": "https://pay.judopay.com/jbv6Er",    
    "postUrl": "https://pay.judopay.com/v1",    
    "reference": "5QcAAAMA11222AAAADwAAAP35xxiieAjIBRllQdLR8fHhvKKEG9Z2lXevB8vpJlhvTozfNw"
}

 

Your reference and payByLinkUrl will differ, as they are unique to each transaction.

 

  1. The reference field is the field you must reference in your Apple Pay™ transaction, within the Web SDK.

 

For more information, see Transaction API /paymentSession

 

Sample PHP: Get Web Payment Reference

Replace any field {{field}} with your own required values.

This is a sample direct API call, using PHP:
<?php

header('Content-Type: application/json');

$userEncode = base64_encode("{{yourAPIToken}}".":"."{{yourAPISecret}}");

$data = array(        
    'judoId' => "{{yourJudoID}}",        
    'amount' => "{{amount}}",        
    'currency' => "{{currency}}",        
    'yourConsumerReference' => "{{yourConsumerReference}}",        
    'yourPaymentReference' => "{{yourUniquePaymentReference}}");

$dataJson = json_encode($data);
$headers = array
    'Content-Type:application/json',  
    'Authorization: Basic '.$userEncode,  
    'API-Version: 6.2'
);

$environment = "https://api.judopay.com/webpayments/payments";
$response = "";
$ch = 
curl_init($environment);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_FRESH_CONNECT, TRUE);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS,$dataJson);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
echo $response;
?>

 

Step 2: Use Judopay's Web SDK

  1. To use Judopay's Web SDK, include the following script In your checkout page: <script src="https://web.judopay.com/js/0.0.25/judopay.min.js"></script>

 

Step 3: 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 4: Update the Apple Pay™ Button

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

var button = judo.digitalWallets.getApplePayButton({
height: 38
width: 240
language: 'EN'
style: 'black'
type: 'buy'});

button.onclick = handleApplePayButtonClick

document.getElementById('apple-pay-button-container').appendChild(button)

</script>   

 

This code sets up the Apple Pay™ Button in Step 2: Use Judopay's Web SDK (if a valid browser is detected and Apple has authorised the domain).
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 5: Handle the Apple Pay™ Button Click

When the Apple Pay™ button is clicked, the invokePaymentWithApplePay, or invokePreAuthWithApplePay method can be called.

 

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

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

<script>
function handleApplePayButtonClick() {

let configuration = {  
amount: '{{amount}}',  
currency: '{{currency}}',  
yourConsumerReference: '{{yourConsumerReference}}',  
yourPaymentReference: '{{yourPaymentReference}}’,  
judoId: '{{judoId}}', //initiativeContext: 'web.judopay.com' // optional, default = window.location.hostname}

judo.digitalWallets
.invokePaymentWithApplePay({{paymentSession}}, configuration)
.then(response => console.log(JSON.stringify(response)))
.catch(error => console.error(error))


</script>
  1. Ensure the configuration options for:

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

  1. The reference value for paymentSession, is obtained from Step 1: Obtain a Payment Session .

 

For the purpose of this exercise, the reference obtained in Step 1 was: 5QcAAAMA11222AAAADwAAAP35xxiieAjIBRllQdLR8fHhvKKEG9Z2lXevB8vpJlhvTozfNw  

Therefore, the call would be:

judo.digitalWallets
.invokePaymentWithApplePay(’5QcAAAMA11222AAAADwAAAP35xxiieAjIBRllQdLR8fHhvKKEG9Z2lXevB8vpJlhvTozfNw’, configuration)
.then(response => console.log(JSON.stringify(response)))
.catch(error => console.error(error))

 

Step 6: Handle the Result

Handle the result within the handleApplePayButtonClick method.

You will either be given:

  • A response JSON object

    (a Judopay receipt object)

  • An error object  

In this sample, the response or error is logged to the console. You must handle this JSON object accordingly from here.

 

Google Pay™ for Web

For merchants wishing to perform Google Pay™ Web payments through Judopay, follow our documentation on how to:

  • Achieve a Google Pay™ Web session from your own webserver

  • Validate the merchant identity through Google

  • Send the payment request to Judopay for processing upstream

 

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

The Judopay Web SDK implements our own easy to use Google Wallet handling service which wraps Google's API requirements.

This makes it very easy for our merchants to implement Google Pay™ Web.

 

Following the new Strong Customer Authentication (SCA) requirements, see the SCA Resource Guide for more information on updating your Google Pay™ implementation in relation to SCA transactions.

  • For more information on Google Pay™'s payment flow, see their Developer Guide.

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

  • Use Google Pay™'s Integration Checklist to ensure you have completed all the required steps in your Android integration.

  • Merchants wishing to go-live with Google Pay™ Web, will need to have a valid Google verified merchant ID.

    • In order to obtain a verified account from Google, and a live Google merchant ID which you will use in the Judopay Web SDK, follow Google's guidelines here.

The documentation and examples here are for testing in Google's sandbox account.

 

Prerequisites

Make sure you have implemented the following prerequisites:

 

Direct from Google:

  • Active Live Merchant ID (before going live)

This is not required for sandbox tests.

 

Direct from Judopay:

  • Judopay Account (Sandbox and eventually live)

  • Judopay APIToken

  • Judopay APISecret

  • Judopay JudoID

 

Back-end Code Base

  • These examples use Judopay's PHP-SDK: Version 4.4.0

  • Your server must be capable of running PHP

 

Merchant Requirement (Google Requirements)

  • Prior to going live with Google Pay™ Web Payments, you must have a valid live merchant ID as provided by Google.

    • Follow Google's guidelines here for details on getting your merchant ID.

 

Step 1: Setting up the Web SDK

The documentation and examples provided, are based on version 0.0.25 of the Web SDK.

To integrate with Judopay's Web SDK:

  1. Include the Judopay Web SDK script: <script src="https://web.judopay.com/js/0.0.25/judopay.min.js"></script>  

  2. Initialise the Judopay Web SDK (for sandbox): let judo = new JudoPay("yourSandBoxAPIToken", true);

For production: let judo = new JudoPay("yourProductionAPIToken", false);

  1. To use the Judopay Web SDK:

    • Set the value to true to use the sandbox environment.

    • Set the value to false to use the production environment.

 

Step 2: Setting the JudopayConfiguration

The digitalWalletsService property is used to handle digital wallets.

  1. Use the setJudoPayConfiguration method provided by the digitalWalletsService property:

judo.digitalWalletsService.setJudoPayConfiguration({    
    judoId: 'yourJudoId',    
    displayName: 'displayName',    
    domainName: 'sourceDomainName',    
    countryCode: 'GB'
})

 

Parameter

Description

judoId

String

Your unique JudoID

displayName

String

A name you wish to be displayed when the Google wallet is called.

This will appear in the wallet as:

domainName

String

Your source website URL, where the payment is coming from.

For example: www.mysite.com

 

Do not include http:// or https://

countryCode

Integer

A valid ISO 3166-1 country code (Alpha 2).

 

Step 3: Setting up the Google Pay™ Configuration


judo.digitalWalletsService.setGooglePayConfiguration({    
    environment: 'TEST',    
    merchantIdentifier: "merchantID",    
    merchantCapabilities: ['PAN_ONLY'],    
    supportedNetworks: ['VISA', 'MASTERCARD', 'AMEX'],    
    type: 'long',    
    style: 'black'
})

 

Parameter

Description

environment

String

Google's Environment.

The case is important, ensure you use UPPERCASE.

  • TEST = Google Sandbox

  • PRODUCTION   = Google Pay Live

You will need a live Google Merchant Identifier (merchantID) from Google before you can test live. Get it here.

merchantIdentifier

String

A unique Google Merchant Identifier.

This is not important for sandbox testing. However prior to going live, you will require a live Google Merchant Identifier.

Get it here.

merchantCapabilities

String

For Google Pay™ Web: currently PAN_ONLY is supported.

supportedNetworks

String

List the Card Networks you plan to support.

Any Card Networks not listed here, the cards of those networks, will not be presented for selection in the Google Wallet.

For example, if you do not plan on supporting American Express, use the following as your supportedNetworks:

  • 'VISA',

  • 'MASTERCARD'

See Google Pay™ Supported Networks for all supported Card Networks.

type

String

The type of Google Pay™ Button to display:

The case is important, ensure you use lowercase.

  • Displays the short version of the Google Pay™ Button.

  • Without the 'Buy with' text:

  • long: Displays the long version of the Google Pay™ Button

  • With the 'Buy with' text:

style

String

The style of the Google Pay™ Button to display:

The case is important, ensure you use lowercase.

  • black: Displays the button type with a black background.

  • white: Displays the button type with a white background.

For example: type = short, style = white

 

For example: type = long, style = white

 

Step 4: Setting up the Wallet Response Handler

The response handler will be called after the consumer selects the card from the Google Pay™ Wallet, and clicks the Pay Button.

  1. Set up the response handler:

judo.digitalWalletsService.responseHandler = (response, error) => { 
    if (response) { // process the response } 
    else { // handle the error } 
}

Once you receive the response from the Google Pay™ Wallet:

  1. Submit the googlePayWallet object to a back-end server application for processing

  2. In the exampe below, it will call the server PHP page: judoGooglePay.php with the digital wallet detail

  3. This sample logs the result from the PHP page to the web console for debugging.

    You should perform further action depending on the payment success or failure. 

 

This sample HTML code uses Jquery to post the wallet, although you can amend this to suit your own requirements.

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

judo.digitalWalletsService.responseHandler = (response, error) => {  
    if (response) {    
    console.log(response);    
    let googlePayWallet = {      
        cardDetails: response.paymentDetails.info.cardDetails,      
        cardNetwork: response.paymentDetails.info.cardNetwork,      
        token: response.paymentDetails.tokenizationData.token,    
};    
console.log(googlePayWallet);    
$.post("judoGooglePay.php", { googlePayWallet: googlePayWallet }, function (     
    data   
) {      
    console.table(data);      
    try {        
    let result = JSON.parse(data);       
    if (result != undefined && result.result == "Success") {          
    alert("Payment Success : " + result.receiptId);          
console.log("Payment Success, your receiptId = " + result.receiptId);        
    } else {          
    alert("Payment Failure : " + result.receiptId);          
    console.log("Payment Failure, something went wrong please try again");       
    }     
}     catch {        
    alert("Major Failure...");       
    console.log("Payment Failure, something went wrong please try again");      
    }   
});  
} else {    
    console.log(error); // handle the error 
    }
};

 

Step 5: Setting up a Purchased Item

Now you have a responder (from Step 4), before calling the judo.digitalWalletsService.setPaymentDetails:

  1. Load your wallet with the items to charge to the consumer.

Copy
Sample code to load a purchased Item into the digital wallet:
const purchasedItemOne = {    
    "label": "Smart Watch",    
    "description": "Watch with integrated GPS tracking and water resistance",   
    "amount": {       
        "value": "1.01",        
        "currency": "GBP"    
    },    
    "pending": false
}

For the purpose of this exercise, the sample code set up the following:

  • One item called: Smart Watch

  • Description of: Watch | Integrated GPS tracking | Water resistance

  • Amount for the item: £1.01 (GBP) 

 This is an ISO 3-digit currency code.

  • Pending: false

If you wish to add multiple items:

  1. Create another object:

const purchasedItemTwo = {    
    "label": "Laptop Stand",    
    "description": "Aluminium stand with heat absorption",    
    "amount": {        
        "value": "10.50",       
        "currency": "GBP"    
        },    
    "pending": false
}

 

By default, Google Pay™ does not handle arithmetic, so the total price would need to be manually calculated and updated every time the consumer changes any payment details.
For example, selecting a different shipping method.

The JudoPaymentItem calculates the total price and updates the price with every payment detail change.

 

  1. Once you have the items created above, set the setPaymentDetails object to these values:

Example : Set payment details for one item:
    
    judo.digitalWalletsService.setPaymentDetails([purchasedItemOne])
or 
    
    Example : Set payment details for multiple items (in this case two):

judo.digitalWalletsService.setPaymentDetails([purchasedItemOne,purchasedItemTwo])

 

Step 6: Setting up Additional Payment Options

You can set up additional options to be provided to the digitalWalletsService.

This can be achieved either by requiring further information from the Google Wallet, or requiring the consumer to add further information before payment.

Copy
An example of the additional options available:
const paymentOptions = {            
    "requestPayerEmail": false,            
    "requestPayerName": false,            
    "requestPayerPhone": false,            
    "requestShipping": false,            
    "shippingType": undefined        
};

 

Parameter

Description

requestPayerEmail

Boolean

false

Do not obtain the consumer's email

true

Obtain the consumer's email

requestPayerName

Boolean

false

Do not obtain the consumer's name

true

Obtain the consumer's name

requestPayerPhone

Boolean

false

Do not obtain the consumer's phone number

true

Obtain the consumer's phone number

requestShipping

Boolean

false

Do not obtain the consumer's shipping information

true

Obtain the consumer's shipping information

shippingType

Boolean

undefined

Do not change this value.

Once you have set your payment options, set them in the digital wallet:: judo.digitalWalletsService.setPaymentOptions(paymentOptions);

 

Step 7: Setting Up Optional Shipping Options

As an optional step, you can set up the following shipping option(s).

The examples below sets up two types of shipping options:

The first option:

freeShipping is the default shipping method (selected: true):

const freeShipping = { "id": "free-shipping",
    "label": "Free Shipping", "description": "This option can take up to two weeks to deliver"
    "amount": { 
        "value": "0.0"
        "currency": "GBP" 
        }, 
    "selected": true
}

 

The second option:

expressShipping is an optional choice for the consumer (selected: false): 

const expressShipping ={ "id": "express-shipping"
    "label": "Express Shipping", "description": "This option will take up to three days to deliver"
    "amount": { 
        "value": "15.0"
        "currency": "GBP" 
        }, 
    "selected": false 
}
  1. Once you have set up your shipping options, ensure your paymentOptions has the "requestShipping": true

For example:
const paymentOptions = {
    "requestPayerEmail": true,
    "requestPayerName": true,
    "requestPayerPhone": false,
    "requestShipping": true,
    "shippingType": undefined
    };

judo.digitalWalletsService.setPaymentOptions(paymentOptions);
  1. Call the digitalWalletsService.setShippingOptions to set up those shipping options: judo.digitalWalletsService.setShippingOptions([freeShipping, expressShipping])

    The following options will be displayed when calling the wallet:

     

 

Step 8: Displaying the Google Pay™ Button

To display the Google Pay™ Button:

  1. Ensure you have a div tag defined where you require the button to appear.

    For the purpose of this exercise, the div tag is called digital-wallets-buttons-container:

<div align="center">
<div style={{display: 'flex', justifyContent: 'center'}}>
<div style={{width: '250px'}} id='digital-wallets-buttons-container'/>
</div>
  1. Display the Google Pay™ Button in the digital-wallets-buttons-container element:

judo.digitalWalletsService.getGooglePayButton('60px').then((googlePayButton) => {    
    const myElement = document.getElementById('digital-wallets-buttons-container')    
    myElement.appendChild(googlePayButton)
})
  1. Adjust the height of the button by changing the (‘60px’), to a relevant height you require.

    For example, ‘128px’ will create a Google Pay™ button that is 128px high.

Sample UI Code:
<!---
Judo Sample Google Pay Web
(c) Judo August 2020
This code is provided free of charge with no warantees or liabilities.
It is correct at time of publication
For assistance please contact developersupport@judopay.com
-->

<!DOCTYPE html>
<head>
<script src="https://web.judopay.com/js/0.0.10/judopay.min.js">
</script>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js">
</script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
</head>
<html>
<body>
<div align="center">
<font face="Arial" size=24>Web SDK GooglePay</font>
</div><BR>
<div align="center">
</div><BR>
<div align="center">
<div style={{display: 'flex', justifyContent: 'center'}}>
<div style={{width: '250px'}} id='digital-wallets-buttons-container'/>
</div><BR>
<script>

// Setup the Judo WebSDK – Use your own APIToken Here
let judo = new JudoPay("yourAPIToken", true);

// Setup the Digital Wallet Configuration
judo.digitalWalletsService.setJudoPayConfiguration({
    // Replace this judoID with your JudoID
    judoId: 'yourJudoID',
    // Replace the name you wish to be displayed on the wallet
    displayName: 'Merchant Name To Display',
    // Replace The root URL of your website
    domainName: "www.ookjar.com",
    // Country Code Set to GB in sample
    countryCode: 'GB'
})

// Setup the Google Specific Configuration

judo.digitalWalletsService.setGooglePayConfiguration({
    // Setup to use Google Test Sandbox Environment
    environment: 'TEST',
    // Setup your merchantID from Google (can be anything on Sandbox, but will need to be valid when going live)
    merchantIdentifier: "merchantID",
    // Leave this setting to PAN_ONLY
    merchantCapabilities: ['PAN_ONLY'],
    // List of supported Card Types, in this sample, VISA, MasterCard and American Express are supported
    supportedNetworks: ['VISA', 'MASTERCARD', 'AMEX'],
    // Google Button Short (no text)
    type: 'short',
    // Google Button Colour (black in this sample)
    style: 'black'
})

// Setup a response handler return to from the wallet selection
judo.digitalWalletsService.responseHandler = (response, error) => {
    if (response) {
        console.log(response)
        let googlePayWallet = {
        cardDetails: response.paymentDetails.info.cardDetails,
        cardNetwork: response.paymentDetails.info.cardNetwork,
        token: response.paymentDetails.tokenizationData.token
        };
        // debug log to console the wallet encrypted detail
        console.log(googlePayWallet);

// Setup a JQuery Post to judoGooglePay.php to process the transaction
  $.post(
              "judoGooglePay.php",
              // Send through the googleWallet Details
              {googlePayWallet: googlePayWallet},
              function(data) {
                console.table(data);
                // Parse the response from judoGooglePay.php
                try {
                    let result = JSON.parse(data);
                    if (result != undefined && result.result == "Success") {
                      alert("Payment Success : "+result.receiptId);
                              console.log("Payment Success, your receiptId = " + result.receiptId);
                          } else {
                      alert("Payment Failure : "+result.receiptId);
                              console.log("Payment Failure, something went wrong please try again");
                          }
                } catch {
                // If unable to parse a major failure is logged  
                  alert("Major Failure...");
                    console.log("Payment Failure, something went wrong please try again");
                }
              }
);
    } else {
      // Log any Error
        console.log(error)// handle the error
    }
}

// Setup the Google Wallet Payment Options
const paymentOptions = {
 // Do not require email 
  "requestPayerEmail": false,
 // Do not require Name
  "requestPayerName": false,
  // Do not require Phone
  "requestPayerPhone": false,
  // Require Shipping Options
  "requestShipping": true,
  // Leave undefined
  "shippingType": undefined
};

// Set Payment Options with the paymenOptions above
judo.digitalWalletsService.setPaymentOptions(paymentOptions);

// Setup one Item being Purchased
const purchasedItemOne = {
    // Set up it's label
    "label": "Smart Watch",
    // Setup it's description
    "description": "Watch with integrated GPS tracking and water resistence",
    "amount": {
      // Set it's amount
        "value": "1.01",
        // Set the currency - sample app uses GBP
        "currency": "GBP"
    },
    // Leave pending - false
    "pending": false
}

// Call the setPaymentDetails with the above item purchase
judo.digitalWalletsService.setPaymentDetails([purchasedItemOne])


// Setup Shipping Option for Free Shipping
const freeShipping = { 
  // Set up unique ID
  "id": "free-shipping"
  // Set Shipping ID Label
  "label": "Free Shipping"
  // Set Shipping Description
  "description": "This option can take up to two weeks to deliver"
  "amount": { 
    // Set Amount - this is free
    "value": "0.0"
    // Set Currency to GBP
    "currency": "GBP" 
  }, 
  // Default to true (default option selected)
  "selected": true 
}

// Setup Second Shipping Option (Express)
const expressShipping = { 
  // Setup unique ID
  "id": "express-shipping",
  // Setup Shipping ID Label 
  "label": "Express Shipping"
  // Setup Shipping Description
  "description": "This option will take up to three days to deliver"
  "amount": { 
    // Setup the amount for shipping - £15.00 in this case
    "value": "15.0"
    // Setup Currency to GBP
    "currency": "GBP" 
  }, 
  // Selected not set, so this will be an option but not default
  "selected": false 
}

// Setup the Wallet shipping from the above two options
judo.digitalWalletsService.setShippingOptions([freeShipping, expressShipping])


// Call to display the GooglePay Button
judo.digitalWalletsService.getGooglePayButton('60px').then((googlePayButton) => {
    const myElement = document.getElementById('digital-wallets-buttons-container')
    myElement.appendChild(googlePayButton)
})
</script>
</body>
</html>

 

Customise your Configuration

To customise your own configuration, make the following changes:

  1. Replace yourAPIToken - with your Judo supplied APIToken:

// Setup the Judo WebSDK – Use your own APIToken Here
let judo = new JudoPay("yourAPIToken", true);
  1. Replace yourJudoID - with your Judo supplied JudoID

  2. Replace Merchant Name To Display - with the name you wish to appear in the wallet

  3. Replace merchantDomain - with your website URL

Do not include http:// or https://

Copy
// Setup the Digital Wallet Configuration
judo.digitalWalletsService.setJudoPayConfiguration({
    // Replace this judoID with your JudoID
    judoId: 'yourJudoID',
    // Replace the name you wish to be displayed on the wallet
    displayName: 'Merchant Name To Display',
    // Replace The root URL of your website
    domainName: "merchantDomain URL",
    // Country Code Set to GB in sample
    countryCode: 'GB'
})
  1. Replace TEST - with PRODUCTION when you are ready to go live

  2. Replace merchantID - with your Google supplied merchant ID

Copy
// Setup the Google Specific Configuration

judo.digitalWalletsService.setGooglePayConfiguration({
    // Setup to use Google Test Sandbox Environment
    environment: 'TEST',
    // Setup your merchantID from Google (can be anything on Sandbox, but will need to be valid when going live)
    merchantIdentifier: "merchantID",
    // Leave this setting to PAN_ONLY
    merchantCapabilities: ['PAN_ONLY'],
    // List of supported Card Types, in this sample, VISA, MasterCard and American Express are supported
    supportedNetworks: ['VISA', 'MASTERCARD', 'AMEX'],
    // Google Button Short (no text)
    type: 'short',
    // Google Button Colour (black in this sample)
    style: 'black'
}

 

Sample Server Code: Installing PHP-SDK

Prerequisite

Before you start, ensure you have installed version  4.4.0 of Judopay's PHP SDK.

 

  1. Create a composer.json file in your document root directory with the following content:

{
  "require": {
    "judopay/judopay-sdk": "4.4.0"
  }
}
  1. Install this version of the Judopay PHP SDK by running: $ composer install

    This should install Judopay's PHP SDK version 4.4.0 in the vendor subdirectory.

    This will be used in the judoGooglePay.php sample code.

 

Sample Server Code: Processing a Google Payment

This is a simplified sample and should not be used for production, as additional error checks should be put into place.

 

To process a Google Payment:

  1. Create a file in your document root called judoGooglePay.php

  2. Copy the code (this is the server code handling of the Google Wallet through Judopay):

This file should be in your root location of your webserver, with the PHP-SDK toolkit in the vendor directory beneath. 

judoGooglePay.php. This is a ‘happy path’ example, with default options set for sample purposes:

<?php
header('Access-Control-Allow-Origin: *');
require './vendor/autoload.php';

$GooglePayWallet = $_POST['googlePayWallet'];
$judoId = "yourJudoID";


$judopay = new Judopay(
  array(
      'apiToken' => 'yourAPIToken',
      'apiSecret' => 'yourAPISecret',
      'judoId' =>  $judoId,
  )
);

$googlePayPayment = $judopay->getModel('GooglePayment');

$googlePayPayment ->setAttributeValues(
    array(
        'judoId' => $judoId,
        'currency' => 'GBP',
        'yourPaymentReference' => substr(md5(rand()), 0, 7),
        'yourConsumerReference' => substr(md5(rand()), 0, 7),
        'amount' => '1.01',
        'googlePayWallet' => $GooglePayWallet
    )
);

try {
    $response = $googlePayPayment->create();
    echo json_encode($response);
} catch (\Judopay\Exception\ValidationError $e) {
    echo $e->json_encode(getSummary());
} catch (\Judopay\Exception\ApiException $e) {
    echo $e->getSummary();
} catch (\Exception $e) {
    echo $e->json_encode(getMessage());
}
?>

 

Please note the following:

  • This is the googlePay upstream handler to send the wallet details to Judopay for upstream processing.

  • This sample code defaults an amount to £1.01 using GBP. You should adjust this depending on the value of item(s) you are requiring payment for.

  • You should never expose your APISecret in any front-end development.

  • This will perform the upstream payment through Judopay's payment processing and will respond with a receipt object from our API, or any relevant error if there was an issue with the payment.

  • Replace the following values to match your own set up requirements:

    • Replace yourJudoID with your Judopay provided JudoID: $judoId = "yourJudoID"

    • Replace yourAPIToken with your Judopay provided APIToken: 'apiToken' => 'yourAPIToken'

    • Replace yourAPISecret with your Judopay provided APISecret: 'apiSecret' => 'yourAPISecret'

 

Google Pay™ Supported Networks

 

The value field is case sensitive. Ensure you use UPPERCASE.

 

Value

Description

Logo

AMEX

American Express Cards

DINERS CLUB INTERNATIONAL

Diners Club International Cards

DISCOVER

Discover Cards

INTERAC

Interac Cards

JCB

JCB Cards

MASTERCARD

Mastercard Cards

VISA

Visa Cards