Get charges

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:

ObjectTypeDescription
createdstringDisplays 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.
customerstringReturns charges associated with the provided customer ID o chargeId.
ending_beforestringSets 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.
expandarray of stringsIndicates the fields to display in response to expanding the fields.
limitintegerIndicates the number of objects (1–100) that the request returns. Default: 10.
starting_afterstringSets 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.

ObjectTypeDescription
gtdate-timeRetrieve results where the created field is greater than the current value.
gtedate-timeRetrieve results where the created field is greater than or equal to the current value.
ltdate-timeRetrieve results where the created field is less than the current value.
ltedate-timeRetrieve 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",
  "data": [
    {
      "id": "1AB2CDEF34G5H",
      "amount": 214,
      "currency": "usd",
      "created": 123456789123,
      "captured": false,
      "ref_num": 987654321,
      "auth_code": 123456,
      "order": "A1BCDD3EF4JKL",
      "outcome": {
        "network_status": "approved_by_network",
        "type": "authorized"
      },
      "paid": true,
      "status": "succeeded",
      "source": {
        "id": "clv_1AAAAAAbCdefJK2l3MnoPQ4r",
        "brand": "DISCOVER",
        "first6": 123456,
        "last4": 4321
      },
      "amount_captured": 214
    },
    {
      "id": “2AB2CDEF34G5I”,
      "amount": 215,
      "amount_refunded": 215,
      "currency": "usd",
      "created": 123456789123,
      "captured": false,
      "ref_num": 987654321,
      "auth_code": 123456,
      "order": “Z2XCDD3EF4JKL",
      "outcome": {
        "network_status": "approved_by_network",
        "type": "authorized"
      },
      "paid": true,
      "refunded": true,
      "status": "succeeded",
      "source": {
        "id": "clv_1AAAAAAbCdefJK2l3MnoPQ4r",
        "brand": "DISCOVER",
        "first6": 123456,
        "last4": 4321
      },
      "amount_captured": 215
    }
  ]
}

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