Table of Contents

1. Surcharge General Information
2. Submitting New Transactions with Surcharge
3. Response for Surcharge Enabled Transactions
4. When Surcharge is Applied
5. How Surcharge is Applied
   1. Nontaxable surcharge
   2. Taxable surcharge
   3. Refunds and surcharge
6. Surcharge Disclosure Requirements
   1. PayJunction platform
   2. Integrated platforms

Surcharge General Information

• Minimum API Version:
  
  • API version 2023-05-16 or above required to receive the surcharge object and fields in transaction response details. See how to use API versions here.
• The surcharge object is only present if surcharge is enabled on the account:
  
  • Existing PayJunction customers must contact PayJunction's customer support team and submit a request to enable surcharge on their account.
• Supported PayJunction Smart Terminals:
  
  • ZeroTouch and Portable Terminals support surcharge. Initiating a payment with surcharge on older Smart Terminals will result in an error: Smart terminal type does not support payment requests on a surcharge-enabled terminal.
• The amountSurcharge field:
  • The amountSurcharge field cannot be set or changed if the terminal is surcharge-enabled. Instead, PayJunction determines if a transaction is eligible for a Surcharge and will automatically calculate and apply the surcharge amount. 
    • Error example: amountSurcharge is not allowed on a surcharge-enabled terminal.
  • For Surcharge enabled accounts, surcharge is disabled on transactions that include a value of $0.00 (or empty) for the amountSurcharge field.

Submitting New Transactions with Surcharge

Surcharge is supported on all of the following PayJunction features:

• Smart Terminal transactions
• Keyed transactions
• Recurring transactions
• Invoice transactions
• Hosted Payment transactions

PayJunction Automatically Determines Surcharge

There is no need to submit any additional data in the request in order to calculate and apply a surcharge. If surcharge is enabled, the amountSurcharge is automatically calculated based on the current surcharge percentage set on the terminal. 

• Note: Use the /GET terminals API to confirm if surcharge is enabled on an account.

For example, if the terminal has a surcharge percentage of 3%, and the amountBase is $10.00, the total amount will be $10.30. A $0.30 amountSurcharge is automatically added to the transaction.

• Note: There are situations where the surcharge cannot be applied (see When Surcharge is Applied). For instance, PayJunction automatically determines the card type and ensures that a surcharge will not be applied on debit cards.

Response for Surcharge Enabled Transactions

Example surcharge response object

{
      "surcharge" : {
            "percentage" : 3.00,
            "status" : "APPLIED|NOT_APPLIED_DEBIT"
      },
}

Basic example of transaction details for an account that has surcharge enabled. In this example, a 3% surcharge was applied to the credit card that was used for payment.

{
      "transactionId": 3601, 
      "uri": "https://api.payjunction.com/transactions/3601", 
      "terminalId" : 10000,
      "action" : "CHARGE",
      "amountBase" : "1.11",
      "amountTax" : "3.00",
      "amountShipping" : "1.00",
      "amountTip" : "2.00",
      "amountSurcharge" : "0.21",
      "amountTotal" : "7.32",
      "surcharge" : {
            "percentage" : 3.00,
            "status" : "APPLIED"
      },
      "method": "KEYED",
      "service": "API",
      "signatureStatus": "SIGNED", 
      "status": "CAPTURE", 
      "created": "2024-01-01T12:34:56Z", 
      "lastModified": "2024-01-01T12:34:56Z", 
      "response": {
            "approved": true, 
            "code": "00", 
            "message": "Approved", 
            "processor": {
                  "authorized": true, 
                  "approvalCode": "PJ20AP", 
                  "avs": {
                        "status": "REQUESTED", 
                        "requested": "BYPASS", 
                        "match": {
                              "ZIP": true, 
                              "ADDRESS": true
                        }
                  }, 
                  "cvv": {
                        "status": "NOT_REQUESTED"
                  }
            }
      }, 
      "settlement": {
            "settled": false
      }, 
      "vault": {
            "type": "CARD", 
            "accountType": "VISA", 
            "lastFour": "1111"
      }, 
      "billing": {
            "firstName": "John", 
            "middleName": "J", 
            "lastName": "Doe", 
            "address": {
                  "address": "1903 State St", 
                  "city": "Santa Barbara", 
                  "state": "CA", 
                  "country": "USA", 
                  "zip": "93101"
            }
      }, 
}

