Tokenisation Specifics

Quick summary

Token formats, aliases, and how to create and use tokens across payment scenarios.

---

Token Formats

A token's format defines what the token string looks like when it is returned to your system. Your merchant account has a default format configured. You can override it per-request using the tokenFormat parameter.

Why format matters

Choosing the right format matters for a few reasons:

• Masked card display — formats that preserve the first 6 and last 4 digits of the PAN allow you to show customers a recognisable card reference (e.g. 411111XXXXXX1111) without storing the real number.
• Database compatibility — ensure your token storage field length matches the format's maximum length.
• Compliance requirements — formats that retain original card digits may have different compliance implications. Confirm with your compliance team.

Available formats

Format	Structure	Length	Example
F6L4AN	First 6 + last 4 of PAN + 6 alphanumeric	16	411111m9fb0d1111
F6L4A	First 6 + last 4 of PAN + 6 alpha	16	411111jbkzWI1111
F6L4F	First 6 + last 4 of PAN + 6 numeric	16	4111119890761111
F2L4AN	First 2 + last 4 of PAN + 10 alphanumeric	16	41Be44uGTx0k1111
F2L4A	First 2 + last 4 of PAN + 10 numeric	16	4121329524851111
19D-PFX9-PASS	Prefix 9 + mod-10 + chars 4–9 from PAN + 6 variable + last 4	19	9494111116921481111
ALPHANUMERIC08	8 alphanumeric characters	8	A5fG6sn4
16N	16 numeric digits	16	1234567890123456
13N	13 numeric digits	13	1234567890123
F6L3A	First 6 + last 3 of PAN + 6 alpha	16	411111ABCDEFG111

---

Aliases

An alias is a custom string you assign to a token, allowing you to reference it by your own identifier (e.g. a customer ID or account number) instead of the system-generated token value.

This is useful when you want to avoid storing two identifiers — you can map a token directly to an ID that already exists in your system, such as a CRM customer number.

Token:  tokenABC
Alias:  CUST-67890

Both are valid in any cardToken field:
  cardToken=tokenABC
  cardToken=CUST-67890

Key points

Rule	Description
Uniqueness	Aliases must be unique within your merchant account — attempting to assign a duplicate alias will return an error
Immutability	Once set, an alias cannot be removed — only updated to a different value
Compatibility	Aliases can be used anywhere a card token is accepted (API, Hosted Payment Page, batch)

---

Creating Tokens

There are three ways to create a token via the Hosted Payment Page. Which you use depends on whether you need to charge the card at the same time as capturing it.

Token Only

Token only (no payment)

Store a card for later use without charging it immediately. This is common for account sign-up flows or subscription onboarding where the first charge happens at a later date.

onlyTokenise=true
tokenControl.token=true
tokenControl.tokenFormat=F6L4AN

How it works

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

Payment + Token

Payment + token

Charge the card and create a token in a single transaction. This is the most common pattern for eCommerce checkouts where you want to save the card for future recurring billing at the same time as the initial purchase.

txnType=0
amount=1000
tokenControl.token=true
tokenControl.tokenUsageLimit=5

Token creation condition

The token is only created if the payment is approved. If the transaction is declined, no token is stored.

Use Existing Token

Payment using an existing token

Charge a previously stored card using its token or alias. The customer does not need to re-enter their card details — the token acts as a reference to the card already stored.

txnType=0
amount=1000
cardToken=tokenABC

Common use cases

This is the standard pattern for recurring billing, subscription renewals, and one-click checkout.

---

Using Tokens in Payments

Once a token exists, it replaces the card number (pan) and expiry date in any payment request. Pass it as the cardToken field across any of the following channels:

Channel	How to use	Notes
Transaction API	Pass cardToken in place of pan and expiryDate	CVC is not required for token-based payments
Hosted Payment Page	Pass cardToken as a URL/form parameter	Customer sees a payment confirmation rather than a card entry form
Batch processing	Include cardToken in the batch file in place of card details	Useful for bulk recurring billing runs

---

Recurring Transactions

For ongoing billing (subscriptions, instalments, automatic renewals), tokens work alongside the recurring transaction type to simplify processing:

Benefits

Simplified processing

• No expiry date required — the token holds the card reference
• No CVC required — CVC validation is only required at the point of initial card capture
• ECM indicator — recurring transactions must use a second ECM digit of 2 (e.g. X2), which signals to CommBank Connected Payments that this is a merchant-initiated transaction

Requirements

Important requirements

Pre-approval required

Recurring transactions are only permissible in specific scenarios that must be pre-agreed with CommBank Connected Payments. Do not use the recurring transaction type without first confirming your use case with CommBank Connected Payments — misuse can result in scheme penalties.

Before implementing recurring transactions:

1. Confirm your use case with CommBank Connected Payments
2. Ensure proper customer consent is obtained
3. Implement appropriate notification mechanisms
4. Use the correct ECM indicator (X2)

---

Restricted Characters

The following characters must not be used in any field (merchant reference, customer ID, metadata, token aliases, etc.) unless explicitly permitted — they will return a validation error.

Prohibited Characters

Characters to avoid

Prohibited characters: ! $ £ € * ^ { } ~ \

Safe characters: alphanumeric (A–Z, a–z, 0–9), hyphen -, underscore _, period .

Examples

Valid and invalid examples

Status	Example	Notes
Accepted	ORDER-12345	Valid format
Accepted	CUST_67890	Valid format
Accepted	token.alias-123	Valid format
Not Accepted	ORDER$12345	Contains $
Not Accepted	INV{2025}	Contains { and }
Not Accepted	ALIAS*TOKEN	Contains *

---

Payment Page Parameters

The following parameters control tokenisation behaviour on the Hosted Payment Page. Pass them as URL parameters or form fields alongside your standard payment parameters.

Parameter	Type	Description	Example
onlyTokenise	Boolean	Render card-capture page only — no payment is processed	true
cardToken	String	Token or alias to use for payment instead of card details	tokenABC
tokenControl.token	Boolean	Generate a token for the card details provided	true
tokenControl.tokenFormat	String	Token format to use; falls back to account default if omitted	F6L4AN
tokenControl.tokenUsageLimit	Integer	Number of uses before token is automatically destroyed; omit for a permanent token	4
tokenControl.channel	String	Free-text reference stored alongside the token — useful for tracking which system or flow created it	Cust4433221

---

Next Steps

Guide	Description
Tokenisation Overview	Introduction to tokenisation concepts and integration options
Integration Guide	Step-by-step implementation instructions for both Web and API methods
API Reference	Complete API endpoint documentation