Surcharging

A surcharge is an additional fee applied to a transaction to recover the cost of card acceptance. Instead of absorbing interchange and scheme fees into your pricing, you pass some or all of that cost directly to the customer at checkout. VINR calculates the surcharge automatically based on card type and your configured rate, adds it to the total before capture, and surfaces it on receipts and in settlement reporting.

How surcharging worksAskCopy

When surcharging is active, VINR inspects the card presented at checkout and resolves the applicable surcharge using your configuration:

1. VINR identifies the card's network and, where available, whether it is a credit or debit card.
2. The surcharge amount is computed — either as a fixed minor-unit value, as a percentage of the payment amount, or automatically at VINR's cost-recovery rate.
3. The surcharge is added to the original amount to form the total charged to the customer.
4. Both the original amount and the surcharge amount appear as separate line items on the hosted checkout, the payment receipt, and the settlement record.

No code changes are needed to handle the math — VINR applies and tracks the surcharge on the payment object so your systems only need to read surchargeAmount from the response.

Enable surchargingAskCopy

Dashboard: go to Settings → Payment processing → Surcharging, toggle the feature on, and choose your default surcharge mode and rate. Changes take effect on new payments immediately.

SDK: pass surchargeConfig when creating a payment to enable surcharging and control the mode for that specific charge.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const payment = await vinr.payments.create({
  amount: 5000,
  currency: 'USD',
  description: 'Order #8821',
  returnUrl: 'https://yoursite.com/orders/8821',
  surchargeConfig: {
    mode: 'automatic',
  },
  metadata: { orderId: '8821' },
});

// After the customer completes checkout:
// payment.amount           → 5000   (original)
// payment.surchargeAmount  → 147    (e.g. 2.95% of 5000, rounded to minor units)
// payment.totalAmount      → 5147   (amount actually charged to the card)

The response object always includes surchargeAmount (integer, minor units) and totalAmount even when the resolved surcharge is zero — this keeps downstream reconciliation logic consistent.

Fixed vs percentage surchargeAskCopy

Example using a percentage with a cap:

const payment = await vinr.payments.create({
  amount: 20000,
  currency: 'USD',
  description: 'Order #9902',
  returnUrl: 'https://yoursite.com/orders/9902',
  surchargeConfig: {
    mode: 'percentage',
    percentage: 0.04,
    maxAmount: 500,
  },
});

// payment.surchargeAmount  → 500   (4% of 20000 = 800, but capped at 500)
// payment.totalAmount      → 20500

When mode is automatic, you do not need to set fixedAmount or percentage — VINR resolves the rate internally from your account's processing cost profile for that card type.

Receipts and disclosureAskCopy

Most jurisdictions that permit surcharging require pre-checkout disclosure. Customers must know the surcharge amount — or at minimum the surcharge rate — before they consent to the charge. VINR's hosted checkout handles this automatically:

• The surcharge amount is displayed as a distinct line item on the payment summary page, before the customer submits.
• The final receipt (email and hosted receipt page) repeats the breakdown: original amount, surcharge, and total.
• The surchargeAmount and totalAmount fields on the payment object are available for inclusion in your own order confirmation emails or PDF invoices.

You remain responsible for regional compliance, including any required signage (e.g. US card network rules requiring a posted notice), any caps on permissible surcharge rates, and any reporting obligations. VINR's tooling satisfies the technical disclosure requirement on the hosted checkout, not the broader compliance programme.

Next stepsAskCopy