Skip to main content

OneClick checkout integration guide

Appmaker provides a way to integrate one-click checkout with your app. This guide will help you understand how to integrate one-click checkout with your app.

Filters and Functions​

Appmaker provides the following filters and functions to integrate one-click checkout with your app:

before-open-checkout - This function is triggered before opening the checkout page. For further details on this function, refer to the before-open-checkout documentation.

webview-custom-url-filters - This filter is used to filter the URLs that are passed inside the webview. For further details on this filter, refer to the webview-custom-url-filters documentation.

Steps to integrate one-click checkout​

To integrate one-click checkout , follow these steps:

  1. Register the function hooks: Register the function before-open-checkout on the activate Function of your extension or theme. 
import {appmaker, appmakerFunctions} from '@appmaker-xyz/core';
import { getCheckout } from './lib/api.js';
import { customPaymentSchema } from './lib/oneclick.js';

export function activate() {
  appmakerFunctions.registerAppmakerFn({
    trigger: 'before-open-checkout', // hook to trigger before opening checkout
    namespace: 'oneclick-update-checkout',// namespace for the function
    fn: getCheckout, // map to the function that will be called
  });
  appmaker.addFilter(
    'webview-custom-url-filters', // hook to add custom url filters
    'oneclick-payment-url-filters', // namespace for the filter
    (currentFilters) => {
      return [...currentFilters, customPaymentSchema]; // add the filter to the list of filters
    },
  );
}
  1. Implement the function: Implement the function that will be called when the before-open-checkout hook is triggered. This function should return the modified parameters. For example, you can use this function to redirect the user to a different page rather than the default checkout page.
import { getOneClickCheckoutUrl } from './oneclick'; // get the checkout url from your api


export async function getCheckout({ currentCart, accessToken }) {
    console.log('currentCart',currentCart);
  if (!currentCart) {
    return null;
  } 
 //get the checkout url from your api
  const checkoutUrl = await getOneClickCheckoutUrl(
    currentCart  
  );  
console.log('checkoutUrl',checkoutUrl);
  return {   
    action: {
      action: 'OPEN_INAPP_PAGE',
      pageId: 'OneClickCheckout',
      pageData: {
        checkoutUrl: checkoutUrl,//pass the checkout url to the page
      },
    },
  };
}

Here we are opening a custom checkout page OneClickCheckout which we have to create in next step and passing the checkout url to the page. We are loading the webview URL in the custom page.

  1. Create a custom page: Create a custom page in your extension or theme. This page will be used to display the checkout page. Let's create oneClickCheckout page in your extension.
export function isOrderCompleted(url) {   
    const regexThankyouPage = /orders\/(.*)$/;
    const isAuthenticatePage = /authenticate/;
    return regexThankyouPage.test(url) && !isAuthenticatePage.test(url);
  }
  
  const onUrlChange = (url, onAction) => {   
    if (isOrderCompleted(url)) {
        const data = getCheckoutData(); // get the checkout data from your order placed API . 
      onAction({
        action: 'SET_ORDER_COMPLETE',
        params: {
            checkout: data,
        },
      });
    }
  
    return true;
  };
  
  // This function is called when the back button is pressed
  const getOnBackButtonPressFunction = ({
    webview,
    onAction,
    canGoBack,
    navigation,
    currentUrl,
  }) => {
    return () => {
      // Should return a function
      if (isOrderCompleted(currentUrl)) {
        onAction({
          action: 'RESET',
          replacePage: true,
        });
      } else if (canGoBack) {
        webview.current.goBack();
      } else {
        navigation.goBack();
      }
return true;
    };
  };
  
  const OneClickCheckout = {
    id: 'checkout',
    status: 'active',
    title: 'Checkout',
    attributes: {
      renderType: 'normal',
      contentContainerStyle: { flex: 1 },
      rootContainerStyle: { flex: 1 },
      backButtonIconName: 'x',
    },
    blocks: [
      {
        name: 'appmaker/webview',
        isValid: true,
        clientId: 'f496b61a-56c9-4862-b4a5-d5438bb530aa',
        attributes: {
          loadingLayout: 'home',
          urlListener: onUrlChange, // this function is called when the url changes and can be used to detect when the order is completed
          getOnBackButtonPressFunction, // back button behaviour
          source: {
            uri: '{{blockData.checkoutUrl}}',
          },
        },
      },
    ],
  };
  export default OneClickCheckout;

