Get a charge

get https://scl-sandbox.dev.clover.com/v1/charges/{chargeId}

Retrieves the details of an existing charge. This information is also returned when a charge is first created, see create a charge or if it is refunded, see create a refund.

Responses

Response body

object

amount

int64

required

Charge amount in cents. If the charge request includes tax (tax_rate_uuid or tax_amount), this value must be the sum of any item prices and any tax or tip.
For example, if the item cost = $10 and the tax is $1, the amount is 1100 cents ($11).
Format: cents

tax_amount

int64

≥ 0

Amount paid in taxes. This value is not automatically added to the total amount. Your app must ensure the Amount property is the total final amount to charge the customer.

tip_amount

int64

≥ 0

Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized.

additional_charges

object

Additional surcharge or other fee applied on the transaction.

amount

integer

Amount of the additional charges applied on the transaction.
Format: Cents

string

13 to 13

Unique identifier of the additional charge.

rate

integer

Item-specific tax of an additonal charge where a 10% rate is defined as 1000000.

type

string

Type of the additional charge collected on the transaction.

CREDIT_SURCHARGE

amount_refunded

int64

required

Amount refunded in cents. This value can be less than the amount property on the charge if a partial refund is issued.

partial_auth

boolean

Indicates if the transaction was partially approved.

billing_details

object

required

address

Billing address.

string | null

Email address of the customer.

name

string | null

Full name of the customer.

phone

string | null

Phone number (including extension) of the customer.

captured

boolean

required

Indicates whether to immediately capture the charge.
Values:
True - Default.
False - Indicates the charge transaction type is AUTH (or PRE-AUTH), and the charge can be captured later using the capture a charge endpoint.

created

int64

required

Charge creation time (Unix timestamp in milliseconds).

currency

string

required

Three-letter ISO 4217 currency code.
Format: Lower case
Length: Maximum 3

customer

string

length ≤ 5000

Unique identifier of the customer associated with the charge.

description

string | null

Detail description of the charge.

external_reference_id

string

Unique identifier (ID), such as an invoice or purchase order (PO) number, that is sent to the merchant's gateway and displayed in settlement records.
Format: Supported for US—alphanumeric characters with in-between spaces.
Length: Maximum 12, including spaces and alphanumeric characters.

external_customer_reference

string

Customer reference number from the merchant's order management system.

auth_code

string | null

Authorization code of the charge, if available.

ref_num

string | null

Reference number returned from the payment gateway when the transaction is successful.

failure_code

string | null

Error code explaining the reason for the charge failure.

failure_message

string | null

Detailed information about the reason for the charge failure.

warning_message

string | null

Detailed warning information about the charge. Example: Missing original transaction identifer for c-token.

string

required

length ≤ 5000

Unique identifier of the charge.

livemode

boolean

required

Indicates whether the token object is live in production.

metadata

string

required

length ≤ 500

Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format.
Length: Maximum 500 characters

object

string

required

Object type.

charge

order

string

length ≤ 5000

Unique identifier of the order.

outcome

object

Explanation of whether and why the payment was accepted.

paid

boolean

required

Indicates whether the charge was successful or authorized for capture.

payment_method_details

string

Indicates the payment method used for the charge.

card ach paypal giftCard

on_behalf_of

boolean

Indicates the transaction was made on someone's behalf.

debt_payment

string

Indicates the status of the charge.

approved declined not_processed

receipt_email

string | null

Email address to which the charge receipt is sent. Receipts are sent only after the charge is paid.
Note: Receipts are not sent in the sandbox environment.

receipt_number

string | null

Receipt number of the charge.

receipt_url

string

required

length ≤ 5000

URL where the charge receipt is accessible. The receipt displays the latest state of the charge, including any refunds. If the charge is for an invoice, the receipt is displayed as an invoice.

refunded

boolean

required

Indicates whether the charge was fully refunded or partial refunded.
Values:
True - Full refunded
False - Partially refunded

shipping

Shipping information for the charge.

