Get charges

North America—United States and 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 ab867xxxx-xxxx-xxxx-xxxx-xxxxxxxxcae2'

Query Parameters

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

Object	Type	Description
`created`	string	Displays results based on an open or closed-ended date and time range. Each filter part requires the 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). The query string uses one of the following formats: {`parameterName}.{comparisonOperator`}=`yyyy-MM-dd HH:mm:ss` or {`parameterName`}.{`comparisonOperator`}={`timestamp`} For example, to filter the results for objects created after January 12, 2021 but before January 15 at 3 PM, add the following to the request: `created.gt=2021-01-12` & `created.lte=2021-01-15 15:00:00`.
`customer`	string	Returns charges associated with the provided customer ID o `customerId`.
`ending_before`	string	Cursor used in pagination. The ending_before object ID sets your place in the list. For example, if you receive 100 objects in a list starting with obj_bar, add ending_before=obj_bar in your subsequent request to retrieve the previous page of the list.
`expand`	array of strings	Additional information provided as an expanded response, for example, a related object nested within the parent. See Use expandable fields..
`limit`	integer	Number of objects returned by the request, ranging between 1 and 100. Default: 10
`starting_after`	string	Cursor used in pagination. The starting_after object ID sets your place in the list. For example, if you receive 100 objects in a list starting with obj_foo, add starting_after=obj_foo in your subsequent request to retrieve the next page of the list.
`threeds_validation_result`	string	EMV® 3-D Secure (3DS) authentication result. 3-D Secure is a protocol that provides an additional security layer for online credit and debit card-not-present (CNP) transactions.
`is_threeds`	string	Indicates whether the transaction is 3-D Secure authenticated.

Created Option parameters

The following options appear when you select the OPTION 1 under the created parameter.

Object	Type	Description
`gt`	date-time	Displays results when the created field is greater than the current value.
`gte`	date-time	Displays results when the created field is greater than or equal to the current value.
`lt`	date-time	Displays results when the created field is less than the current value.
`lte`	date-time	Displays results when 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",
  "data": [
    {
      "id": "WBKGFT6X1VB1G",
      "amount": 214,
      "currency": "usd",
      "created": 1719882650000,
      "captured": false,
      "customer": "ADFRQ4R2YAYBY",
      "ref_num": "1287124121",
      "auth_code": "446057",
      "order": "WFCWS95Z8E4GR",
      "outcome": {
        "network_status": "approved_by_network",
        "type": "authorized"
      },
      "paid": true,
      "status": "succeeded",
      "source": {
        "id": "clv_1T7xxxx-xxxx-xxxx-xxxx-xxxxxxxxcae2",
        "brand": "DISCOVER",
        "first6": "601136",
        "last4": "6668"
      },
      "amount_captured": 214
    },
    {
      "id": "3QYJA61J9YYRY",
      "amount": 212,
      "currency": "usd",
      "created": 1719619573000,
      "captured": false,
      "customer": "AEJPTN7HH3RY2",
      "ref_num": "484331764",
      "auth_code": "482883",
      "order": "ZZVRJB0J7ZGPC",
      "outcome": {
        "network_status": "approved_by_network",
        "type": "authorized"
      },
      "paid": true,
      "status": "succeeded",
      "source": {
        "id": "clv_1T7xxxx-xxxx-xxxx-xxxx-xxxxxxxxcae2",
        "brand": "DISCOVER",
        "first6": "651000",
        "last4": "0810"
      },
      "amount_captured": 212
    }
  ]
}

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`

Updated 4 months ago