Create and pay for orders (SDK)
Most applications need to allow merchants to manage order data that payments are associated with. The Ecommerce SDKs provide resources for performing order-related actions.
1. Create an order
To create an order, call the [create an order](https://docs.clover.com/reference/postorders)
endpoint and pass in the minimum required order information:
currency
email
items
from clover import Order
order = Order.create(
currency='usd',
email='[email protected]',
items=[
{
'amount': 1358,
'currency': 'usd',
'description': 'Lemon cupcake with blackberry frosting',
'quantity': 2,
'tax_rates'=[
{
'name': 'Sale',
'tax_rate_uuid': '{tax_uuid}'
}
]
}
]
)
require('dotenv').config();
const Clover = require("clover-ecomm-sdk");
let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let ENVIRONMENT = process.env.ENVIRONMENT;
const cloverInst = new Clover(ACCESS_TOKEN, {
environment: ENVIRONMENT
});
let order = cloverInst.orders.create({
currency: 'usd',
email:'[email protected]',
items:{
'amount': 1358,
'currency': 'usd',
'description': 'Lemon cupcake with blackberry frosting',
'quantity': 2,
'tax_rates':{'name':'Sale','tax_rate_uuid':'{tax_uuid}'}
}
});
In this example, the item-level tax is set using the tax_rates
object. You can set the tax value for each item in three ways.
Tax object | Description |
---|---|
Tax as UUID (recommended) | To set the tax based on merchant tax information, use tax_rate_uuid . This is the recommended approach.Taxes are set under Setup > Taxes & Fees on the Merchant Dashboard. You can retrieve this merchant tax information with /v3/merchants/{mId}/tax_rates . |
Tax as percentage | To set a tax percentage, set the rate as an integer. For example, use 1000000 for a 10% tax. |
Tax as amount | To set a flat fee, use tax_amount . |
This returns an order object in JSON. The id
value is the unique identifier of the order needed for other requests.
{
"id": "6WDD8Y1AQ7WCT",
"object": "order",
"amount": 2716,
"tax_amount": 272,
"amount_returned": 0,
"currency": "usd",
"created": 1580416974000,
"email": "[email protected]",
"items": [
{
"type": "sku",
"quantity": 2,
"amount": 1358,
"currency": "usd",
"description": "Lemon cake with blackberry frosting"
"tax_rates": [
{
"name" : "Sale",
"tax_rate_uuid" : "77FAGR71YYD5M"
}
]
}
],
{
"type" : "tax",
"amount" : 272,
"description" : "Sales Tax"
}
],
"status": "created"
}
2. Pay for an order with a source
To pay for an order using a tokenized card, call the pay for the order
endpoint and pass in the order's ID and a payment source
.
import clover
pay = clover.Order.pay(orderId, source='clv_1TSTSpbfbN6Jh5CqCm3bMQne')
require('dotenv').config();
const Clover = require("clover-ecomm-sdk");
let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let ENVIRONMENT = process.env.ENVIRONMENT;
const cloverInst = new Clover(ACCESS_TOKEN, {
environment: ENVIRONMENT
});
let pay = cloverInst.orders.pay(
orderId,
{source:'clv_1TSTSpbfbN6Jh5CqCm3bMQne'},
function(err, order) {
//handle errors and successful payment
}
)
NOTE
In case you are adding a customer while creating an order, you can set the source value to the customer UUID while paying for the created order.
The card is charged for the full order amount, and an order object is returned showing the status
as paid
. See the REST API Reference for complete information about the returned values.
{
"id": "6WDD8Y1AQ7WCT",
"object": "order",
"amount": 2716,
"tax_amount": 272,
"amount_paid": 2716,
"tax_amount_paid": 272,
"currency": "usd",
"charge": "5E1ZZ9JJMA5Z6",
"created": 1582301374000,
"email": "[email protected]",
"ref_num": "015600501490",
"auth_code": "OK2183",
"items": [
{
"quantity": 2,
"amount": 1358,
"description": "Lemon cake with blackberry frosting"
"tax_rates": [
{
"name": "Sale",
"rate": 1000000
}
]
}
],
...
card details
...
"status": "paid",
"status_transitions": {
"paid": 1582301378011
}
}
3. Add a tip to your order
You can use the tip_amount
(in cents) value to add a tip before paying for an order.
import clover
pay = clover.Order.pay(orderId, tip_amount=300,
source='clv_1TSTSpbfbN6Jh5CqCm3bMQne')
require('dotenv').config();
const Clover = require("clover-ecomm-sdk");
let ACCESS_TOKEN = process.env.ACCESS_TOKEN;
let ENVIRONMENT = process.env.ENVIRONMENT;
const cloverInst = new Clover(ACCESS_TOKEN, {
environment: ENVIRONMENT
});
let pay = cloverInst.orders.pay(
orderId,
{tip_amount: 300, source:'clv_1TSTSpbfbN6Jh5CqCm3bMQne'},
function(err, order) {
//handle errors and successful payment
}
)
Calculations with tips
Always submit the charge amount and tip separately. In the above Python example, for a subtotal of $27.16 and a tip of $3:
Subtotal | Tip | |
---|---|---|
Correct | amount=2716 | tip_amount=300 |
Incorrect | amount=3016 | tip_amount=300 |
Updated 14 days ago