United States

Canada

The Get charges endpoint retrieves details of existing charges previously created using the Create a charge endpoint.

Request example

The following is a sample request when issuing the Get charges endpoint:

curl --request GET \
     --url https://scl-sandbox.dev.clover.com/v1/charges \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer ab86a5e8-48f3-b3bd-8c45-d415e9867833'

Query Parameters

The following table describes the query parameters to use with the Get charges endpoint:

Object	Type	Description
`created`	string	Displays filtered results based on an open- or closed-ended date or time range. Requires: - A parameter name, such as created or status_transitions - A comparison operator (gt, gte, lt, or lte), and - A date/time or Unix timestamp (in milliseconds). Format: The query uses one of the following formats: - `{parameterName}.{comparisonOperator}=YYYY-MM-DDThhmmss` - `{parameterName}.{comparisonOperator}={timestamp}` Example: To filter the results for objects created after January 12, 2021, but before January 15 at 3:00 PM, add the following to the request: - `gt`=`2021-01-12` - `lte`=`2021-01-15T150000` Go to the Created Option parameters section.
`customer`	string	Returns charges associated with the provided customer ID o `chargeId`.
`ending_before`	string	Sets your place in the object list. Example: If you receive 100 objects in a list starting with `obj_bar`, you can `addending_before=obj_bar` in your subsequent request to retrieve the previous page of the list.
`expand`	array of strings	Indicates the fields to display in response to expanding the fields.
`limit`	integer	Indicates the number of objects (1–100) that the request returns. Default: 10.
`starting_after`	string	Sets your place in the object list. Example: If you receive 100 objects in a list starting with `obj_foo`, you can add `starting_after=obj_foo` in your subsequent request to retrieve the next page of the list.

Created Option parameters

The following options appear when you select the Option# parameter under the created parameter.

Object	Type	Description
`gt`	date-time	Retrieve results where the created field is greater than the current value.
`gte`	date-time	Retrieve results where the created field is greater than or equal to the current value.
`lt`	date-time	Retrieve results where the created field is less than the current value.
`lte`	date-time	Retrieve results where the created field is less than or equal to the current value.

Response example

The following is a sample response when running the Get charges endpoint:

{
  "object": "list",
  "url": "/v1/charges",
  "has_more": true,
  "data": [
    {
      "id": "6CK2MJSF87X2M",
      "amount": 10,
      "currency": "usd",
      "created": 1656626930000,
      "captured": false,
      "customer": "NAYQEY34V6H24",
      "ref_num": "218100500005",
      "auth_code": "OK0974",
      "order": "97C57CARRRFMM",
      "outcome": {
        "network_status": "approved_by_network",
        "type": "authorized"
      },
      "paid": true,
      "status": "succeeded",
      "source": {
        "id": "clv_1TSTSB95isdhZ94NizpP3w5b",
        "brand": "VISA",
        "first6": "400556",
        "last4": "2123"
      }
    }
  ]
}

Responses

The following table describes the possible responses when running the Get charges endpoint:

Message	Description	Variable	Description
`200`	string		Returns the charge object with any captured value set to `true`.
`400 Bad Request`	string	charge	Returns when a card-related error occurs. Indicates the unique ID of the failed charge.
`400 Bad Request`	string	code	Returns additional information about the error that you can use to provide user-friendly handling of the issue.
`400 Bad Request`	string	decline_code	Returns when a card issuer declined the transaction. Includes the reason for the decline if specified by the card issuer.
`400 Bad Request`	string	doc_url	Returns a link for more information about the reported error code.
`400 Bad Request`	string	message	Provides detailed information about the error code. For card-related errors, use this information to inform users.
`400 Bad Request`	string	param	If the error is related to a specific parameter, this value lists the parameter. You can inform users of a particular issue in the entered card information.
`400 Bad Request`	string	type	Returned error type: - `api_connection_error` - `api_error` - `authentication_error` - `card_error` - `idempotency_error` - `invalid_request_error` - `rate_limit_error`