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 app settings for an iframe integration.
- 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. - Generate an
apiAccesskey
—First generate an OAuthaccess_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.
- 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 your OAuth-generatedaccess_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 3 days ago