Using Store Builder Library to Provide Customer Details

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.recognize() 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 E.U. Customer Via a Secure Payload
• Data Precedence

Using fastspring.builder.recognize() OR the paymentContact Object within the SBL Session

During checkout preparation (before 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 used to pre-fill checkout fields with the information.

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 is visible and editable during the checkout.

The purpose of these methods is 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, you can use the following methods 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 I.D. 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":"example-product-1",
      "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 is only 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 are hidden during the checkout, and only payment details will be collected. Here is a full list of fields that you can provide through the secure payload and their validation rules:

Important:  If details in the contact object of a secure payload do not pass validation, FastSpring treats those details 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 behavior 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 does not see the fields and cannot correct the problem. Therefore, if address validation is vital 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 checkbox 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 are 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 E.U. Customer Via a Secure Payload

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

Data Precedence

If FastSpring receives customer data from more than one source for the same session, FastSpring uses the following logic to decide which customer data applies to the order:

• If data has been provided (and validated) through a secure payload, it is used, and no data entry (other than payment details) will be allowed.
• If you have provided the data through the fastspring.builder.recognize() call or via the paymentContact object in an SBL session, it is used to pre-fill fields of the checkout flow. However, any data entered by the customer during the checkout overrides data supplied by these methods.
• If data has been returned to FastSpring from a payment provider such as Amazon Pay or PayPal, it is only 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 overrides 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