source

object | null

Payment source of the charge. This can be a token or an alternate tender.

string

length ≤ 5000

Unique identifier (Clover token).

object

string

length ≤ 5000

Type of source. Example: Card or Bank account.

address_city

string | null

City of the customer's address. Can include district, suburb, town, or village.

address_country

string | null

Billing address country, if provided.

address_line1

string | null

First line of the customer's address. Can include the street address, PO box, or company name.

address_line1_check

string | null

Result of the verification check of the address.

pass failed unavailable unchecked

address_line2

string | null

Second line of the customer's address. Can include the apartment, suite, unit, or building number.

address_state

string | null

State of the customer's address. Can include county, province, or region.

address_zip

string | null

Postal or ZIP code of the customer's address.

address_zip_check

string | null

Result of the verification check of the address postal code.

pass failed unavailable unchecked

brand

string | null

Card brand.

country

string | null

2-character country code.

cvc_check

string | null

Result of the verification check of the cvv code.

pass failed unavailable unchecked

exp_month

string

length ≤ 5000

Card expiration month in 2-digit format.
Format: mm

exp_year

string

length ≤ 5000

Card expiration year in 2-or 4-digit format.
Format: yy or yyyy

fingerprint

string

length ≤ 5000

Unique identifier for this source.

first6

string

length ≤ 5000

First 6 numbers of the primary account number.

funding

string

length ≤ 5000

Type of card used for the payment.

last4

string

length ≤ 5000

Last 4 numbers of the primary account number.

name

string

length ≤ 5000

Cardholder's full name on the card.

status

string

required

length ≤ 5000

Payment status of the charge.

succeeded pending failed

stored_credentials

object

Stored credentials for a transaction. For subsequent payments with a saved card, stored credentials are available only with multi-pay (mTokens) tokens. See Save a card for future transactions for more information.

sequence

string

Indicates sequence of the external tokens such as Transarmor token.
Values:
FIRST - for new transarmor tokens
SUBSEQUENT - for existing transarmor tokens

FIRST SUBSEQUENT

is_scheduled

boolean

Indicates whether the transaction is scheduled or part of an installment.
Values:
True - Transaction is scheduled.
False - Transaction is part of an installment. Installments are only available in the US.

initiator

string

Indicates with whose consent the transaction is initiated.
Values:
Cardholder
Merchant

MERCHANT CARDHOLDER

installment_info

object

Installment information for the transaction.

soft_descriptor

object

Soft descriptor information for a transaction. This information displays on the customer's card statement in place of the merchant's business information on record.

dba_name

string

length ≤ 38

Merchant doing business as (DBA) name, product, or service.
Length: Max 38 alphanumeric characters.

street

string

Merchant's street address.

city

string

Merchant's city.

region

string

length ≤ 2

Merchant's state.
Format: 2-character postal abbreviation (US only).

postal_code

string

Merchant's postal code.

country_code

string

length between 3 and 3

Merchant's country code.
Format: 3-digit; see the Country code reference.

merchant_contact_info

string

Merchant's phone number or email address.
Format: Max 13 characters for Discover® and Visa® transactions.

threeds

object

3DSecure validation result.

validation_result

string

Indicates validation result of 3DSecure transaction.

AUTHENTICATION_FAILED AUTHENTICATION_SUCCESSFUL ISSUER_DOES_NOT_PARTICIPATE ATTEMPTED_UNSUCCESSFULLY ATTEMPTED_SUCCESSFULLY NOT_POSSIBLE

source

string

Source of the 3DSecure transaction. Example: CLOVER or NON_CLOVER

gift_card

object

Indicates meta data of the gift card.

previous_balance

integer

Indicates the previous balance before the transaction was initiated.

new_balance

integer

Indicates the updated balance after the transaction is completed.

lock_amount

integer

Indicates the value on the card that was locked due to a balance lock transaction.

expiration_date

string

Indicates the account expiration date.

lock_id

integer

Unique lock number identifier for each balance lock record. The lock_id helps capture the authorized amount and is applicable for pre-auth and capture flow.

number

string

Embossed card number on the gift card or the ift card number. Only applicable for virtual gift card activation.

security_card_value

string

Gift card security code. Only applicable for virtual gift card activation.

level2

object

Additional data for purchase card transactions (US only).

tax_amount

int64

Part of the transaction amount that indicates the sales tax. A pc_order_number is required when including a tax_amount.

tax_indicator

integer

Taxable status of the transaction.
Values:
0 – No tax information provided.
1 – Tax amount is provided.
2 – Purchase item is tax exempt or non-taxable.

1 2

purchase_identifier

string

Identifier, such as stock keeping unit (SKU), code or reference number that the merchant or customer uses to identify the purchase.

pc_order_number

string

Order number or customer reference number reported as part of the purchase card data.

discount_amount

int64

Discount amount for the transaction.
Format: Cents

freight_amount

int64

Freight amount included for the transaction.
Format: Cents

duty_amount

int64

Duty amount included for the transaction.
Format: Cents

destination_postal_code

string

Postal or ZIP code of the delivery location.

ship_from_postal_code

string

Postal or ZIP code of the shipping location.

destination_country_code

integer

Delivery location country code.
Format: 3-digit code; see the Country code reference.

merchant_tax_id

string

Only for Mastercard®. Identifier (ID) for the tax the merchant collects for the transaction.

product_description

string

Description of the purchased item.

level3

object

Additional data for purchase card level3 transactions (US only). Supported for Mastercard® and Visa® only. Purchase card level2 is mandatory for level3 transactions.

service_code

string

length ≤ 3

Required for all non-keyed transactions and swiped transactions. Service code extracted from the track data.

magnetic_Stripe_Ind

boolean

Indicates whether magnetic stripe card was used.
Values:
True - magnetic stripe swiped transaction
False

level3_line_items

array of objects

List of level3 line items.

level3_line_items

object

item_description

string

required

length ≤ 35

Required for reduced interchange and for Mastercard®. ItemMerchandise description.
Format:
For Mastercard, level 3 must not be all 0s (zeros) or all high/low values.
For Visa, level 3 must not be all spaces or all 0s (zeros).
Length: Maximum 35 characters.

product_code

string

required

length ≤ 12

Required for Mastercard and Visa. Product or Universal Product Code (UPC).
Format: Must not be all spaces.

unit_cost

int64

required

Unit cost of level3 line item.
Format: For Visa must not be all spaces or 0s (zeros).

quantity

number

required

Item quantity information; required for reduced interchange.
Format: Must not be all spaces or 0s (zeros); Last 4 digits are considered decimal places, example: 20.0000

discount_amount

int64

Discount amount applied to the level3 line item.
Format: For Visa level2 must not be all 0s (zeros), if a discount exists.

unit_of_measure

string

required

length ≤ 12

Unit of measurement codes used for international trade. Required for reduced interchange for both Mastercard and Visa. See Unit of Measurement codes.

commodity_code

string

length ≤ 12

Required for Visa. Indicates classification of purchased items.

saved_credentials_on_file

object

Data about any surcharge or other fee applied to a transaction.

tokenType

string

Multi-pay token type such as TransArmor.

TRANSARMOR

value

integer

The percentage of the total assessed as a surcharge or other fee. This value is set when a merchant is boarded to Clover Percentages are defined to four decimal places. For example, the value of a 3.5% surcharge is 35000 (3.5*10000).

ref_num

string

Identifier of additional charges.

ecomind

string

Defaults to ecom

Indicates the source of the card data.

ecom moto retail

amount_captured

int64

Total amount captured for pre-auth transactions.

Language

Credentials

OAuth2


xxxxxxxxxx
1
curl --request GET \
2
     --url https://scl-sandbox.dev.clover.com/v1/charges/chargeId \
3
     --header 'accept: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Successful response. Charge details are displayed.

defaultError response