The custom page has one block of type appmaker/webview which is used to load the checkout page. The urlListener function is called when the URL changes and can be used to detect when the order is completed. The getOnBackButtonPressFunction function is called when the back button is pressed. This function is used to handle the back button behaviour.

Additional and important note: Need to send the order data to the action SET_ORDER_COMPLETE when the order is completed. This data will be used to send the relevant data to checkout completed event. The data has to be in a required format.

Format:

{
  "id": "gid://shopify/Checkout/fecfb108e39c2576698093f3d47c6623?key=f9811df98a255a6f7e48fd97a8e9a792",
  "totalPrice": { "amount": "549.0", "currencyCode": "INR" },
  "lineItems": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/CheckoutLineItem/427763830621660?checkout=fecfb108e39c2576698093f3d47c6623",
          "title": "test FAB 5 Glossy 5 in 1 Lipstick 7.5 Gm",
          "variant": {
            "id": "gid://shopify/ProductVariant/42776383062166",
            "product": {
              "id": "gid://shopify/Product/7820752486550",
              "vendor": "test Cosmetics"
            },
            "price": { "amount": "549.0", "currencyCode": "INR" },
            "image": {
              "url": "https://cdn.shopify.com/s/files/1/0597/9422/7350/files/test_Fab5Gloss_ListingPI_01_250x.jpg?v=1696499518"
            }
          },
          "quantity": 1
        }
      },
      {
        "node": {
          "id": "gid://shopify/CheckoutLineItem/429380034561500?checkout=fecfb108e39c2576698093f3d47c6623",
          "title": "product test",
          "variant": {
            "id": "gid://shopify/ProductVariant/42938003456150",
            "product": {
              "id": "gid://shopify/Product/7875757441174",
              "vendor": "8ml"
            },
            "price": { "amount": "0.0", "currencyCode": "INR" },
            "image": {
              "url": "https://cdn.shopify.com/s/files/1/0597/9422/7350/files/test_01_250x.jpg?v=1696499518"
            }
          },
          "quantity": 1
        }
      }
    ]
  },
  "order": {
    "id": "gid://shopify/Order/5445579931798?key=98f3a1edc21e4e02d9f351799a181061",
    "orderNumber": 954722,
    "name": "2122954722",
    "shippingAddress": {
      "firstName": "john",
      "lastName": "doee",
      "name": "john",
      "phone": "123456788"
    },
    "email": "[email protected]"
  }
}
  1. getOneClickCheckoutUrl function: This function is used to get the checkout URL from your API. You can use this function to get the checkout URL from your API.
export const getOneClickCheckoutUrl = async (
    checkoutObject,   
  ) => {
    const url = 'https://appmaker.xyz/'; // replace this with your url
    return url;
  };

  // you can filter the urls that you get in checkout page here
export const customPaymentSchema = {
  id: 'oneclick-payment-schema',
  regex: [
    /phonepe:\/\/pay\?.*/i,
    /paytm:\/\/upi\/pay?.*/i,
    /paytmmp:\/\/pay?.*/i,
    /upi:\/\/pay?.*/i,
    /tez:\/\/upi\/pay?.*/i,
  ],
  action: (url) => {
    return {
      action: 'OPEN_URL',
      params: {
        url,
      },
    };
  },
};

customPaymentSchema is used to filter the URLs that are passed inside the webview. You can use this filter to filter the URLs that are passed inside the webview.

  1. Now when you click on the checkout button, it will be navigated to the Url that you have returned in the getOneClickCheckoutUrl function. You can modify the checkout page as per your requirement.

Sample template for the checkout page can be found here.