General FAQs

What’s the difference between the Clover Platform API and Ecommerce API for creating orders?  

Clover provides two distinct APIs for order creation, each suited to different use cases:

• Platform API (Atomic orders): Best for POS-style apps. Supports inventory, modifiers, and customer records. Use the Platform API if you're working with inventory and in-store logic.
• Ecommerce API : Designed for online stores. Supports shipping, billing, and web checkout flows. Use the Ecommerce API if you're building for online payments and delivery.

How can I process payments through the Clover API from my custom web app?

To process payments directly from your web app, use the Ecommerce API. You'll need to:

• Associate each customer in your app with their Clover customer ID.
• Get an API token for authentication.
• Send the order total and customer details through the API.
• Receive a success or failure response after processing.

You can see detailed guidance and sample codes in the Ecommerce API Reference. Alternatively, you can generate payment links from the Merchant Dashboard using Payment links.

How can I update a customer's credit card using Clover APIs if a card is already attached?

Clover does not support direct updates to an existing vaulted card's details, such as the card number. The 409 Conflict occurs when trying to save a card that Clover recognizes as already existing for that specific customer entry. To update a card, you must first remove the old payment source and then attach a new one.

1. Retrieve the card ID or sourceId  by sending a request to the Get a list of customers endpoint: GET /v3/merchants/{merchantId}/customers/{customerId}?expand=cards
   Note: Make sure to use expand=cards to get the full card object, which includes the UUID required for the revoke request.
2. Revoke the existing payment source using the Revoke a payment source endpoint.
3. Use the Create a card-on-file endpoint to vault the new tokenized card data.

How can I pass a dynamic amount to a Clover payment link button from my PHP website?

You cannot pass a dynamic amount to a standard Payment Link button created in the Merchant Dashboard. Instead, you must use the Clover Hosted Checkout API to generate a unique checkout session for each transaction.

The workflow for PHP developers is as follows:

1. Create a Checkout session: Your PHP backend sends a POST request to /invoicingcheckoutservice/v1/checkouts with the dynamic amount and line item details. Ensure your request includes your Merchant ID and Private API Key (or OAuth token) in the headers.
   Note: Always pass the price as an integer in cents (e.g., $10.00 is 1000).
2. Get the Redirect URL: Clover responds with a JSON object containing an href(the checkout URL).
3. Redirect the user: Your script redirects the customer to that href to complete their payment securely on Clover servers.

$payload = [  
    "customer" => ["email" => "[email protected]"],  
    "shoppingCart" => [  
        "lineItems" => [  
            [  
                "name" => "Custom Product",  
                "unitQty" => 1,  
                "price" => 5000 // Correct: $50.00 in cents
            ]  
        ]  
    ]  
];

Can I obtain a token or card-on-file (COF) identifier without capturing a CVV?

Storing card data without CVV is not supported by Clover APIs. Clover requires the CVV to tokenize a card and create a card-on-file (COF) record. This is a security requirement to ensure the cardholder is present and authorizes the card to be stored. If your business model involves delayed billing, consider:

• Pre-authorizing the card at the time of collection.
• Requesting payment upfront using Hosted Checkout or the Ecommerce API.

Why am I getting the error Invalid Request. Pay request sent for stored credentials transaction with invalid source when using the Clover payment API?

This error occurs when a request is made for a stored credential transaction, such as a recurring payment or a subsequent charge using a card token (source) that is invalid. If the token wasn’t saved to a customer during creation, it becomes single-use only and cannot be reused for stored credential transactions. Make sure to associate the token with a customer to enable reuse.

To reuse a card, the token must be vaulted. This is done by associating the token with a Customer object (POST /v1/customers). Once saved to a customer, Clover generates a multi-pay token that can be used for future charges.

Do private tokens used in Clover Ecommerce API expire? What is the purpose of public tokens?

Yes, OAuth access tokens (private tokens) used with the Clover Ecommerce API do expire. These tokens are typically used for secure, ongoing API access and must be refreshed periodically. However, if you're using a merchant-generated token, which is created manually by a merchant for a specific integration, it currently does not expire. This type of token is intended for one-off use cases where a merchant provides access for a custom app built specifically for them.

Public tokens, on the other hand, are generally used for client-side verification and initial authentication flows. They are not sufficient for performing sensitive operations like payments or inventory management and are typically exchanged for private tokens during the OAuth flow.

Learn more about API keys and OAuth tokens for secure ecommerce.

How can I migrate existing credit card data to Clover without CVV? Is it possible to create a card token without CVV?

Clover requires the CVV to tokenize a credit card using the Create card token endpoint. This is a security requirement and cannot be bypassed.

The recommended approach is to request the customers to re-enter their card details using the Clover secure iframe or checkout flow. This ensures compliance with PCI and tokenization requirements. If your previous processor supports detokenization, you may be able to retrieve full card details (including the CVV) securely; however, this is rare and typically not permitted under PCI-DSS.

Tip: If you have card-on-file (CoF) needs, once you obtain the initial token, which requires the CVV, you can use the vaultedCard or customerId flow for future charges. Those subsequent charges do not require the CVV to be sent again.

