Surcharge Payments

Set up tokenization

Follow the Tokenization guide to load ZeroGateway.js and configure your card fields. For the surcharge flow, modify the callback to fetch the rate instead of sending the token directly to your charge endpoint:

payment.js
let paymentToken = null;
let maskedCardNumber = null;
let binCard = null;
let enteredAmount = null;

CollectJS.configure({
  fields: {
    ccnumber: { selector: "#ccnumber", placeholder: "Card number" },
    ccexp:    { selector: "#ccexp",    placeholder: "MM / YY" },
    cvv:      { selector: "#cvv",      placeholder: "CVV" },
  },
  callback: async function (response) {
    paymentToken = response.token;
    maskedCardNumber = response.card.number;          // required on the charge as card.number
    binCard = response.card.number.slice(0, 6);       // first 6 digits of the masked number
    enteredAmount = parseInt(document.getElementById("amount").value); // cents

    await fetchRate(paymentToken, binCard, enteredAmount);
  },
});

document.getElementById("payment-form").addEventListener("submit", function (e) {
  e.preventDefault();
  CollectJS.startPaymentRequest();
});

Fetch the surcharge rate

After tokenization, send the token, BIN and amount to your server, which calls the Strictly GET /v1/public/payment/rate endpoint. It reads three query parameters:

The parameter is tokenId, not paymentToken. The rate call does not consume the token — only the charge does.

payment.js — fetch rate
async function fetchRate(token, binCard, amount) {
  const res = await fetch(`/api/rate?amount=${amount}&binCard=${binCard}&tokenId=${token}`);
  const { data } = await res.json();

  showReviewStep(data);
}

On your server. The example below uses Java, but this works the same in any server-side language:

RateController.java — Spring Boot
@RestController
@RequestMapping("/api")
public class RateController {

    private static final String RATE_URL =
        "https://api.paywithzero.net/v1/public/payment/rate";

    @GetMapping("/rate")
    public ResponseEntity<Map<String, Object>> getRate(
            @RequestParam String amount,
            @RequestParam String binCard,
            @RequestParam String tokenId) throws Exception {

        String credentials = Base64.getEncoder().encodeToString(
            (System.getenv("STRICTLY_EMAIL") + ":" + System.getenv("STRICTLY_PASSWORD")).getBytes()
        );

        String url = RATE_URL + "?amount=" + amount + "&binCard=" + binCard + "&tokenId=" + tokenId;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", "Basic " + credentials)
            .header("key-hash", System.getenv("STRICTLY_KEY_HASH"))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        return ResponseEntity.ok(
            new ObjectMapper().readValue(response.body(), Map.class)
        );
    }
}

The response:

Code
{
  "data": {
    "amount": 1000,
    "surcharge": 35,
    "totalAmount": 1035,
    "creditRate": 3.5,
    "debitRate": 0,
    "brand": "visa",
    "cardType": "credit"
  }
}

Obtaining binCard

The tokenization callback returns card: { number, exp, hash } — there is no bin field. The BIN is the first 6 digits of card.number (the masked number keeps them: 411111******1111 → 411111). On the Strictly gateway send both tokenId and binCard; if the BIN cannot be derived, the token value is accepted as a fallback for binCard.

Show the customer the breakdown

Display the rate data before the customer can confirm. This is required for surcharging compliance:

payment.js — show review step
function showReviewStep(rateData) {
  document.getElementById("review-base").textContent      = formatCents(rateData.amount);
  document.getElementById("review-surcharge").textContent = formatCents(rateData.surcharge);
  document.getElementById("review-total").textContent     = formatCents(rateData.totalAmount);

  document.getElementById("step-card").style.display   = "none";
  document.getElementById("step-review").style.display = "block";
}

function formatCents(cents) {
  return new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(cents / 100);
}

index.html — review step
<div id="step-review" style="display:none">
  <table>
    <tr><td>Base amount</td>           <td id="review-base"></td></tr>
    <tr><td>Surcharge</td>             <td id="review-surcharge"></td></tr>
    <tr><td><strong>Total</strong></td><td id="review-total"></td></tr>
  </table>
  <button id="btn-pay">Pay</button>
  <button id="btn-back">Back</button>
</div>

Charge with the base amount

When the customer confirms, send the token, the masked card number and the base amount to your server, then charge with that base amount. The API computes the surcharge server-side from the same BIN and adds it to the charged total, so it matches the /rate quote the customer saw. Never send totalAmount as amount: the surcharge would be applied twice.

payment.js — confirm payment
document.getElementById("btn-pay").addEventListener("click", async () => {
  const res = await fetch("/api/charge", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      paymentToken,
      cardNumber: maskedCardNumber,
      amount: enteredAmount,                              // base amount in cents
      email: document.getElementById("email").value,
      billingAddress: collectBillingAddress(),            // { address, city, state, zipCode, country }
    }),
  });

  const result = await res.json();
  if (result.success) {
    window.location.href = "/success";
  } else {
    alert("Payment failed: " + result.error);
  }
});

The example below uses Java, but this works the same in any server-side language:

ChargeController.java — Spring Boot
@RestController
@RequestMapping("/api")
public class ChargeController {

    private static final String CHARGE_URL =
        "https://api.paywithzero.net/v1/public/payment/charge";

    @PostMapping("/charge")
    public ResponseEntity<Map<String, Object>> charge(
            @RequestBody ChargeRequest req) throws Exception {

        String credentials = Base64.getEncoder().encodeToString(
            (System.getenv("STRICTLY_EMAIL") + ":" + System.getenv("STRICTLY_PASSWORD")).getBytes()
        );

        // Base amount only: the API adds the surcharge for this BIN server-side
        Map<String, Object> body = Map.of(
            "amount",         req.getAmount(),
            "card",           Map.of(
                "paymentToken", req.getPaymentToken(),
                "number",       req.getCardNumber()   // masked, from the callback
            ),
            "contact",        Map.of("email", req.getEmail()),
            "billingAddress", req.getBillingAddress(),
            "order",          Map.of(
                "amount",   req.getAmount(),
                "shipping", 0, "tax", 0, "discount", 0
            ),
            "capture", true
        );

        HttpRequest chargeRequest = HttpRequest.newBuilder()
            .uri(URI.create(CHARGE_URL))
            .header("Authorization", "Basic " + credentials)
            .header("key-hash", System.getenv("STRICTLY_KEY_HASH"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(
                new ObjectMapper().writeValueAsString(body)))
            .build();

        HttpResponse<String> chargeResponse = HttpClient.newHttpClient()
            .send(chargeRequest, HttpResponse.BodyHandlers.ofString());

        Map<String, Object> result = Map.of(
            "success", chargeResponse.statusCode() == 201,
            "data",    new ObjectMapper().readValue(chargeResponse.body(), Map.class)
        );

        return ResponseEntity.ok(result);
    }
}