Omnitoken

An Omnitoken is a unique digital token generated within a Merchant's chain that enhances security and traceability for transactions. As part of Value-Added Services, Omnitoken serves as a secure substitute for sensitive payment information, ensuring safe and seamless transactions. For Partners, enabling Omnitoken for their Merchant Portfolio offers increased security, streamlined transactions, and future-proofing capabilities. By using Omnitoken, Partners can provide their Merchants with a secure and efficient payment solution that aligns with industry standards and supports various payment technologies.

Enable the Omnitoken Service

To optimize your experience, make sure the following criteria is met:

A triPOS-compatible, Omnitoken-enabled terminal provided by the key injection facility (KIF) is used.
Each relevant Merchant and Customer account is activated for Omnitoken.
VCORE is used as the processing platform because Omnitoken exclusively works with the VCore Express gateway.
You are familiar with Worldpay Express Gateway APIs and Payrix Pro APIs.

Our Omnitoken service effectively minimizes card exposure and data theft, reduces PCI scope, and boosts confidence in digital transactions. Omnitoken is beneficial across various industries, spanning from traditional physical stores to online payment processors requiring secure tokenization data storage, recurring subscription billing, or streamlined product pre-order payment processing. Explore how to enable the Omnitoken service through both the Portal and API methods described in the following sections.

See each of the sections below for steps to enable and activate Omnitokens:

Using the Portal

Complete the following steps to enable Omnitoken Parameter for your Partners:

Click Divisions in the left-hand navigation panel and access the profile for the Division (Partner portfolio) you want to enable.
Click Parameters from the left-hand Division Profile menu.
Click the Add Parameters button in the upper-right corner.
Click the Edit icon in the upper-right corner and scroll to Omnitoken Enabled
Turn on the Omnitoken Enabled toggle and select Enabled from the dropdown list.
Click the Confirm icon in the upper-right corner of the page to complete the process.

Result: The Partner is now enabled to provide Omnitoken capabilities to their Merchants using compatible payment terminals.

Using the API

Enable Omnitoken Parameter for your Partners using the /parameters endpoint. You can see the full endpoint reference available in our API documentation.

POST /parameters HTTP/1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com

Request Body

{
    "login ": "t1_log_123abc4d567890efg1h2i34",
    "OmnitokenEnabled": "1",
    "inactive": 0,
    "frozen": 0
}

Tip
If you have an existing parameter configuration, you can use the PUT method to update it with the same request body.

By using one of the methods above, your Merchant(s) will now automatically mint new Omnitokens when processing card payment terminal transactions, securely and seamlessly tokenizing customer payment methods, making them available for reuse in the future.

Activate Omnitokens

Once the Omnitoken parameter has been enabled for a Partner and its subsequent Merchant portfolio (Division), the Omnitoken must be activated or “enabled” for each Merchant or Group. By activating Omnitokens, Partners can ensure increased security measures, efficient payment processing, and future-proof tokenization capabilities for their Merchants. Let's explore how to activate Omnitokens through both the Portal and API methods.

Using the Portal

Complete the steps in the following sections:

Activate Omnitoken for a Single Merchant - Merchant Profile page

Click Settings in the left navigation panel to open the Settings page.
Click Omnitoken, under the Value-Added Services section of the page.
Click Enable next to the Merchant you’d like to Activate.

Result: The individual Merchant was enabled for Omnitoken providing the providing the ID, service, and date of enablement.

Activate Omnitoken for a Merchant Group - Group Profile page

Click Groups in the left navigation panel to open the Groups page.
Locate the group in the table and click on any information in the table row to open the Group Profile page.
Click VALUE-ADDED SERVICE ENABLEMENT from the left menu.
Click the Add Service button in the upper-right corner.
Select Omnitoken from the Value-Added Service dropdown list, then click Add.

Result: The new Omnitoken enablement for the group will appear on the Value-Added Services Enablement page table, providing the ID, service, and date of enablement.

