NAV
Spreedly Logo

Express Javascript API

These are the API docs for version 2 of the Spreedly Express Javascript API.

Spreedly Express is available from the following URL:

https://core.spreedly.com/iframe/express-2.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
email
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.

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",
  "first_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
email
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

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”