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

Checkout

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
• Items -> line_price -> discounts - which needs to be applied to items
• Discounts - The combined discount value applied at each item level [ Can be used to show on the Checkout Page. Else show discount at each item level above ]
• 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

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", # per quantity
                "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" # all item level discount for all quantities combined            
        }
    ],

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

Sample Output

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

Validate Merchant

Sample

Sample Body

{
	"api_key": <>,
  "store_name": <>
}

Sample Output

# Success
200
{
  "status": "success", 
  "message": ""
}

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

Flow

• 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

Reference

Shopify Draft Order API

https://shopify.dev/docs/api/admin-rest/2023-04/resources/draftorder#post-draft-orders