Pass a Secure Request

Pass encrypted payloads to FastSpring.

You can use the Store Builder Library (SBL) to pass sensitive information in an encrypted format. This is necessary to hide information that customers should not have access to. To secure the information, follow the steps below:

  1. Set up encryption in FastSpring.
  2. Create a session object containing relevant data.
  3. Locally encrypt the session object to protect the data.
  4. Pass the encrypted payload to FastSpring.

FastSpring will decrypt the payload and apply the information to the associated order session.

Set Up Encryption

🚧

This step is only necessary for initial setup. If you have set up encryption before, you can skip this step.

  1. Navigate to Integrations > Store Builder Library.
  2. Copy the Access Key. You will use this key and data-access-key to initialize the SBL.
  3. Create a Private/Public certificate pair.
    • Private: Create a 2048-bit RSA private key. Do not share this key. You will use the private key PEM file privatekey.pem to create your secureKey.
    • Public: Create a 2048-bit RSA public key. Only share this key with FastSpring. FastSpring will use your public key PEM file publiccert.pem to decrypt your payload.
  4. Under File Upload, click Choose File. Select the file containing your public certificate.
  5. Click Save.

Create a Session Object

Create a session object containing all of the information which you would like to encrypt. The required fields will vary depending on the information collected.

<script>
var fscSession = {
    'reset': true,
    'products' : [
                    {
                        'path':'example-product',
                        'quantity': 1
                    }
    ],
    'coupon': 'YOUR10OFF'
}
</script>
<script
    id="fsc-api"
    src="https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.8.7/fastspring-builder.min.js"" type="text/javascript"

Locally Encrypt the Session Object

After you create the session object, locally encrypt the data. This varies depending on the programming language you are using. FastSpring will use your secureKey string and publiccert.pem to decrypt your securePayload string.

Java

  1. Create a 16-byte aesKey for each payload.
final KeyGenerator keyGenerator = KeyGenerator.getInstance("AES"); keyGenerator.init(128); final SecretKey secretKey = keyGenerator.generateKey() ; final byte[] aesKey = secretKey.getEncoded() ;
  1. Use the random 16-byte AES key to create the securePayload string from your unencryptedString. This is typically a Base64 string, but it can be a raw byte.
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);
  1. Use the random 16-byte AES key to create the securePayload string from your unencryptedString.
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 uses your secureKey string and publiccert.pem to decrypt your securePayload string.

PHP

  1. Create a 16 byte AES key for each payload.
$aesKey = openssl_random_pseudo_bytes(16) ; # or urandom() or any other random byte generator
  1. Use the random 16-byte AES key to create the securePayload string from your unencryptedString. This is typically a Base64 string, but it can be a raw byte.
$cipherText = openssl_encrypt($unencryptedString, "AES-128-ECB", $aesKey, OPENSSL_RAW_DATA) ;
$securePayload = base64_encode($cipherText) ;
  1. Encrypt your AES key with the privatekey.pem file. This creates your secureKey string.
$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 secureKey string and publiccert.pem to decrypt your securePayload string.

Pass the Encrypted Payload

There are 2 ways to pass the encrypted payload:

  • fscSession: Apply the data when the page loads.
<script>
var fscSession = {
    'secure': {
        'payload': securedData, // string of encrypted data passed from the server
        'key': secureKey // secure key passed from the server
    }
}
</script>
<!-- placing the session object before the Library is initialized ensures that the data will be sent with the very first request -->
<script
    id="fsc-api"
    src="https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.8.7/fastspring-builder.min.js"" type="text/javascript" 
...
  • fastspring.builder.secure(): Send the request.
<script>
    fastspring.builder.secure(securedData, secureKey);
</script>

Pass a Secure Request in Test Mode

If you are placing a test order, you do not need to encrypt private information. This allows you to troubleshoot and adapt each payload and encryption.

<script>
    Fastspring.builder.secure(nonEncryptedJSON, '');
</script>

Accepted Fields

The following tables display the fields which can be securely encrypted. Required fields will vary depending on what you include in your JSON string.

Contact Information

Field

Data Type

Description

contact

object

Customer contact information. This is required if you pass accountCustomKey.

The SBL does not prompt the customer to enter this information at checkout.

   firstName

