Spreedly Express v1 (Deprecated)

These are the docs for an old version of Spreedly Express. If you are implementing a new checkout experience, please see the most recent Spreedly Express documentation.

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 configuration or styling on your behalf; you simply drop it into your page. 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.

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 highly 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

By default, Express works by attaching itself to an existing HTML form on your checkout page, after which it will:

  1. Display the payment window when the form’s submit button is pressed
  2. Add a new payment_method_token field to the form after the user’s payment method has been tokenized by the Spreedly service
  3. Automatically submit the form after the payment method token has been added

The net result is that, to your backend service, storing and tokenizing a payment method at Spreedly looks like a normal form submission.

To start, add the following form to your checkout page:

<form action="https://yoursite.com/order/new" method="POST" id="express-form">
  <input id="express-submit" type="submit" value="Pay Now" disabled="true">
  <script
    src="https://core.spreedly.com/iframe/express-2.min.js" id="express-script"
    data-environment-key="5WtRCxOhabLibNkQjnxIiXfzA8V"
    data-amount="$123.56"
    data-company-name="Your Company Name Here"
    data-sidebar-top-description="Place a short description of your business here"
    data-sidebar-bottom-description="List order and/or item information here">
  </script>
</form>

This will create a simple form with a single button that, when pressed, will open the Express window.

Customize display

The attributes of the form, and the embedded script, are used to customize the display and function of Express and can be modified as needed to reflect the customer’s transaction:

Element Attribute Description
form id=express-form The form must have this exact id value so Spreedly Express can locate it on the page
action=http://yoursite.com/pay The URL of the endpoint you want the form submitted to after a payment_method_token field has been added by Express
form > input type="submit" The button that will trigger the Express payment form to open
id="express-submit" It must have this exact id value
disabled=true Set it to start disabled. Express will dynamically enable the button when Express has successfully loaded on the page.
form > script id="express-script" Add a script element within the form using this id
src="https://core.spreedly.com/iframe/express-2.min.js" Load the Express script using this URL
data-environment-key="your-environment-key" Set the key of the Spreedly environment you want your customers’ payment methods stored using this attribute
data-amount The amount (including currency symbol) that will be shown to your customers on Express
data-full-name If you already know your customer’s name, setting it with this attribute will autofill the name field in Express
data-company-name The name of your business to show on Express
data-sidebar-top-description A description/tagline for your business (limited to 65 characters)
data-sidebar-bottom-description A description of the purchase (limited to 65 characters)

The example form used here has no other elements other than the submit button. However, if you have other data about the customer’s order (order id, total amount, customer id etc…), you can add these to the form as hidden elements. This data will then get submitted alongside the payment method token, allowing you to record the necessary relationships between customer and tokenized payment method in your persistent systems.

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 simply set the appropriate data element and Express will add it to the payment method it creates on the Spreedly server. This is not information Express will collect for you in its display window - it will simply pass through data you already have about your customer when tokenizing the payment method so your payment method record at Spreedly is complete.

You can add one or more of the following to the script element (all of which are optional):

Script attribute Description
data-email The email address of the customer
data-address1 The first line of the customer’s billing address
data-address2 The second line of the customer’s billing address
data-city The city of the customer’s billing address
data-state The state of the customer’s billing address
data-zip The zip/postal code of the customer’s billing address
data-country The country of the customer’s billing address
data-phone_number The customer’s billing phone number
data-company The customer’s company
data-shipping_address1 The first line of the customer’s shipping address
data-shipping_address2 The second line of the customer’s shipping address
data-shipping_city The city of the customer’s shipping address
data-shipping_state The state of the customer’s shipping address
data-shipping_zip The zip/postal code of the customer’s shipping address
data-shipping_country The country of the customer’s shipping address
data-shipping_phone_number The phone number of the customer’s shipping address

For instance, to add some basic customer information to the payment method when it’s submitted to Spreedly, you could use the following form:

<form action="https://yoursite.com/order/new" method="POST" id="express-form">
  <input id="express-submit" type="submit" value="Pay Now" disabled="true">
  <script
    src="https://core.spreedly.com/iframe/express-2.min.js" id="express-script"
    data-environment-key="5WtRCxOhabLibNkQjnxIiXfzA8V"
    data-amount="$123.56"
    data-company-name="Your Company Name Here"
    data-sidebar-top-description="Place a short description of your business here"
    data-sidebar-bottom-description="List order and/or item information here"

    data-email="customer@gmail.com"
    data-address1="123 Main St."
    data-city="Small Town"
    data-state="NC"
    data-zip="27511"
    data-country="US"
    >
  </script>
</form>

Executing the transaction

After Spreedly Express tokenizes your customer’s payment method and submits the checkout form, it is up to you to execute the actual transaction from your backend server environment. 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).

When the checkout form is submitted, extract the payment_method_token parameter and use it to 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>
        <payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <retain_on_success>true</retain_on_success>
      </transaction>'

You can review the Spreedly API reference docs for details of the direct API, including the purchase and authorize calls.

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

Express is compatible with the following browser versions:

  • Internet Explorer 10.0 and above
  • Google Chrome 30 and above
  • Firefox 30 and above
  • Safari 6 and above
  • iOS Safari 6 and above

Versioning

Spreedly Express is versioned by major numerical, e.g., 2. 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 and deployed as the current version number, making no action required by you to be running on a secure, stable version. For this reason, please do not store a copy of the javsacript library on your servers, always reference the version hosted on spreedly.com.

Examples

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.