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
- Create a global developer account and select the Hosted Checkout checkbox in the Ecommerce Settings.
- Generate the merchant public token or
apiAccessKey
to make calls to the card tokenization server to tokenize a card, as follows:- For a single merchant—Generate an Ecommerce API token on the Clover Merchant Dashboard for a Hosted checkout integration type and note the
merchantId
.- Public key—Use as the Ecommerce public API key or
apiAccessKey
for tokenization. - Private key—Set as the Bearer token in the Authorization header to use Ecommerce APIs. When the merchant integrates Clover Hosted Checkout on their website, the token is automatically set up with the required Clover permissions.
- Public key—Use as the Ecommerce public API key or
- For multiple merchant businesses—First generate an OAuth
access_token
and then use it to generate an Ecommerce API key (PAKMS key) orapiAccessKey
.
- For a single merchant—Generate an Ecommerce API token on the Clover Merchant Dashboard for a Hosted checkout integration type and note the
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.
- Send a
POST
request to the/invoicingcheckoutservice/v1/checkouts
endpoint. - Enter the required parameters in the
shoppingCart
object in thelineItems
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.
- 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
oremail
.
- 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 as1000000
.
- In the header X-Clover-Merchant-Id, enter the merchantId.
- Set the
authorization: Bearer
as the merchant-specific private key or the OAuth-generated expiringaccess_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 arate
for the merchant's tax rates. Therate
is an integer where a 10% tax is defined as1000000
. 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 12 days ago