You can delete this enablement at any time by clicking the ⋮ button on the right-hand column of the Omnitoken table listing.

Using the API

View the full endpoint reference here.

Activate Omnitoken for a Single Merchant: POST /omniTokens

POST /omniTokens HTTP/1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com

Request Body

{
    "entity": "t1_ent_123abc4d567890efg1h2i34",
    "platform": "VCORE",
    "enablementDate": "2024-06-20 16:53:29",
    "inactive": 0,
    "frozen": 0
}

Response Body

{
    "id": "t1_otk_123abc4d567890efg1h2i34",
    "created": "2024-06-06 16:53:29.4722",
    "modified": "2024-06-06 16:53:29.4722",
    "creator": "t1_log_123abc4d567890efg1h2i34",
    "modifier": "t1_log_123abc4d567890efg1h2i34",
    "enablementDate": "2024-06-06 16:53:29",
    "org": null,
    "division": null,
    "partition": null,
    "entity": "t1_ent_123abc4d567890efg1h2i34",
    "platform": "VCORE",
    "inactive": 0,
    "frozen": 0
}

Activate Omnitokens for a Merchant Group (Org): POST /orgsVASOmnitokens

View the full endpoint reference here.

POST /orgsVASOmnitokens HTTP/1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com

Request Body

{
    "entity": "t1_ent_123abc4d567890efg1h2i34",
    "platform": "VCORE",
    "enablementDate": "2024-06-20 16:53:29",
    "inactive": 0,
    "frozen": 0
}

Response Body

{
    "id": "t1_ovo_123abc4d567890efg1h2i34",
    "created": "2024-06-06 16:53:29.4722",
    "modified": "2024-06-06 16:53:29.4722",
    "creator": "t1_log_123abc4d567890efg1h2i34",
    "modifier": "t1_log_123abc4d567890efg1h2i34",
    "org": null,
    "inactive": 0,
    "frozen": 0
}

Omnitoken Fees

Using the robust Payrix Pro fee engine, Omnitoken-based actions can generate fees for Merchants to their Partners. Below is a list of use cases where the actions qualify for fees:

Qualified for Omnitoken Fee Charges

Minting a new Omnitoken through Terminal Sale, $0 Authorization, or Refund from new card info.
Minting a new Omnitoken through Card Not-Present Sale, $0 Authorization or Refund from new card info
Minting a new Omnitoken using a pre-existing Payrix Pro token.
Lookup of an existing Omnitoken using the original primary account number (PAN) used to first mint the Omnitoken.

Not Qualified for Omnitoken Fee Charges

Reusing a Terminal-minted Omnitoken for a Sale, $0 Authorization, or Refund Card Not-Present transaction

Notes
Fees are incurred for both minting new tokens and looking up existing tokens based on the PAN:
A "Minting" action occurs when the VCore RAFT platform encounters a specific PAN for the first time to generate a new Omnitoken.
A "Lookup" action occurs happens when the VCore RAFT platform identifies a previously minted PAN and retrieves the corresponding Omnitoken.
To avoid unnecessary lookup charges, Merchants can use the actual token value instead of the PAN information in a new transaction.

See Fee Management for information and detailed instructions for setting up Merchant fees including Omnitoken-related fees.

Minting Omnitokens

In the Omnitoken Use Cases section, we take a closer look at real-life applications of Omnitoken technology to simplify future transactions, step up security measures, and set the stage for future tokenization capabilities for Merchants and Partners. Dive into how Omnitokens are minted, verified and reused to guarantee streamlined and secure payment options.

Note
The majority of the use cases outlined below utilize API services not available through the Portal. For the best experience, visit the Worldpay Express Gateway Developer Engine and Payrix Pro API Documentation Portal.

Mint a new Omnitoken (Card Present)

