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:

ObjectTypeDescription
createdstringDisplays 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.
customerstringReturns charges associated with the provided customer ID o customerId.
ending_beforestringCursor 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.
expandarray of stringsAdditional information provided as an expanded response, for example, a related object nested within the parent. See Use expandable fields..
limitintegerNumber of objects returned by the request, ranging between 1 and 100.
Default: 10
starting_afterstringCursor 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_resultstringEMV® 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_threedsstringIndicates 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.

ObjectTypeDescription
gtdate-timeDisplays results when the created field is greater than the current value.
gtedate-timeDisplays results when the created field is greater than or equal to the current value.
ltdate-timeDisplays results when the created field is less than the current value.
ltedate-timeDisplays 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:

MessageDescriptionVariableDescription
200stringReturns the charge object with any captured value set to true.
400 Bad RequeststringchargeReturns when a card-related error occurs. Indicates the unique ID of the failed charge.
400 Bad RequeststringcodeReturns additional information about the error that you can use to provide user-friendly handling of the issue.
400 Bad Requeststringdecline_codeReturns when a card issuer declined the transaction. Includes the reason for the decline if specified by the card issuer.
400 Bad Requeststringdoc_urlReturns a link for more information about the reported error code.
400 Bad RequeststringmessageProvides detailed information about the error code. For card-related errors, use this information to inform users.
400 Bad RequeststringparamIf 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 RequeststringtypeReturned error type:

- api_connection_error
- api_error
- authentication_error
- card_error
- idempotency_error
- invalid_request_error
- rate_limit_error