When Surcharge is Applied

Surcharges can only be applied to specific card payment types. For example, debit cards are exempt from surcharge. PayJunction determines the card type and adds a surcharge when applicable.

How Surcharge is Applied

The surcharge amount is calculated by applying the configured percentage to the subtotal of the transaction or schedule. The subtotal is the sum of all amounts (minus amountTax if the surcharge is taxable, see below).

We round half up to the closest penny if the calculated surcharge amount includes a fraction of a penny. For example, a surcharge amount of $7.765 is rounded to $7.77, and $7.764 is rounded to $7.76. The exact amount is returned in the response.

Consider a transaction request with the following parameters:

  ➜ curl https://api.payjunction.com/transactions ... \
  -d amountBase=10 \
  -d amountShipping=5 \
  -d amountTax=1.20 \
  -d amountTip=3.30

The subtotal is $19.50. Assuming a surcharge percentage of 3%, the calculated amountSurcharge is $0.585, which is rounded to $0.59. The final amountTotal is $20.09. Response for the request above:

  {
  "transactionId" : 12773,
  "uri" : "https://api.payjunction.com/transactions/12773",
  "terminalId" : 10000,
  "action" : "CHARGE",
  "amountBase" : "10.00",
  "amountTax" : "1.20",
  "amountShipping" : "5.00",
  "amountTip" : "3.30",
  "amountSurcharge" : "0.59",
  "amountTotal" : "20.09",
  "surcharge" : {
    "percentage" : 3.00,
    "status" : "APPLIED"
  },
  ...
}

Nontaxable surcharge

The subtotal used to calculate the surcharge amount is the sum of all available amount fields, including tax:

• amountBase
• amountShipping
• amountTax
• amountTip

The amountSurcharge is then added to the subtotal.