When a Merchant is enabled for Omnitoken, their triPOS Express-compatible payment terminal hardware is automatically generates new Omnitokens for customer payment methods through a secure minting process enabled by the relevant Key Injection Facility (KIF).

Method 1: Mint a new Omnitoken through terminal Sale, $0 Authorization, or Refund transaction.

Complete the following steps:

Note
This process uses the Worldpay Express Gateway API service for triPOS Card-Present transactions. Visit the Worldpay Express Gateway Developer Engine for request body requirements and response body examples.

A Sale (POST /api/v1/sale) or Auth (POST /api/v1/authorization) transaction is initiated from a triPOS-enabled terminal, where the getToken parameter is set with a value of Omnitoken.
The customer then swipes or inserts their card into the payment terminal, finalizing the Sale or Auth transaction.
The transaction is processed by Worldpay, which responds with a success message including the tokenID, ExpirationMonth, ExpirationYear, and NetworkTransactionID.

Result: The new Omnitoken data has been successfully minted to the Merchant’s Chain and can be utilized for future transactions.

Note
This process also applies to a Refund (POST /api/v1/refund) transaction where the customer’s card information is captured to disburse refund amounts. When a refund is issued in this process, a NetworkTransactionID value will not be reurned by the Omnitoken service.

Method 2: Mint a new Omnitoken through Direct Information Capture

You can also mint an Omnitoken sending a request directly to the POST /api/v1/token/omni endpoint, capturing the customer card payment information at the same triPOS-enabled terminal.

This will return the same token details; tokenID, ExpirationMonth, ExpirationYear, and NetworkTransactionID as Method 1, which will be saved

Result: The new Omnitoken data has been successfully minted to the Merchant’s Chain and can be utilized for future transactions.

Mint a new Omnitoken (Card Not Present)

Omnitoken-enabled Merchants can also process payments and generate new Omnitokens from customer payment information by using the Payrix Pro payment acceptance options available through the /txns endpoint, such as Sale or $0 Authorization types.

Mint a new Omnitoken through an Online Sale, $0 Authorization, or Refund transaction.

Send a POST /txns request body with the customer’s info in a customer object and the card payment info into the payment object within the token object like so:

{
    "merchant": "t1_mer_6695a6b295d1faadecfce52",
    "origin": "2",
    "type": "1",
    "first": "John",
    "last": "Doe",
    
    "token": {
        "customer": {
            "first": "John",
            "last": "Doe",
            "email": "[email protected]"
            },
        "payment": {
            "number": "4111111111111111",
            "cvv": "123"
        },
        "expiration": "1234",
        "inactive": "0",
        "frozen": "0" 
    }
}

When the transaction is submitted, the Worldpay platform will process the transaction and mint a new Omnitoken to the Merchant’s Chain. When the transaction response is returned to the Payrix Pro server, the new /tokens resource will then be created, where the following will occur:

The new customer resource is created, associating the customer with the new Omnitoken
The token parameter’s value will be populated with the new Omnitoken’s hash value,
The Omnitoken parameter will be populated with its token record value

You can quickly access this information by sending a GET request to /tokens.

