Create a charge

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

📘

Important

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

Before you create a charge, complete the following:

Request example

The following is a sample request when issuing create 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:

ObjectTypeDescription
amountint64Required charge 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).
currencystringRequired. Three-letter ISO 4217 currency code.
Format: lower case.
capturebooleanIndicates 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.
descriptionstringText describing the charge.
ecomindstringIndicates who entered the card data used for a charge—the customer (ecom) or merchant (moto).
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.
receipt_emailstringEmail address that receives the charge receipt.
soft_descriptorobjectSoft descriptor information displays on the customer's card statement in place of the merchant's business information on record. See Setting soft descriptors.
sourcestringRequired. Payment source to be charged, such as a token or alternate_tender.
stored_credentialsobjectStored 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.
level2objectAdd Level 2 data for the purchase card transactions (US only). See Level 2 data.
level3objectAdd Level 3 data for the purchase card transactions (US only). See Level 3 data.
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.
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.
tip_amountint64Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized.
tenderobjectCustom 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 Mastercard and Visa:

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

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

Possible Responses

The following table describes the possible responses when running the create a charge 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 RequeststringmessageReturns 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