Setup a custom checkout

Step-by-step details for setting up a custom checkout provider for mason apps

Merchants can integrate a custom checkout provider for accelerated checkouts. This is powered with the support of draft orders and redirecting users to the checkout provider, post-creation of this draft order. The express checkout flow should support standard functionalities that are part of the default platform checkout flows e.g. Shopify checkout.

Pre-requisites for setup

The custom checkout provider should support the following.

Custom Discounts

  • Ability to pass custom discount to be applied on each item

Revenue Attribution

  • Ability to specify attribution details in properties & tags of the default order
    • Properties can be excluded from checkout UI (it's meant for internal bookkeeping)
    • Tags should be displayed

Setup guide for custom checkouts

Step 1: Register with mason

To initiate the integration process, the checkout provider needs to sign up with Mason and get access to their developer token. There is a 24 hr window for verification of the details. You will receive an email once the account is active. Once active you get your developer token from "Settings".


This token must be used for all future API calls.

All API calls made from mason to the checkout providers will have an HMAC signature generated using this token as a secret key in the Headers. You can use this Header value to verify the API calls are being made from Mason.

Step 2: Create your checkout app

Create an app with the mandatory details for the custom checkout to be available as an option for merchants. The provider needs to make a request to register the custom checkout app. This API validates the provider token. See API Reference

Step 3: Setup custom checkout in store

Stores can configure the custom checkout provider before adding any Mason app to their store. To be able to do this, they select their preferred provider and add the unique api_key for their store.

Once the merchant sets up the custom checkout we validate that the api_key with the provider.


Voila! That's it the merchant is all set to use your custom checkout.

Once the checkout is setup on any one app it's available as the default for all apps by Mason that go live on their stores.

Checkout flow

During checkout, when the shopper clicks checkout on any app we send over the draft order details to the "Create Checkout API" exposed by the custom checkout provider.

Merchant Validation Flow

Before calling create checkout API, we validate the api_key configured by the store. Once this is validated, we go to the checkout flow

API Contract


The Create Checkout API should be able to support the following input

  • API Key - To uniquely identify the Shopify store in their system
  • Items - containing details of the product & variant being bought & quantity
  • Discount - which needs to be applied to items
  • Properties - in each item containing the attribution information
  • Tags - to be shown with the order in the Shopify dashboard
  • Sig - This is the signature created using the payload below ( without the sig field ) and the common key shared between Mason & Checkout provider. To ensure data is not tempered, this key can be used by the checkout provider to validate the payload


Sample body

  	"api_key": <> # To uniquely identify the Shopify store in their system
    "items": [
            "id": "43497948545272", # variant id
            "quantity": 2, 
            "properties": [ # For attribution. Same as required by Shopify
              "name": "<key1>",
              "value": "<val1>"
            "line_price": {
                "sub_total": "699.00",
                "discounts": [{  
                  "code": "Discount title", # code for display
                  "amount": "75.00"  # pass per quantity value here
                  "code": "discount2",
                  "amount": "25.00"
    "discounts": [ 
            "type": "CUSTOM_DISCOUNT",
            "code": "Discount title",
            "amount": "150.00"            

    "tags": ["by mason", "Diwali Special"],
    "sig": <>

Sample Output

  "response": {
    "checkout_url": "<url where user should be redirected to for checkout>"

Validate Merchant


Sample Body

	"api_key": <>,
  "store_name": <>

Sample Output

# Success
  "status": "success", 
  "message": ""

# Error Case
  "status": "failure", 
  "message": "<reason for failure>"


  • Apps powered by the mason shopping engine show customer-specific discounts. Customers can directly checkout the products by clicking Get Discount

  • On clicking Get Discount, the mason engine computes the items to be purchased and passes them forward ( along with eligible discount, tags, etc ) to the express checkout service.
  • Express checkout service should return a checkout URL on which the user needs to be redirected to start the checkout flow


Shopify Draft Order API