{
    "customer": {
        "id": "t1_cus_123abc4d567890efg1h2i34",
        "created": "2024-07-23 08:56:57.5358",
        "modified": "2024-07-23 08:56:57.5358",
        "creator": "t1_log_123abc4d567890efg1h2i34",
        "modifier": "t1_log_123abc4d567890efg1h2i34",
        "login": "t1_log_123abc4d567890efg1h2i34",
        "merchant": "t1_mer_123abc4d567890efg1h2i34",
        "first": "John",
        "middle": null,
        "last": "Doe",
        "company": null,
        "email": null,
        "fax": null,
        "phone": null,
        "country": null,
        "zip": "11111",
        "state": null,
        "city": null,
        "address2": null,
        "address1": null,
        "inactive": 0,
        "frozen": 0
    },
    "payment": {
        "id": "g12345a6bc7890",
        "method": 2,
        "number": "1111",
        "routing": "0",
        "bin": "411111",
        "payment": null,
        "lastChecked": null,
        "last4": null,
        "mask": null
    },
    "id": "t1_tok_123abc4d567890efg1h2i34",
    "created": "2024-07-23 08:56:57.5442",
    "modified": "2024-07-23 08:56:57.5442",
    "creator": "t1_log_123abc4d567890efg1h2i34",
    "modifier": "t1_log_123abc4d567890efg1h2i34",
    "token": "1a234bcd56e789fgh0i1jkl234mn5678",
    "expiration": "1025",
    "name": null,
    "description": null,
    "custom": null,
    "authTokenCustomer": null,
    "status": "ready",
    "origin": null,
    "entryMode": null,
    "Omnitoken": "1234567890123456",
    "inactive": 0,
    "frozen": 0
}

To confirm the minting process was successful, perform a call to GET /tokenResults like so:

GET /tokenResults/{id} HTTP/1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com

Response Body

{
    "id": "t1_tkr_123abc4d567890efg1h2i34",
    "created": "2024-07-22 02:14:33.3973",
    "modified": "2024-07-22 02:14:33.3973",
    "creator": "t1_log_123abc4d567890efg1h2i34",
    "modifier": "t1_log_123abc4d567890efg1h2i34",
    "txn": "t1_txn_123abc4d567890efg1h2i34",
    "token": "t1_tok_123abc4d567890efg1h2i34",
    "merchant": "t1_mer_123abc4d567890efg1h2i34",
    "code": "OmnitokenMinting",
    "Omnitoken": "1234567890123456"
}

Result: The new Omnitoken has been successfully minted, and verified through the /tokenResults record.

Convert a Payrix Pro Token to Minted Omnitoken

Merchants with pre-existing customer records likely have Payrix Pro platform-hosted tokenized payment methods that they would like to migrate to Omnitoken for flexibility between Card Not-Present and Card-Present payment acceptance scenarios. Following the process below, Merchants can easily mint a new Omnitoken from a Payrix Pro Token by making small adjustments to their Card Not-Present transaction request.

Tip
If you're new and transferring tokens from another processor, follow steps in Migrate Tokens from Another Processor, then use the Omnitoken service to re-tokenize from Payrix Pro Tokens for a streamlined process.

Complete the following steps to convert a Payrix Pro Token to Minted Omnitoken:

A sale, refund or $0 auth transaction is sent using the Payrix Pro /txns endpoint and a pre-existing customer payment token in the token field.
The PAN details associated with the Payrix Pro Token are captured. At this time, the Worldpay processor will verify if the Merchant (specifically if their Merchant ID (MID)) supports and is enabled for the Omnitoken service.

Worldpay will then process the transaction and mint the Omnitoken, returning the following response in the token object:

{
    "id": "t1_txn_123abc4d567890efg1h2i34",
    "created": "2024-07-22 17:57:21.5351",
    "modified": "2024-07-22 17:57:22.4056",
    ...
    "token": { 
        "id": "t1_tok_123abc4d567890efg1h2i34",
        "created": "2024-07-22 17:57:21.5351",
        "modified": "2024-07-22 17:57:22.4056",
        "creator": "t1_log_123abc4d567890efg1h2i34",
        "modifier": "t1_log_123abc4d567890efg1h2i34",
        "customer": "t1_cus_123abc4d567890efg1h2i34",
        "token": "1a234bcd56e789fgh0i1jkl234mn5678",
        "expiration": "1234",
        "name": null,
        "description": null,
        "custom": null,
        "authTokenCustomer": null,
        "status": "ready",
        "origin": null,
        "entryMode": null,
        "Omnitoken": 1234567890123456
    },
    "payment": "g12345a6bc7890",
    "fortxn": null,
    "fromtxn": null,
    ...
}

