Prerequisites

  Step 1 — Request a Session Token (Server-Side)

Call the session endpoint from your server, not the browser. The Authorization header contains your API secret. If you call it from the browser, anyone can steal your key.

The session token is a one-time token that expires in 5 minutes by default (configurable via expires). Request it fresh for each checkout — never cache or reuse tokens.

{
  "transactionType":      "PURCHASE",
  "purchaseAmount":       1025,
  "language":             "en",
  "amount":               "hidden",
  "avs":                  "both",
  "email":                true,
  "invoice":              "editable",
  "invoiceNumber":        "INV-001",
  "transactionDescription": "Order #2024-001",
  "expires":              "2026-06-30T23:59:59.0Z",
  "useRecaptcha":         true,
  "webhookUrl":           "https://your-site.com/webhook",
  "disableSubmitIndicator": false,
  "ignoreInitAuthTimeout": false
}

// Server-side — Node.js example
const response = await fetch(
  'https://uat.ca.shc.payfacto.cloud/secure-hosted-checkout/v1/sessions',
  {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${Buffer.from('username:password').toString('base64')}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({
      transactionType: 'PURCHASE',
      purchaseAmount:  1025,    // $10.25 in cents — mandatory for PURCHASE
      language:        'en'
    })
  }
);

const { token } = await response.json();
// Return this token to the browser — never expose your API key

  Restricting Payment Methods — allowList

When allowList is omitted entirely, every payment method enabled on the merchant account is offered.

{
  "transactionType": "PURCHASE",
  "purchaseAmount":  1025,
  "language":        "en",
  "allowList": [
    "VISA",
    "MASTERCARD",
    "APPLE_PAY",
    "PAYMENT_FORM"
  ]
}

  Webhook Best Practices

  Step 2 — Add the Script and Placeholder to Your Page

Add the SHC library script tag to your page <head> and an empty <div> wherever you want the card form to appear. The default container id is shc-fields — you can use a different id but must tell SHC about it via the sourceElement option.

<!-- 1. Add the SHC script to your page <head> -->
<script src="https://uat.ca.shc.payfacto.cloud/secure-hosted-checkout/v1/browser/shc.js"></script>

<!-- 2. Add a placeholder div where the iframe will appear -->
<div id="shc-fields"></div>

  Step 3 — Pass the Token to shc() in the Browser

Your server returns the session token to the browser as JSON. The browser then calls the global shc() function with the token as the first argument. The second argument is a callback. The callback fires when the cardholder clicks Pay. The third argument is optional and is an object containing browser-side options.

// Fetch the session token from your server, then call shc()
function getShcToken(done) {
  fetch('/your-server/get-shc-token')
    .then(r => r.json())
    .then(data => done(data.token));
}

getShcToken(shcToken => {
  shc(shcToken, response => handleResponse(response));
});

// shc() draws the iframe inside #shc-fields automatically

These options are different from session options — they control how the iframe behaves once it is created. Pass them as the third argument to shc(). Each entry in fields must have both visibility and value or SHC throws an error.

const options = {
  sourceElement:   'my-checkout-div',  // use a different container id
  cardholderName:  'Jane Doe',         // pre-fill and hide the name field
  purchaseAmount:  1025,               // hidden field, required for 3DS
  fields: {
    email:   { visibility: 'enabled',  value: 'jane@example.com' },
    postal:  { visibility: 'disabled', value: 'M5V 1A1' },
    address: { visibility: 'hidden',   value: '123 Main St' }
  }
};

shc(shcToken, response => handle(response), options);

  Step 4 — Handle the Callback Response

Never fulfil an order based on the callback alone. Always verify the HMAC on your server (Step 5) before releasing goods or services.

