Express API lifecycle
API documentation for version 2 and version 3 of the Spreedly Express Javascript API.
Express overview
Review the Express payment form guide for general-purpose information on using Express.
Spreedly Express is available from the following URL: https://core.spreedly.com/iframe/express-3.min.js
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.
// Invoke methods on the "SpreedlyExpress" global object,
// for instance...
SpreedlyExpress.openView();
Lifecycle
Including the Express Javascript file on a checkout page does not automatically load the library. Express’s lifecycle must be explicitly managed using these functions.
init
Initialize the Express library with secure tokenization. This must be the first call made to Express.
SpreedlyExpress.init("C7cRfNJGODKh4Iu5Ox3PToKjniY", {
"nonce": "dd6b70a5-e070-4fa2-a3ca-0db0b45f78d0", // Unique per session (e.g., UUID)
"certificateToken": "certificate",
"timestamp": "1738252535",
"signature": "SERVER_GENERATED_HMAC" // HMAC-SHA256(nonce + private key, certificate, timestamp)
"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": "[email protected]"
});
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 | Autofill 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 |
Security Requirements
⚠️ These arguments are required to authenticate requests to Spreedly's Core API for new and existing payment methods.
nonce
: A unique, cryptographically random value generated per session to prevent replay attacks.timestamp
: A timestamp of the request which indicates the window of time anonce
is valid; Epoch time recommended.certificateToken
: the Spreedly certificate token returned to a merchant when storing the public portion of their asymmetric key pair; used for verification of the digital signature.signature
: A server-generated hash string created by a merchant using thenonce
+timestamp
+certificateToken
, signed with a merchant-controlled private key.
Key Notes
- Security Compliance:
- Enabling this functionality allows for further confidence in risk assessments, performance of rate-limiting and other moderation strategies for transaction attempts using Express on a payment page.
- HMAC validation ensures request integrity and authenticity, aligning with PCI-DSS 4.0’s script/data integrity requirements.
- Never hardcode secrets client-side—generate
signature
server-side using a securely stored private key.
- Implementation Steps:
- Generate a unique
nonce
(e.g., UUID) for each payment session, and for each instance of Express. - Compute
signature
server-side via HMAC-SHA256 using thenonce
+timestamp
+certificateToken
and your private key. - Send these arguments during the
init
call to ensure authentication of your session and associated Create payment method call.
- Generate a unique
Enabling authentication
To enable authentication of your Create payment method API calls via Express, visit the environment settings page in app.spreedly.com.
We recommend selecting iFrame or Express only, and ensuring Express is properly configured with the arguments for secure tokenization prior to enabling its setting under "Enhanced Security". Once saved, this authenticate transactions from Express in this environment only, using a session nonce + HMAC signature and timestamp.

Note: When enabled, all Create payment method calls will be impacted and require authentication. This includes Express using the described session nonce authentication mechanism, or basic HTTP authorization for payment methods tokenized via API.
Callbacks
onInit | Description |
---|---|
onInit | Triggered when init has completed and other page elements can be safely enabled (such as the payment button) |
openView
Open the Express payment window to collect the user’s payment information.
SpreedlyExpress.openView();
Signature
openView()
unload
Completely unloads Express. Removes all DOM elements. Resets all callback functions.
SpreedlyExpress.unload();
Signature
unload()
Updated 8 days ago