Note that when the Omnitoken parameter displays null or no value, the token parameter indicates the Payrix Pro token, created on the Payrix Pro platform.

If a numeric value appears for the Omnitoken parameter, the token parameter displays the hashed value of the Omnitoken created through the Worldpay processor.

Upon the successful execution of this operation, the tokenResults endpoint will specify the type of action that took place by displaying "code": "OmnitokenMinting". This indicates a successful Omnitoken Minting event happened for the token record.

Result: The Customer’s previous Payrix Pro Token is now minted as an Omnitoken, making it accessible for future Card-Present and Card Not-Present payments.

Retrieve an Omnitoken from a Transaction

After minting a new Omnitoken, you may want to retrieve its record to ensure minting was successful or to locate the information for further reuse via API.

There are several ways to locate an Omnitoken value after it has been minted:

Using the Portal

Complete the steps in a section below to retrieve an Omnitoken value from the Portal.

Method 1: Transaction Details or Terminal Transaction Details

Click Payment History from the Dashboard.
Locate the transaction listed on the table and click on the table listing to open the transaction details page.
From the Transaction Details page, click Transaction from the left page menu.
The Omnitoken and Omnitoken expiration dates will be displayed in the lower right portion of the details form.
(Optional) You can also gather more information about the specific terminal transaction by clicking Terminal Transaction on the left-hand menu of the Transaction Details page - OR - clicking the Terminal Transactions button in the upper right of the Payment History table.

Result: The new Omnitoken hash value and expiration date are displayed in their respective fields on the Transaction Details or Terminal Transactions pages.

Method 2: The Customer Profile for the Transaction Customer

Access the Customers page from the Dashboard (under the Payments category).
Click the listing the Omnitoken-associated customer to open the Customer Profile.
Click Payment Methods from the left-hand menu of the Profile.
Select the listed Token value from the table, to view the Payment Method detail page.

Result: This new Omnitoken hash value is displayed in the Token field.

Using the API

There are 5 GET requests available to return Omnitoken information in various ways based on your preference. See the table below for more information.

Note
All records returned with an Omnitoken parameter value, represent a successfully minted Omnitoken.

Visit our API documentation to view the response parameters for each API request below.

