Launching the Checkout Experience

After loading the SDK, you may use it to launch the checkout UI, using the ChargeAfter.checkout.present function.

UI Configuration

To ensure a seamless customer experience, you will need to provide the customer and cart information in a JSON format to launch the checkout UI. An example can be found below:

// Present the checkout modal box and pass it an options object
ChargeAfter.checkout.present({
     // Consumer information
    consumerDetails: {
        firstName: "John",
        lastName: "Doe",
        email: "[email protected]",
        mobilePhoneNumber: "2124454545",
        merchantConsumerId: "merchant-internal-consumer-id",
        shippingAddress: {
            line1: "3 My Street",
            line2: "My Building, 4th floor",
            city: "New York",
            zipCode: "10019",
            state: "NY",
        },
        billingAddress: {
            line1: "3 My Street",
            line2: "My Building, 4th floor",
            city: "New York",
            zipCode: "10019",
            state: "NY",
        }
    },

    // Cart information
    cartDetails: {
        items: [
            {
                name: "Awesome Product",
                price: 1999.0,
                sku: "AWSMPRDCT",
                quantity: 2,
                leasable: true,
                productCategory: "Product category",
                warranty: {
                    name: "Awesome Warranty",
                    price: 100.0,
                    sku: "AWSMWRNTY"
                }
            }
        ],
        discounts: [
            {
                name: "Birthday discount",
                amount: 20
            }
        ],
        
        merchantOrderId: "<order id>", // OPTIONAL. Passed to interested lenders
        taxAmount: 199.0,
        shippingAmount: 19.0,
        totalAmount: 4296.0
    },

    // This callback allows you to process the result of customers data update 
    onDataUpdate: function(updatedData, callback) {
        callback({
          taxAmount: CALCULATED_TAX_AMOUNT,
          shippingAmount: CALCULATED_SHIPPING_AMOUNT,
          totalAmount: UPDATED_TOTAL_AMOUNT
        });
    },

    // This callback allows you to process the result of the checkout process
    // if onComplete function is provided on sdk init, both will fire
    callback: function(token, data, error) {
      
    },
  
    // Available values: E_COMMERCE / IN_STORE / CALL_CENTER
    channel: "E_COMMERCE",
  
    // This object is OPTIONAL
    preferences: { 
      language: 'En',
      country: 'US'
    },
  
    // This object is OPTIONAL
    currency : "USD",

    // This string is OPTIONAL. Will continue the prequalification to checkout.
    applicationId : "<id received from apply (prequalify)>",
  
    // This object is OPTIONAL
		filter: {
      creditTiers : ["SubPrime"], //possible value Prime, NearPrime, SubPrime
    }
  	
    // This object is OPTIONAL. This is used in the managed flow only.
    // managed: {
   	//	 token: 'XXXX-XXXX-XXXX-XXXX'
    // }
  
  	// This parameter is OPTIONAL. This is used to load the Checkout UI directly to a specific lender
    // lenderId : XXXXXXXXX,
});

import { prequalify, checkout } from "@chargeafter/payment-sdk";

await checkout({
  	config: {
        env: {
            name?: "production" | "sandbox", // defaults to "production"
            apiKey: "<your api key>",
        }
    },
    // This callback allows you to process the result of customers data update 
    onDataUpdate: async (updatedData, callback) => {
			// process updated data and trigger callback with updated cart amount
			// see "OnDataUpdate" section below.  
      callback({
        taxAmount: CALCULATED_TAX_AMOUNT,
        shippingAmount: CALCULATED_SHIPPING_AMOUNT,
        totalAmount: UPDATED_TOTAL_AMOUNT
      });
      
    },
     // Consumer information
    consumerDetails: {
        firstName: "John",
        lastName: "Doe",
        email: "[email protected]",
        mobilePhoneNumber: "2124454545",
        merchantConsumerId: "merchant-internal-consumer-id",
        shippingAddress: {
            line1: "3 My Street",
            line2: "My Building, 4th floor",
            city: "New York",
            zipCode: "10019",
            state: "NY",
        },
        billingAddress: {
            line1: "3 My Street",
            line2: "My Building, 4th floor",
            city: "New York",
            zipCode: "10019",
            state: "NY",
        }
    },

    // Cart information
    cartDetails: {
        items: [
            {
                name: "Awesome Product",
                price: 1999.0,
                sku: "AWSMPRDCT",
                quantity: 2,
                leasable: true,
                productCategory: "Product category",
                warranty: {
                    name: "Awesome Warranty",
                    price: 100.0,
                    sku: "AWSMWRNTY"
                }
            }
        ],
        discounts: [
            {
                name: "Birthday discount",
                amount: 20
            }
        ],
        
        merchantOrderId: "<order id>", // OPTIONAL. Passed to interested lenders
        taxAmount: 199.0,
        shippingAmount: 19.0,
        totalAmount: 4296.0
    },
  
    // Available values: E_COMMERCE / IN_STORE / CALL_CENTER
    channel: "E_COMMERCE",
  
    // This object is OPTIONAL
    preferences: { 
      language: 'En' 
    },
  
    // This object is OPTIONAL
    currency : "USD",

    // This string is OPTIONAL. Will continue the prequalification to checkout.
    applicationId : "<id received from apply (prequalify)>",
  
    // This object is OPTIONAL
    // appSettings: {
    //     containerSelector: "#my-container-selector",
    // },
  	
    // This object is OPTIONAL. This is used in the managed flow only.
    // managed: {
   	//	 token: 'XXXX-XXXX-XXXX-XXXX'
    // }
  
  	// This parameter is OPTIONAL. This is used to load the Checkout UI directly to a specific lender
    // lenderId : XXXXXXXXX,
});

