# Checkout integration

Important
This page describes a necessary step in the **[direct API integration](/developer-portal/direct-integration-landing)** process.

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

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

Before beginning, you may wish to familiarise yourself with the checkout workflow in the **[technical diagrams](/developer-portal/technical-diagrams#checkout-workflow)** documentation pages.

## 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 April. **Never share your Secret API Key.**

April uses an [authentication key header](/developer-portal/api-reference/#authentication) to authenticate API calls.

## Step 2 - Displaying the April 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.


```javascript
<div id="april-cont"></div>
<script src="https://checkout-v3.au.meetapril.io/v3/checkout-v3.0.0.min.js"></script>
<script>
    const AprilCheckout = window.AprilCheckout.createCheckout();
    AprilCheckout.init({
        publicKey: "live_pk_xxxxxxxxxxxxxxxxxxxxx",
        email: "buyer@gmail.com",  // optional
        customerToken: "",  // optional, signed in customer token.
        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 */
        isB2B: false, // optional, B2B only
        hideB2BUsageScopeOptions: false, // optional, B2B only, hide "Save card for" options
        paymentToken: function(token, paymentData) { /* Once the checkout is complete this function will be called.
            Use the `token` on your server to complete the transaction. */
        }
    });
    AprilCheckout.render({
        elementId: "april-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 */
        hideApplePay: false, // Optional, hides the Apple Pay button
        hideGooglePay: false, // Optional, hides the Google Pay button
        primaryColor: '#793DE4' // Optional, theme primary color (HEX)
    });
    AprilCheckout.errorHandler(function (err) {
        // Handle errors
    });
    AprilCheckout.eventHandler(function (event) {
        // Handle events
    });
</script>
```

### AprilCheckout.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](/developer-portal/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 | Signed in customer token. |
| `isB2B` | Optional | B2B only |
| `hideB2BUsageScopeOptions` | Optional | B2B only, hide "Save card for" options. |


### AprilCheckout.render inputs:

| Parameter | Required/Optional | Description |
|  --- | --- | --- |
| `elementId` | Required | The HTML element ID of the checkout. For example, “april-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 payment) 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. |
| `hideApplePay` | Optional | Hides the Apple Pay button. |
| `hideGooglePay` | Optional | Hides the Google Pay button. |


### Outputs:

The April checkout will be rendered onto the web page.

## Step 3 - Integrating the checkout

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

| Method | Description |
|  --- | --- |
| `init()` | Initialises the AprilCheckout. |
| `render()` | Renders the AprilCheckout form. |
| `reset()` | Will reset the April 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 April form. |
| `submit()` | Initiates the submit process. In full payments, April will start processing card information and return the paymentToken via the paymentToken callback. In Buy Now Pay Later payments, April 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: `AprilCheckout.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 AprilCheckout by registering a callback function via the


```javascript
AprilCheckout.errorHandler(function(err) { // Process });
```

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


```javascript
{ message: "error reason" }
```

### Event handler

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


```javascript
AprilCheckout.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:


```javascript
{ eventName: "event_name", eventData: { key: "value" } }
```

April currently supports the following events:

- **Toggled payment type**



```JSON
    {
        eventName: "limepay_toggled_payment_type",
        eventData: {
            paymentType: "payplan"
        }
    }
```

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

- **Payment plan terms accepted**



```JSON
    {
        eventName: "limepay_payment_plan_terms_accepted"
    }
```

- **First payment amount charged**



```JSON
    {
        eventName: "limepay_first_payment_amount_changed",
        eventData: {
            previousFirstPaymentAmount: 2500,
            updatedFirstPaymentAmount: 4500,
            currency: "AUD"
        }
    }
```

### The `paymentData` object

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


```typescript
paymentToken: (token: string, paymentData: PaymentData) => { }
```


```typescript
type CardPaymentSource = {
  cardPaymentSourceId?: string;
  last4: string;
  cardBin: string;
  brand: '' | 'American Express' | 'MasterCard' | 'Visa';
  funding: 'credit' | 'debit' | 'chargecard' | 'prepaid' | 'deferreddebit' | 'unknown';
  expMonth: number;
  expYear: number;
  country: string;
}
type PaymentSource = {
  cardPaymentSource?: CardPaymentSource;
}
type 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](/developer-portal/payments)** to enable correct transaction functionality.

Configure **[error and payment action handling](/developer-portal/error-handling)**.

Visit the **[testing](/developer-portal/testing)** documentation page to confirm the integration is fully functional.

Return to the initial **[direct API integration](/developer-portal/direct-integration-landing)** landing page.

br
br
**[Return to documentation home](/).**