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

If you display transaction data in your app, you must include data from a few fields.

Check if a merchant is set up for surcharging

To check if a merchant is set up for surcharging

1. Send a GET request to the /v3/merchants/{mId}/ecomm_payment_configs endpoint.
2. 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
  }
  ...
}

View surcharge for a paid transaction

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

Request

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"
        }
      }
    ]
  }
}

Response

The response includes an additionalCharges object with the following information:

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

View surcharge for a refund transaction

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. The customer paid with a credit card so was was refunded an additional $0.52 of the original surcharge for a total refund of $15.52.

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, which includes the $15.00 amount plus a 3.5% surcharge refund of $0.52.

Understand convenience fees

Merchants can collect a fixed convenience fee using the 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.

View convenience fee for a paid transaction

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

Request

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

The response includes an additionalCharges object with the following:

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, that is the $20.00 amount plus a $3.00 convenience fee.

View convenience fee for a refund transaction

Request

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

The response includes the following information:

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 refunded amount includes the $15.50 amount plus a $3.00 convenience fee.