Surcharging with Stax API

What is credit card surcharging?

A payment card surcharge is a fee that is added to a payment when a customer uses their credit card for payment. Surcharging allows merchants to pass on some of the costs of accepting credit cards along to their customers.

Rules and Limitations

  • A surcharge can only be applied to credit card transactions, not debit or prepaid cards.
  • Merchant account must be set up for surcharging
  • Merchant must fill out forms with Visa and Mastercard to notify these card brands that they wish to surcharge their customer
  • When implementing surcharging, the software must clearly notify the customer that a surcharge fee is being applied.
    • This may include the payment screen, receipts, emails, reporting, etc.
  • The documentation here only accounts for card not present transactions. For information about card present transactions, please reach out to support.

Technical Implementation

Surcharging payment flow:

Prerequisite: Account must be set up for surcharging

  1. Create a customer (optional)
  2. Tokenize a credit card - Tokenizing a card will handle creating a customer if no customer record already exists.
  3. Calculate the surcharge amount to display to the payer using the tokenized card
  4. Charge the tokenized card

Making the Surcharge Payment

With surcharging enabled, Stax will always assess a surcharge for credit card transactions on a merchant account which has surcharging enabled.

To understand if a merchant account is set up for surcharging, developers can query the GET Merchant Registration endpoint and check to see that the value of cnp_credit_surcharge_rate is greater than 0. Additionally, querying the GET Merchant endpoint will return a boolean property is_surcharging_merchant which when true will indicate the merchant account is set up for surcharging.

Developers should NOT include the surcharge amount in the total being sent into the Charge a Payment Method route when making a payment.

Example If a transaction’s pre-surcharge total is $100, and a $4 surcharge should be assessed, the front end of the application should display that the surcharge will be $4, and that $104 will be charged to the customer, but the total that should be sent into the request to Stax API should remain 100.

Creating surcharged transactions do not require any special fields passed into the API. Using the $104 example from above, you would display to the payer that they will be charged $104, while the actual request POST body to the API will look something like this:

  "payment_method_id": "853c9tt3-e361-4194-97eb-03a268a832e9",
  "meta": {
    "tax": 0,
    "subtotal": 100
  "total": 100,
  "pre_auth": 0

Charge a Payment Method Documentation →

Calculating the Surcharge Amount

To calculate the surcharge amount of a transaction, developers can use the Review a transaction’s surcharge information endpoint, which checks if the merchant is set up for surcharging, and will check that the tokenized payment method’s bin_type is "CREDIT" to provide relevant surcharge information to be used in a UI to indicate bin type, surcharge rate, surcharge amount, and the total with surcharge added.

Using the same $104 example above, where the transaction’s total is $100, and the merchant’s surcharge rate is 4%, the response of the Review route on a credit card will look like this:

  "bin_type": "CREDIT",
  "surcharge_rate": 4.0,
  "surcharge_amount": 4.00,
  "total_with_surcharge_amount": 104.00

NOTE: When a card is detected to be a debit card, no surcharge will be added.

Testing Surcharging

A sandbox account must be specifically configured for surcharging. If you are interesting in testing surcharging, please request a sandbox account if you do not already have one, and reach out to support to configure your sandbox account for surcharging.

Once your sandbox account is set up properly, you will be able to fully test the Implementation flow outlined above, using our test card numbers.

Request a Sandbox account →