string

Customer’s first name. Required when passing contact information.

   lastName

string

Customer’s last name. Required when passing contact information.

   email

string

Customer’s email address. Required when passing contact information.

   company

string

Customer’s company name. Required if the storefront requires it.

address

object

Customer address information.

   addressLine1

string

Line 1 of the customer’s mailing address. Required if the order includes physical fulfillments.

   addressLine2

string

Line 2 of the customer’s mailing address.

   city

string

The city in the customer’s address. Required if the order includes physical fulfillments.

   region

string

2-character ISO region code of the associated US state. Required if the order includes physical fulfillments, and the recipient resides in the US.

   postalCode

string

Customer’s postal code. Required for credit card transactions.

   phoneNumber

string

Customer’s phone number. Required if the storefront requires it.

   country

string

2-character ISO country code. Required if the order includes physical fulfillments.

accountCustomKey

string

The Account ID in your system. If you pass this string, the contact object is required.

account

string

FastSpring-generated Account ID (optional).

taxId

string

The customer’s VAT ID or GST ID. FastSpring will validate it in conjunction with the IP address country. If valid, tax exemption is applied. This field is optional.

Product Information

Field

Data Type

Description

items

object

Lists the product information for each product in the session.

product

string

Product ID that is added to the cart.

quantity

integer

Quantity of the product being added to the cart.

pricing

object

If you pass a “pricing” object, define all applicable pricing options.

trial

integer

Number of free trial days. Required for subscriptions.

interval

string

Billing frequency. "adhoc", "day", "week", "month", or "year".

   intervalLength

integer

Number of billings per intervalLength period.

   intervalCount

integer

Number of billings until subscription expires. Input null for unlimited billings.

quantityBehavior

string

Display and behavior of the quantity field. "allow", "lock", or "hide" the quantity field from customers at checkout.

quantityDefault

integer

Default product quantity. Required if you do not pass the quantity string above.

price

object

Price of the product. You can pass multiple currencies.
Example: { “USD”: 5.0, “EUR”: 4.0 }.

   discountType

string

Type of discount to be applied to the product. "percent" or "amount".

   quantityDiscounts

object

Specify the quantity required to receive a product discount. Then, enter the discount amount or percent.
Example (percent): { 2: 10.0 }
Example (amount): { 2: {“USD”,5.0} }

     discountReason

object

Customer-facing reason for the discount.
Example: {“en”: “English Text”, “de”: “German Text” }

     discountDuration

integer

Number of subscription billings to which the discount applies.

     dateLimitsEnabled

boolean

Allows a date range in which the discount is valid.

     startDate

string

Earliest date that the discount applies.

     endDate

string

Expiration date of the discount.

     startTime

string

Earliest time that the discount applies. Specify in UTC.

     endTime

string

Discount expiration time. Specify in UTC.

   reminder_enabled

boolean

Enable or disable subscription payment reminder notifications.

   reminder_value

string

Interval unit for subscription payment reminder email messages . "day", "week", "month", or "year".

   reminder_count

integer

Number of interval units prior to the next billing date when subscription payment reminder email messages will be sent.

   payment_overdue

boolean

Enable or disable subscription payment overdue notifications.

   overdue_interval_value

integer

interval unit for subscription payment overdue notification email messages.

   overdue_interval_count

integer

Total number of subscription payment overdue notifications that FastSpring sends prior to canceling the subscription.

   overdue_interval_amount

integer

Number of overdue_interval units between each subscription payment overdue notification message.

   cancellation_interval_count

integer

Number of cancellation_interval units prior to subscription cancellation.

   cancellation_interval_value

string

Interval unit for subscription cancellation (subscription only). "day", "week", "month", or "year".

display

object

Customer-facing product display name.
Example: {“en”: “English Display”, “de”: “German Display” }

description

object

Customer-facing product description.
Example: {“en”: “English Description”, “de”: “German Description” }

image

string

URL of the product icon image.

selected

boolean

Control whether or not the selected product appears in the cart.

removeable

boolean

Control whether or not customers can remove the item from their cart.

attributes

object

Product attributes.

sku

string

Product SKU ID

tags

object

Order tags.


Did this page help you?