Transaction Fees

Overview

Acquiring payment transactions surface a fee breakdown via the fees field. Each entry describes one fee associated with the transaction, with a sign that tells you whether the fee debits or credits your payable amount.

The fees: [PaymentTransactionFee!] field is exposed on:

• PaymentDebitTransaction — payment (charge) transactions.
• PaymentCreditTransaction — refund transactions.
• PaymentOrderLineItem — line items within a payment order.

Fee shape

PaymentTransactionFee is an interface. All concrete fee types share the same two fields:

Field	Type	Description
accountingDirection	AccountingDirection	Direction the fee is moving from the subscriber's perspective. DEBIT deducts the fee from the total payable amount; CREDIT credits it.
feeAmount	Amount	The amount of the fee.

Fee categories

Discriminate concrete fee types via __typename. Each concrete type currently exposes the same fields as the interface; identification is by __typename only.

Concrete Type	What It Represents
MerchantFeePaymentTransactionFee	Merchant-side processing fees (Highnote's discount fee and per-transaction surcharges such as keyed-in, virtual terminal, cross-border, foreign exchange).
InterchangeFeePaymentTransactionFee	Interchange fee assessed between the acquirer and the card issuer.
NetworkFeePaymentTransactionFee	Network assessment fee charged by the card network (for example, Visa or Mastercard).
UndeterminedFeePaymentTransactionFee	Appears when the underlying fee category is UNSPECIFIED, UNKNOWN, or any unrecognized value — read accountingDirection and feeAmount like the other types.

Fees by pricing model

Whether a fee category is populated depends on the Pricing Model configured on the subscriber's contract. UndeterminedFeePaymentTransactionFee can appear on any model when the network or processor has not classified the fee.

Network Fee is not currently populated

Production code does not emit fees for NetworkFeePaymentTransactionFee today. The schema includes the type so subscribers can parse __typename defensively for forward compatibility as the schema evolves.

Pricing Model	Interchange	Merchant	Network
Blended	—	Yes	—
Interchange Plus (IC+)	Yes	Yes	—
Interchange Plus Plus (IC++)	Yes	Yes	Planned
Tiered	Yes	Yes	Planned

Query fee details

The following request and response demonstrate the fees array when populated.

Request example

Query the transaction by ID and select __typename on each fee to discriminate the concrete fee type:

query PaymentTransactionFees($id: ID!) {
  node(id: $id) {
    __typename
    ... on PaymentTransaction {
      id
      fees {
        __typename
        accountingDirection
        feeAmount {
          currencyCode
          value
          decimalPlaces
        }
      }
    }
  }
}

Response example

Interchange fees use four decimal places to support sub-cent precision. The transaction's payable amount is reduced by $0.0165 of interchange and $0.30 of merchant fees. See Acquiring transaction precision for the convention.

{
  "data": {
    "node": {
      "__typename": "PaymentDebitTransaction",
      "id": "<PAYMENT_DEBIT_TRANSACTION_ID>",
      "fees": [
        {
          "__typename": "InterchangeFeePaymentTransactionFee",
          "accountingDirection": "DEBIT",
          "feeAmount": {
            "currencyCode": "USD",
            "value": 165,
            "decimalPlaces": 4
          }
        },
        {
          "__typename": "MerchantFeePaymentTransactionFee",
          "accountingDirection": "DEBIT",
          "feeAmount": {
            "currencyCode": "USD",
            "value": 30,
            "decimalPlaces": 2
          }
        }
      ]
    }
  }
}