Wallet Assist Widget | Hosted Widgets | Subscribe Pro Documentation

Details regarding all of the WalletAssist Widget methods, including the payment method schema and example usage.

Please see our Widget Configuration docs for more information about the UI modals.

Payment Profile Schema

Property	Type	Description	Required
`id`	number	Subscribe Pro payment profile ID.	Yes
`customerId`	string	Subscribe Pro customer ID.	Yes
`paymentToken`	string	Unique payment token for this payment profile. Used to retrieve the payment profile from the vault.	Yes
`creditcardType`	string	Type of credit card: `visa`, `master`, `american_express`, `discover`, `visa`, `jcb`, `diners_club`, or `dankort`.	-
`creditcardFirstDigits`	string	First 6 digits of the card.	-
`creditcardLastDigits`	string	Last 4 digits of the card.	-
`creditcardMonth`	string	Credit card expiration month.	-
`creditcardYear`	string	Credit card expiration year.	-
`vaultSpecificFields`	JSON object	Any additional fields specific to the payment vault.	-
`billingAddress.firstName`	string	Customer's first name.	Yes
`billingAddress.middleName`	string	Customer's middle name.	-
`billingAddress.lastName`	string	Customer's last name.	Yes
`billingAddress.company`	string	Name of customer's company.	-
`billingAddress.street1`	string	Street address line 1.	-
`billingAddress.street2`	string	Street address line 2.	-
`billingAddress.city`	string	City or locality name.	Yes
`billingAddress.region`	string	Region or state name/code.	Yes
`billingAddress.postcode`	string	Postal code.	Yes
`billingAddress.country`	string	Country name OR two-letter ISO 3166-1 alpha-2 country code.	Yes
`billingAddress.phone`	string	Telephone number associated with the address.	-

Example Payment Profiles

Payment Profile:

var paymentProfile = {
  paymentProfile: {
    id: 123123123,
    customerId: '989889898',
    paymentToken: 'ABCD-UNIQUE-PAY-TOKEN',
    creditcardType: 'master',
    creditcardFirstDigits: '555555',
    creditcardLastDigits: '4444',
    creditcardMonth: '3',
    creditcardYear: '2025',
    vaultSpecificFields: {
      sfcc: {
        payment_instrument_id: '12341234123',
      },
    },
    billingAddress: {
      firstName: 'Bob',
      middleName: 'A',
      lastName: 'Jones',
      company: 'Bobs Emporium',
      street1: '123 Here St',
      street2: 'Apt B',
      city: 'Baltimore',
      region: 'MD',
      postcode: '21212',
      country: 'US',
      phone: '410-123-4567',
    },
  },
};

New Payment Profile:

var paymentProfile = {
  paymentProfile: {
    customerId: '989889898',
    paymentToken: 'ABCD-UNIQUE-PAY-TOKEN',
    creditcardType: 'master',
    creditcardFirstDigits: '555555',
    creditcardLastDigits: '4444',
    creditcardMonth: '3',
    creditcardYear: '2025',
    vaultSpecificFields: {
      sfcc: {
        payment_instrument_id: '12341234123',
      },
    },
    billingAddress: {
      firstName: 'Bob',
      middleName: 'A',
      lastName: 'Jones',
      company: 'Bobs Emporium',
      street1: '123 Here St',
      street2: 'Apt B',
      city: 'Baltimore',
      region: 'MD',
      postcode: '21212',
      country: 'US',
      phone: '410-123-4567',
    },
  },
};

Events & Example Usage

The Wallet widget uses the following methods that may be called depending on the customer's actions from the website's wallet page:

onBeforePaymentProfileDeleted

If the specified paymentProfile is used for one or more subscriptions, a modal window will prompt the user to select a different payment method for their subscription(s) before the payment method is deleted. Subscribe Pro then deletes the payment method via API.

Parameter	Type	Description
`paymentProfile`	object	The payment profile JSON object that the customer wants to delete.
`onContinue`	function	Callback function created by the client to proceed once the customer has made their choice in the modal. This function should expect the specified payment profile as well as a string value as its parameters -- `not_found` if the payment profile isn't found in Subscribe Pro (in which case the site should present its default payment deletion modal), `delete` if the customer chose to delete the payment profile, and `do_not_delete` if the customer clicked the cancel button.

Example usage:

var widgetConfig = {
    element: 'sp-wallet-widget',
    apiBaseUrl: '{{apiBaseUrl}}',
    apiAccessToken: '{{apiAccessToken}}',
    vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
    customerId: '{{customerId}}',
    theme: 'my-custom-theme-name',
};

// Call widget init()
WalletAssist.init(widgetConfig);

var payment = {
    "paymentProfile": {
        "customerId": "989889898",
        "paymentToken": "ABCD-UNIQUE-PAY-TOKEN",
        "creditcardType": "master",
        "creditcardFirstDigits": "555555",
        "creditcardLastDigits": "4444",
        "creditcardMonth": "3",
        "creditcardYear": "2025",
        "vaultSpecificFields": {
            "sfcc": {
            "payment_instrument_id": "12341234123"
            }
        },
        "billingAddress": {
            "firstName": "Bob",
            "middleName": "A",
            "lastName": "Jones",
            "company": "Bobs Emporium",
            "street1": "123 Here St",
            "street2": "Apt B",
            "city": "Baltimore",
            "region": "MD",
            "postcode": "21212",
            "country": "US",
            "phone": "410-123-4567"
        }
    }
};

function onContinue(paymentProfile, result) {
  if (result === 'delete')
    // Delete the address
    ...
  else if (result === 'do_not_delete')
    // Don't delete
    ...
  else if (result === 'not_found')
    // Show site's delete modal
    ...
}

// When a customer deletes a payment profile
WalletAssist.onBeforePaymentProfileDeleted({payment}, onContinue);

onPaymentProfileCreated

The newPaymentProfile is created in Subscribe Pro via API.

Parameter	Type	Description
`paymentProfile`	object	The payment profile JSON object that the customer has created.

Example usage:

var widgetConfig = {
  element: 'sp-wallet-widget',
  apiBaseUrl: '{{apiBaseUrl}}',
  apiAccessToken: '{{apiAccessToken}}',
  vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
  customerId: '{{customerId}}',
  theme: 'my-custom-theme-name',
};

// Call widget init()
WalletAssist.init(widgetConfig);

var payment = {
  paymentProfile: {
    customerId: '989889898',
    paymentToken: 'ABCD-UNIQUE-PAY-TOKEN',
    creditcardType: 'master',
    creditcardFirstDigits: '555555',
    creditcardLastDigits: '4444',
    creditcardMonth: '3',
    creditcardYear: '2025',
    vaultSpecificFields: {
      sfcc: {
        payment_instrument_id: '12341234123',
      },
    },
    billingAddress: {
      firstName: 'Bob',
      middleName: 'A',
      lastName: 'Jones',
      company: 'Bobs Emporium',
      street1: '123 Here St',
      street2: 'Apt B',
      city: 'Baltimore',
      region: 'MD',
      postcode: '21212',
      country: 'US',
      phone: '410-123-4567',
    },
  },
};

// newPayment is the payment profile returned from Subscribe Pro API containing the new SP address ID
const newPayment = await WalletAssist.onPaymentProfileCreated({ payment });

onPaymentProfileUpdated

The paymentProfile is updated in Subscribe Pro via API. If an existing payment method is selected to be a "default" payment method, a modal window will prompt the user to replace the former "default" with the new one.

Parameter	Type	Description
`previousPaymentProfile`	object	The payment profile JSON object of the payment profile before it was updated.
`newPaymentProfile`	object	The payment profile JSON object of the updated payment profile.

Example usage:

var widgetConfig = {
  element: 'sp-wallet-widget',
  apiBaseUrl: '{{apiBaseUrl}}',
  apiAccessToken: '{{apiAccessToken}}',
  vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
  customerId: '{{customerId}}',
  theme: 'my-custom-theme-name',
};

// Call widget init()
WalletAssist.init(widgetConfig);

var previousPayment = {
  paymentProfile: {
    id: 12345,
    customerId: '989889898',
    paymentToken: 'ABCD-UNIQUE-PAY-TOKEN',
    creditcardType: 'master',
    creditcardFirstDigits: '555555',
    creditcardLastDigits: '4444',
    creditcardMonth: '3',
    creditcardYear: '2025',
    vaultSpecificFields: {
      sfcc: {
        payment_instrument_id: '12341234123',
      },
    },
    billingAddress: {
      firstName: 'Bob',
      middleName: 'A',
      lastName: 'Jones',
      company: 'Bobs Emporium',
      street1: '123 Here St',
      street2: 'Apt B',
      city: 'Baltimore',
      region: 'MD',
      postcode: '21212',
      country: 'US',
      phone: '410-123-4567',
    },
  },
};