{
  "success": true,
  "response": {
    "authCode": "754062",
    "avs": "U",
    "brand": "VISA",
    "card": "************4242",
    "cvv2Cvc2Status": "M",
    "expiry": "1226",
    "invoiceNumber": "41343428",
    "isoResponseCode": "00",
    "issuerMessage": "AP",
    "lastFour": "4242",
    "name": "Test Card",
    "paymentMethod": "VISA CARD",
    "purchaseAmount": 500,
    "purchaseCurrency": "CAD",
    "purchaseDate": "2026-06-23 17:49:16 EDT",
    "secureId": "33f19cdc-5b74-456a-8e95-51527c5cc910",
    "status": "SUCCEEDED",
    "store": {
      "address": {
        "line1": "123 Some Street",
        "city": "Toronto",
        "state": "ON",
        "postalCode": "A1A 1A1",
        "country": "CA"
      },
      "email": "contact@merchant-store.com",
      "name": "Merchant Store",
      "phone": "(123) 456-7890",
      "website": "www.merchant.com"
    },
    "token": "c2FLxMZn51DZAMjAM3CkcppWf",
    "transactionDescription": "Transaction Description",
    "transactionId": "af569819-0125-4979-9dff-a81cda21ebd0",
    "transactionType": "PURCHASE",
    "type": "CREDIT"
  },
  "metadata": {
    "algorithm": "sha256",
    "HMAC": "3928cbccac77e3b66404c37bbfa2ec44dc8f839ed478fcc4637e29f600ec70e4",
    "receipt": "",
    "timestamp": "2026-06-23 17:49:16 EDT"
  }
}

{
  "success": true,
  "response": {
    "accountType": "BANK_ACCOUNT_CHEQUING",
    "expiry": "1230",
    "invoiceNumber": "61341840",
    "lastFour": "6457",
    "paymentConsentId": "37c3449c-e876-4190-9284-3a744048e8b5",
    "paymentMethod": "INTERAC_DIRECT",
    "purchaseAmount": 500,
    "purchaseCurrency": "CAD",
    "purchaseDate": "2026-06-23 17:34:12 EDT",
    "secureId": "d2f01954-a644-45b9-b1f3-03930f436af5",
    "status": "SUCCEEDED",
    "store": {
      "address": {
        "line1": "123 Some Street",
        "city": "Toronto",
        "state": "ON",
        "postalCode": "A1A 1A1",
        "country": "CA"
      },
      "email": "contact@merchant-store.com",
      "name": "Merchant Store",
      "phone": "(123) 456-7890",
      "website": "www.merchant.com"
    },
    "transactionDescription": "Transaction Description",
    "transactionId": "3ab9cd17-babb-4c53-aa02-23ed4bb0e962",
    "transactionType": "PURCHASE",
    "type": "INTERAC_DIRECT"
  },
  "metadata": {
    "algorithm": "sha256",
    "HMAC": "ee0600b30d0f0c955d40854334fd97245eb3c30d4bebc60668310c83fb221c4c",
    "receipt": "",
    "timestamp": "2026-06-23 17:34:12 EDT"
  }
}

{
  "success": false,
  "response": {
    "type": "CARD_DECLINED",
    "code": "INVALID_NUMBER",
    "message": "card number is incorrect"
  }
}

  Step 5 — Verify the HMAC (Server-Side)

Always verify HMACs on your server, never in the browser. The check only proves anything if your API secret stays secret.

Run JSON.stringify(response.response) — the inner response object, not the full envelope — through HMAC-SHA256 keyed with your API secret. Compare the result against metadata.HMAC. If they differ, discard the response and do not fulfil the order.

const crypto = require('crypto');

function verifyHmac(shcResponse, apiSecret) {
  const computed = crypto
    .createHmac(shcResponse.metadata.algorithm, apiSecret)
    .update(JSON.stringify(shcResponse.response))
    .digest('hex');

  return computed === shcResponse.metadata.HMAC;
}

if (!verifyHmac(response, process.env.API_SECRET)) {
  throw new Error('HMAC mismatch — do not process this response');
}
// Safe to fulfil the order

  Custom Forms

If the default styling options are not enough, you can build your own form. Wrap it in a <div> with an id, and pass that id to shc() as sourceElement. Give any input the matching SHC field id to activate validation, formatting, and secure submission for that field.

Before SHC copies your custom form into the secure iframe, it strips <script>, <iframe>, <object>, <a> tags, any <input type=submit> or <button type=submit>, the action and method attributes from <form> tags, and all inline JavaScript event handlers. This prevents code injection.

<div id="custom-form">
  <form style="display: flex; flex-direction: column; gap: 12px;">
    <!-- Hidden name field — value pre-filled -->
    <input type="hidden" name="name" value="JOHN DOE" />

    <!-- SHC handles validation for fields with matching ids -->
    <input id="shc-card-input"   name="card"   type="text" placeholder="1234 1234 1234 1234" required autocomplete="cc-number" />
    <input id="shc-expiry-input" name="expiry" type="text" placeholder="MM / YY"             required />
    <input id="shc-cvv-input"    name="cvv"    type="text" placeholder="123"                 required autocomplete="cc-csc" />

    <!-- 3DS hidden fields (required if 3DS is enabled on your account) -->
    <input id="purchaseAmount"   name="purchaseAmount"   type="hidden" value="1025" />
    <input id="purchaseCurrency" name="purchaseCurrency" type="hidden" value="CAD" />
    <input id="purchaseDate"     name="purchaseDate"     type="hidden" value="2026-06-01T14:30:00.000Z" />

    <button id="shc-pay-button" type="button">Pay</button>
  </form>
