Digital Wallets

Step 1: Prerequisites

We currently support both Google Pay and Apple Pay digital wallet services. Each service has its own registration process that you must complete prior to processing digital wallet transactions.

Supported Card Networks

Gravity supports the following card networks for processing in US dollars and settling for US-based merchant accounts:

  • Visa
  • Mastercard
  • American Express
  • Discover
  • JCB

Available digital wallet services

Select the digital wallet service you wish to make available and follow the steps to complete your registration.

Google Pay

Google Pay is Google’s digital wallet service, allowing customers to make secure payments online using credit and debit cards stored in a customer’s Google Pay wallet.

All merchants must adhere to the Google Pay API’s Acceptable Use Policy and merchants will need to accept the terms defined in the Google Pay API Terms of Service.

How to register with Google Pay’s Business Console

  1. Set up a Google account for business purposes if you do not already have one.
  2. Log into your Google account and go to the Business Console landing page at https://pay.google.com/business/console/. Enter your DBA name and agree to Google Pay API’s terms of service.    
  3. Select “Business Profile” from the sidebar and then “Edit Profile”. Complete all required (*) sections in the Business Profile and click “Save”.

  4. Click on “View Integrations”.
  5. Under “Integrate with your website” click on “Add website”.
  6. Under “Your website”, enter the exact website domain where you will display the Google Pay button for customers to make payments during checkout. Under “Your Google Pay API integration type” select “Gateway”.
  7. Under “Screenshots of your buyflow”, upload screenshots of your checkout flow as described. As your Google Merchant ID will not be approved for production yet, you will need to take screenshots of your integration in emergepay’s sandbox environment in order to display the Google Pay visual elements.
    1. For “Payment method screen”, use a screen capture of your checkout page displaying the “Google Pay” button.
    2. For “Google Pay API payment screen”, use a screen capture of the Google Pay payment sheet that gets loaded after the customer clicks the “Google Pay” button
  8. At this point, the “Submit for approval” button should be enabled and blue. You can click the button at any time to submit your Google Pay integration for approval.
  9. Your integration status will change with the note “Your integration is being reviewed”. You will need to check back periodically to see when your integration has passed and your Google Merchant ID can be used in production. The approval process can take 3 to 5 business days.
  10. Your Google Merchant ID is displayed in the upper right corner of all screens in the Business Console from the first time you log in. You will need to provide the Google Merchant ID to Gravity support so they can configure the Google Merchant ID in your Gravity account.

Action Required

You are required to contact an Integration Specialist to provide your Google Merchant ID before moving on to Step 2: Interacting with the Payment Sheet.

Apple Pay

Apple Pay allows customers to make secure payments online using credit and debit cards stored in a customer’s Apple Wallet.

Supported Authentication Methods

These are the supported formats in which Apple Pay will provide the user authorized payment payload.

  • Cryptogram 3DS – Apple authorizes an encrypted payload with a tokenized version of the card number in the form of a 3DS cryptogram

Action Required

Our Apple Pay integration requires no prerequisite registration process with Apple. Please reach out to an Integration Specialist for access to Dashboard and the ability to progress to Step 2: Interacting with the Payment Sheet.

Step 2: Interacting with the Payment Sheet

Prior to this step, you must reach out to an Integration Specialist for assistance in completing your digital wallet registration as described in Step 1: Prerequisites.

Client-Side only

Our SDK provides several functions, event handlers, and callbacks for use with interacting with the digital wallets payment sheets.

Functions

setRequiredFields(fields: object): void

This function allows you to select which fields the customer will be required to provide. The valid properties that can be supplied in fields can be seen below.

Be advised

This function will throw an error if the input supplied does not pass validation.

Name Details Required Description
billing Type: object No The billing details the customer should be required to provide. See Billing below
shipping Type: object No The shipping details the customer should be required to provide. See Shipping below

Billing

Name Details Required Description
address Type: boolean

Default value: false

 No Indicate whether the customer’s billing address should be required

Shipping

Name Details Required Description
address Type: boolean

Default value: false

 No Indicate whether the customer’s shipping address should be required
email Type: boolean

Default value: false

 No Indicate whether the customer’s email should be required
phoneNumber Type: boolean

Default value: false

 No Indicate whether the customer’s phone number should be required

setTransactionDetails(details: object): void

This function allows you to specify the transaction details that will be presented to the customer in the payment sheet. The valid properties that can be supplied in details can be seen below.

Be advised

This function will throw an error if the input supplied does not pass validation.

Name Details Required Description
total Type: string

Example formats:
10
1.23

 Yes The total amount that should be presented to the customer.
shippingMethods Type: array of objects No The selectable shipping methods that should be presented to the customer. See Shipping Methods below
lineItems Type: array of objects Yes The line items that should be presented to the customer. See Line Items below

