API Reference

Caddi Popup and <iframe> Workflows

This page will help you get started with integrating Caddi into your frontend checkout.

The Caddi.launch() functionality provided by caddi.js allows you to launch the Caddi popup workflow or iframe workflow. If you use the popup workflow, your merchant checkout page will appear darkened in the background on a desktop view while the customer is completing the Caddipay checkout. If you use the iframe workflow then you are free to implement any page appearance changes that make sense for your site.

During the checkout process the customer will be walked through a series of steps to identify themselves, confirm they qualify for credit, and take their initial payment method and details. Upon abandoning the process, receiving an error or upon successful completion, they will be returned to your checkout.

  1. If the customer completes the Caddi popup workflow successfully, the orderToken and the orderStatus CREATED will be passed to the onComplete method, at which stage you should allow the customer to confirm their order. Additionally this method will be passed the properties phoneNumber containing the customer's unique phone number, and downPayment containing the initial amount that will be paid by the customer upon later calling /v1/confirm-order. If you have opted-in to receiving additional customer data then you will also receive a customer property with more customer details. See below for further information.
  2. If the customer does not successfully complete or cancels the Caddi popup workflow, the orderToken and the orderStatus CANCELLED will be passed to the onComplete method. You should ask the customer to retry, or select an alternative payment method.
  3. If an unexpected problem occurs, the object passed to onComplete will contain a property error which will be a string describing the error. Though the orderStatus should always be ERROR in this instance, it is advisable to check for any orderStatus not equal to CREATED or CANCELLED as per the below example.
  4. When the Caddipay iframe is closed for any reason, Caddi.onClosed will be called.

If the CREATED status is received, the Merchant website should enable the user to press a button finalizing their order.

If the CANCELLED status is received, the Merchant website should show an appropriate message asking the customer to retry the Caddi process or select an alternative payment method.

If the ERROR status or any other status is received, the Merchant website should encourage the customer to select an alternative payment method.

Caddi.launch

launch(orderToken, optionsopt)

Launch the Caddipay checkout
Parameters:
Name Type Attributes Description
orderToken string The orderToken return from the /v1/create-order API
options object <optional>
 Launch options
Properties
Name Type Attributes Description
iframeContainerId string <optional>
 If provided, launch the Caddipay checkout in an iframe inside an element with this id

Example implementation

<html>
  <head>
    // MERCHANT_ID below should be replaced with the public identifier provided to you by Caddi
    // Replace src with https://api-sandbox.caddipay.com/v1/caddi.js?merchant=MERCHANT_ID in your test environments
    <script id="caddijs" type="text/javascript" src="https://api.caddipay.com/v1/caddi.js?merchant=MERCHANT_ID" async></script>
  </head>
  <body>
    <button id="caddi-payment">
      Continue to Payment
    </button>
    <div id="caddi-container"><!-- iframe checkout container --></div>
    <script type="text/javascript">
      var script = document.querySelector("#caddijs");
      script.addEventListener('load', function() {
	      document.getElementById("caddi-payment").addEventListener("click", function() {
	        // ORDER_TOKEN is retrieved on your server uniquely for each checkout
	        // See POST /v1/create-order
	        Caddi.launch("ORDER_TOKEN");
	        // iframe version:
	        // Caddi.launch("ORDER_TOKEN", {iframeContainerId: "caddi-container"});
	      });
	      Caddi.onComplete = function(data) {
	        if (data.orderStatus === "CREATED") {
	          // The customer has confirmed payment details and schedule with Caddi
	          // At this point, you may show an option for completing checkout
              // This data object will additionally contain: orderToken, phoneNumber, downPayment
	        } else if (data.orderStatus === "CANCELLED") {
	          // The customer did not provide details or closed the popup
	          // Ask them to retry, or select an alternative payment method
	        } else {
	          // Another error occurred which you should log
	          // See data.error for further details (this will be a string describing the error)
	        }
	      };
        Caddi.onClosed = function() {
          // If this function is defined, it will be called when the customer closes the Caddipay
          // window or iframe.          
        };
      });
    </script>
  </body>
</html>

Caddi.onComplete()

Caddi.onComplete = (data: OnCompleteData) => void

type OnCompleteData =
  | {
      orderStatus: 'CANCELLED'
      orderToken: string
    }
  | {
      orderStatus: 'CREATED'
      orderToken: string
      phoneNumber?: string
      downPayment?: number
      customer?: Customer
    }
  | {
      orderStatus: 'ERROR'
      error: string
    }

type Customer = {
  firstName: string
  lastName: string
  email: string
  residentialAddress: {
    line1: string
    line2?: null | string
    city: string
    state: string
    zip: string
    country: string
  }
}

📘

Testing

Ensure you are using <https://api-sandbox.caddipay.com/v1/caddi.js> in your test environments. This will allow you to test the Caddi popup workflow without requiring real customer or payment details.