This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)
FastSpring’s Store Builder Library (SBL) allows you to provide customer details (such as name and email address) before initiating the checkout process. There are three ways to provide pieces of customer information using SBL:
- Using the fastspring.builder.recgonize() method
- Using the paymentContact object within the SBL session
- Using a secure payload
Using fastspring.builder.recognize() OR the paymentContact Object within the SBL Session
During checkout preparation (prior to launching the checkout process), you can provide customer details using the fastspring.builder.recognize() call, or within the paymentContact object of session data that you may push to SBL (e.g. using fastspring.builder.push()). Either way, the data you provide is not validated by FastSpring; it is only used to pre-fill checkout fields with the information. The information will be validated when the customer attempts to check out.
The fastspring.builder.recognize() call and the paymentContact object in an SBL session require at least an email address; other fields are optional. All the data provided through these methods will be visible and editable during the checkout.
These methods are intended to allow you to provide "potential" customer details. For example, if a customer lands on your page from a link in an email message and your page is designed to parse the URL parameters, the email address can be "recognized" so the customer does not have to enter it again. Here is a full list of fields that can be provided through the "recognize" call or in the paymentContact object within an SBL session:
In addition to using fastspring.builder.recognize() to pass in the fields above, the following methods can be used to pass specific pieces of customer data when not using a secure payload:
|fastspring.builder.language('')||Pass in the two-character ISO language code (e.g., "de" for German, "fr" for French, etc.).|
|fastspring.builder.taxId('')||For customers in locations where FastSpring accepts a tax ID to prevent collection of VAT or GST.|
Likewise, when using the SBL session object, the order language and the customer's tax ID can be supplied but must be passed outside the paymentContact object, using "language":"<2-character ISO language code>" and "taxId":"<id>", respectively.
Example 1: Three methods called separately to pass in data for a customer in Germany who wants to order in English and is exempt from paying VAT
Example 2: Using the session object to pass in product and quantity plus data for a customer in France who wants to order in English and is exempt from paying VAT
Using a Secure Payload
Data provided inside the contact object of a secure payload is validated when submitted, and will only be stored if it is valid. It goes through the same validation process it would have gone through when the customer attempted to checkout, but this happens upon submission instead of waiting for the checkout. If such data passes validation, all the corresponding fields will be hidden during the checkout and only payment details will be collected. Here is a full list of fields which can be provided through the secure payload and their validation rules:
These three fields are always required in the secure payload. For example, you cannot provide a customer's address without providing his or her name and email address. First and last name need to be at least 1 character long, and email must be a valid email address.
Optional, not validated
Required if enabled on the store. However, you can always provide the address and it will be validated even if not required when creating or updating an account using secure payload or /account call.
Fields in bold are required. Additionally, for U.S. addresses, region must have a valid value for the supplied postalCode. For example, if region is "US-CA", meaning California, the postalCode value must be a valid California ZIP code. If the postalCode provided does not correspond to the region, the address will not pass validation.
region format = "<2-character ISO country code>-<2-character ISO U.S. state code>", e.g., "region":"US-TX" for Texas
region (required for US)
Required if enabled on the store
If not provided, assumed during checkout based on geo IP location
Specifying the customer’s country in a secure payload also sets the language automatically, overriding order language selection based on the browser’s default language. You can also set the language separately in the secure payload using "language", outside the contact object.
Important: If details in the contact object of a secure payload do not pass validation, they will be treated in the same way as a fastspring.builder.recognize() call; i.e., the data will be pre-filled but fields will be visible during the checkout. This allows customers to correct the mistakes. However, in the case of address fields, if your Storefront is not configured to display those fields, the customer will not see the fields or be able to correct the problem. Therefore, if address validation is important to your business, we encourage you to do one of the following:
- validate the address supplied by the customer before passing it in via a secure payload
- ensure that your Storefront has the Force physical address collection for all orders check box selected (on the Checkout page of a Popup Storefront's SETTINGS, or the General Settings page for a Web Storefront's SETTINGS) so that the fields will be displayed when necessary
In addition to the contact object of a secure payload, there are two other pieces of customer information you can pass separately in the payload:
|language||Pass in the two-character ISO language code (e.g., "de" for German, "fr" for French, etc.)|
|taxId||For customers in locations where FastSpring accepts a tax ID to prevent collection of VAT or GST|
Example 1: Passing in Data for a U.S. Customer Via the Contact Object of a Secure Payload
Example 2: Passing in Language and Tax ID for an EU Customer Via a Secure Payload
In the event that customer data is received from more than one source, FastSpring uses the following logic to decide which customer data will be used for the order:
- If data has been provided (and validated) through a secure payload, it will be used and no data entry (other than payment details) will be allowed.
- If data has been provided through the fastspring.builder.recognize() call or via the paymentContact object in an SBL session, it will be used to pre-fill fields of the checkout flow, but any data entered by the customer during the checkout will override data supplied by these methods.
- If data has been returned to FastSpring from a payment provider such as Amazon Pay or PayPal, it will only be stored as part of the order record if it matches data entered by the customer during the checkout. Otherwise, the data entered by the customer will override data returned from the payment method.
In simple form, the order of precedence is as follows:
- Secure Payload
- Data entered during checkout
- Recognized / paymentContact data
- Data from the payment method