Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt

Use this file to discover all available pages before exploring further.

What is it? Additional charges that can be applied to transactions when using authorizeCustomerInitiatedTransaction or authorizeRecurring mutations that are intended to offset the fees incurred when processing a transaction. Please note that the rules and laws for when and how to collect these fees are complicated and vary for each card network and every state and continue to evolve. It’s recommended that you consult an attorney to ensure all the rules/laws are followed correctly prior to implementing.
When to Use
  • You want to pass processing costs to customers who choose specific payment methods.
  • You need to charge additional fees for certain payment channels (e.g., online payments).
  • You operate in states/regions that allow convenience or service fees.
ScenarioBen makes a $100 purchase at Maple Street Coffee, one of Clearpath Payment’s acceptors, and is charged a $3 convenience fee for paying online. Clearpath Payments processes the transaction for a total of $103.

​
Implementation rules

  1. Only one fee type can be included per transaction
  2. The fee amount must be included in the total transaction amount
  3. Available fee types:
    • CONVENIENCE: A convenience fee is a charge passed on to customers for the privilege of paying for a product or service in a way that is not standard for a business. For example, movie theaters have traditionally sold tickets in person at the box office. For those sales they cannot assess a convenience fee. However, if the movie theater provides customers an alternative option to pay by phone or over the internet using a credit card the theater can charge a convenience fee.
    • SERVICE: A type of convenience fee that is restricted to merchants within specific merchant category codes (MCC) such as education and government. Some networks require registration to use a service fee.
    • SURCHARGE: A type of convenience fee that is assessed on all transactions, not just certain channels. Banned by some states. Card networks must be notified prior to assessing. Each card network and state has rules on how the fee can be assessed.
  4. Depending on the card network and the type of fee the fee may be combined with purchase amount in a single transaction OR processed as two separate transactions (one transaction for the purchase amount and a second transaction for the fee amount). The rules are complicated so please contact your Tesouro representative for guidance.

​
Adding a fee

When adding a fee, specify:
  • The fee type (CONVENIENCE, SERVICE, or SURCHARGE)
  • The fee amount
  • Total amount that includes the fee
Use the cohortId field to link multiple transactions that are related to the same payment. A cohort ID should be used when you use separate transactions for the purchase amount and the fee which will allow you to track the related transactions together in reporting and reconciliation. 
{
  "cohortId": "241a938f-0d5a-42e8-8e4c-cab22cd816b8",
  "transactionAmountDetails": {
    "totalAmount": 103.0, // Base amount + fee
    "baseAmount": 100.0, // Original amount
    "currency": "USD",
    "fees": [
      {
        "type": "CONVENIENCE",
        "feeAmount": 3.0
      }
    ]
  }
}

mutation AuthorizeCIT($input: AuthorizeCustomerInitiatedTransactionInput!) {
  authorizeCustomerInitiatedTransaction(
    authorizeCustomerInitiatedTransactionInput: $input
  ) {
    authorizationResponse {
      status: __typename
      cardDetails {
        paymentBrand
        last4
      }
      tokenDetails {
        token
      }
      transactionId
      paymentId
    }
    errors {
      ... on Error {
        message
        __typename
      }
    }
  }
}

{
  "data": {
    "authorizeCustomerInitiatedTransaction": {
      "authorizationResponse": {
        "status": "AuthorizationApproval",
        "networkApprovalCode": "808907",
        "authorizationAmountDetails": {
          "approvedAmount": 103,
          "requestedAmount": 103,
          "currency": "USD"
        },
        "cardDetails": {
          "paymentBrand": "VISA",
          "last4": "0005"
        },
        "tokenDetails": {
          "token": "ae1d0699-a5f3-4548-aaa8-068b57564118"
        },
        "transactionId": "c0b554b8-7819-11ee-acb0-7445f363cd81",
        "paymentId": "c0b554b8-7819-11ee-acb0-7445f363cd81",
        "systemTraceAuditNumber": "808040",
        "networkResponseDetails": {
          "processorResponseCode": "A0000",
          "networkResponseCode": "00"
        },
        "avsResponseDetails": {
          "networkCode": null
        }
      },
      "errors": null
    }
  }
}