Skip to main content

Tokenisation Integration Guide

This guide walks you through implementing tokenisation via the Connected Payments iFrame — capture a card, create a token, and process payments using the token.

Icon
Before you begin

What you'll need:

  • configId - Your iFrame configuration ID
  • userName - Your Connected Payments username with transaction permissions
  • secretKey - Your shared secret key (for HMAC generation)
  • HTTPS-enabled website (for embedded iFrames)

Read first:

Code samples: Code samples within this document are provided for reference purposes only and are not intended for production use.

How it works​

There are two main workflows for tokenisation with the iFrame. You can capture a card and create a token without charging (token-only), or capture a card, create a token, and charge in a single step (payment + token). Once a token exists, you can process future payments either through the iFrame or via the Submit Purchase API.

Summary:

  1. Customer loads the iFrame on your site
  2. Card details are captured securely — card data never touches your server
  3. A token is generated and returned to you via webhook or PostMessage
  4. You store the token against the customer in your system
  5. Future payments use the token instead of card details — via iFrame or API

Choose your approach​

ApproachWhen to useHow it works
Token only (onlyTokenise=true)Account sign-up, subscription onboarding, saving a card for laterCard is captured and tokenised — no payment occurs
Payment + Token (tokenControl.token=true)First purchase where you also want to save the cardPayment is processed and token is created in a single step

Once the token is stored, choose how to process future payments:

MethodWhen to useNotes
iFrame with cardTokenCustomer-present scenarios (e.g. one-click checkout)Stored card details are pre-populated; all fields except PAN are editable
Submit Purchase APIServer-initiated payments (e.g. recurring billing, subscriptions)No customer interaction required — fully server-to-server

Step 1: Generate HMAC signature​

All iFrame requests require an HMAC SHA-256 signature generated server-side. The process is the same as the standard iFrame integration — the only difference is the parameters you include.

Server-side only — Never expose secretKey in client code.

For token-only flows, include onlyTokenise=true alongside the tokenisation control parameters. No amount is needed for the HMAC.

Node.js
const crypto = require("crypto");

const params = {
  configId: "5f06c5f5-d4cb-483b-b0b2-242f48516dc5",
  userName: "merchant.iframes",
  txnType: 1,
  merchReference: `TOKEN-${Date.now()}`,
  amount: 0,
};

const paramString = `configId=${params.configId}&userName=${params.userName}&txnType=${params.txnType}&merchReference=${params.merchReference}&amount=${params.amount}`;

const verifyMessage = crypto
  .createHmac("sha256", process.env.CONNECTED_PAYMENTS_SECRET_KEY)
  .update(paramString)
  .digest("hex");
PHP
$params = [
    'configId' => '5f06c5f5-d4cb-483b-b0b2-242f48516dc5',
    'userName' => 'merchant.iframes',
    'txnType' => 1,
    'merchReference' => 'TOKEN-' . time(),
    'amount' => 0
];

$paramString = http_build_query($params);
$verifyMessage = hash_hmac('sha256', $paramString, getenv('CONNECTED_PAYMENTS_SECRET_KEY'));
Python
import hmac
import hashlib
import os
import time

params = {
    'configId': '5f06c5f5-d4cb-483b-b0b2-242f48516dc5',
    'userName': 'merchant.iframes',
    'txnType': 1,
    'merchReference': f'TOKEN-{int(time.time())}',
    'amount': 0
}

param_string = '&'.join([f"{k}={v}" for k, v in params.items()])
verify_message = hmac.new(
    os.getenv('CONNECTED_PAYMENTS_SECRET_KEY').encode(),
    param_string.encode(),
    hashlib.sha256
).hexdigest()
C#
using System.Security.Cryptography;
using System.Text;

string paramString = $"configId=5f06c5f5-d4cb-483b-b0b2-242f48516dc5&userName=merchant.iframes&txnType=1&merchReference=TOKEN-{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}&amount=0";

using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("CONNECTED_PAYMENTS_SECRET_KEY"))))
{
    byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(paramString));
    string verifyMessage = BitConverter.ToString(hash).Replace("-", "").ToLower();
}

Step 2: Build the iFrame URL​

Append the parameters and HMAC to the iFrame endpoint. Add onlyTokenise=true for token-only flows, or tokenControl.token=true for payment + token flows.

const baseUrl =
  "https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted";
const iframeUrl = `${baseUrl}?${paramString}&onlyTokenise=true&tokenControl.token=true&tokenControl.tokenFormat=F6L4AN&verifyMessage=${verifyMessage}`;
info

Your assembled URL will look like this for the Hosted implementation:

https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted?configId=5f06c5f5-d4cb-483b-b0b2-242f48516dc5&userName=merchant.iframes&txnType=1&merchReference=TOKEN-1234567890&amount=0&onlyTokenise=true&tokenControl.token=true&tokenControl.tokenFormat=F6L4AN&verifyMessage=abc123def456...

Your assembled URL will look like this for the Embedded implementation:

https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/embedded?configId=5f06c5f5-d4cb-483b-b0b2-242f48516dc5&userName=merchant.iframes&txnType=1&merchReference=TOKEN-1234567890&amount=0&onlyTokenise=true&tokenControl.token=true&tokenControl.tokenFormat=F6L4AN&verifyMessage=abc123def456...

Setting onlyTokenise=true renders a card-capture-only page. No payment occurs regardless of any amount or txnType values passed alongside it.

Step 3: Implement the iFrame​

Choose how to display the card capture form to your customers.

<iframe
  id="connectedpayments-iframe"
  src="YOUR_GENERATED_URL"
  width="100%"
  height="600px"
  frameborder="0"
  allow="payment"
>
</iframe>

Step 4: Receive the token​

After the customer submits their card details, Connected Payments returns the token. How you receive it depends on your integration type.

Server-to-server webhooks are the recommended and most reliable way to receive tokens.

View webhook implementation example
app.post("/webhook", express.json(), (req, res) => {
  // 1. Validate signature
  const signature = req.headers["x-signature"];
  if (!isValidSignature(req.body, signature)) {
    return res.status(401).end();
  }

  // 2. Extract token from response
  const { responseCode, merchReference, cardToken } = req.body;

  if (cardToken) {
    // Store token against customer
    saveTokenForCustomer(merchReference, cardToken);
  }

  if (responseCode === "00") {
    // Payment successful (for payment + token flows)
    fulfillOrder(merchReference);
  }

  // 3. Acknowledge receipt (must return 200)
  res.status(200).send("OK");
});

Configuration: Webhooks are configured in your iFrame config. Contact CommBank Support to set up.

Response handling comparison​

MethodUse CaseValidation
WebhookAuthoritative token storage & paymentsSignature required
RedirectImmediate user feedback (hosted)Signature required
PostMessageReal-time UI updates (embedded)Origin check only

Approach:

  1. Primary: Use webhooks for authoritative token storage and payment processing
  2. Secondary: Use redirects or PostMessages for immediate customer feedback
  3. Always: Validate signatures on webhooks and redirects
  4. Never: Store tokens based solely on PostMessages

Step 5: Use the token for future payments​

Once you have a stored token, use it to charge the customer without them re-entering card details. You have two options:

Process payment via iFrame using cardToken​

Pass the stored cardToken as a URL parameter when building the iFrame URL. The stored card details are pre-populated in the payment form, with all fields except the PAN (card number) editable by the customer.

const crypto = require("crypto");

const params = {
  configId: "5f06c5f5-d4cb-483b-b0b2-242f48516dc5",
  userName: "merchant.iframes",
  txnType: 1,
  merchReference: `ORDER-${Date.now()}`,
  amount: 2999, // $29.99 in cents
};

const paramString = `configId=${params.configId}&userName=${params.userName}&txnType=${params.txnType}&merchReference=${params.merchReference}&amount=${params.amount}`;

const verifyMessage = crypto
  .createHmac("sha256", process.env.CONNECTED_PAYMENTS_SECRET_KEY)
  .update(paramString)
  .digest("hex");

const baseUrl =
  "https://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hosted";
const iframeUrl = `${baseUrl}?${paramString}&cardToken=STORED_TOKEN_VALUE&verifyMessage=${verifyMessage}`;

When to use: Customer-present scenarios like one-click checkout, subscription renewals with customer confirmation, or re-billing after a failed payment.

Complete examples​

View full Node.js implementation — Token only, then API payment
// server.js
const express = require("express");
const crypto = require("crypto");
const axios = require("axios");
const app = express();

const CONFIG = {
  configId: "5f06c5f5-d4cb-483b-b0b2-242f48516dc5",
  userName: "merchant.iframes",
  secretKey: process.env.CONNECTED_PAYMENTS_SECRET_KEY,
  apiUserName: process.env.ES_USERNAME,
  apiPassword: process.env.ES_PASSWORD,
  baseUrl: "https://sandbox.connectedpayments.commbank.com.au",
};

// --- Step 1: Generate token-only iFrame URL ---
function generateTokenOnlyUrl(customerRef) {
  const params = {
    configId: CONFIG.configId,
    userName: CONFIG.userName,
    txnType: 1,
    merchReference: customerRef,
    amount: 0,
  };

  const paramString = `configId=${params.configId}&userName=${params.userName}&txnType=${params.txnType}&merchReference=${params.merchReference}&amount=${params.amount}`;

  const verifyMessage = crypto
    .createHmac("sha256", CONFIG.secretKey)
    .update(paramString)
    .digest("hex");

  const urlParams = new URLSearchParams(params);
  urlParams.append("onlyTokenise", "true");
  urlParams.append("tokenControl.token", "true");
  urlParams.append("tokenControl.tokenFormat", "F6L4AN");
  urlParams.append("verifyMessage", verifyMessage);

  return `${CONFIG.baseUrl}/hosted/?${urlParams.toString()}`;
}