Example: $100 charge (including $8.05 tax), surcharge is applied at 3%:

  {
 ➜ curl https://api.payjunction.com/transactions ... \
  -d amountBase=91.95 \
  -d amountTax=8.05

{
  "transactionId" : 12773,
  "uri" : "https://api.payjunction.com/transactions/12773",
  "terminalId" : 10000,
  "action" : "CHARGE",
  "amountBase" : "91.95",
  "amountTax" : "8.05",
  "amountSurcharge" : "3.00",
  "amountTotal" : "103.00",
  "surcharge" : {
    "percentage" : 3.00,
    "status" : "APPLIED"
  },
  ...
}

Taxable Surcharge

Depending on local and state laws, merchants may be required to collect taxes on surcharges. In this case, the surcharge amount must be calculated before taxes and the tax amount must be increased to include the surcharge. The tax amount on the surcharge is specified using an additional request parameter, amountSurchargeTax:

If both amountSurchargeTax and amountTax are present in the request, the subtotal on which the surcharge amount is calculated is the sum of all amount fields minus amountSurchargeTax and amountTax:

• amountBase
• amountShipping
• amountTip

If a surcharge applies to the payment method, then the two tax fields are combined, and all the amounts are added to the total:

• amountTax = amountTax + amountSurchargeTax
• amountTotal = amountTax + amountSurcharge + amountBase + amountShipping + amountTip

If a surcharge does not apply to the payment method, amountSurchargeTax is discarded, and the total amount does not include amountSurcharge:

• amountTotal = amountTax + amountBase + amountShipping + amountTip

For example, consider a sale for $91.95 taxed at 8.75% (amountTax is $8.05). Surcharge is enabled on the terminal at 3%. If surcharge is applied, an amountSurcharge of $2.76 is added to the transaction (3% of $91.95). In this case, the amountSurchargeTax should be set to $0.24 (8.75% of $2.76).

The API request is:

  ➜ curl https://api.payjunction.com/transactions ... \
  -d amountBase=91.95 \
  -d amountTax=8.05 \
  -d amountSurchargeTax=0.24

If surcharge applies to the payment method, the amountTax in the response is the sum of amountSurchargeTax and amountTax ($0.24 + $8.05 = $8.29). Note that the total amount is the same as the transaction in the Nontaxable surcharge example above ($103), but amountSurchargeTax and amountTax are different:

  {
  "transactionId" : 12773,
  "uri" : "https://api.payjunction.com/transactions/12773",
  "terminalId" : 10000,
  "action" : "CHARGE",
  "amountBase" : "91.95",
  "amountTax" : "8.29",
  "amountSurcharge" : "2.76",
  "amountTotal" : "103.00",
  "surcharge" : {
    "percentage" : 3.00,
    "status" : "APPLIED"
  },
  ...
}

If surcharge does not apply to the payment method, amountSurchargeTax is discarded:

  {
  "transactionId" : 12773,
  "uri" : "https://api.payjunction.com/transactions/12773",
  "terminalId" : 10000,
  "action" : "CHARGE",
  "amountBase" : "91.95",
  "amountTax" : "8.05",
  "amountTotal" : "100.00",
  "surcharge" : {
    "percentage" : 3.00,
    "status" : "NOT_APPLIED_DEBIT"
  },
  ...
}

The amounts of transactions and schedules processed with taxable surcharge cannot be edited after processing. Any attempt will result in an API error:

  ➜ curl localhost:8081/trinity/api/schedules/12773 -X PUT -d amountShipping=0
{
  "errors" : [ {
    "message" : "The Schedule amount(s) could not be updated because a surcharge with tax was applied. A new schedule is required."
  } ]
}

Refunds and Surcharge

Charges and refunds processed on a surcharge-enabled terminal always include surcharge if applicable.

Full refunds include the full surcharge of the original transaction. For partial refunds, a proportional amount of the original surcharge is applied.

For example, a customer buys two $4.50 items, for a total of $9.27 ($9 of goods, plus $0.27 of surcharge at 3%). If they return one of the items, a $4.64 refund is issued ($4.50 refund for the item, plus $0.14 refund for the surcharge, rounded up from $0.135).

We always ensure the refunded amount does not exceed the original charged amount. In the example above, if the customer also returns the second item later, a $4.63 refund is issued: $4.50 for the item, and $0.13 for the surcharge. Note that with our rounding rules the surcharge amount should be $0.14, but since we already refunded $0.14, only $0.13 of the original $0.27 surcharge is left to refund.

Surcharge Disclosure Requirements

Card brand association rules require merchants to disclose surcharge information to their customers:

1. At the entrance of their store;
2. At the point of sale (in store and online); and
3. As a line item on the receipt.

PayJunction platform

PayJunction’s payment processing platform automatically handles surcharge disclosure for:

1. Card-present transactions on our Smart Terminals (point of sale);
2. Card-not-present transactions processed through our Hosted Payments and Invoices ecommerce solutions (point of sale); and
3. Receipts sent by or printed from PayJunction.

Integrated platforms

If your merchants are processing ecommerce transactions through your integrated software, we recommend that you include surcharge disclosure information before the customer checks out.

Disclosure messages vary depending on which brands are accepted by the merchant, state laws, and current surcharge percentage.

We provide a disclosure message on the Terminal Response. The disclosure is available for surcharge-enabled terminals in the surcharge.disclosure field as an array of strings, each string representing a paragraph for easy formatting. All paragraphs must be displayed on the checkout page with a font size of at least 10 points (based on Arial font family).

Avoid caching and / or storing the text in your application. Disclosure messages can change over time, and we recommend requesting a fresh copy from the API every time it’s needed.

Example disclosure from the Terminal API Response:

  {
  "terminalId" : 10123,
  ...
  "surcharge" : {
      "enabled" : true,
      "percentage" : 3.00,
      "taxable" : false,
      "disclosure" : [ "A surcharge applies to credit card transactions. The current rate is 3%. No surcharge applies to debit card transactions.", "To cover the cost of processing a credit or charge card transaction, and pursuant to section 5-2-212, Colorado revised statutes, a seller or lessor may impose a processing surcharge in an amount not to exceed the merchant discount fee that the seller or lessor incurs in processing the sales or lease transaction. A seller or lessor shall not impose a processing surcharge on payments made by use of cash, a check, or a debit card or redemption of a gift card." ]
    }
}

Example checkout page displaying the above disclosure: