Checkout integration

Important

This page describes a necessary step in the direct API integration process.

If you are using an e-commerce platform such as Magento, Woocommerce or Salesforce, this section is not relevant to your integration of Limepay.

The first stage in integrating the standard Limepay package is integrating the visible checkout onto the web store page.

Step 1 - Finding your API access keys

Open your merchant dashboard and find your unique Publishable and Secret API Keys.

Your Publishable API Key is used for all outgoing communications from the frontend of your website and checkout page, while your Secret API Key is used for server-side communication with Limepay. Never share your Secret API Key.

Limepay uses an authentication key header to authenticate API calls.

Step 2 - Displaying the Limepay checkout

Insert the javascript below into your checkout page and replace the publicKey: entry “live_pk_xxxxxxxxxxxxxxxxxxxxx” with your unique Publishable API Key of the same format.

Copy
Copied
<div id="limepay-cont"></div>
<script src="https://checkout-v3.limepay.com.au/v3/checkout-v3.0.0.min.js"></script>
<script>
    var LimepayCheckout = window.LimepayCheckout.createCheckout();
    LimepayCheckout.init({
        publicKey: "live_pk_xxxxxxxxxxxxxxxxxxxxx",
        email: "buyer@gmail.com",  // optional
        customerToken: "",  // optional, note this is used instead of email for B2B and in-store flows.
        customerFirstName: "John",  // optional
        customerMiddleName: "",  // optional
        customerLastName: "Doe",  // optional
        customerResidentialAddress: "283 Clarence Street, Sydney NSW 2000",  // optional
        hidePayLaterOption: false,  /* optional (default false),
            can pass (true or false), it will show/hide the BNPL option */
        paymentToken: function(token, paymentData) { /* Once the checkout is complete this function will be called.
            Use the `token` on your server to complete the transaction. */
        }
    });
    LimepayCheckout.render({
        elementId: "limepay-cont",
        currency: "AUD",
        amount: 15000,  // should be in cents (integer)
        paymentType: "paycard", /* Optional (default "paycard"),
            selected payment option ("paycard" or "payplan") */
        showPayNow: true,  /* Optional,
            enables Pay Now button for pay by card option */
        showPayPlanSubmit: true,  /* Optional,
            enables Submit Payment Plan button for split payments option */
        primaryColor: '#793DE4' // Optional, theme primary color (HEX)
    });
    LimepayCheckout.errorHandler(function (err) {
        // Handle errors
    });
    LimepayCheckout.eventHandler(function (event) {
        // Handle events
    });
</script>

LimepayCheckout.init inputs:

Parameter Required/Optional Description
publicKey Required Merchant’s unique Publishable API Key.
hidePayLaterOption Required Enter “true” or “false” (default is “true”). Shows, hides “pay in instalments” option.
paymentToken Required This is a callback Javascript function that your integration must define. It will be called when the customer has completed with the checkout and a paymentToken is ready to be used. Using the paymentToken will be explained in the processing payments pages.
email Optional Customer email, populated from previously entered information. If set, this can aid in notifying up front if the customer is eligible to pay in instalments.
customerFirstName Optional Populated from previously entered information.
customerMiddleName Optional Populated from previously entered information.
customerLastName Optional Populated from previously entered information.
customerResidentialAddress Optional Populated from previously entered information.
customerToken Optional, used in place of email for B2B configurations and virtual payments.

LimepayCheckout.render inputs:

Parameter Required/Optional Description
elementId Required The HTML element ID of the checkout. For example, “limepay-cont”.
currency Required Enter “AUD” or “NZD”. Currency the transaction will be processed in.
amount Required The transaction amount in minor currency units (e.g. cents, where $1 is represented as 100).
paymentType Required Enter “paycard” (one time payemnt) or “payplan” (pay in instalments) to select payment option (default is “paycard”).
showPayNow Optional Enter “true” to show Pay Now button for paycard option.
showPayPlanSubmit Optional Enter “true” to show Submit Payment Plan button for “pay in instalments” option.

Outputs:

The Limepay checkout will be rendered onto the web page.

Step 3 - Integrating the checkout

Implement the following methods, as required, to integrate the Limepay checkout into the merchant's store:

Method Description
init() Initialises the LimepayCheckout.
render() Renders the LimepayCheckout form.
reset() Will reset the Limepay form. The customer will be presented with the initial step. Any created payment plans will be discarded. In situations where there is a "card_declined" error thrown at the time the merchant tries to get paid for the order (Step 4), we recommend using this function to reset the Limepay form.
submit() Initiates the submit process. In full payments, Limepay will start processing card information and return the paymentToken via the paymentToken callback. In Buy Now Pay Later payments, Limepay will set up the payment plan and return the paymentToken via the paymentToken callback.
update() Allows the merchant to update the transaction amount. For instance: LimepayCheckout.update({amount: 24600});.
errorHandler() Will accept a function which will be called in the event a checkout input validation error has occurred.
eventHandler() Will accept a function which will be called when a selected list of events takes place.
hide() and show() Calling these methods allow you to toggle the display of the checkout UI. This can be useful when providing the logic for the paymentToken callback. For example, you could hide the checkout until you get a response from a server-side request.

Error handler

The host application can listen to any errors occurring within the LimepayCheckout by registering a callback function via the

Copy
Copied
LimepayCheckout.errorHandler(function(err) { // Process });

method. The callback function is passed the single argument err - a JSON object with the following structure:

Copy
Copied
{ message: "error reason" }

Event handler

The LimepayCheckout generates events which the host application can listen to through a callback function. Use

Copy
Copied
LimepayCheckout.eventHandler(function(event) { // Process });

to register a callback function for event handling. The callback function is passed the single argument event - a JSON object with following structure:

Copy
Copied
{ eventName: "event_name", eventData: { key: "value" } }

Limepay currently supports the following events:

  • Toggled payment type
    Copy
    Copied
    {
        eventName: "limepay_toggled_payment_type",
        eventData: {
            paymentType: "payplan"
        }
    }
    info

    PaymentType is either payplan (instalments) or paycard (full payment)

  • Payment plan terms accepted
    Copy
    Copied
    {
        eventName: "limepay_payment_plan_terms_accepted"
    }
  • First payment amount charged
    Copy
    Copied
    {
        eventName: "limepay_first_payment_amount_changed",
        eventData: {
            previousFirstPaymentAmount: 2500,
            updatedFirstPaymentAmount: 4500,
            currency: "AUD"
        }
    }

The paymentData object

The Limepay checkout will also pass a second paymentData argument to the paymentToken callback containing additional payment details:

Copy
Copied
paymentToken: (token: string, paymentData: PaymentData) => { }
Copy
Copied
interface CardPaymentSource {
  cardPaymentSourceId: string;
  last4: string;
  brand: '' | 'American Express' | 'MasterCard' | 'Visa';
  expMonth: number;
  expYear: number;
  country: string;
}
interface PaymentSource {
  cardPaymentSource?: CardPaymentSource;
}
interface PaymentData {
  amount: number;
  currency: 'AUD' | 'NZD';
  payType: 'PayInFull' | 'PayPlan';
  paymentMethodType: 'Card' | 'NetworkToken' | 'DirectDebit';
  paymentSource?: PaymentSource;
}

What's next?

Important

The integration is not yet finished. These next steps must be completed to gain full functionality.

Configure payment processing to enable correct transaction functionality.

Configure error and payment action handling.

Visit the testing documentation page to confirm the integration is fully functional.

Return to the initial direct API integration landing page.



Return to documentation home.

Copyright © April Solutions 2023. All right reserved.