Launch the Checkout UI

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

UI Configuration

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

// Present the checkout modal box and pass it an options object
ChargeAfter.checkout.present({
     // 1.
    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"
        }
    },

    // 2.
    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: 4297.0
    },

    // 3.
    onDataUpdate: function(updatedData, callback) {
        callback();
    },

    // 4.
    callback: function(token, data, error) {

    },
  
    // 5.
    channel: "e_commerce", //available values: e_commerce / in_store / call_center
  
    // 6. This object is OPTIONAL
    // preferences: { language: 'En' },
  
    // 7. This object is OPTIONAL
    // currency : "USD",
  
    // 8. This object is OPTIONAL
    // appSettings: {
    //     containerSelector: "#my-container-selector",
    // }
});

🚧

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 (1)

It is the recommended best practice to provide all the available customer information when launching the checkout.

Depending on the specific financial products used, the ConsumerDetails object might be optional or required. If the information is not provided, ChargeAfter will collect it from the consumer and inform the merchant via the onDataUpdate callback (see below)

📘

Billing and Shipping address

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

The CartDetails Object (2)

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

Name

Type

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

Optionally nested within each item object in the items field is the warranty field, defined in the format:

Name

Type

Format

name

string

Required

price

number

Required, currently restricted to USD only

sku

string

Required

Discounts

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

name

string

Required

amount

number

Required

Checkout Information

The following fields provide additional checkout information.

Name

Type

Format

totalAmount

number

Required, currently restricted to USD only

taxAmount

number

Required, currently restricted to USD only

shippingAmount

number

Required, currently restricted to USD only

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.

🚧

The totalAmount field represents the bottom line for this checkout, after adding tax and shipping cost, and subtracting any discounts.

The OnDataUpdate Callback (3)

  • In the onDataUpdate field you are asked to provide a function that will be called whenever any customer information is updated during the checkout flow.

Once you receive the updated information, you would need to process it (for instance, change the shipping address), and let ChargeAfter know of any subsequent changes to relevant values (such as tax amount, for instance, if the customer updated their address and change their state)

The callback function will be sent the following arguments:

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

Requirement

totalAmount

Required

taxAmount

Required

shippingAmount

Required

items

Required

consumerDetails

Required

discounts

Required

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 be 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”).

The Completion Callback (4)

  • The callback will be invoked upon checkout flow completion. The callback should accept 3 arguments (function callback(token, data, error))
    • token - a confirmation token that can be used to commit a charge. This parameter will be null if the user was not able to checkout successfully (in case of a decline or error)
    • data - information that was collected before and during the checkout flow. This object contains the following fields:

Name

Type

Description

consumerDetails

object

Non-sensitive consumer details that they entered during the checkout flow - use this information to process the order in the merchant’s systems.

lender

object

The lender that is behind the selected financing option, as detailed below

totalAmount

number

taxAmount

number

shippingAmount

number

The Lender Object

Name

Type

Description

id

string

The lender’s unique identifier in our system

name

string

The lender’s name

  • error - an error object containing details about the failure. This parameter will be 'undefined' in case of a successful checkout flow. The object type will be:
{
    "code": "Error code",
    "message": "Human readable description of the error"
}

Error codes:

Code

Description

BACK_TO_STORE

Consumer clicked the “Back to Store” button

CONSUMER_CANCELLED

Consumer intentionally closed the Checkout UI

CREATE_CHECKOUT_FAILED

Checkout creation or merchant settings fetch failed

BILLING_SHIPPING_MISMATCH

Billing and shipping address must be the same

GENERAL

Some general error occured (message should provide more information)

Preferences (5)

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

Language

language is an optional field of type String (not case sensitive), which represents the language in which the Checkout UI will be launched. 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 (6)

ChargeAfter fully supports multi-currency. The currency field is optional type of String, followed by the ISO 4217 code. The default value is USD.

App Settings (7)

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

Container Selector

containerSelector is an optional field of type String, which represents a CSS selector for the container element into which the Checkout UI should be rendered

  • If set, the Checkout UI will be rendered into the first element matching the provided selector (we use document.querySelector(containerSelector))
  • If not set, the Checkout UI will be rendered into a new div appended to the body (default behavior)

What’s Next
Did this page help you?