Release NotesAnnouncementsVideosBlog
Guides

Create a checkout session request

North America—United States and Canada

Use the Create checkout endpoint to request a new checkout session for a customer transaction. Hosted checkout sessions are intended to be short-lived and expire 15 minutes after creation.

Prerequisites

  1. Create a global developer account and select the Hosted Checkout checkbox in the Ecommerce Settings.
  2. Generate the hosted checkout private token and note the merchantId When the merchant integrates hosted checkout on their website, the token is automatically set up with the required Clover permissions.
  3. Generate an apiAccesskey—First generate an OAuth access_token and then use it to generate an Ecommerce API key (PAKMS key). This is required for tokenization.

Create a checkout session request

A hosted checkout session request must include an empty customer object and a shoppingCart with one or more items. The shoppingCart provides information about the item or items being purchased.

  1. Send a POST request to the /invoicingcheckoutservice/v1/checkouts endpoint.
  2. Enter the required parameters in the shoppingCart object in the lineItems array of objects:
  • note—Description or note related to the item, for example, additional information if item variants are available for purchase.
  • price—Unit price of the item.
  • name—Item name.
  • unitQty—Item quantity.
  1. Enter the required customer parameters as follows:
  • If the customer information feature is enabled for the merchant (HCO_CUSTOMER_INFO_FEATURE_ENABLED) then enter:
    • firstName—Customer's first name.
    • lastName—Customer's last name.
    • email—Email address to receive a receipt when the checkout process is finished.
  • If the merchant has not enabled the customer information feature, then enter only one of the following: firstName lastName or email.
  1. Optional. Enter the merchant's tax rate in the taxRates array. See Add taxes to transactions.
  • name—Tax name.
  • rate—Tax rate, as an integer where a 10% tax is defined as 1000000.
  1. In the header X-Clover-Merchant-Id, enter the merchantId.
  2. Set the authorization: Bearer as your OAuth-generated access_token.

The response includes the following elements:

  • href—URL for the checkout session.
  • checkoutSessionId—Unique session identifier.
  • createdTime—Time the session was created (in Unix time).
  • expirationTime—Time when the checkout session will expire (in Unix time).

Request and response example—Hosted checkout session

curl --request POST \
     --url 'https://apisandbox.dev.clover.com/invoicingcheckoutservice/v1/checkouts' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'X-Clover-Merchant-Id: {merchantId}' \
     --data '{
       "customer": {
         "email": "[email protected]",
         "firstName": "Alex",
         "lastName": "Smith",
         "phoneNumber": "5555551010"
       },
       "shoppingCart": {
         "lineItems": [
           {
             "note": "No pulp",
             "name": "Orange juice",
             "price": 600,
             "unitQty": 2
           },
           {
             "note": "Non-dairy",
             "name": "French toast",
             "price": 1200,
             "unitQty": 1
           }
         ]
       }
     }'

{
    "href": "https://example.com/checkout/59283e4a-cade-4aba-b99d-e4d6c7c4b81a",
    "checkoutSessionId": "59283e4a-cade-4aba-b99d-e4d6c7c4b81a",
    "createdTime": 1603917691672,
    "expirationTime": 1603918591667
}

Add taxes to transactions

Hosted checkout requests are not linked to the merchant's Clover inventory, so any default tax configuration is not applied to hosted checkout payments. There are two requirements for taxes to be applied to a request:

  • The merchant must have an existing tax rate.
  • The tax is included on any applicable line items in the request. To do so, when you create a checkout session request, add the taxRates array and a rate for the merchant's tax rates. The rate is an integer where a 10% tax is defined as 1000000. If more than one rate has the same value, the first is used for the checkout process.
{
  "lineItems": [
    {
      "name": "Mug",
      "price": 1000,
      "unitQty": 1,
      "taxRates": [
        {
          "name": "CO state tax",
          "rate": 1000000
        }
      ]
    }
  ]
}

Related topics

Updated 2 days ago