var newPayment = {
  paymentProfile: {
    id: 12345,
    customerId: '989889898',
    paymentToken: 'EFGH-UNIQUE-PAY-TOKEN',
    creditcardType: 'visa',
    creditcardFirstDigits: '222222',
    creditcardLastDigits: '3333',
    creditcardMonth: '2',
    creditcardYear: '2024',
    vaultSpecificFields: {
      sfcc: {
        payment_instrument_id: '12341234123',
      },
    },
    billingAddress: {
      firstName: 'Bob',
      middleName: 'A',
      lastName: 'Jones',
      company: 'Bobs Emporium',
      street1: '123 Here St',
      street2: 'Apt B',
      city: 'Baltimore',
      region: 'MD',
      postcode: '21212',
      country: 'US',
      phone: '410-123-4567',
    },
  },
};

// updatedPayment is the updated payment profile returned from Subscribe Pro API
const updatedPayment = WalletAssist.onPaymentProfileUpdated({
  previousPayment,
  newPayment,
});

onDefaultPaymentProfileChanged

When the customer sets a newDefaultPaymentProfile, a UI modal will display to allow the customer the option to apply the new default payment profile to their subscriptions. If the previousDefaultPaymentProfile is used on subscriptions, that modal will also include the option to apply the new default only to the subscriptions currently using the previous default payment profile.

Parameter	Type	Description
`previousDefaultPaymentProfile`	object	The payment profile JSON object of the previous default payment profile.
`newDefaultPaymentProfile`	object	The payment profile JSON object of the new default payment profile.

Example usage:

var widgetConfig = {
  element: 'sp-wallet-widget',
  apiBaseUrl: '{{apiBaseUrl}}',
  apiAccessToken: '{{apiAccessToken}}',
  vaultEnvironmentKey: '{{spreedlyEnvironmentKey}}',
  customerId: '{{customerId}}',
  theme: 'my-custom-theme-name',
};

// Call widget init()
WalletAssist.init(widgetConfig);

var previousDefaultPayment = {
  paymentProfile: {
    id: 12345,
    customerId: '989889898',
    paymentToken: 'ABCD-UNIQUE-PAY-TOKEN',
    creditcardType: 'master',
    creditcardFirstDigits: '555555',
    creditcardLastDigits: '4444',
    creditcardMonth: '3',
    creditcardYear: '2025',
    vaultSpecificFields: {
      sfcc: {
        payment_instrument_id: '12341234123',
      },
    },
    billingAddress: {
      firstName: 'Bob',
      middleName: 'A',
      lastName: 'Jones',
      company: 'Bobs Emporium',
      street1: '123 Here St',
      street2: 'Apt B',
      city: 'Baltimore',
      region: 'MD',
      postcode: '21212',
      country: 'US',
      phone: '410-123-4567',
    },
  },
};

var newDefaultPayment = {
  paymentProfile: {
    id: 67890,
    customerId: '989889898',
    paymentToken: 'EFGH-UNIQUE-PAY-TOKEN',
    creditcardType: 'visa',
    creditcardFirstDigits: '222222',
    creditcardLastDigits: '3333',
    creditcardMonth: '2',
    creditcardYear: '2024',
    vaultSpecificFields: {
      sfcc: {
        payment_instrument_id: '12341234123',
      },
    },
    billingAddress: {
      firstName: 'John',
      middleName: 'A',
      lastName: 'Doe',
      street1: '456 Somewhere Rd',
      street2: 'Apt Z',
      city: 'Baltimore',
      region: 'MD',
      postcode: '21224',
      country: 'US',
      phone: '234-234-2345',
    },
  },
};

WalletAssist.onDefaultPaymentProfileChanged({
  previousDefaultPayment,
  newDefaultPayment,
});

Wallet Assist Widget - Widget Details

Payment Profile Schema

Example Payment Profiles

Events & Example Usage

onBeforePaymentProfileDeleted

onPaymentProfileCreated

onPaymentProfileUpdated

onDefaultPaymentProfileChanged