Shipping Methods

Name Details Required Description
id Type: string Yes A unique id for the shipping method.
label Type: string Yes The label to present to the customer that describes the shipping method
description Type: string No A more detailed description of the shipping method
amount Type: string

Example formats:
10
1.23

 Yes The amount associated with the shipping method

Line Items

Name Details Required Description
label Type: string Yes The label to display to the customer that describes the line item
amount Type: string Yes The amount associated with the line item

appendButtons(config: object): void

This function allows you to specify the button configuration for the digital wallets buttons that will be appended to your site. The valid properties that can be supplied in config can be seen below.

Be advised

This function will throw an error if the input supplied does not pass validation.

Name Details Required Description
appendToId Type: string Yes The element to append the digital wallets buttons to
color Type: string

Possible values:
– black
– white

 No The color of the digital wallets buttons

Defaults to black
type Type: string

Possible values:
– normal
– compact

 No The style of the digital wallets buttons

Defaults to compact
inheritDimensionsFromId Type: string No An element to inherit the width and height from for the digital wallets buttons

Event Handlers

oncancel: () => void

An event handler that’s called when the customer cancels the transaction in the payment sheet

onerror: (error) => void

An event handler that’s called when a validation error occurs when setting transaction details, setting required fields, or calling the callback functions

onuserauthorized: (response: object) => void

An event handler that’s called when the customer confirms the transaction information displayed in the payment sheet. The response will contain payment sheet-specific data, including the encrypted token data, and will need to be sent to your server, combined with some other transaction properties, and ultimately sent to emergepay to charge the customer.

Be advised

The completePayment callback function must be called in this event handler.

The properties in response can be seen below:

Name Details Description
type Type: string

Possible values:
– applePay
– googlePay

 The type of digital wallet used by the customer to run the transaction
isSandbox Type: boolean The value set in your digital wallets configuration that indicates whether the transaction should use live funds from the customer’s account
billing Type: object The customer’s billing information returned from the payment sheet. See Billing below
shipping Type: object The customer’s shipping information returned from the payment sheet. See Shipping below
card Type: object Basic information about the customer’s card
token Type: object Encrypted token information. The properties in this object vary depending on the digital wallet used

Billing

Name Details Description
firstName Type: string The customer’s first name
lastName Type: string The customer’s last name
addressLines Type: array of strings The customer’s billing address
administrativeArea Type: string The customer’s billing administrative area
countryCode Type: string The customer’s billing country code
locality Type: string The customer’s billing locality
postalCode Type: string The customer’s billing postal code

Shipping

Name Details Description
firstName Type: string The shipping contact’s first name
lastName Type: string The shipping contact’s last name
email Type: string The shipping contact’s email
phoneNumber Type: string

Format: all digits

 The shipping contact’s phone number
method Type: object The selected shipping method.

The values in this object are the same as you supplied for one of the shipping methods in the emergepay wallets SDK
addressLines Type: array of strings The shipping contact’s address
administrativeArea Type: string The shipping contact’s administrative area
countryCode Type: string The shipping contact’s country code
locality Type: string The shipping contact’s locality
postalCode Type: string The shipping contact’s postal code

onshippinginfoupdate: (shippingInfo: object) => void

An event handler that’s called when the customer updates their shipping information.

Be advised

The updateShippingInfo callback function must be called in this event handler.

The properties in shippingInfo can be seen below:

Name Details Description
administrativeArea Type: string The shipping contact’s administrative area
countryCode Type: string The shipping contact’s country code
locality Type: string The shipping contact’s locality
postalCode Type: string The shipping contact’s postal code

onshippingmethodupdate: (shippingMethod: object) => void

An event handler that’s called when the customer selects a new shipping method in the payment sheet.

Be advised

The updateShippingMethod callback function must be called in this event handler.

The properties in shippingMethod can be seen below:

Name Details Description
id Type: string The id of the shipping method selected
label Type: string The label of the shipping method selected
description Type: string The description of the shipping method selected
amount Type: string The amount of the shipping method selected

Callback functions

completePayment(status: object): void

This function must be called with the approval status of the transaction after being ran through emergepay. This callback will dismiss the payment sheet or allow the customer to try again depending on the value supplied.

Be advised

This function will throw an error if the input supplied does not pass validation.

The valid properties that can be supplied in status can be seen below:

Name Details Required Description
approved Type: boolean Yes Indicate to the payment sheet whether the transaction ran through emergepay was successful. If true, the payment sheet will be dismissed. If false, the user may be able to change the values selected in the payment sheet and try again.
errors Type: array of StatusError

Minimum number of elements if provided: 1

 No Any errors that should be presented to the customer on the payment sheet. See StatusError below

StatusError

Name Details Required Description
code Type: string

Allowed Values:
– billingInvalid
– shippingInvalid
– shippingUnserviceable
– other

 Yes The error code corresponding to the error. This will trigger different behavior in the payment sheet.
field Type: string

Allowed values vary by code supplied:

billingInvalid:
– addressLines
– administrativeArea
– countryCode
– locality
– name
– postalCode

shippingInvalid and shippingUnserviceable:
– addressLines
– administrativeArea
– countryCode
– emailAddress
– locality
– name
– phoneNumber
– postalCode

other:
N/A

 Conditionally

This field is required when the code is billingInvalid, shippingInvalid, or shippingUnserviceable.

This field should not be supplied when the code is other.

 The field on the payment sheet that had an error. This may be highlighted in the payment sheet depending on the digital wallet being used.
message Type: string Yes A message to display to the customer in the payment sheet corresponding to the error.

updateShippingInfo(update: object): void

This function must be called to update the details displayed in the payment sheet after the customer has changed their shipping information.

Be advised

This function will throw an error if the input supplied does not pass validation.

The valid properties that can be supplied in update can be seen below:

Name Details Required Description
total Type: string

Example formats:
10
1.23

 Yes The new amount to present to the customer
lineItems Type: array of objects No The new line items to present to the customer. If supplied, at least 1 line item should be present in the array. See Line Items above for detailed information about the valid properties for each line item.
shippingMethods Type: array of objects No The new shipping methods to present to the customer. See Shipping Methods above for detailed information about the valid properties for each shipping method.
errors Type: array of ShippingInfoError

Minimum number of elements if provided: 1

 No Any errors that should be presented to the customer on the payment sheet. See ShippingInfoError below

ShippingInfoError

Name Details Required Description
code Type: string

Allowed Values:
– shippingInvalid
– shippingUnserviceable

 Yes The error code corresponding to the error. This will trigger different behavior in the payment sheet.
field Type: string

Allowed Values:
– administrativeArea
– countryCode
– locality
– postalCode

 Yes The field on the payment sheet that had an error. This may be highlighted in the payment sheet depending on the digital wallet being used.
message Type: string Yes A message to display to the customer in the payment sheet corresponding to the error.

updateShippingMethod(update: object): void

This function must be called to update the details displayed in the payment sheet after the customer has changed the selected shipping method

Be advised

This function will throw an error if the input supplied does not pass validation.

The valid properties that can be supplied in update can be seen below:

Name Details Required Description
total Type: string

Example formats:
10
1.23

 Yes The new amount to present to the customer
lineItems Type: array of objects No The new line items to present to the customer. If supplied, at least 1 line item should be present in the array. See Line Items above for detailed information about the valid properties for each line item.

Sample Code

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Sample Integration</title>
    <style>
        #checkout {
            cursor: pointer;
            color: white;
            background-color: black;
            width: 150px;
            height: 40px;
            border: none;
            font-size: 1.1em;
            margin: 0 10px;
        }
    </style>
</head>

<body>
    <div>
        <div id="wallets-container" class="wallets">
            <button id="checkout">Checkout</button>
        </div>
    </div>
    <script src="https://assets.emergepay-sandbox.chargeitpro.com/cip-hosted-wallets.js"></script>
    <script>
        const wallets = new emergepayWallets("YOUR-PUBLIC-ID");

        wallets.setRequiredFields({
            billing: {
                address: true,
            },
            shipping: {
                address: true,
                email: true,
                phoneNumber: true,
            },
        }).catch(err => console.log(err.data));

        wallets.setTransactionDetails({
            total: "15.00",
            shippingMethods: [
                { id: "S1", label: "Express Shipping", description: "Delivery: 3-5 days", amount: "0.00" },
                { id: "S2", label: "Priority Shipping", description: "Delivery: 2 days", amount: "5.00" },
            ],
            lineItems: [
                { label: "Express Shipping", amount: "0.00" },
            ],
        }).catch(err => console.log(err.data));

        wallets.appendButtons({
            appendToId: "wallets-container",
            color: "black",
            type: "compact",
            inheritDimensionsFromId: "checkout",
        }).catch(err => console.log(err.data));

        wallets.oncancel = () => console.log("wallet transaction canceled");

        wallets.onerror = error => console.log(error);

        wallets.onuserauthorized = response => {
            console.log(response);

            wallets.completePayment({ approved: true });
        };

        wallets.onshippinginfoupdate = shippingInfo => {
            console.log(shippingInfo);

            wallets.updateShippingInfo({
                total: "15.90",
                lineItems: [
                    { label: "Subtotal", amount: "15.00" },
                    { label: "Express Shipping", amount: "0.00" },
                    { label: "Estimated Tax", amount: "0.90" },
                ],
                shippingMethods: [
                    { id: "S1", label: "Express Shipping", description: "Delivery: 3-5 days", amount: "0.00" },
                    { id: "S2", label: "Priority Shipping", description: "Delivery: 2 days", amount: "5.00" },
                ],
            });
        };

        wallets.onshippingmethodupdate = shippingMethod => {
            console.log(shippingMethod);

            wallets.updateShippingMethod({
                total: (15.90 + (+shippingMethod.amount)).toFixed(2),
                lineItems: [
                    { label: "Subtotal", amount: "15.00" },
                    { label: shippingMethod.label, amount: shippingMethod.amount },
                    { label: "Estimated Tax", amount: "0.90" },
                ],
            });
        };
    </script>
</body>

</html>

Step 3: Processing the transaction

After receiving a response from the emergepay wallets SDK onuserauthorized event handler, you should now be able to send the response to your server and process the transaction by making a request to emergepay.

emergepay Wallets SDK Response

This is the same as the response object received in the onuserauthorized event handler from the emergepay wallets SDK. For convenience, the properties in response are included below.

The values in the response received from the wallets SDK should not be modified in any way, they should be merged with the properties outlined in the Additional Properties section below.

Name Details Description
type Type: string

Possible values:
applePay
googlePay

 The type of digital wallet used by the customer to run the transaction
isSandbox Type: boolean The value set in your digital wallets configuration that indicates whether the transaction should use live funds from the customer’s account
billing Type: object The customer’s billing information returned from the payment sheet. See Billing below
shipping Type: object The customer’s shipping information returned from the payment sheet. See Shipping below
card Type: object Basic information about the customer’s card
token Type: object Encrypted token information. The properties in this object vary depending on the digital wallet used

Billing

Name Details Description
firstName Type: string The customer’s first name
lastName Type: string The customer’s last name
addressLines Type: array of strings The customer’s billing address
administrativeArea Type: string The customer’s billing administrative area
countryCode Type: string The customer’s billing country code
locality Type: string The customer’s billing locality
postalCode Type: string The customer’s billing postal code

Shipping

Name Details Description
firstName Type: string The shipping contact’s first name
lastName Type: string The shipping contact’s last name
email Type: string The shipping contact’s email
phoneNumber Type: string

Format: all digits

 The shipping contact’s phone number
method Type: object The selected shipping method.

The values in this object are the same as you supplied for one of the shipping methods in the emergepay wallets SDK
addressLines Type: array of strings The shipping contact’s address
administrativeArea Type: string The shipping contact’s administrative area
countryCode Type: string The shipping contact’s country code
locality Type: string The shipping contact’s locality
postalCode Type: string The shipping contact’s postal code

Additional Properties

The properties below can be added to the wallets response prior to sending the payload to emergepay.

 

Name Details Required Description
amount Type: string Yes The transaction amount
transactionType Type: string

Possible values:
– CreditSale
– CreditAuth
– CreditReturn

 Yes The type of transaction to run
externalTransactionId Type: v4 uuid Yes A unique transaction identifier
transactionReference Type: string No The order id associated with the transaction

 

Sample Code

This sample code shows how to run a digital wallets transaction using emergepay.

const axios = require("axios");
const { v4 } = require("uuid");

//Ensure that you replace these with valid values before trying to issue a request
const oid = "your_oid";
const authToken = "your_authToken";
const environmentUrl = "environment_url";

const url = `${environmentUrl}/orgs/${oid}/transactions/wallets`;
const requestConfig = {
  "Content-Type": "application/json",
  "Authorization": `Bearer ${authToken}`
};

// the response from the emergepay wallets SDK
const transactionData = {};
transactionData.amount = "10.25";
transactionData.transactionType = "CreditSale";
transactionData.externalTransactionId = v4();
transactionData.transactionReference = "12345";

axios.post(url, { transactionData }, requestConfig)
.then(response => {
  console.log(response);
})
.catch(error => {
  console.log(error);
});
import axios from "axios";
import { v4 } from "uuid";

try {
  //Ensure that you replace these with valid values before trying to issue a request
    const oid: string = "your_oid";
    const authToken: string = "your_authToken";
    const environmentUrl: string = "environment_url";

  const url = `${environmentUrl}/orgs/${oid}/transactions/wallets`;
  const requestConfig = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${authToken}`
  };

  // the response from the emergepay wallets SDK
  const transactionData = {};
  transactionData.amount = "10.25";
  transactionData.transactionType = "CreditSale";
  transactionData.externalTransactionId = v4();
  transactionData.transactionReference = "12345";

  const response = await axios.post(url, { transactionData }, requestConfig);
} catch (error) {
 console.log(error);
}