Can I remove the tax field from the ecommerce charge receipt if no taxes are applied?

No, the tax field in the receipt cannot be removed. Even if the service being sold does not include taxes, the Clover Ecommerce API generates standardized receipts where the tax line item is a mandatory field, defaulting to $0.00 if no tax is calculated or provided in the charge request.

Is the x-forwarded-for header required for Ecommerce API create and capture charge requests?

Yes, Clover now requires the x-forwarded-for header for all Ecommerce charge and capture requests. This header must include the client’s IP address where the payment originates. This applies even when using multi-use or previously generated tokens.

What’s the best way to integrate credit card payments into our internal PHP-based order system?

You can use the Clover Ecommerce API to preauthorize payments (set capture=false) and later use capture the charge when the product ships.

Send a POST request to /v1/charges, setting capture: false. This holds the funds on the customer's card for a limited time (typically 7 days, depending on the bank) but does not finalize the sale. When you are ready to ship, send a POST request to /v1/charges/{chargeId}/capture. You cannot capture an amount greater than the original authorization.

This works well for internal browser-based apps. The iframe integration is also supported but is more suited for customer-facing flows. You can generate a merchant Ecommerce API token to authenticate requests.

Fraud rules

Why are customer payments failing due to minor differences in billing address formatting? Can I adjust the security settings to prevent this?

Payment failures can occur when the billing address entered doesn't exactly match the one on the cardholder's statement. Clover uses AVS (Address Verification Service), which may decline transactions due to minor differences like "St." vs "Street" or "PO Box" vs "P.O. Box". This is a standard fraud prevention measure.

What you can do:

• Clover merchant settings: If you're a Clover merchant, you can review and adjust your Ecommerce fraud settings in the Dashboard. These settings may allow you to relax address verification requirements.
• Contact Clover Support: For assistance with modifying fraud settings or understanding address verification behavior, contact Clover support directly.

Best practices:

• Customer guidance: Prompt customers to enter their billing address exactly as it appears on their credit card statement.
• Form validation: Consider adding inline tips or examples in your checkout form to reduce formatting errors.

Why does token generation fail for AMEX and Mastercard but work for Visa and Discover?

The error may be due to incorrect brand values in your request body. Use AMEX for American Express and MC for Mastercard in your request body to avoid the Invalid JSON format error.

Gift card

Do we have test gift cards?

Currently, we do not provide test gift cards.

Hosted Checkout

Can I use Clover Hosted Checkout with an existing customer?

No, Clover Hosted Checkout does not support linking to existing customers. The customer object is used only to collect information for the current transaction. Even if you enter an existing customer ID from the Clover database in the customer.id field when creating the checkout, it does not link to that record. The checkout does not autopopulate details such as name or email, and a new customer record is created upon payment. The id field under the customer object is only for assigning a custom ID to the new customer; if left blank, Clover auto-generates one.

How can I pass a simple cart total to the Clover Hosted Payment Page using the Ecommerce API?

You can use Clover Hosted Checkout that generates the checkout_post_url. This allows you to redirect customers to a secure payment page with pre-filled transaction details. Send a POST request to: https://checkout.clover.com/v1/checkout

Here's a basic example of the payload structure. Replace amount with your cart total (in cents), and set redirectUrl to the page you want users to land on after a successful payment.

{
  "customer": {
    "email": "[email protected]"
  },
  "shoppingCart": {
    "lineItems": [
      {
        "name": "Cart Total",
        "unitQty": 1,
        "price": 1000
      }
    ]
  },
  "amount": 1000,
  "currency": "usd",
  "successUrl": "https://yourdomain.com/success",
  "cancelUrl": "https://yourdomain.com/cancel"
}

How can I check the status of a Hosted Checkout session using the checkoutSessionId  on Clover production site?

Currently, Clover does not provide a GET API endpoint to retrieve the status of a hosted checkout session using the checkoutSessionId. Sessions are valid for 15 minutes, and if payment is not completed within that window, a new session must be created. The session becomes visible in the Merchant Dashboard only after payment is completed.

The recommended approach is to use webhooks. To track payment status, set up Clover webhooks to receive real-time notifications when a payment is completed.

Can I use Clover Hosted Checkout for a standalone ecommerce site without POS or inventory features?

Yes, Clover Hosted Checkout can be used for standalone ecommerce sites focused solely on digital payments. For example, if you want to pass cart and price information to the Hosted Checkout page and redirect users back to your site, you can use this integration. Note that you can use production API tokens in the sandbox environment. To begin development, you’ll need to generate a sandbox-specific Ecommerce API Token. See Hosted Checkout integration.

How can I retrieve the customer note from a hosted payment form using the Clover API?

If a customer note was added during checkout, it is typically stored in the note field of the line item within the order. To retrieve it: Use the Orders API and expand the lineItems field: GET /v3/merchants/{merchantId}/orders/{orderId}?expand=lineItems

In the response, check each line item for the note property. If the note was added at the order level (not tied to a specific item), it may appear in the order’s top-level note field. However, most Hosted Checkout implementations associate notes with line items.

Why is the service fee not displaying in Clover Hosted Checkout even though it’s configured in the sandbox account?

