Manage transaction data (REST API)

Retrieve transaction information

Using the Clover REST API, you can access detailed transaction data for use and display in your application. At a minimum, your application needs the read payments permission to access this data. If your app will allow the merchant to update payment or authorization data, your app must also request permission to write payments.

Understand surcharges (US only)

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. If you are going to display transaction data in your app, you will need to use data from a few different 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://sandbox.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.

curl --request GET \
  --url 'https://sandbox.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 - the number of cents paid as a surcharge on the credit card transaction
• rate - the percentage of the total used to calculate the amount multiplied by 10000. A 3.5% rate is represented as 35000.
• type - the 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 to cover the cost of processing
  • INTERAC_V2 - a fixed amount added to Interac debit transactions
• payment - contains the UUID of the associated payment

🚧

IMPORTANT

The 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).

This expansion can also be used when getting data about refunds. In the case of a partial refund, you can retrieve the updated order and surcharge to display in your app.

curl --request GET \
  --url 'https://sandbox.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"
        }
      }
    ]
  }
}

The response includes the following data:

• orderRef.total - the number of unrefunded cents remaining on the order
• amount - the number of cents refunded to the customer
• payment.amount - the number of cents originally paid for the order
• additionalCharges.elements.amount - the number of surcharged cents refunded to the customer
• additionalCharges.elements.rate - the decimal percentage of the total used to calculate the amount
• additionalCharges.elements.type - the 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 to cover the cost of processing
• INTERAC_V2 - a fixed amount added to Interac debit transactions
• additionalCharges.elements.refund - contains the UUID of the associated refund

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

🚧

IMPORTANT

The 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

There are two ways a customer can add a tip to a payment: on the Clover device or on a paper receipt. If a tip is added on the device, the tipAmount is added to the payment amount and then the sum is multiplied by the surcharge rate to determine the total charged to the customer's card. For example, if the order amount is $25.00 and the customer adds a 20% tip ($5), they will be charged an additional 3.5% surcharge ($1.05) if they pay with a credit card.

(2500 + 500) * 1.035 = 3105

If a tip is added on paper, the tip is not included when calculating the surcharge.

Understand convenience fees

Merchants using Virtual Terminal as an alternative payment channel can collect a fixed amount convenience fee. If you are going to display transaction data in your app, you will need to use data from a few different fields to ensure proper reporting for these 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.

curl --request GET \
  --url 'https://sandbox.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"
        }
      }
    ]
  }
}

The response includes an additionalCharges object showing the following:

• amount - the 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

The 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).

This expansion can also be used when getting data about refunds.

curl --request GET \
  --url 'https://sandbox.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"
        }
      }
    ]
  }
}

The response includes the following data:

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

🚧

IMPORTANT

The 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).