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

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