Manage transaction data (REST API)

Retrieve transaction information

Clover REST API enables access to detailed transaction data for utilization and display in your application. Your application must possess read payment permission to access this data. If your app enables the merchant to update payment or authorization data, it must also request permission to write payments.

Understand credit card surcharge

A credit card surcharge is a percentage of the post-tax order total collected to partially or fully cover the merchant's costs associated with processing credit card payments. Some merchants are configured to add a surcharge to eligible credit BIN credit card transactions they process. Surcharges are only applied when the customer pays with an eligible credit BIN credit card; they are not added to debit, cash, or other forms of payment. Surcharge rules are set by the card networks.

Clover onboards merchants for credit card surcharging in the following countries:

• Canada, excluding Quebec
• United States, excluding states with legal restrictions or prohibitions

Canada uses a flat 2.40% credit card surcharge rate, while in the US, the surcharge can vary by merchant, with most US merchants having a surcharge of 3.00%.

If you display transaction data in your app, you must use data from a few fields. To check if a merchant is set up for surcharging, send a GET request to the /v3/merchants/{mId}/ecomm_payment_configs endpoint. In the response, check that the surcharging.supported value is true. You can also see the merchant's credit card surcharge rate in the rate field.

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{merchantUUID}/ecomm_payment_configs' \
  --header 'accept: application/json'

{
  "surcharging": {
    "supported": true,
    "rate": 0.035
  }
  ...
}

To view the surcharge data for a transaction, add the expand query parameter with the value additionalCharges as shown in the following example.

Calculate surcharge for paid transaction

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{merchantUUID}/payments/{paymentUUID}?expand=additionalCharges' \
  --header 'accept: application/json'

{
  "id": "RCFSJ33GPYM3D",
  "amount": 3500,
  ...
  "additionalCharges": {
    "elements": [
      {
        "id": "AGPT72N3N5TDM",
        "amount": 122,
        "rate": 35000,
        "type": "CREDIT_SURCHARGE",
        "payment": {
          "id": "RCFSJ33GPYM3D"
        }
      }
    ]
  }
}

The response includes an additionalCharges object showing the following:

• amount - amount paid in paid as a surcharge on the credit card transaction.
• rate - percentage of the total used to calculate the amount multiplied by 10000. A 3.5% rate is represented as 35000.
• type - kind of additional charge processed for the transaction. At the time of this writing, this can be one of two values:
  • CREDIT_SURCHARGE - a percentage fee added to a credit card transaction from an eligible credit BIN to cover the cost of processing.
  • INTERAC_V2 - a fixed amount added to Interac debit transactions.
• payment - contains the Universally Unique Identifier (UUID) of the associated payment

🚧

IMPORTANT

Total amount paid by the customer is the sum of the payment amount and additionalCharges.amount. In the preceding example, the customer was charged $36.22 (the $35.00 amount plus a 3.5% surcharge of $1.22).

Calculate the surcharge for the refund transactions

The paid transaction calculation is applicable for refund data. You can retrieve the updated order and surcharge for a partial refund to display in your app.

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{merchantUUID}/refunds/{refundUUID}?expand=additionalCharges' \
  --header 'accept: application/json'

{
  "id": "JRWNWS4Y7SSTP",
  "orderRef": {
    "id": "KTRPNSER0FA5W",
    "total": 2000
  },
  "amount": 1500,
  "payment": {
    "id": "ZV67XE59NGF1Y"
    "amount": 3500,
  },
  "additionalCharges": {
    "elements": [
      {
        "id": "AGPT72N3N5TDM",
        "amount": 52,
        "rate": 35000,
        "type": "CREDIT_SURCHARGE",
        "refund": {
          "id": "JRWNWS4Y7SSTP"
        }
      }
    ]
  }
}

In this example, the customer was refunded $15.00 of the original $35.00. Because the customer paid with a credit card, the customer was refunded an additional $0.52 of the original surcharge for a total refund of $15.52.

🚧

IMPORTANT

Total amount refunded to the customer is the sum of the refund amount and additionalCharges.amount. In the example, the customer was refunded $15.52 (the $15.00 amount plus a 3.5% surcharge refund of $0.52).

Tips and surcharges

A customer can add a tip to a payment in two ways:

• Through the device: When the customer adds the tipAmount to the payment amount through the device. The sum is multiplied by the surcharge rate to determine the total charged to the customer's card.  If the order total is $25.00, and the customer adds a 20% tip of $5, they will be charged an additional 3.5% surcharge of $1.05 if the payment is made by credit card. That is (2500 + 500) * 1.035 = 3105
• On paper: If a tip is added on paper, the tip is not included when calculating the surcharge.

Understand convenience fees

Merchants can collect a fixed convenience fee using Virtual Terminal as an alternative payment channel. If you display transaction data in your app, you must use data from several fields to ensure proper reporting for merchants.

To view the convenience fee collected for a transaction, add the expand query parameter with the value additionalCharges as shown in the following example.

Calculate surcharge for paid transaction

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{merchantUUID}/payments/{paymentUUID}?expand=additionalCharges' \
  --header 'accept: application/json'

{
  "id": "MERQ5J3KFETNY",
  "amount": 2000,
  ...
  "additionalCharges": {
    "elements": [
      {
        "id": "3NTR8H89C1D8M",
        "amount": 300,
        "type": "CONVENIENCE_FEE",
        "payment": {
          "id": "MERQ5J3KFETNY"
        }
      }
    ]
  }
}

Response includes an additionalCharges object showing the following:

• amount - number of cents paid as a convenience fee on the transaction
• type - the kind of additional charge processed for the transaction (in this case, CONVENIENCE_FEE)
• payment - contains the UUID of the associated payment

🚧

IMPORTANT

Total amount paid by the customer is the sum of the payment amount and additionalCharges.amount. In the preceding example, the customer was charged $23.00 (the $20.00 amount plus a $3.00 convenience fee).

Calculate the convenience fees for refund transaction

curl --request GET \
  --url 'https://apisandbox.dev.clover.com/v3/merchants/{merchantUUID}/refunds/{refundUUID}?expand=additionalCharges' \
  --header 'accept: application/json'

{
  "id": "CY3XR7R6D9B3P",
  "amount": 1550,
  "additionalCharges": {
    "elements": [
      {
        "id": "12DB2D19N2SXE",
        "amount": 300,
        "type": "CONVENIENCE_FEE",
        "refund": {
          "id": "CY3XR7R6D9B3P"
        }
      }
    ]
  }
}

Response includes the following data:

• amount - number of cents refunded to the customer
• additionalCharges.elements.amount - number of cents refunded to the customer originally charged as a convenience fee
• additionalCharges.elements.type - kind of additional charge processed for the transaction (in this case, CONVENIENCE_FEE)
• additionalCharges.elements.refund - contains the UUID of the associated refund

🚧

IMPORTANT

Total amount refunded to the customer is the sum of the refund amount and additionalCharges.amount. In the example, the customer was refunded $18.50 (the $15.50 amount plus a $3.00 convenience fee).