Create a charge

United States
Canada

Use the Create a charge endpoint to charge a credit cards or other payment sources. See Clover Ecommerce basics before you start creating a charge.

The best practice is to initially create a charge in the sandbox environment so that any given payment source, such as a credit card, is not charged.

Prerequisites

  1. Set up a sandbox developer account.
  2. Create an app in the sandbox. See also Ecommerce app permissions.
  3. Generate a card token. You need to generate a new card token for each payment.

Steps

  1. Send a POST request to the v1/charges endpoint to create a charge.
  2. Enter the required parameters in the request:
    1. amount
    2. currency
    3. source
  3. Use the source token from the v1/charges endpoint to create and pay for orders and accept tips. For example, to process a payment with your app, use the v1/charges endpoint to autocreate an order and perform the transaction. The payment is charged to a source, which is a credit card or debit card tokenized with the hosted tokenizer.

Request example

The following table describes the request parameters to create a charge:

curl --request POST \
     --url 'https://scl-sandbox.dev.clover.com/v1/charges' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer ab86a5e8-48f3-b3bd-8c45-d415e9867833' \
     --header 'Content-Type: application/json' \
     --header 'x-forwarded-for: {client_ip}' \
     --data '{"ecomind":"ecom"}'\

Request parameters

The following table describes the request parameters to use when creating a charge:

ObjectTypeDescriptionRequired/Optional
amountint64Charge amount in cents. If the charge request includes tax (tax_rate_uuid or tax_amount), this value must be the sum of all item prices and any tax or tip. Example: If the item costs $10 and the tax is $1, the amount is 1100 ($11).
Format: Cents
Required
currencystringThree-letter ISO 4217 currency code. Note: Merchants in Canada and United States (US) can now accept customer payments in currency other than the US Dollar (USD). See Multi Currency Pricing (MCP).
Format: Lower case
Length: Maximum 3
Required
capturebooleanIndicates whether to immediately capture the charge.
Values:
- true - Default
- false- Indicates the charge transaction type is AUTH (or PRE-AUTH), and the charge is captured later using the capture endpoint.
Optional
partial_redemptionbooleanIndicates if the charge can be authorized for a lesser amount.
Values:
- true
- false - Default
Optional
descriptionstringText describing the charge. This information is often displayed to users.Optional
ecomindstringIndicates who entered the card data used for a charge—the customer (ecom) or merchant (moto).Optional
external_reference_idstringIdentifier (ID), such as an invoice or purchase order (PO) number, that is passed 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.
Optional
external_customer_referencestringCustomer reference number from merchant's order management system.Optional
receipt_emailstringEmail address to which the charge receipt is sent. Receipt are sent only after the charge is paid.
Note: Receipts are not sent in the sandbox environment.
Optional
metadataobjectSet 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.
Expand the object to check entries.
soft_descriptorobjectSoft descriptor information displays on the customer's card statement in place of the merchant's business information on record. See Set soft descriptors.Expand the object to check entries.
sourcestringPayment source to be charged, such as a token or alternate_tender.Required
stored_credentialsobjectStored credentials for a transaction. For subsequent payments with a saved card, stored credentials are available only with multi-pay tokens. See Save a card for future transactions.Expand the object to check entries.
level2objectAdd Level 2 data for the purchase card transactions (US only). See Level 2 data.Expand the object to check entries.
level3objectAdd Level 3 data for the purchase card transactions (US only). See Level 3 data.Expand the object to check entries.
threeds_authentication_resultobjectEMV ® 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.Expand the object to check entries.
tax_rate_uuidstringTax universally unique identifier (UUID). Use the Get all tax rates endpoint to retrieve merchant tax UUID information. The tax is not automatically added to the total amount, so apps must ensure the amount property contains the total charge to the customer.Optional
tax_amountint64Amount paid in taxes. This value is not automatically added to the total amount, so apps must ensure the amount property contains the total charge to the customer.Optional
tip_amountint64Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized.Optional
tenderobjectCustom tender to make a charge or pay for the order.Expand the object to check entries.

Multi Currency Pricing (MCP)

Clover offers multi-currency pricing by allowing local currency codes in the currency field. Merchants in Canada and can accept payment, and submit refunds in regional currencies with settlement currency as USD. Once the customer completes the transaction in their submitted currency, Clover uses the current exchange rate at the time of authorization to estimate the paid amount in USD. This amount displays in the merchant's closeout report.

To use this feature, merchants need to create a charge with a currency other than USD, and the MCP allows the gateway to accept it for authentication. Clover supports MCP only for Mastercard® and Visa®. Hence, make sure your merchants submit charges in USD for any other network transactions.

Example: A US merchant expands their online market and starts servicing in London through e-commerce and can now accept payments in euros.

Note: The digital receipt displays transaction details in the currency selected by the customer, and the transactions detail screen displays the settlement amount in the merchant’s local currency.

Response example


{
  "id": "ABDFEFG1HIJK2", 
  "amount": 122,
  "payment_method_details": "card",
  "amount_refunded": 0,
  "currency": "usd",
  "created": 123456789123,
  "captured": true,
  "ref_num": 987654321,
  "auth_code": 123456,
  "outcome": {
    "network_status": "approved_by_network",
    "type": "authorized"
  },
  "paid": true,
  "status": "succeeded",
  "source": {
    "id": "clv_1AAAAAAbCdefJK2l3MnoPQ4r",
    "brand": "DISCOVER",
    "exp_month": 12,
    "exp_year": 2025,
    "first6": 112233,
    "last4": 1111
  },
  "ecomind": "ecom"
}

Possible responses

The following table describes the possible responses when running the create a charge endpoint:

MessageDescriptionVariableDescription
200stringSuccessful response. Returns the charge object with any captured value set to true.
400 Bad RequeststringchargeReturns when a card-related error occurs. Unique identifier of the failed charge.
400 Bad RequeststringcodeAdditional information about the error to help users identify the issue.
400 Bad Requeststringdecline_codeReturns when a card issuer declines the transaction. This includes the reason for the decline if specified by the card issuer.
400 Bad Requeststringdoc_urlURL (link) for more information about the reported error code.
400 Bad RequeststringmessageDetailed information about the error code. For card-related errors, this can provide more information to users.
400 Bad RequeststringparamIf the error is related to a specific parameter, this value lists the parameter. You can use this to inform users entering card information of a specific problem with their entry.
400 Bad RequeststringtypeReturned error type:
- api_connection_error
- api_error
- authentication_error
- card_error
- idempotency_error
- invalid_request_error
- rate_limit_error