Spreedly Express

There are a variety of ways to send payment data to Spreedly, many of which aim to ensure sensitive data never touches your server environment. Express is the simplest approach and does not require any styling on your behalf; you simply drop it into your page and wire up a few Javascript calls. Of all the options offered by Spreedly to collect card data, Express is the fastest, simplest way to incur the least amount of PCI scope.

If you are looking for specific commands or options, please see the Express Javascript API reference

User experience

Spreedly Express provides a thoughtful user experience without any need for you to design the UI and implement validation yourself. Simply drop in Express and your payment method collection form will include real-time validation of the credit card fields and visual feedback of the card type:

If there are validation errors, they are clearly displayed to the user and tooltips are provided to assist them fixing the issue with the field.

If your users are on a mobile device, the display will be automatically scaled down to best fit the device’s screen size

Spreedly Express is recommended for its polished user experience and continous updates representing the best practices for collecting credit card data, all without requiring any work from your development team.

Add to checkout page

To add Express to your checkout page, first include the Express javascript:

<script src="https://core.spreedly.com/iframe/express-3.min.js"></script>

Then, using Javascript, initialize Express with the Spreedly environment where you want payment methods to be tokenized along with any display and payment method options:

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"

You can view the full list of supported initialization options in the Express reference docs.

Once initialized, the only thing left to do is to tell Express to open when you’re ready to collect payment information. This can be as simple as attaching it to a payment button on your checkout page.

<form id="payment-form" action="https://yoursite.com/checkout">
  <input type="hidden" name="payment_method_token" id="payment_method_token">
  <input type="button" value="Enter Payment Info" onclick="SpreedlyExpress.openView();">

This will create a form with a button that, when pressed, will open the Express window pre-configured with the options set in init.

Executing the transaction

After Spreedly Express tokenizes your customer’s payment method, the onPaymentMethod callback is triggered. Register a callback which takes the resulting payment method token and sends it to your servers for processing.

Note: Once a payment method token has been returned, the Express modal will no longer open. In order to open the modal, you must call unload and then init.

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

Once the payment method token has been submitted to your backend, execute the actual transaction using the Spreedly direct API. This is necessary because the browser is not a secure environment and should never contain your Spreedly access secret (which is required to invoke the transactional portion of the Spreedly API).

From your backend system, execute a purchase (or auth) against the appropriate gateway using the direct API:

$ curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/json' \
  -d '{
        "transaction": {
          "payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
          "amount": 100,
          "currency_code": "USD",
          "retain_on_success": true

$ curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>

Customize display

Express provides sensible defaults for most labels and gives you the ability to provide your own text if you’d like to change the default verbiage or provide language support. In the call to init the first set of options are the display options - you can provide your own overrides here.

If your page structure is such that you can only determine these values after Express initialization you can use the setDisplayOptions call to modify the payment window display options post-init.

Additional payment information

It is quite common to collect more than just the required fields when storing a payment method. If you wish to provide more detailed payment information, such as billing address or email, you can provide these to init as the second options argument.

If your page structure is such that you can only determine these values after Express initialization you can use the setPaymentMethodParams call to modify the payment method params post-init.

Secure submissions

In order to achieve the highest levels of PCI-DSS v3 compliance with Spreedly Express, you need to disable the creation of payment methods via the direct API. After confirming you are not using the XML, JSON, JSONP, CORS or transparent direct methods of adding a payment method, enable the “Spreedly iFrame or Express Only option in the Environment Settings page of your environment.

This prevents direct API submission of payment methods which is required to detect malicious attacks and, in general, enforce adherence to the PCI standard. The only way payment methods can be added to this Spreedly environment will be through the Express (or iFrame) payment forms.

Browser compatibility

In general, Spreedly supports browser versions that are actively maintained and have up-to-date security profiles. At the time of this writing, that list includes:

We additionally require that all browsers support TLS 1.2 or higher.


Spreedly Express is versioned by major numerical, e.g., 3. Backwards-incompatible new features will cause the major version number to increment and will only be deployed if you update the script reference on your checkout page (meaning you choose when to accept major upgrades).

Any critical bug fixes or security updates will be automatically deployed as the current version number, thus automatically allowing you to run a secure, stable version. Therefore, please do not store a copy of the JavaScript library on your servers; instead, always reference the version hosted by Spreedly.


If, at any point, you experience difficulty implementing Express, please refer to the sample app to see working examples. There are two examples available, a basic sample as well as a more involved sample which uses the autofill feature and sets additional parameters for the payment token.