Judopay Documentation

Google Pay™ for Web

G_Pay_Logo.png

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

Note

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.

Caution

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)

    Note

    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

Tip

The documentation and examples provided, are based on version 0.0.10 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.10/judopay.min.js"></script>  

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

    Caution

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

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

Note

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:

GP_Step_2.png

domainName

String

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

For example: www.mysite.com

Note: 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.

Note: The case is important, ensure you use UPPERCASE.

  • TEST = Google Sandbox

  • PRODUCTION   = Google Pay Live

Note: 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.

Note: 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.

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

Note: The case is important, ensure you use lowercase.

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

    Without the 'Buy with' text:

GP_Short.png

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

    With the 'Buy with' text:

GP_Long.png

style

String

The style of the Google Pay™ Button to display:

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

GP_Short_White.png

 

For example: type = long, style = white

GP_Long_White.png

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.

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

Note

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

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) 

    Note

    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
}

Note

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.

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.

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:

GP_step_7.png

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.

Example 4. 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:

  • Replace yourAPIToken - with your Judo supplied APIToken:

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

  • Replace yourJudoID - with your Judo supplied JudoID

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

  • Replace merchantDomain - with your website URL

    Note

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

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

  • Replace TEST - with PRODUCTION when you are ready to go live

  • Replace merchantID - with your Google supplied merchant ID

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

Note

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

Note

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

Example 5. 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

Note

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

Value

Description

Logo

AMEX

American Express Cards

American_Express_logo.png

DISCOVER

Discover Cards

Discover.png

INTERAC

Interac Cards

Interac.png

JCB

JCB Cards

JCB.jpg

MASTERCARD

Mastercard Cards

Mastercard_logo.gif

VISA

Visa Cards

Visa_2014_logo.png
See also: