Configuring Clover Invoicing APIs
Merchants can use Clover's Invoicing APIs to get paid by customers. An invoice can be a "one time" invoice or a recurring invoice sent on a regular basis, such as a subscription. Once a subscription is created, Clover's invoicing APIs will send out a recurring invoice.
Merchants can use the Invoicing Checkout Service API to create an invoice in the Clover database. Once created, an email is sent automatically to the targeted customer with a link for the customer to use to make a payment. Merchants are then notified automatically when a customer pays an invoice. Merchants can also use the Invoice Manager app on their Clover merchant dashboard to view the status of each invoice.
Clover processes invoice payments using the fully secure PCI-compliant hosted checkout page, which can be customized by merchants.
IMPORTANT
The
Clover Recurring PaymentsAPI, the CloverInvoicing Checkout ServiceAPI, and the recurring payments apps are not for use with HIPAA merchants.
Invoicing tutorials
Creating an invoice
To create an invoice, send a POST request to the invoicingcheckoutservice/v1/invoices endpoint. Set the Authorization header as your OAuth-generated access_token.
Required header parameters:
X-Clover-Merchant-Id
Request body fields
Field | Description | Required / Optional |
|---|---|---|
| Invoice amount | required |
| Date invoice is due | optional |
| Customer first name | optional |
| Customer last name | optional |
| Customer email address | required |
| Customer phone number | optional |
| Invoice title | optional |
| Note text | optional |
Sample request and response
curl --request POST \
--url 'https://sandbox.dev.clover.com/invoicingcheckoutservice/v1/invoices' \
--header 'accept: application/json' \
--header 'authorization: Bearer {access_token}' \
--header 'X-Clover-Merchant-Id: {mId}' \
--header 'content-Type: application/json' \
--data-raw '{
"customerFirstName": "John",
"customerLastName": "Doe",
"customerEmailAddress": "[email protected]",
"customerPhoneNumber": "6502107888",
"amount": 1000,
"notes": "This is test note"
}
{
"id": "{id}",
"customerUuid": "{customerUuid}",
"amount": 1000,
"orders": [
{
"id": "ZYG47EM0RC3AR"
}
],
"merchantUuid": "{mId}",
"collectionMethod": "SEND_INVOICE",
"status": "PENDING",
"dueTime": "[email protected]:40:02.908+0000",
"expirationTime": "[email protected]:40:02.908+0000",
"timelines": [
{
"status": "CREATED",
"paymentStatus": "UNPAID",
"reminderCount": 1,
"createdTime": "[email protected]:40:03.192+0000"
},
{
"status": "NOTIFIED",
"paymentStatus": "UNPAID",
"reminderCount": 1,
"createdTime": "[email protected]:40:03.266+0000"
}
],
"checkoutSession": {
"id": "4a882db3-651d-428e-825f-638fd4ef21e0",
"status": "UNPAID",
"sessionDetails": {
"merchant": {
"name": "Test Merchant 1",
"ownerId": "15FHQCZQC1JNP",
"ownerEmail": "[email protected]",
"logos": {
"elements": []
},
"properties": {
"defaultCurrency": "USD"
},
"id": "{mId}"
},
"shoppingCart": {
"lineItems": [],
"total": 1000
},
"customer": {
"firstName": "FirstName",
"lastName": "LastName",
"emailAddresses": {
"elements": [
{
"emailAddress": "[email protected]"
}
]
},
"phoneNumbers": {
"elements": [
{
"phoneNumber": "4083216789"
}
]
}
},
"metaData": {}
},
"merchantUuid": "{mId}",
"expirationTime": "[email protected]:40:02.908+0000",
"createdTime": "[email protected]:40:03.194+0000",
"modifiedTime": "[email protected]:40:03.197+0000"
},
"createdTime": "[email protected]:40:03.185+0000",
"modifiedTime": "[email protected]:40:03.185+0000"
}
Note the invoice id that is returned for future operations.
NOTE
If you create a one-time invoice and do not specify a due date in the request, then the due date will be the invoice creation date, plus seven days. If you send a due date in the request, then that is the invoice due date.
Sample customer invoice
The customer clicks the Pay (amount) link to pay the invoice.
After paying an invoice, the customer receives a receipt and the merchant is notified that the invoice was paid.
Retrieving invoices
To retrieve an invoice, send a GET request to the invoicingcheckoutservice/v1/invoices/ endpoint. Set the Authorization header as your OAuth-generated access_token.
Required header parameters:
X-Clover-Merchant-Id
Sample response
The response returns a list of the merchant's subscriptions and subscription details.
[
{
"id": "{id}",
"customer": {
"id": "{id}",
"firstName": "John",
"lastName": "Doe",
"emailAddresses": {
"elements": [
{
"emailAddress": "[email protected]"
}
]
},
"phoneNumbers": {
"elements": [
{
"phoneNumber": "4085551965"
}
]
}
},
"amount": 1000,
"dueTime": "[email protected]:56:09.000+0000",
"sentTime": "[email protected]:56:09.000+0000",
"status": "OVERDUE",
"collectionMethod": "SEND_INVOICE"
},
...
{
"id": "{id}",
"customer": {
"id": "{id}",
"firstName": "John",
"lastName": "Doe",
"emailAddresses": {
"elements": [
{
"id": "2SXZ55BB5HV7E",
"emailAddress": "[email protected]"
}
]
}
},
"subscriptionUuid": "BYPVM7S9Y37D8",
"amount": 100,
"dueTime": "[email protected]:56:09.000+0000",
"sentTime": "[email protected]:56:09.000+0000",
"status": "PAID",
"collectionMethod": "CHARGE_AUTOMATICALLY"
},
...
]
Editing an invoice
You can edit invoices if they have not been paid yet. To edit an invoice, send a PUT request to the invoicingcheckoutservice/v1/invoices/{id} endpoint (where id is the invoice id). Set the Authorization header as your OAuth-generated access_token.
Required path parameters:
id(invoice id)
Required header parameters:
X-Clover-Merchant-Id
Editable fields
Field | Editable? (Y/N) |
|---|---|
| Y |
| Y |
| N |
| N |
| N |
| N |
| Y |
| N |
Sample request and response
curl --request PUT \
--url 'https://sandbox.dev.clover.com/invoicingcheckoutservice/v1/invoices/{id}' \
--header 'accept: application/json' \
--header 'authorization: Bearer {access_token}' \
--header 'X-Clover-Merchant-Id: {mId}' \
--header 'content-Type: application/json' \
--data-raw '{
"amount" : 400
}'
{
"id": "{id}",
"customerUuid": "{customerUuid}",
"amount": 400,
"orders": [
{
"id": "45G1MGYAKQ8DR"
}
],
"merchantUuid": "{mId}",
"collectionMethod": "SEND_INVOICE",
"status": "OVERDUE",
"dueTime": "[email protected]:48:46.000+0000",
"expirationTime": "[email protected]:48:46.000+0000",
"timelines": [
{
"status": "CREATED",
"paymentStatus": "UNPAID",
"reminderCount": 1,
"remindedTime": "[email protected]:48:47.000+0000",
"createdTime": "[email protected]:48:46.000+0000"
},
{
"status": "NOTIFIED",
"paymentStatus": "UNPAID",
"reminderCount": 1,
"remindedTime": "[email protected]:48:47.000+0000",
"createdTime": "[email protected]:48:47.000+0000"
}
],
"checkoutSession": {
"id": "5b472535-d18c-45ec-aa72-f940bcbc9845",
"status": "UNPAID",
"sessionDetails": {
"merchant": {
"name": "Test Merchant 1",
"ownerId": "{ownerId}",
"ownerEmail": "[email protected]",
"logos": {
"elements": []
},
"properties": {
"defaultCurrency": "USD"
},
"id": "{mId}"
},
"shoppingCart": {
"lineItems": [],
"total": 400
},
"customer": {
"firstName": "FirstName",
"lastName": "LastName",
"emailAddresses": {
"elements": [
{
"emailAddress": "[email protected]"
}
]
},
"phoneNumbers": {
"elements": [
{
"phoneNumber": "4085981116"
}
]
}
},
"metaData": {}
},
"merchantUuid": "{mId}",
"expirationTime": "[email protected]:48:46.000+0000",
"createdTime": "[email protected]:48:46.000+0000",
"modifiedTime": "[email protected]:34:27.000+0000"
},
"createdTime": "[email protected]:48:46.000+0000",
"modifiedTime": "[email protected]:48:47.000+0000"
}
Deleting an invoice
You can delete invoices if they have not already been paid. To delete an invoice, send a PUT request to the invoicingcheckoutservice/v1/invoices/{id} endpoint (where id is the invoice id. Set the Authorization header as your OAuth-generated access_token.
Required header parameters:
X-Clover-Merchant-Id
curl --request PUT \
--url 'https://sandbox.dev.clover.com/invoicingcheckoutservice/v1/invoices/{id}' \
--header 'accept: application/json' \
--header 'authorization: Bearer {access_token}' \
--header 'X-Clover-Merchant-Id: {mId}' \
--header 'content-Type: application/json' \
--data-raw '{
"delete" : true
}'
Related topics
Updated 4 months ago