Request	Request Description	Note
`GET /terminalTxns/{id}`	Locates the Hash Value and Record Value for the Omnitoken minted from a Terminal (Card-Present) transaction.	This method is best if you have a recent terminalTxn ID to use to help specify the results. Format: `t1_ttx_123abc4d567890efg1h2i34`
`GET /txns/{id}`	Locates the Hash Value and Record Value for the Omnitoken minted from an online (Card Not-Present) transaction.	This method is best if you have a recent txn ID to use to help specify the results. Format: `t1_txn_123abc4d567890efg1h2i34`
`GET /tokens`	Returns all tokenized payment methods, with associated customer values.	This method is best when looking for a specific customer ID associated to an Omnitoken to filter to the exact record you’re searching.
`GET /tokenResults`	Returns records of all Omnitoken actions including successful minting, lookup, or usage.	These tokenResults are associated with the applicable fees for Omnitoken and can be used to help locate them if your Merchant has a specific concern about Omnitoken fees.
`GET /customers`	Returns all customer records created on the Payrix Pro platform.	This is useful in scenarios where you know the customer associated with the Omnitoken. You can also utilize the GET /tokens method mentioned above and append the endpoint with `/{id}` request with the specific ID of that customer. Format: `t1_cus_123abc4d567890efg1h2i3``

Re-use an Omnitoken for a New Transaction

After minting a new Omnitoken, you will eventually re-use the tokenized payment method for a future transaction. Below are the methods available for re-use from a triPOS terminal (Card Present) and directly from Payrix Pro online payment acceptance options (Card Not-Present):

Card-Present

Complete the following steps to reuse an Omnitoken in a Card-Present transaction.

Note
This process utilizes the Worldpay Express Gateway API service for triPOS Card-Present transactions. Visit the Worldpay Express Gateway Developer Engine for request body requirements and response body examples.

A Sale (POST /api/v1/sale/token) or Auth (POST /api/v1/authorization/token) transaction is initiated from a triPOS-enabled terminal.
The transaction is processed by Worldpay, which responds with a success message including the tokenID, ExpirationMonth, ExpirationYear, and NetworkTransactionID.

Result: The new transaction has been processed using the existing Omnitoken as the payment method.

Note
This process also applies to a Refund (POST /api/v1/refund) transaction where the customer’s card information is captured to disburse refund amounts. When a refund is issued in this process, a NetworkTransactionID value will not be returned by the Omnitoken service.

Card Not-Present

Complete the following steps to reuse an Omnitoken in a Card Not-Present transaction:

Configure a new POST /txns request, with a Type of Sale, $0 Auth, Refund, or Sale w/ Card-on-File.
In the token object of the request body, add the Omnitoken token value returned from the minting process.
Important!
Be sure to copy the Omnitoken field value, as this is the record for the Omnitoken. Do not copy the token parameter inside of the object as this is the hash value of the actual token and the service will not recognize it.
Submit the Transaction as normal to the VCORE platform.

Result: The new transaction has been submitted referencing the Omnitoken as the intended tokenized payment method, and will update the tokenResults record accordingly to show "code": "OmnitokenUsage"

Note
Reusing an Omnitoken from a previous terminal (Card-Present) transaction for a new Card Not-Present transactions will not meet the criteria for Merchant fees.

More on Omnitokens

Below is additional information regarding Chains, Vaults, Minting, and other Omnitoken-specific technology and terminology to enhance your comprehension of the workflow.

Chains

Chains represent a hierarchical structure designed to facilitate the sharing of tokens across different levels of the Merchant hierarchy. These Chains play a crucial role in organizing and linking various business accounts within the Omnitoken ecosystem, allowing for the seamless utilization of tokens across multiple Merchant IDs (MIDs). By establishing this hierarchical framework, Chains enable efficient token management and distribution, enhancing coordination and operational effectiveness within the Worldpay payment processing system.

Note
Chains are activated by the Payrix Pro platform for each Partner.

The SuperChain is an advanced, top-level Chain for all other Chains. It allows for the sharing of tokens across the Merchant hierarchy at both the Chain and SuperChain levels. By using rollup IDs to link different business accounts, the SuperChain system ensures seamless token sharing and management within the Worldpay ecosystem. This centralized approach to managing business accounts under a unified Omnitoken hierarchy enhances efficiency and coordination across multiple Merchant IDs (MIDs).

Chain Requirements

Upon boarding the platform, your portfolio will be enabled for Omnitoken with a Chain ID assigned automatically, allowing your Merchants to plug and play with the new terminal to mint new Omnitokens to their Chains upon successful boarding.

Vaults

A Vault serves as a secure digital repository within a Merchant's chain where Omnitokens are stored. These Omnitokens are unique digital tokens generated from transactions to replace sensitive payment information, ensuring secure and seamless payment processing. The Vault enhances security measures by safeguarding these tokens and provides traceability for transactions. By utilizing the Omnitoken Vault, s can securely manage and utilize Omnitokens for various payment transactions, aligning with industry standards and supporting advanced payment technologies.

Minting

Minting is the process of generating new Omnitokens on a Merchant’s Chain from a transaction to be used in future transactions, specifically for Card Present (CP) and Card Not Present (CNP) transactions. Here's how minting works within the Omnitoken chain structure. Minting Omnitokens provides enhanced security, improved traceability, on-demand scalability, and future-proofing with compatibility with future payment technologies and industry standards to ensure seamless integration into the new cutting-edge functions and features.

Minting Requirements

A triPOS-compatible payment terminal enabled by the KIF.
A valid credit card with associated cardholder information.