🚧
In order to avoid any impact to the performance of your website, the script is loaded asynchronously. This means that the ChargeAfter.checkout.present() function might not be available immediately after document load.

The ConsumerDetails Object

It is recommended to provide all the available customer information when launching the ChargeAfter Checkout UI.

Depending on the specific financial products used, the ConsumerDetails object can be optional or required. If any of the consumer details are not provided when launching the checkout UI, ChargeAfter will collect it from the consumer and inform the merchant via the onDataUpdate callback (see below).

The following details can and should be provided:

Name	Type	Description	Required/Optional	Validations
firstName	string	Consumer first name. For example: "John"	Required Is optional when onDataUpdate callback function is used	All letters, spaces and hyphens.
lastName	string	Consumer last name. For example: "Doe"	Required Is optional when onDataUpdate callback function is used	All letters, space,s and hyphens.
email	string	Consumer email. Should be a valid email format. For example: "[email protected]"	Required Is optional when onDataUpdate callback function is used	All letters, hyphens, numbers, symbols, of periods.
mobilePhoneNumber	string	Consumer phone number. For example: "2124454545"	Required Is optional when onDataUpdate callback function is used	Numbers. No spaces, periods, or symbols are allowed.
merchantConsumerId	string	The merchant identifier for the consumer	Required Is optional when onDataUpdate callback function is used
shippingAddress	object	The shipping address object. See more info in Address object.	Required Is optional when onDataUpdate callback function is used	See more info in Address object.
billingAddress	object	The billing address object. See more info in Address object.	Required Is optional when onDataUpdate callback function is used	See more info in Address object.

Address object:

Name	Type	Description	Required/Optional	Validation
line1	string	Address line 1	Required	All letters, spaces, numbers, hyphen, hash symbol (#) and periods
line2	string	Address line 2	Optional	All letters, spaces, numbers, hyphen, hash symbol (#) and periods
city	string	City name. For example: "New York" (US) or “Edmonton” (CA)	Required	All letters, spaces, numbers and hyphens.
zipCode	string	ZipCode / Postal Code. For example: "10019" or "10019-1232" / “A1A 1A1”	Required
state	string	State/Province. The value to be set is either 2 character state code or State/Province name. For example: "New York"/“Alberta”	Required

🚧
Billing and Shipping address
As an anti-fraud measure, billingAddress and shippingAddress (if provided) must be the same, otherwise, the checkout will not work. If the order is an in-store pickup, please provide only the billing address.

The cartDetails Object

Cart Details is an array that contains various elements of the cart:

Name	Type	Required/Optional, Format
items	array	Required
discounts	array	Optional
merchantOrderId	string	Optional
taxAmount	number	Required
shippingAmount	number	Required
totalAmount	number	Required

Items is an array that contains the details of every item in the cart:

Name	Type	Required/Optional, Format
name	string	Required
price	number	Required
sku	string	Required
quantity	number	Required, integer
leasable	boolean	True if the specific item is leasable. False or undefined if not. If an item is not leasable, some leasing options will not be available to pay for the order
productCategory	string	Product category or full taxonomy path
warranty	object	Optional (see Warranty section below)

Discounts

The discounts field is an optional array that consists of one or more of applied discounts:

Name	Type	Required/Optional
name	string	Required
amount	number	Required

Warranty

Optionally nested within each item object, is the warranty object. If added, then all fields below are required as shown:

Name	Type	Required/Optional
name	string	Required
price	number	Required
sku	string	Required

🚧
All items from your website's cart must be included in the cartDetails portion of the code and must be equal to the total amount of the cart. This may include warranty, discounts, fees (recycling, installation, delivery, etc.)
Amount/price fields are restricted to present up to 2 decimal places. In cases where a number has more than 2 decimal places, ChargeAfter will automatically round it up to the nearest whole cent.
Currency for these fields is determined by merchant country.
The totalAmount field represents the bottom line for this checkout, after adding tax and shipping cost, and subtracting any discounts.

The OnDataUpdate Callback

In the onDataUpdate field we enable to provide a function that will be called whenever consumer information is changed during the checkout flow - which might require cart changes such as shipping, discounts etc.

The process works as follows:
Consumer makes changes to their personal information such as their shipping address state in the ChargeAfter modal, ChargeAfter triggers the callback with the updated details in the updatedData object, merchant is expected to calculate the new cart, and return the updated object (or trigger the callback argument in case of async)

updatedData

An object that is very similar to the options object that is provided initially in the ChargeAfter.checkout.present(opt) call. It contains the updated checkout details, and it is composed of the following fields (see the full object above for further details):

Name	Type
totalAmount	Number
taxAmount	Number
shippingAmount	Number
items	Array
consumerDetails	Object
discounts	Array

callback

Once the data passed back to the merchant using this callback has been processed, the merchant should return the refreshed information including any changes back to ChargeAfter.

The "onDataUpdate" function can return a value. However, if you choose not to return a value, you would need to call the provided "callback" function later on to pass the updated information back to ChargeAfter.

The data update should have the following structure:

Name	Requirement
shippingAmount	Optional
taxAmount	Optional
totalAmount	Optional

Examples
If you want to update the shipping and tax amount depending on the entered ZIP code, the function can be implemented like this:

function(updatedData, callback) {
      var zipCode = updatedData.consumerDetails.billingAddress.zipCode;
      if (zipCode) {

          // ... call backend to calculate updated shipping and tax amount,
          // and invoke callback with result

          callback({
              taxAmount: CALCULATED_TAX_AMOUNT,
              shippingAmount: CALCULATED_SHIPPING_AMOUNT,
              totalAmount: UPDATED_TOTAL_AMOUNT
          });
      } else {
          // nothing to update, so just invoke callback with no parameters
          callback();

          // alternatively (see next paragraph), just return an empty object
          // return {};
      }

      // no need to return, as we're invoking the callback above
  }

Alternatively, this function may return a value immediately. In this case, there’s no need to call the callback function. If no value is returned (like in the example above), then the callback function is expected to be invoked.
For example, if the updated checkout details are available on the spot, then simply return it:

function(updatedData, callback) {
      var zipCode = updatedData.consumerDetails.billingAddress.zipCode;
      if (zipCode) {
          // calculate updated shipping and tax amount and return it
          return {
              taxAmount: CALCULATED_TAX_AMOUNT,
              shippingAmount: CALCULATED_SHIPPING_AMOUNT,
              totalAmount: UPDATED_TOTAL_AMOUNT
          };
      } else {
          // nothing to update, but making sure to return an object
          return {};
      }
  }

🚧
Do not forget to either immediately return an object from the onDataUpdate function, or invoke the callback function. The merchant’s website response is a condition for moving forward with the checkout flow.
Remember to pass the correct types in the callback. For example, amount fields (like totalAmount) are typically numbers, and not strings (i.e. 45.9 rather than “45.9”).

Channel

The channelobject is an optional parameter that indicates where the merchant initiated the flow (E_COMMERCE / IN_STORE / CALL_CENTER)

Preferences

The preferences object is optional, and has the following fields:

Language - to specify the language in which the Checkout UI will be launched. The is an optional filed of String type. The expected value should consist of two letters representing the language. The default value is En and other languages currently supported are:

English - En
French - Fr

Currency - to specify currencies in fields and variables. The is an optional filed of String type, followed by the ISO 4217 code. ChargeAfter provides the multi-currency functionality, which allows merchants to accept payments in a variety of currencies for the buyer's and merchant's convenience. The default value is USD.
Country - to specify countries and regions supported by ChargeAfter in fields and variables. The is an optional filed of String type, followed by the ISO-3166 country codes. The default value is US.

Launching the Checkout Experience

UI Configuration

🚧

The ConsumerDetails Object

🚧
Billing and Shipping address

The cartDetails Object

Discounts

Warranty

🚧
All items from your website's cart must be included in the cartDetails portion of the code and must be equal to the total amount of the cart. This may include warranty, discounts, fees (recycling, installation, delivery, etc.)

The OnDataUpdate Callback

🚧
Do not forget to either immediately return an object from the onDataUpdate function, or invoke the callback function. The merchant’s website response is a condition for moving forward with the checkout flow.

Channel

Preferences

UI Configuration

🚧

The ConsumerDetails Object

🚧Billing and Shipping address

The cartDetails Object

Discounts

Warranty

🚧All items from your website's cart must be included in the cartDetails portion of the code and must be equal to the total amount of the cart. This may include warranty, discounts, fees (recycling, installation, delivery, etc.)

The OnDataUpdate Callback

🚧Do not forget to either immediately return an object from the onDataUpdate function, or invoke the callback function. The merchant’s website response is a condition for moving forward with the checkout flow.

Channel

Preferences

🚧
Billing and Shipping address

🚧
All items from your website's cart must be included in the cartDetails portion of the code and must be equal to the total amount of the cart. This may include warranty, discounts, fees (recycling, installation, delivery, etc.)

🚧
Do not forget to either immediately return an object from the onDataUpdate function, or invoke the callback function. The merchant’s website response is a condition for moving forward with the checkout flow.