Secure payloads

Use secure payloads to prefill customer details, pricing, or other sensitive data in your Store Builder checkout. This method encrypts the payload on your server using a signed key pair and passes it to FastSpring using fscSession or fastspring.builder.secure(). FastSpring decrypts the payload at runtime and applies it to the session.

Note: Secure payloads are typically used to lock fields like name, email, price, or tax ID. This method is ideal for passing verified customer data that should not be editable during checkout.

Why use secure payloads?

Secure sensitive values that should not be visible or editable at checkout:

• Lock contact fields: Prevent buyers from modifying name, email, or address
• Apply validated IDs: Include tax IDs or account IDs without exposing them
• Restrict payment methods: Pre-select and enforce a specific payment option

What this guide covers

This guide explains how to:

• Set up encryption for secure payloads
• Create and encrypt a secure session payload
• Pass the payload using fscSession or fastspring.builder.secure()
• Work with secure test payloads in development
• Understand accepted fields and payload structure

Set up encryption

Before you can pass a secure payload to your store checkout, you need to complete a one-time encryption setup in your FastSpring account.

1. In the FastSpring App, go to Developer Tools > Store Builder Library.

2. Copy your Access Key. You will use this in the data-access-key attribute when initializing Store Builder.

3. Generate a 2048 bit RSA key pair.

   • Create a private key and save it as privatekey.pem. Keep this file secure and do not share it. You will use it on your server to encrypt the payload and generate the secureKey.
   • Create a public key and save it as publiccert.pem. Share this with FastSpring only. FastSpring will use it to decrypt your payload at checkout.

   If you haven’t done this before, check out resources on generating RSA key pairs in your preferred language or tooling (like OpenSSL or Node crypto). Make sure your key length is 2048 bits.

4. Upload your publiccert.pem file using the File Upload section.

5. Click Save.

   You will use the private key to encrypt session data on your server and generate the secure payload. FastSpring will use the public key to decrypt it at checkout.

Create and encrypt your payload

After setting up encryption, you can create a secure payload on your server and pass it into Store Builder. A secure payload is a JSON object containing session data that is encrypted using your private key. FastSpring uses your uploaded public key to decrypt the payload at checkout.

Only supported fields should be included in your payload. Fields like reset and checkout are not valid in secure session objects.

The exact implementation depends on your backend language, but the core process is the same across platforms.

Example payload before encryption

Here’s a basic example of what your unencrypted session data might look like before you encrypt it. This is the structure you will stringify and encrypt to create your securePayload.

{
  "contact": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "[email protected]",
    "country": "DE"
  },
  "items": [
      {
        "product": "example-product",
        "quantity": 1,
        "pricing": {
          "price": {
          "USD": 19.00
          }
        }
      }
	]
}

Tip: You can include address fields inside the contact object or as a top-level address object. If your store requires physical address collection, make sure it is enabled in your store settings.

How to encrypt the payload

You will generate the securePayload and secureKey in your backend using your private key. The logic is the same regardless of language:

• Encrypt the payload with a randomly generated AES key
• Encrypt that AES key using your private RSA key (privatekey.pem)
• Pass both encrypted values to Store Builder at checkout

Java

Follow these steps to create your secure payload in Java:

1. Generate a 16-byte AES key
   You will use this key to encrypt your session data before passing it to FastSpring.

final KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
keyGenerator.init(128);
final SecretKey secretKey = keyGenerator.generateKey();
final byte[] aesKey = secretKey.getEncoded();

2. Encrypt the payload using AES-128-ECB with PKCS5 padding
   This creates your securePayload string, which contains the encrypted session data.

final SecretKeySpec secretKeySpec = new SecretKeySpec(aesKey, "AES");
final Cipher encryptCipher = Cipher.getInstance("AES/ECB/PKCS5Padding");
encryptCipher.init(Cipher.ENCRYPT_MODE, secretKeySpec);
final byte[] cleartext = unencryptedString.getBytes("UTF-8");
final byte[] ciphertext = encryptCipher.doFinal(cleartext);
final String securePayload = Base64.getEncoder().encodeToString(ciphertext);

3. Encrypt the AES key using your private RSA key
   Use the privatekey.pem file you created during the encryption setup step. This creates the secureKey.

final org.bouncycastle.openssl.PEMReader pemReader =
    new org.bouncycastle.openssl.PEMReader(new StringReader(privateKeyPEM));
final KeyPair keyPair = (KeyPair) pemReader.readObject();
pemReader.close();

final PrivateKey privateKey = keyPair.getPrivate();
final Cipher clientPrivateCipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
clientPrivateCipher.init(Cipher.ENCRYPT_MODE, privateKey);

final byte[] aesKeyEncrypted = clientPrivateCipher.doFinal(aesKey);
final String secureKey = Base64.getEncoder().encodeToString(aesKeyEncrypted);

FastSpring will use your uploaded publiccert.pem to decrypt the secureKey and unlock the securePayload at checkout.

PHP

Follow these steps to create your secure payload in PHP:

1. Generate a 16-byte AES key
   You will use this key to encrypt the session data before passing it to FastSpring.

$aesKey = openssl_random_pseudo_bytes(16);

2. Encrypt the payload using AES-128-ECB
   This creates the securePayload string, which contains the encrypted session data.

