Create a charge

Use the Create a charge endpoint to charge a credit cards or other payment sources.

📘

Important

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

Prerequisites

Before you create a charge, complete the following:

Request example

The following are sample request when issuing a created a charge endpoint:

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' \
     --data '{"ecomind":"ecom"}'

Request Parameters

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

Object

Type

Description

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 all items' prices and any tax or tip. Example: if the item costs $10 and the tax is $1, the amount is 1100 ($11).

currency

string

Required. Three-letter ISO 4217 currency code. Format: lower case.

capture

boolean

Indicates the charge is to be immediately captured. Default: true. If the value is set to false, the charge transaction type is AUTH (or PRE-AUTH), and the charge is captured later using the capture endpoint.

description

string

Text describing the charge.

ecomind

string

Indicates who entered the card data used for a charge—the customer (ecom) or merchant (moto).

external_reference_id

string

Identifier (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.

receipt_email

string

Email address which receives the charge receipt.

soft_descriptor

object

Soft descriptor information displays on the customer's card statement in place of the merchant's business information on record. See Setting soft descriptors.

source

string

Required. The payment source to be charged, such as a token or alternate_tender.

stored_credentials

object

Stored credentials for a transaction. For subsequent payments with a saved card, stored credentials are available only with multi-pay tokens. See Saving a card for future transactions.

level2

object

Add Level 2 data for the purchase card transactions (US only). See Level 2 data.

level3

object

Add Level 3 data for the purchase card transactions (US only). See Level 3 data.

tax_rate_uuid

string

Tax Universally unique identifier (UUID). You can retrieve merchant tax UUID information using the Get all tax rates endpoint. The tax is not automatically added to the total amount, so apps must ensure the amount property contains the total charge to the customer.

tax_amount

int64

Amount 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.

tip_amount

int64

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

tender

object

Custom tender to make a charge or pay for the order

Responses examples

The following are sample responses when issuing a created a charge for both Visa and For Mastercard:

For Visa

{
    "amount": 3333,
    "tax_amount": 100,
    "currency": "USD",
    "capture": true,
    "source": "clv_1TSTSd9tS8KdC6X2ejYXABxB",
    "level2": {
        "discount_amount": 0,
        "freight_amount": 0,
        "duty_amount": 0,
        "ship_from_postal_code": "94085",
        "destination_postal_code": "94085",
        "destination_country_code": "840",
        "vat_shipping_amount": 0,
        "tax_amount": 100,
        "tax_indicator": "TAXABLE",
        "pc_order_number": "111111"
    },
    "level3": {
        "service_code": null,
        "magnetic_Stripe_Ind": false,
        "level3_line_items": [
            {
                "item_description": "This is tax id item",
                "product_code": "222",
                "quantity": 1,
                "unit_cost": 1000,
                "discount_amount": 0,
                "commodity_code": "222",
                "unit_of_measure": "EA"
            }
        ]
    }
}

For Mastercard

{
    "amount": 3333,
    "tax_amount": 100,
    "currency": "USD",
    "capture": true,
    "source": "clv_1TSTSRJxMdtfJR5e7CqhQZ7r",
    "level2": {
        "discount_amount": 0,
        "freight_amount": 0,
        "duty_amount": 0,
        "ship_from_postal_code": "94085",
        "destination_postal_code": "94085",
        "destination_country_code": "840",
        "vat_shipping_amount": 0,
        "tax_amount": 100,
        "tax_indicator": "TAXABLE",
        "pc_order_number": "111111"
    },
    "level3": {
        "service_code": null,
        "magnetic_Stripe_Ind": false,
        "level3_line_items": [
            {
                "item_description": "This is tax id item",
                "product_code": "222",
                "quantity": 1,
                "unit_cost": 1000,
                "discount_amount": 0,
                "unit_of_measure": "EA"
            }
        ]
    }
}

Possible Responses

The following table describes the possible responses when running this endpoint:
The following table describes the possible responses when running the Get a charge 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?