Get all payments
Use the Get all payments endpoint to retrieve all payment details for a merchant with a single call, including the total amount, tip amount, tax amount, and result status. You can also filter your search results based on the filter
and expand
queries.
Tip
To retrieve a single payment, use the Get a single payment endpoint.
Prerequisites
- Must have a sandbox developer account.
- Must have a
bearer token
to access the API.
(Create an app in sandbox to generate a bearer token.) - Must have a
mId
to run the query. - Must have existing payments in the specified merchant account.
Steps
- Send a Get request to
/v3/merchants/{mId}/payments
. - Enter the
mId
(merchant identifier). - Enter the value in the following optional parameters:
filter
expand
90-day restrictions on payment data request results
The
Get all payments
pilotThe
get all payments
restriction of 90 days for search results is limited to specific merchants. Clover will gradually deploy the restriction across the merchant base. As we do this, you can use the Get all payments endpoint to see the restrictions configured for your merchants.
When retrieving payment information, the results will not exceed 90 days. This constraint is true even if the search query exceeds a 90-day span using the time-based fields, such ascreatedTime
, modifiedTime
, or clientCreatedTime
.
Note
In all of these time-based fields, Clover uses the common timestamp methods that are milliseconds from the same epoch time as Unix time (Jan 1, 1970). If your app requires Unix time, divide the Clover timestamp by 1000.
Date-filter scenarios
The following examples show how to use query operators to when making single-date and date-range requests. The example results table shows how the 90-day limit impacts the respective search results.
Operators used these examples:
AND
>
...(greater than)>=
...(greater than or equal to)<
...(less than)<=
...(less than or equal to)
Single-date requests
Single-date queries only specify the beginning or the end date, for example:
>{date1}
...(get all payments after {date1})>={date1}
...(get all payments after or on {date1})<{date1}
...(get all payments before {date1})<={date1}
...(get all payments before or on {date1})
Date-range requests
Date-range queries specify the beginning and end of a date range, for example:
>{date1} AND <{date2}
...(get all payments after {date1} and before {date2})>{date1} AND <={date2}
...(get all payments after {date1} and before or on {date2})<={date1} AND <{date2}
...(get all payments after or on {date1} and before {date2})<={date1} AND <={date2}
...(get all payments after or on {date1} and before or on {date2})
Example query results
To illustrate the impact of the 90-day limit applied to query results, this table shows sample results expected with and without the 90-day limit for simple single-date requests. For date-range requests, the results can be extrapolated. In these examples, {date1} is Jan 1, 2024.
REQUEST condition | Expected results | 90-day limit applied to results |
---|---|---|
>{date1} | all payments after {date1} | all payments up to 90 days after {date1} |
example: | (all payments from Jan 2, 2024 until today) | (all payments from Jan 2, 2024 until Mar 30, 2024) |
>={date1} | all payments after {date1} including those on {date1} | all payments up to 90 days after {date1} including those on {date1} |
example: | (all payments from Jan 1, 2024 until today) | (all payments from Jan 1, 2024 until Mar 30, 2024) |
<{date1} | all payments before {date1} | all payments up to 90 days before {date1} |
example: | (all payments from Dec 31, 2023 back to the first payment record in the system) | (all payments from Dec 31, 2023 back to Oct 3, 2023) |
<={date1} | all payments before {date1} including those on {date1} | all payments up to 90 days before {date1} including those on {date1} |
example: | (all payments from Jan 1, 2024 back to the first payment record in the system) | (all payments from Jan 1, 2024 back to Oct 3, 2023) |
<={future date} | all payments before {current time} | all payments up to 90 days before {current time} |
example: | (all payments from the current time back to the first payment record in the system) | (all payments back 90 days from the current time) |
Request example
curl --request GET \
--url https://api.sandbox.dev.clover.com/v3/merchants/5Axxxxxxxxxx1/payments?filter=modifiedTime%3E1704070800000' \
--header 'accept: application/json' \
--header 'authorization: Bearer d952xxxx-xxxx-xxxx-xxxx-xxxxxxxxcae2'
Response example
{
"elements": [
{
"id": "VKxxxxxxxxxxG",
"order": {
"id": "50xxxxxxxxxxG"
},
"tender": {
"href": "https://apisandbox.dev.clover.com/v3/merchants/5Axxxxxxxxxx1/tenders/JCxxxxxxxxxx8",
"id": "JCxxxxxxxxxx8"
},
"amount": 212,
"cashbackAmount": 0,
"employee": {
"id": "XxxxEMPLOYEE"
},
"createdTime": 1726876836000,
"clientCreatedTime": 1726876836000,
"modifiedTime": 1726876835000,
"offline": false,
"result": "SUCCESS",
"note": ""
},
{
"id": "G3xxxxxxxxxxM",
"order": {
"id": "W7xxxxxxxxxxP"
},
"tender": {
"href": "https://apisandbox.dev.clover.com/v3/merchants/5Axxxxxxxxxx1/tenders/JCxxxxxxxxxx8",
"id": "JCxxxxxxxxxx8"
},
"amount": 214,
"cashbackAmount": 0,
"employee": {
"id": "XxxxEMPLOYEE"
},
"createdTime": 1726358433000,
"clientCreatedTime": 1726358433000,
"modifiedTime": 1726358432000,
"offline": false,
"result": "SUCCESS",
"note": ""
},
}
Updated 2 days ago