Wallet Assist Widget - Widget Details


Details regarding all of the Wallet 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

PropertyTypeDescriptionRequired
idnumberSubscribe Pro payment profile ID.Yes
customerIdstringSubscribe Pro customer ID.Yes
paymentTokenstringUnique payment token for this payment profile. Used to retrieve the payment profile from the vault.Yes
creditcardTypestringType of credit card: visa, master, american_express, discover, visa, jcb, diners_club, or dankort.-
creditcardFirstDigitsstringFirst 6 digits of the card.-
creditcardLastDigitsstringLast 4 digits of the card.-
creditcardMonthstringCredit card expiration month.-
creditcardYearstringCredit card expiration year.-
vaultSpecificFieldsJSON objectAny additional fields specific to the payment vault.-
billingAddress.firstNamestringCustomer's first name.Yes
billingAddress.middleNamestringCustomer's middle name.-
billingAddress.lastNamestringCustomer's last name.Yes
billingAddress.companystringName of customer's company.-
billingAddress.street1stringStreet address line 1.-
billingAddress.street2stringStreet address line 2.-
billingAddress.citystringCity or locality name.Yes
billingAddress.regionstringRegion or state name/code.Yes
billingAddress.postcodestringPostal code.Yes
billingAddress.countrystringCountry name OR two-letter ISO 3166-1 alpha-2 country code.Yes
billingAddress.phonestringTelephone 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.

ParameterTypeDescription
paymentProfileobjectThe payment profile JSON object that the customer wants to delete.
onContinuefunctionCallback 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.

ParameterTypeDescription
paymentProfileobjectThe 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.

ParameterTypeDescription
previousPaymentProfileobjectThe payment profile JSON object of the payment profile before it was updated.
newPaymentProfileobjectThe 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.

ParameterTypeDescription
previousDefaultPaymentProfileobjectThe payment profile JSON object of the previous default payment profile.
newDefaultPaymentProfileobjectThe 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});