Get charges

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"
      }
    }
  ]
}

Possible 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

Did this page help you?