Prerequisites

  Endpoints

SHP uses two endpoints: one to create the session link (your server calls this), and one that is the hosted payment page itself (the customer's browser visits this).

  Step 1 — Create a Link

Call POST /secure-hosted-checkout/v1/links from your server. The only required field is transactionType. The response includes a linkUrl — this is the full URL of the hosted payment page you will redirect the customer to.

This call must be made from your server, not the browser. The Authorization header contains your API secret. Never expose it in client-side code.

{
  "transactionType": "PURCHASE",
  "purchaseAmount":  1025,
  "language":        "en"
}

{
  "transactionType":      "PURCHASE",
  "purchaseAmount":       1025,
  "language":             "en",
  "invoiceNumber":        "INV-2024-001",
  "invoice":              "hidden",
  "amount":               "hidden",
  "description":          "Order #2024-001 — 2x Widget Pro",
  "email":                true,
  "avs":                  "both",
  "successUrl":           "https://your-site.com/paid",
  "declineUrl":           "https://your-site.com/declined",
  "expires":              "2024-06-30T23:59:59",
  "uses":                 1,
  "sendEmail":            false,
  "transactionDescription": "Receipt description",
  "webhookUrl":           "https://your-site.com/webhook"
}

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

const data = await response.json();
// data.linkUrl is the URL to redirect the customer to
console.log(data.linkUrl);

{
  "id":              "59e36fcb-ff9d-48be-972e-8960a4c8d4ac",
  "description":     null,
  "expires":         "2026-11-04T14:34:14.667Z",
  "language":        "fr",
  "uses":            "1",
  "usesUsed":        "0",
  "purchaseAmount":  1025,
  "transactionType": "PURCHASE",
  "linkUrl": "https://uat.ca.shc.payfacto.cloud/secure-hosted-checkout/v1/browser/hosted-pages?link=59e36fcb-ff9d-48be-972e-8960a4c8d4ac"
}

  Step 2 — Redirect the Customer

Once your server has the linkUrl, send the customer's browser to it. You can do this with a server-side HTTP redirect, a client-side JavaScript redirect, a link in an email, or by generating a QR code. See the Helper Endpoints section for QR code generation.

// After your server creates the session and returns linkUrl to the browser:
window.location.href = data.linkUrl;

// Or server-side redirect (e.g. Express):
res.redirect(data.linkUrl);

// The URL looks like:
// https://uat.ca.shc.payfacto.cloud/secure-hosted-checkout/v1/browser/hosted-pages
//   ?link=59e36fcb-ff9d-48be-972e-8960a4c8d4ac

  Step 3 — Handle the Customer Return

After the customer pays (or fails), PayFacto redirects them to your successUrl or declineUrl. The linkId is appended as a query parameter. Use it to retrieve the transaction result from PayFacto before fulfilling the order.

Never fulfil an order based on the browser redirect alone. The redirect only tells you the customer returned — it does not prove the payment succeeded. Always verify the result server-side using the linkId or HMAC webhook before releasing goods or services.

// PayFacto redirects the customer to your successUrl after payment.
// Example: https://your-site.com/paid?linkId=59e36fcb-ff9d-48be-972e-8960a4c8d4ac

// On your server, retrieve the transaction result using the linkId:
const result = await fetch(
  `https://uat.ca.shc.payfacto.cloud/secure-hosted-checkout/v1/links/${linkId}/responses`,
  {
    headers: { 'Authorization': `Basic ${apiKey}` }
  }
).then(r => r.json());

  Step 4 — Verify the HMAC

Every PayFacto response includes a metadata.HMAC field — a SHA-256 fingerprint of the response body, signed with your API secret. Recalculate it on your server to confirm the response came from PayFacto and was not tampered with in transit.

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

const crypto = require('crypto');

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

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

if (!verifyHmac(shpResponse, process.env.API_SECRET)) {
  throw new Error('HMAC mismatch — do not process this response');
}

  Helper Endpoints

These endpoints let you manage links after creation — look up their state, cancel them, retrieve results, or generate a QR code for in-person or invoice use.

// Get the hosted-page URL as plain text
GET /browser/links/{linkId}/url

// Get a QR code image (PNG) of the link — embed directly in an  tag
GET /browser/links/{linkId}/qrcode

// Look up the current state of a link
GET /links/{linkId}

// Cancel / expire a link immediately
POST /links/{linkId}/cancel

// Get all responses recorded against a link
GET /links/{linkId}/responses

// Get all transactions created from a link
GET /links/{linkId}/transactions