Using Store Builder Library to Provide Customer Details

Overview

FastSpring’s Store Builder Library (SBL) allows you to provide customer details (such as name and email address) before initiating the checkout process.

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
  • 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
  • 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
• Data Precedence

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:

• email
• firstName
• lastName
• company
• addressLine1
• addressLine2
• city
• region
• country
• postalCode
• phoneNumber

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:

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

fastspring.builder.recognize({"email":"ne1@all.com","firstName":"Leeroy","lastName":"Jenkins","country":"DE"})

fastspring.builder.language("en")

fastspring.builder.taxId("DE1234567")

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

var s = {
  "reset": true,
  "products" : [
    {
      "path":"product-one",
      "quantity": 1
    }
  ],
  "paymentContact": {
    "email":"ne1@all.com",
    "firstName":"Leeroy",
    "lastName":"Jenkins",
    "country":"FR"
  },
  "language":"en",
  "taxId":"FR123456789"
}


fastspring.builder.push(s)

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:

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:

Example 1:  Passing in Data for a U.S. Customer Via the Contact Object of a Secure Payload
 

{  
   "contact":{  
      "email":"ne1@all.com",
      "firstName":"Leeroy",
      "lastName":"Jenkins",
      "region":"US-CA",
      "postalCode":"93101"
   }
}

Example 2:  Passing in Language and Tax ID for an EU Customer Via a Secure Payload
 

{  
   "contact":{  
      "email":"ne1@all.com",
      "firstName":"Leeroy",
      "lastName":"Jenkins",
      "country":"DE"
   },
   "language":"en",
   "taxId":"DE1234567"
}

Data Precedence

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:

1. Secure Payload 
2. Data entered during checkout
3. Recognized / paymentContact data
4. Data from the payment method