Express Javascript API
These are the API docs for versions 2 and 3 of the Spreedly Express Javascript API.
Spreedly Express is available from the following URL:
https://core.spreedly.com/iframe/express-3.min.js
// Invoke methods on the "SpreedlyExpress" global object,
// for instance...
SpreedlyExpress.openView();
By default, an instance of Spreedly Express will be available on the host page as SpreedlyExpress. Invoke the functions described in these docs using the SpreedlyExpress object.
Lifecycle
Including the Express Javascript file on a checkout page does not automatically load the library. Express’s lifecycle must be explictly managed using these functions.
init
SpreedlyExpress.init("C7cRfNJGODKh4Iu5Ox3PToKjniY", {
"amount": "$9.83",
"company_name": "Acme Widgets",
"sidebar_top_description": "Providing quality widgets since 2015",
"sidebar_bottom_description": "Your order total today",
"full_name": "First Last"
}, {
"email": "customer@gmail.com"
});
Initialize the Express library. This must be the first call made to Express.
Signature
init(environmentKey, displayOptions, paymentMethodParams)
Arguments
| Name | Description |
|---|---|
| environmentKey | The key of the Spreedly environment where the payment method should be tokenized |
| displayOptions | Map of display options |
| paymentMethodParams | (optional) Map of values to add to tokenized payment method |
displayOptions supports the following values:
| Name | Description |
|---|---|
| amount | The amount to display to the user, including currency. E.g., $9.83. |
| company_name | The name of the merchant |
| sidebar_top_description | Text to display under the company name |
| sidebar_bottom_description | Text to display under the amount |
| close_label | Label to use to dismiss the Express view. Defaults to “Cancel”. |
| name_label | The input label to use for the user’s name field |
| number_label | The input label to use for the credit card number field |
| cvv_label | The input label to use for the credit card verification field |
| expiration_label | The input label to use for the credit card expiration field |
| submit_label | The label for the submit button. Default is “Pay Now”. |
| full_name | Auto-fill the user’s name field by specifying a value here |
paymentMethodParams supports the following values, which will be stored on the payment method record at Spreedly:
| Name |
|---|
| address1 |
| address2 |
| city |
| state |
| zip |
| country |
| phone_number |
| company |
| shipping_address1 |
| shipping_address2 |
| shipping_city |
| shipping_state |
| shipping_zip |
| shipping_country |
| shipping_phone_number |
Callbacks
| Name | Triggered |
|---|---|
| onInit | Triggered when init has completed and other page elements can be safely enabled (such as the payment button) |
openView
SpreedlyExpress.openView();
Open the Express payment window to collect the user’s payment information.
Signature
openView()
unload
SpreedlyExpress.unload();
Completely unloads Express. Removes all DOM elements. Resets all callback functions.
Signature
unload()
Configuration
Express can be configured outside the initial init invocation.
setRecache
SpreedlyExpress.setRecache("56wyNnSmuA6CWYP7w0MiYCVIbW6" , {
"card_type": "visa",
"last_four_digits": "1234"
});
Set Express to update the CVV on an already tokenized credit card instead of collecting new payment method information.
Note: A credit card must be retained in your environment in order to re-cache its CVV.
Signature
setRecache(token, options)
Arguments
| Name | Description |
|---|---|
| token | Token of existing payment method in the Spreedly environment |
| options | Map of recache options for existing payment method. Set card_type to support CVV validation and brand icons, and last_four_digits to show the last four digits in the number field. |
setDisplayOptions
SpreedlyExpress.setDisplayOptions({
"amount": "$9.83",
"company_name": "Acme Widgets",
"sidebar_top_description": "Providing quality widgets since 2015",
"sidebar_bottom_description": "Your order total today",
"full_name": "First Last"
});
Set display options for the Express window. Will override any options set on init.
Signature
setDisplayOptions(options)
Arguments
| Name | Description |
|---|---|
| options | Map of display options |
Display options include:
| Name | Description |
|---|---|
| amount | The amount to display to the user, including currency. E.g., $9.83. |
| company_name | The name of the merchant |
| sidebar_top_description | Text to display under the company name |
| sidebar_bottom_description | Text to display under the amount |
| close_label | Label to use to dismiss the Express view. Defaults to “Cancel”. |
| name_label | The input label to use for the user’s name field |
| number_label | The input label to use for the credit card number field |
| cvv_label | The input label to use for the credit card verification field |
| expiration_label | The input label to use for the credit card expiration field |
| submit_label | The label for the submit button. Default is “Pay Now”. |
| full_name | Auto-fill the user’s name field by specifying a value here |
setPaymentMethodParams
SpreedlyExpress.setPaymentMethodParams({
"email": "customer@gmail.com"
});
Set additional payment method parameters for storage at Spreedly. Will override any parameters set on init.
Signature
setPaymentMethodParams(parameters)
Arguments
| Name | Description |
|---|---|
| parameters | Map of parameters to add to the tokenized payment method |
Payment method parameters include:
| Name |
|---|
| address1 |
| address2 |
| city |
| state |
| zip |
| country |
| phone_number |
| company |
| shipping_address1 |
| shipping_address2 |
| shipping_city |
| shipping_state |
| shipping_zip |
| shipping_country |
| shipping_phone_number |
toggleCvv
SpreedlyExpress.toggleCvv();
Toggles the visibility of the CVV field within the Express modal. When the CVV field is hidden, the CVV will not be required for tokenization.
Signature
toggleCvv()
Callbacks
Express supports a variety of callbacks that allow developers to be notified on specific events.
onInit
SpreedlyExpress.onInit(function() {
document.getElementById("pay-button").disabled = false;
});
Triggered when init has successfully completed and Express is ready for display or further configuration.
Callback signature
function()
onViewClose
SpreedlyExpress.onViewClose(function() {
console.log('event: view closed');
});
Triggered when the Express view is closed. This callback is invoked when either the user manually closes the view or unload() is called.
Callback signature
function()
onPaymentMethod
SpreedlyExpress.onPaymentMethod(function(token, paymentMethod) {
// Send requisite payment method info to backend
var tokenField = document.getElementById("payment_method_token");
tokenField.setAttribute("value", token);
var masterForm = document.getElementById('payment-form');
masterForm.submit();
});
Triggered when a payment method has been successfully tokenized at Spreedly. The resulting payment method token (and any additional data) should now be sent to your backend server environment for transacting.
Callback signature
function(token, formData)
Arguments
| Name | Description |
|---|---|
| token | The token of the newly tokenized payment method. Tokens are alphanumerics in the form M8TBiUmc19cjV16PdMbsj65uViL. |
| formData | A map of the data entered into the Express payment form, i.e. “full_name” ,“month” ,“year” |