$cipherText = openssl_encrypt($unencryptedString, "AES-128-ECB", $aesKey, OPENSSL_RAW_DATA);
$securePayload = base64_encode($cipherText);

3. Encrypt the AES key using your private RSA key
   Use the privatekey.pem file you created during the encryption setup step. This creates the secureKey.

$privateKeyFileName = realpath("privatekey.pem");
$privateKey = openssl_pkey_get_private("file://$privateKeyFileName");
openssl_private_encrypt($aesKey, $aesKeyEncrypted, $privateKey);
$secureKey = base64_encode($aesKeyEncrypted);

FastSpring will use your uploaded publiccert.pem to decrypt the secureKey and unlock the securePayload at checkout.

Pass the secure payload

Once you've created your securePayload and secureKey, you can pass them to Store Builder using either fscSession or fastspring.builder.secure().

Use fscSession before Store Builder loads

Apply the encrypted data when the page loads by defining fscSession before Store Builder initializes.

<script>
var fscSession = {
  secure: {
    payload: securePayload, // encrypted payload string generated on your server
    key: secureKey          // encrypted AES key string passed from your backend
  }
};
</script>

<!-- Define the session object before loading the Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-url"
  data-access-key="your-access-key">
</script>

Use fastspring.builder.secure() after Store Builder loads

You can also pass the secure payload dynamically using fastspring.builder.secure() after the script has initialized.

<script>
    fastspring.builder.secure(securedData, secureKey);
</script>

This method is helpful when your payload is generated on the fly or fetched from your backend after the page loads.

Test with unencrypted payloads (development only)

If you are placing a test order, you can pass private information unencrypted for testing purposes only. This allows you to troubleshoot and adapt your payload and encryption logic before going live.

<script>
    fastspring.builder.secure(nonEncryptedJSON, "");
</script>

Accepted fields

The following fields are supported in secure payloads. Field requirements may vary depending on your store settings and the data you pass. Address fields can be included either inside the contact object or as a separate top-level address object.

If your store requires physical address collection, make sure that option is enabled in your store settings.

Contact information

These fields allow you to include customer and account information in your secure payload. You can structure address fields inside the contact object or as a top-level address object.

Example: Contact and account fields

Here’s a full example showing how to pass contact information, tax ID, and account identifiers in a secure payload. Fields shown here are optional unless otherwise noted in the Contact information table.

{
  "contact": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "company": "Example Co.",
    "addressLine1": "456 Example Ave",
    "addressLine2": "Suite 789",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94107",
    "phoneNumber": "555-123-4567",
    "country": "US"
  },
  "accountCustomKey": "external-id-456",
  "account": "fs-account-id-abc123",
  "taxId": "GB123456789"
}

Payment method settings

You can pre-select a preferred payment method and optionally hide all other options from the buyer during checkout.

Example: Pre-select a payment method

Here’s a short example that pre-selects PayPal and hides all other payment methods during checkout.

{
  "contact": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "country": "US"
  },
  "items": [
			{
				"product": "example-product",
				"quantity": 1,
				"pricing": {
					"price": {
					"USD": 19.00
					}
				}
			}
	  ]
  "paymentMethod": "paypal",
  "hideOtherPaymentMethods": true
}

Be sure the selected payment method is enabled in your store settings. Otherwise, it will be ignored at checkout.

Product information

These fields define the products added to the cart using the items array. You can specify quantities, pricing, trial periods, display settings, and more.

Example: Full product payload structure

Here’s a complete example of a secure payload with detailed product configuration, including subscription settings, pricing, display content, and optional metadata.

{
  "items": [
    {
      "product": "product-path",
      "quantity": 1,
      "pricing": {
        "trial": 30,
        "interval": "month",
        "intervalLength": 1,
        "intervalCount": null,
        "quantityBehavior": "allow",
        "quantityDefault": 1,
        "price": {
          "USD": 5.0,
          "EUR": 4.0
        },
        "discountType": "percent",
        "quantityDiscounts": {
          "1": {
            "USD": 5.0,
            "EUR": 4.0
          }
        },
        "discountReason": {
          "DE": "German text"
        },
        "discountDuration": 1,
        "dateLimitsEnabled": true,
        "startDate": "2025-01-01",
        "endDate": "2025-12-31",
        "startTime": "00:00",
        "endTime": "23:59",
        "reminder_enabled": true,
        "reminder_value": "day",
        "reminder_count": 1,
        "payment_overdue": true,
        "overdue_interval_value": "day",
        "overdue_interval_count": 1,
        "overdue_interval_amount": 3,
        "cancellation_interval_count": 1,
        "cancellation_interval_value": "day"
      },
      "display": {
        "DE": "German text"
      },
      "description": {
        "values": {
          "full": {
            "values": {
              "en": "English description"
            }
          }
        }
      },
      "image": "https://example.com/image.png",
      "selected": true,
      "removable": true,
      "attributes": {
        "key": "value"
      },
      "sku": "internal-product-sku-1234"
    }
  ],
  "tags": {
    "key": "value"
  }
}

Tip: This example includes supported fields for subscriptions, pricing rules, and product display. You can simplify the structure based on your needs. Not all fields are required, so only include what applies to your product.

FAQs