Payment Method Features

Explore the features available when creating and managing Payment Methods with Moneris API. Learn how uniqueness prevents duplicate records, how card data and existing Data Keys can be tokenized or reused, how permanent token formats work, and how tokenization affects card-brand loyalty programs.

Uniqueness

When a merchant creates a Payment Method, the system must detect if that exact payment instrument — like a specific credit card — is already registered. The Uniqueness feature does this by checking business-defined factors such as Merchant ID and the card's fingerprint. If a match exists, it returns the existing record instead of creating a duplicate.

Why is this important? Without uniqueness, merchants might accumulate many Payment Method entries for the same card, causing confusion in reconciliation, lifecycle management, and raising error risks. Uniqueness ensures one Payment Method per card per merchant, keeping data cleaner and easier to manage.

Note that uniqueness is not the same as idempotency. Idempotency prevents duplicate submissions of the exact same request (like retries), while uniqueness works at the business level: even if requests differ in metadata, it recognizes the same card and avoids duplicates. Idempotency handles technical retries; uniqueness protects data integrity. Together, they keep the Payment Method store reliable and uncluttered.

Card Tokenization via Moneris API

When creating a Payment Method through the Moneris API , merchants can use two distinct paths depending on whether they are starting fresh with raw card data or already hold a Data Key.

Option 1 — Submit Card Data (New Tokenization Flow):

If the merchant does not yet have a Data Key, they can send the full card details (card number, expiry, CVV) directly in the request. Moneris API will tokenize the card using the format specified in the optional permanentTokenFormat field, create a new Payment Method, and return three key pieces of information: the paymentMethodId (e.g. pm0001KT7BWW…), the permanentToken (the Data Key), and the format that was used. In short, one API call gives the merchant both a Payment Method ID and a Data Key and no separate tokenization step required.

Option 2 — Submit an Existing Data Key (Reuse Flow):

If the merchant already possesses a Data Key, created previously, they can pass that directly into the create request. Moneris API will link the existing Data Key to a new Moneris Payment Method ID record without re-tokenizing or making additional calls. The response returns the same Data Key the merchant sent in, now associated with a Payment Method ID. This means no data conversion, no extra latency, and full cross-system compatibility, the merchant can continue using the same Data Key on Moneris API and other Moneris applications seamlessly.

Which option should I use?

If you are a new merchant or onboarding new cards, we recommend Option 1 so you can create everything in a single step. If you are an existing merchant with established Data Keys, we recommend Option 2 to bring those tokens into Moneris API without migration, you keep using what you already have.

Data Key permanent Token Format

Additional, when you create a Payment Method ID using card data through the API (Option 1) you can control how your permanent token (Data Key) looks by setting the permanentTokenFormat field in your request. Think of this field as a preference selector: it tells the system which format you want your token returned in, based on your integration needs.

Here's how it works

When a card is successfully tokenized, the system generates a Data Key that represents that card for future use. The format of that token depends on the value you pass:

Value	What you get?
0 or blank	A standard 25-character alphanumeric token (e.g., `aBcDeFgHiJkLmNoPqRsTuVwXy`) — no card digits visible.
1	A token that preserves the first 6 and last 4 digits of the card number, and matches the original card number length. Useful if your downstream systems expect a value that "looks like" a card number.
2	Same as above (first 6 + last 4 visible), but without preserving the original card number length — the token may be shorter or longer than the PAN.
0U	Same as `0` (25-char alphanumeric), but Unique — the system guarantees that tokenizing the same card again will always return the same token.
1U	Same as `1` (first 6 + last 4, length-preserved), but Unique.
2U	Same as `2` (first 6 + last 4, no length preservation), but Unique.
4U	First 6 + last 4 visible, no length preservation, with alpha characters guaranteed in the generated portion, and Unique.

What does "Unique" mean?

When you choose a format ending in U, the system ensures that if the same card is tokenized more than once (for the same merchant ID), it will always return the same token rather than generating a new one each time. This is particularly helpful for deduplication, you can rely on the token value itself to identify whether a card has already been stored, without needing additional lookups.

If you omit the field (or pass 0), you'll receive a standard 25-character token with no uniqueness guarantee, meaning tokenizing the same card twice, for the same merchant ID, could produce two different tokens for the same card.

Recommendation

If your system needs to detect duplicate cards or avoid storing the same card multiple times, choose one of the U (Unique) formats. If you also need partial card visibility for display or routing purposes, pair uniqueness with format 1U, 2U, or 4U depending on whether you need length preservation or alpha-guaranteed characters.

Card Brand Loyalty

When the Moneris API generates a Data Key for a card, it is important to understand that this process does not interfere with any Card Brand loyalty programs associated with that card. (e.g., Visa, Mastercard rewards).

The Data Key replaces the card number only for merchant-side storage, when a transaction is processed, the Card Brand network still receives all the information it needs (including the PAR - Payment Account Reference) to attribute the purchase to the cardholder's loyalty profile. Points, rewards, and tier benefits continue to accumulate normally. Merchants can adopt Data Keys with confidence that their customers' loyalty benefits remain fully intact.