Payments and Refunds FAQs

Why doesn't the Clover Payment API response include card details or the last four digits of the card?

When accessing the Payments API the response does not include card details by default. To retrieve card-related information, such as the last four digits, you must use the expand=cardTransaction query parameter: {{baseUrl}}/v3/merchants/{{merchantId}}/payments?expand=cardTransaction.
This expands the cardTransaction object in the response, which contains the card details you're looking for.
To learn more, see Use expandable fields for API responses.

Why am I not receiving the first6Digit and authCode for manual refunds and offline transactions?

For offline transactions, limited information is available until the device reconnects and the transaction is successfully processed. As a result, the authCode may not be generated immediately, and the First6Digit may not be accessible. In cases of manual refunds or offline transactions, it's possible that the transaction is not authorized or is declined, which prevents these details from being returned.

Can I capture a pre-authorized payment in offline mode using the Payment Connector?

No. Capturing a pre-authorized payment requires the Clover device to be online. While Clover supports Offline Payments for standard Sale transactions, where the payment is queued for later processing, Pre-Auth and Capture operations require real-time communication with the payment gateway to verify and lock funds.

Does Clover support payments in Canadian dollars (CAD)?

Yes, Clover supports processing payments in Canadian dollars (CAD). Clover offers Multi-Currency Pricing (MCP) by allowing local currency codes in the currency field. The United States and Canadian merchants can accept payments and submit refunds in regional currencies with settlement currency as United States dollars (USD).

Once the customer completes the transaction in their regional 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.

Is there a Clover API to attach a customer’s signature to a payment transaction?

No, Clover does not provide an API to manually attach a signature to a payment transaction. If a customer signs during the payment flow, the signature is automatically linked to the transaction and is viewable in the Merchant Dashboard. Clover has moved away from requiring signatures as part of the payment flow. See CVM changes for more details and the blog: Clover Semi-Integration Signature Verification: No More Waiting on Your Payment Flow.

Key points:

• Automatic signature capture: If the customer signs during the payment process, Clover automatically stores the signature.
• Manual signature capture: If you use /v1/device/read-signature to collect a signature separately, there is no API to attach it to a transaction afterward.
• Storage responsibility: If you need to retain the signature for compliance or customer records, you must store it in your own system.

Can I do a manual refund through Apple Pay on the Clover POS?

Yes, Clover POS supports manual (naked) refunds using Apple Pay as a tender option.

How is the amount submitted calculated for card transactions in the Clover monthly processing statements?

The amount submitted in the Clover monthly merchant processing statement refers to the gross total of card transactions processed on a given day, before any deductions such as fees, refunds, or chargebacks. Clover calculates tax and fees per item or per order, depending on the transaction's structure. Rounding rules and surcharges may cause slight discrepancies between your app’s totals and the Clover-reported amounts.

To understand and reconcile this amount with your app’s order data:

1. Use the Clover Payments API to retrieve card transactions. Send a GET request to: /v3/merchants/{merchantId}/payments?expand=order, tender, additionalCharges
   The response provides the order ID linked to the payment, the tender type, and any additional charges, such as surcharges or service fees.
2. Match payments to orders. Each payment object includes a reference to the associated order. You can cross-reference this with your internal order records to calculate totals.
3. Understand surcharges and fees. Clover may apply credit card surcharges (such as: 3%) depending on merchant settings. These are included in the payment amount and can be retrieved using expand=additionalCharges. 
4. View monthly statements. Merchants can access detailed statements on the Merchant Dashboard. The Merchant Processing Statement displays the total submitted, fees deducted, and net deposits.

How can I find the Idempotency-Key for a refund created after an app crash?

Clover records the Idempotency-Key for each transaction, but it is not exposed through the standard refund API response. To track a refund after a crash:

1. Save the Idempotency-Key in your POS database before making the refund request.
2. Use the refund ID or payment ID to query existing refunds through the REST API.
3. Compare timestamps and amounts to identify the most recent refund.
4. If needed, contact Clover Developer Relations at: [email protected] with refund details for deeper investigation. See Track transactions with idempotency keys.

How should I correctly handle taxes for orders created using the Clover REST API?

To ensure taxes are properly calculated and reported for API-generated orders, see Calculate order totals. This guide covers how to:

• Apply tax rates to line items using the taxRates field.
• Ensure taxes appear under “Tax Collected” in the Reporting app.
• Structure orders so tax details are reflected in the Payments > Taxes section.

Proper configuration of tax rates and order structure is essential for accurate reporting.