// Serve card capture page
app.get("/save-card/:customerId", (req, res) => {
  const iframeUrl = generateTokenOnlyUrl(
    `TOKEN-${req.params.customerId}-${Date.now()}`,
  );
  res.render("save-card", { iframeUrl });
});

// --- Step 2: Receive token via webhook ---
app.post("/webhook/token", express.json(), (req, res) => {
  if (!isValidSignature(req.body, req.headers["x-signature"])) {
    return res.status(401).end();
  }

  const { cardToken, merchReference } = req.body;

  if (cardToken) {
    // Store token for future use
    saveTokenForCustomer(merchReference, cardToken);
  }

  res.status(200).send("OK");
});

// --- Step 3: Charge using stored token via API ---
app.post("/charge/:customerId", express.json(), async (req, res) => {
  const token = await getStoredToken(req.params.customerId);

  const response = await axios.post(
    `${CONFIG.baseUrl}/pfr/v1/gateway/purchase`,
    {
      userName: CONFIG.apiUserName,
      password: CONFIG.apiPassword,
      cardToken: token,
      merchReference: `ORDER-${req.params.customerId}-${Date.now()}`,
      amount: String(req.body.amount),
      txnType: "1",
      requestorIp: req.ip,
      ecm: "31",
    },
    { headers: { "Content-Type": "application/json" } },
  );

  if (response.data.responseCode === "00") {
    res.json({ success: true, txnReference: response.data.txnReference });
  } else {
    res.json({ success: false, message: response.data.message });
  }
});

app.listen(3000);

Tokenisation parameters​

The following parameters control tokenisation behaviour on the iFrame. Pass them as URL parameters alongside your standard payment parameters.

ParameterTypeDescriptionExample
onlyTokeniseBooleanRender card-capture page only — no payment is processedtrue
tokenControl.tokenBooleanGenerate a token for the card details providedtrue
tokenControl.tokenFormatStringToken format to use; falls back to silo default if omittedF6L4AN
tokenControl.tokenUsageLimitIntegerNumber of uses before token is automatically destroyed; omit for a permanent token4
tokenControl.channelStringFree-text reference stored alongside the token — useful for tracking which system or flow created itCust4433221
metadataObjectCustom key-value pairs for your reference{"CRN": "12345"}
info

When onlyTokenise=true, payment parameters such as txnType, merchReference, and amount are not required. However, they are still included in the HMAC signature for consistency.

Token formats​

Your merchant account has a default format configured at the silo level. You can override it per-request using the tokenControl.tokenFormat parameter.

FormatStructureLengthExample
F6L4ANFirst 6 + last 4 of PAN + 6 alphanumeric16411111m9fb0d1111
F6L4AFirst 6 + last 4 of PAN + 6 alpha16411111jbkzWI1111
F6L4FFirst 6 + last 4 of PAN + 6 numeric164111119890761111
ALPHANUMERIC088 alphanumeric characters8A5fG6sn4
16N16 numeric digits161234567890123456

For the full list of token formats, see Tokenisation Specifics.

Submit Purchase API reference​

When using the Submit Purchase API with a stored token, include these fields in your request body:

FieldTypeRequiredDescription
userNameStringYesConnected Payments username
passwordStringYesConnected Payments password
cardTokenStringYesThe stored token (or alias) — replaces pan and cardExpiryDate
merchReferenceStringYesUnique merchant reference for this transaction
amountStringYesAmount in cents
txnTypeStringYesTransaction type (e.g. "1" for purchase)
requestorIpStringYesIP address of the cardholder or originating system
ecmStringNoEntry class mode — use "31" for internet, "32" for internet recurring
currencyStringNoISO-4217 currency code (defaults to AUD)
metadataObjectNoCustom key-value pairs for your reference
info

CVC is not required for token-based payments. The token holds a reference to the card already stored in the silo.

For full API documentation, see Submit a Purchase Request.

Environments​

EnvironmentHosted URLEmbedded URLAPI Base URL
Sandboxhttps://sandbox.connectedpayments.commbank.com.au/es-client-frontend/hostedhttps://sandbox.connectedpayments.commbank.com.au/es-client-frontend/embeddedhttps://sandbox.connectedpayments.commbank.com.au
Productionhttps://connectedpayments.commbank.com.au/es-client-frontend/hostedhttps://connectedpayments.commbank.com.au/es-client-frontend/embeddedhttps://connectedpayments.commbank.com.au

Testing​

Use the sandbox environment with test cards only. Never use real card numbers in test or development environments.

Verification steps:

  1. Generate a token-only iFrame URL and capture a test card
  2. Confirm the token is returned in your webhook
  3. Use the token to process a payment via the iFrame or Submit Purchase API
  4. Verify the payment result in your webhook

For full test details, see the Testing Guide.