Use Remote Pay SDKs for surcharging

Retrieve transaction information

Payment responses that the Clover device returns provide detailed transaction data for your application to use and display.

Understand credit card surcharges

Prerequisites

To work with surcharge data, your app must use the following minimum SDK version for your language/platform:

View surcharge for a transaction

Some merchants are configured to add a surcharge to all credit card transactions they process. This surcharge is a set percentage of the post-tax order total. To display transaction data in your app, you need to use data from different fields.

Request

The surcharge data for a transaction is reported in the PaymentResponse.payment.additionalCharges object, where PaymentResponse is one of the following—SaleResponse, AuthResponse, or PreAuthResponse.

{
  "payment": {
    "id": "2XPG4P9BK0WYP",
    "order": {
      "id": "7SBV9RRMT55AM"
    },
    "tender": {
      "label": "Credit Card",
    },
    "amount": 5457,
    "tipAmount": 0,
    "taxAmount": 357,
    "externalPaymentId": "C80J7Q7YXEME1",
    "cardTransaction": {
      "cardType": "DISCOVER",
      "entryType": "SWIPED",
      "last4": "6668",
      "type": "AUTH",
      "authCode": "590537",
      "referenceId": "024500500420",
      "transactionNo": "000041",
      "state": "CLOSED",
      "extra": {
        "authorizingNetworkName": "DISCOVER",
        "cvmResult": "NO_CVM_REQUIRED"
      },
      "cardholderName": "DEV KIT DISCOVER TESTCARD",
    },
    "additionalCharges": [
      {
        "id": "AGPT72N3N5TDM",
        "amount": 190,
        "rate": 35000,
        "type": "CREDIT_SURCHARGE"
      }
    ]
  }
}

Response

The response includes an additionalCharges object with the following information:

Response parameter	Description
`amount`	Amount in cents paid as a surcharge on the credit card transaction.
`rate`	Percentage of the total used to calculate the `amount` multiplied by 10000. Example: A 3.5% `rate` displays as `35000`.
`type`	Additional charge type processed for the transaction. Values: `CREDIT_SURCHARGE`—Percentage fee added to a credit card transaction from an eligible credit BIN to cover the cost of processing. `CONVENIENCE_FEE`—Fixed amount added to a debit or credit transaction processed using an alternative payment channel. `INTERAC_V2`—Fixed amount added to Interac debit transactions.

The total amount paid by the customer is the sum of the payment amount and additionalCharges.amount. In the example, the customer is charged $56.47 that is the $54.57 amount plus a 3.5% surcharge of $1.90.

View surcharge for a refund and void

Surcharge can also be used for refunds and voids. The surcharge data for a transaction is reported in the RefundPaymentResponse.refund.additionalCharges or VoidPaymentResponse.payment.additionalCharges object.

Request

{
  "success": true,
  "result": "SUCCESS",
  "reason": "voidSent",
  "message": "No extended information provided.",
  "payment": {
    "id": "SAWVHQD257AN4",
    "order": {
      "id": "N70SW85DW24VY"
    },
    "amount": 10470,
    "tipAmount": 0,
    "taxAmount": 31,
    "result": "SUCCESS",
    "additionalCharges": [
      {
        "id": "AGPT72N3N5TDM",
        "amount": 336,
        "rate": 35000,
        "type": "CREDIT_SURCHARGE"
      }
    ]
  }
}

Response

The response includes an additionalCharges object with the following information:

Response parameter	Description
`amount`	Surcharge amount in cents that is refunded or voided.
`rate`	Decimal percentage of the total used to calculate the `amount`.
`type`	Charge type added to the original payment. Values: `CREDIT_SURCHARGE`—Percentage fee added to a credit card transaction from an eligible credit BIN to cover the cost of processing. `CONVENIENCE_FEE`—Fixed amount added to a debit or credit transaction processed using an alternative payment channel. `INTERAC_V2`—Fixed amount added to Interac debit transactions.

Interac debit card surcharges

The information in this section applies to Remote Pay SDKs version 4 and above. Earlier versions of the SDK provided surcharge data for Interac transactions, but this fee was combined with the order total into a single value as the response amount field. Integrations upgrading from version 3 need a code change to ensure proper handling of the now separate surcharge and transaction amount values for Interac transactions.

Updated 5 days ago