Card Surcharges

Applies to: Payments API | Terminal API | Mobile Payments SDK

Card surcharges allow merchants to pass on the cost of card processing to customers who choose to pay with a credit card instead of cash or other payment methods. When a payment includes a surcharge, Square provides detailed information about the surcharge amounts in the payment record through the applied_card_surcharge_details (CardSurchargeDetails) property.

This guide explains how to retrieve and interpret surcharge information when fetching payments that were processed with card surcharges through the Terminal API or Mobile Payments SDK.

When you retrieve a payment that includes a card surcharge using GetPayment or ListPayments, the response includes surcharge information in the card_details.applied_card_surcharge_details field.

The applied_card_surcharge_details property contains one money sub-property:

• card_surcharge_money - The base surcharge amount levied by the merchant for using a card payment instead of cash or another payment type. This amount only includes the surcharge itself, not any additional fees or taxes on the surcharge.

This amount is specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents).

The applied_card_surcharge_details field only appears on payments that have a surcharge applied. For payments without surcharges, this field is not present in the response.

The following example shows how to retrieve a payment and access its surcharge information:

When a payment includes a surcharge, the response includes the applied_card_surcharge_details field:

{
  "payment": {
    "id": "PAYMENT_ID",
    "created_at": "2024-12-15T10:30:00.000Z",
    "updated_at": "2024-12-15T10:30:05.000Z",
    "amount_money": {
      "amount": 10300,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "VISA",
        "last_4": "1234",
        "exp_month": 12,
        "exp_year": 2025
      },
      "applied_card_surcharge_details": {
        "card_surcharge_money": {
          "amount": 300,
          "currency": "USD"
        }
      },
      "entry_method": "KEYED",
      "cvv_status": "CVV_ACCEPTED",
      "avs_status": "AVS_ACCEPTED"
    },
    "location_id": "LOCATION_ID",
    "total_money": {
      "amount": 10300,
      "currency": "USD"
    }
  }
}

In this example:

• The base payment amount is $100.00 (10000 cents)
• The card surcharge is $3.00 (300 cents)
• The total payment amount is $103.00 (10300 cents)

When processing payments with surcharges in your application, consider the following:

To determine the original purchase amount before surcharges:

// Example in JavaScript
const payment = // ... retrieved payment object
const cardDetails = payment.card_details;

if (cardDetails.applied_card_surcharge_details) {
  const totalAmount = payment.amount_money.amount;
  const surchargeAmount = cardDetails.applied_card_surcharge_details.card_surcharge_money.amount;
  const baseAmount = totalAmount - surchargeAmount;

  console.log(`Base amount: ${baseAmount}`);
  console.log(`Surcharge: ${surchargeAmount}`);
  console.log(`Total charged: ${totalAmount}`);
}

When displaying payment details to customers or in reports, clearly separate:

• The base purchase amount
• The card processing surcharge
• The total amount charged

When working with card surcharges:

1. Check for surcharge presence - Always verify if applied_card_surcharge_details exists before attempting to access its fields, as it's only present on payments with surcharges.

2. Handle currency properly - Remember that all money amounts are in the smallest currency unit. Convert appropriately for display purposes.

3. Maintain transparency - Clearly communicate surcharge amounts to customers in receipts and payment confirmations.

4. Consider regional regulations - Be aware that surcharge regulations vary by region. Some jurisdictions have specific rules about card surcharges.

5. Reconciliation - When reconciling payments, account for both the base surcharge and any additional amounts separately for accurate financial reporting.

Card surcharges are configured and applied when creating payments through:

• Terminal API - For in-person payments using Square Terminal
• Mobile Payments SDK - For mobile payment applications

The surcharge configuration happens at payment creation time through these APIs. The Payments API only provides read access to surcharge details after the payment is created.

When using payment webhooks, the payment.created and payment.updated webhook events include the applied_card_surcharge_details field for payments with surcharges.

• Retrieve Payments - Learn more about fetching payment details
• Card Payments - Overview of card payment processing
• Terminal API Documentation - Configure surcharges for in-person payments
• Mobile Payments SDK - Implement surcharges in mobile applications
• Working with Monetary Amounts - Understanding currency handling in Square APIs