Hosted Checkout doesn’t automatically display service fees unless they’re manually added via API. Check your sandbox developer account settings to ensure the service fee is correctly configured to appear with subtotal, tax, and tip. You’ll need to:

1. Retrieve the service charge ID: GET /v3/merchants/{mId}/default_service_charge
2. Apply it to the order: POST /v3/merchants/{mId}/orders/{orderId}/service_charge

For more information, see:

• Transaction data: Charges and fees
• Hosted Checkout integration

Why isn’t my API token working for Clover Hosted Checkout and why does “Try it” keep loading?

For Clover Hosted Checkout, the access token must be sent as a Bearer authorization header—it cannot be included as a URL parameter. Ensure your token’s integration type is set to Hosted Checkout; using the wrong integration type will cause errorsm, such as 406 Not Acceptable.

To fix the 406 Not Acceptable error or authentication failures, verify the following in your Merchant Dashboard (not the Developer Dashboard):

1. Go to Settings > View all settings, and the Ecommerce API Tokens.
2. Check Integration Type: Ensure the token is set specifically to Hosted Checkout. A token generated for "Iframe" or "API Only" will often reject Hosted Checkout session requests.

Note: Clover allows only one active Ecommerce token per merchant. Generating a new one will typically invalidate the previous one.

Hosted Iframe

How can I integrate Clover Iframe checkout into a private web app for a single merchant?

For a private app serving one merchant, use the Ecommerce API token from the Merchant Dashboard (Settings > Ecommerce > Ecommerce API Tokens). This token enables secure communication after enabling 2FA and location access.

If your sandbox token stopped working, it may have expired. You can:

• Regenerate the token through the Developer Dashboard. See Generate Ecommerce API tokens (public and private keys.
• Set up OAuth; recommended for multi-merchant apps, but usable for private apps too.

For iframe integration in sandbox, select Hosted iFrame + API/SDK to get public and private keys for secure checkout embedding.

Will a payment window display on an Ecommerce site when a payment request is sent to Clover?

Yes, a payment window can open on your Ecommerce site if the Clover iFrame integration is properly implemented. If it does not appear, it’s likely due to a misconfiguration in your integration code.

Why does clover.createToken() return null when CARD_STREET_ADDRESS is missing or invalid in the iframe integration?

On the iframe integration, if the merchant has AVS (Address Verification System) fraud rules enabled, the clover.createToken() method can return null without a detailed error message when CARD_STREET_ADDRESS is missing or invalid. This differs from required fields, such as CARD_NUMBER, which returns a structured validation error.

Can I store a customer’s credit card for future use when using the Iframe?

Yes, you can store a customer's credit card for future use when using the Iframe. The Hosted Iframe is designed to tokenize card data, and you can use the returned card token to save the card to a customer profile for future transactions. This process is compliant with PCI-DSS standards and requires explicit cardholder consent. For implementation details, see:

• Save a card for future transactions
• Iframe integrations

Can I change the language of input placeholders in the Iframe?

Yes, you can change the language of input placeholders in the hosted iframe by setting the locale parameter when initializing the Clover SDK. Supported locale options include "en", "en-CA", and "fr-CA". Example:

const clover = new Clover('your-api-key', { locale: 'fr-CA' });
const elements = clover.elements();

This will localize the input fields, including placeholders, to French (Canada). See Customize iframe elements.

Can I use the same Clover Ecommerce API token for both iframe integration and REST API access?

Yes, you can use the same Ecommerce API token for both hosted iframe integration and REST API access. Clover provides a public key (apiAccessKey or PAKMS key) for iframe tokenization and a private key that serves as the Bearer token for REST API calls. These are generated together when you create an Ecommerce API token for the integration type Hosted iFrame + API/SDK in the Merchant Dashboard. See the following for more information:

• Set up an Ecommerce API token
• Iframe—Create a payment form
• Ecommerce API—Accept payments flow

Plugins

How can I accept Clover payments on my WordPress site using WooCommerce?

You can integrate Clover with your WordPress site by using the Clover Payments for WooCommerce plugin. This allows you to accept secure payments through your Clover merchant account. To set it up:

1. Install and activate the Clover Payments for WooCommerce plugin.
2. Generate an Ecommerce API token with integration type: Hosted iFrame + API/SDK.
3. Copy the Public Token, Private Token, and Merchant ID.
4. Configure the plugin in WooCommerce > Settings > Payments > Clover Payments by entering the tokens and Merchant ID in the respective fields.
5. Select the environment: Sandbox for testing or Production for live transactions, then save the changes.

For detailed instructions, see Clover Payments for WooCommerce.

Virtual Terminal

Can I use the Virtual Terminal to accept payments on a non-Clover Android mobile device?

The Clover Virtual Terminal is designed for use in the Clover Merchant Dashboard, which can be accessed through a web browser on desktop or mobile devices. It is not intended for integration into third-party mobile applications.

If you're building a payment solution for a non-Clover Android device, you should use the Ecommerce API, which is designed for developers to integrate secure online payments into custom applications. The Ecommerce API provides endpoints for creating charges, managing inventory, and handling merchant data.