</div>

<script>
  shc(shcToken, response => handle(response), { sourceElement: 'custom-form' });
</script>

window.addEventListener('message', event => {
  console.log(event.data); // { message: 'whatever you put in data-message' }
});

  Styling the Form

SHC reads a <style> tag with the id shc-style and injects it into the iframe. This is the only way to style the iframe — normal CSS on your page does not reach inside it.

<style id="shc-style">
  /* Your custom styles here — applied inside the SHC iframe */
</style>

/* Hide all field icons */
.confidante-field-img svg { visibility: collapse; }

/* Hide just the card icon */
#shc-card-img { visibility: collapse; }

/* Move icons to the right side */
.confidante-field-img svg      { left: auto; right: 5px; }
.confidante-field-validate svg { display: none; }

/* Show supported card brands (hidden by default) */
#shc-card-brands { display: flex; justify-content: center; }

/* Show the session timeout countdown (hidden by default) */
#shc-countdown { display: block; }

/* Remove the outer border */
#target { border: 0; padding: 0; padding-top: 20px; }

/* Full re-skin — underline style with a custom button color */
#shc label {
  margin-bottom: 15px;
  position: relative;
  border: 0;
  border-bottom: 1px solid #ddd;
  box-shadow: none;
}
#shc input:not(.shc-hidden-fields) {
  width: 100%;
  padding: 20px 0 10px 0;
  margin-top: 20px;
  border: none;
  outline: none;
}
#shc span.confidante-field-span {
  position: absolute; top: 0; left: 0;
  transform: translateY(40px);
  font-size: 0.825em;
  transition-duration: 400ms;
}
#shc button {
  padding: 15px 0;
  margin-top: 20px;
  background: #BC955C;
  color: #fff;
  border: 1px solid #BC955C;
  cursor: pointer;
  border-radius: 3px;
}
#shc label:focus-within > span.confidante-field-span,
#shc input:not(:placeholder-shown) + span.confidante-field-span {
  color: #BC955C;
  transform: translate(32px, 12px);
}

  Listening for Events and Sending Commands — shcMessenger

shc() returns an shcMessenger object. Use .on() to listen for events from the form, and the send methods to control the form programmatically.

let shcMessenger;

getShcToken(shcToken => {
  shcMessenger = shc(shcToken, response => handle(response));
});

// ── Listen for form events ───────────────────────────────────
shcMessenger.on('shc-card-brand',      data => console.log('Brand:', data.brand));
shcMessenger.on('shc-ready-to-submit', data => console.log('Ready:', data.isReady));
shcMessenger.on('shc-submit',          ()   => console.log('Form submitted'));
shcMessenger.on('shc-3ds',             ()   => console.log('3DS started'));
shcMessenger.on('shc-3ds-challenge',   ()   => console.log('3DS challenge shown'));
shcMessenger.on('shc-response',        data => console.log('Result:', data));
shcMessenger.on('shc-reset',           ()   => console.log('Form reset'));

// ── Send commands to the form ────────────────────────────────
shcMessenger.sendBlockSubmit();    // disable Pay button programmatically
shcMessenger.sendUnblockSubmit();  // re-enable Pay button
shcMessenger.sendSubmit();         // submit the form (ignored if fields invalid)
shcMessenger.sendCancel();         // destroy the form entirely

  Helper Endpoints

If you need to retrieve the result of a session after the callback fires — for example, to reconcile server-side — use these GET endpoints. Plug the secureId from the response into the URL.

// All base URLs: https://uat.ca.shc.payfacto.cloud/secure-hosted-checkout/v1

GET /sessions/{secureId}/response     // Full response from a session
GET /sessions/{secureId}/transaction  // Underlying transaction data
GET /sessions/{secureId}/receipt      // HTML receipt (if generated)

  3D Secure Test Cards (UAT)

Use these card numbers in UAT to test every 3DS outcome. For all scenarios: Cardholder Name = Test Card, CVV = 123 (or 1234 for Amex).