Omnitoken

Omnitoken is a secure, omnichannel payment tokenization solution from Worldpay that replaces sensitive cardholder data with a unique, format-preserving token. This tokenization method protects transactions across card present (CP) and card not present (CNP) channels. It reduces fraud, lowers your PCI compliance scope, and supports one-time and recurring payments.

Enabling Omnitoken for your Merchant portfolio provides advantages like enhanced security, streamlined transactions, and future-proof capabilities. This solution offers a secure payment method that adheres to industry standards, allowing your Merchants to process payments without storing card data and ensuring compatibility with current and emerging payment technologies.

Getting Started

Omnitoken payment tokens can be used across CP and CNP transactions. There are different requirements for each payment channel.

To use Omnitoken in any environment, you must meet the following requirements:

Your Merchant must be onboarded to the Vantiv Core (VCore) platform.
Omnitoken must be enabled for the Merchant's Account on the Payrix Pro Platform
You are familiar with Worldpay’s triPOS Cloud Transaction APIs and Payrix Pro Transaction APIs.

Contact your Partner Success Manager to enable Omnitoken for your account.

Important!
For CP transactions, you must also have a triPOS-compatible, Omnitoken-enabled terminal provided by an approved key injection facility (KIF).

Enable Omnitoken for Your Merchants

After the Omnitoken parameter is enabled for your account, you must enable Omnitoken for each of your Merchants or Group. The Omnitoken must be enabled for each Merchant or Group. See the following sections for steps to activate Omnitokens through both the Portal and API methods.

Enable Omnitoken with the Portal

This method enables the Omnitoken service for an individual Merchant in your portfolio. You can use this method when one Merchant decides to enable Omnitoken at a later time or is not part of an existing Group with Omnitoken enabled.

Complete the steps in the following sections:

Enable a Single Merchant

Follow these steps to enable the Omnitoken service for a single Merchant:

Click Settings in the left navigation pane.
Click Omnitoken, under Value-Added Services.
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.

Enable a Group

This method enables the Omnitoken service for a Group in your portfolio. This method is best when using a Group to apply other shared settings to multiple Merchants and ensures that future Merchants added to the Group automatically have Omnitoken enabled.

Follow these steps to enable the Omnitoken service for a specific Group:

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 Add Service 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 appears 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.

Enable Omnitoken with the API

You can use the API to enable the Omnitoken service for your Merchants. See the Payrix Pro API Specification for complete details on Omnitoken endpoints.

Enable a Single Merchant

Use the following steps to enable Omnitoken for one Merchant:

Create a POST /omniTokens request and include a request body with the Entity ID for the Merchant being enabled. Add the parameter and value "platform": "VCORE" to ensure the Merchant is enabled through the required platform.
```
POST /omniTokens HTTP/1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com
```
```
{
    "entity": "t1_ent_123abc4d567890efg1h2i34",
    "platform": "VCORE",
    "enablementDate": "2024-06-20 16:53:29",
    "inactive": 0,
    "frozen": 0
}
```
Note: You can build the same request body with a DELETE /omniTokens request to disable Omnitoken for a Merchant.

Submit the request. A successful 200 OK response contains details about the newly enabled Merchant:

{
    "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
}

Result: Omnitoken is enabled for your Merchant and they can now use the service to tokenize customer payments.

Enable a Group (Org)

Use the following steps to enable Omnitoken for a Group (Org):

Create a POST /orgsVASOmnitokens request and include a request body with the Org ID for the Group (Org) being enabled.

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

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

Submit the request. A successful 200 OK response contains details about the newly enabled Group (Org):

{
    "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
}

Result: Omnitoken is enabled for your Group and the enrolled Merchants can now use the service to tokenize customer payments.

By using one of the methods above, your Merchants 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.

Mint Omnitokens

Minting generates new Omnitokens on a Merchant’s Chain from transactions for reuse in future transactions, specifically for CP and CNP transactions. Minting improves traceability and compliance with industry standards to ensure seamless integration into new functions and features.

Mint Omnitokens in Card Not Present Transactions

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 Omnitokens with Online Transactions

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.

{
    "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 processes 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 is created, where the following occurs:

The new customer resource is created, associating the customer with the new Omnitoken.
The token parameter’s value returns the new Omnitoken’s hash value.
The Omnitoken parameter returns 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, create a GET /tokenResults/{id} request using the token ID from the last response as the {id} value.

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

Submit the request. A successful 200 OK response contains details about Omnitoken minting status.

{
    "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.

Mint Omnitokens in Card Present Transactions

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

Mint Omnitokens with a triPOS Terminal Transaction

This process uses the triPOS Cloud Transaction API service for triPOS CP transactions. See the triPOS Cloud Transaction API Specification for comprehensive details on the request and response parameters.

Complete the following steps:

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 used 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 is not returned by the Omnitoken service.

Mint a new Omnitoken with 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 returns the same token details: tokenID, ExpirationMonth, ExpirationYear, and NetworkTransactionID as Method 1, which is saved

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

Convert Payrix Pro Tokens to Minted Omnitokens

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 CP and CNP 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 verifies if the Merchant (specifically if their Merchant ID (MID)) supports and is enabled for the Omnitoken service.

Worldpay processes 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 specifies 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.

Get Omnitoken Details from a Transaction

After minting a new Omnitoken, you might 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.

Get Omnitoken Values from Transaction Details or Terminal Transaction Details Page

Click Payment History on the left navigation panel.
Select the relevant transaction to open the Transaction Details page.
Click Transaction on the Transaction Details left menu to see the Omnitoken token value and expiration date.
(Optional) You can also gather more information about the specific terminal transaction from the Terminal Transaction section of the Transaction Details menu, or clicking the Terminal Transactions button on 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.

Get Omnitoken Values from the Customer Profile Page

Click Customers page from the Dashboard (under the Payments category).
Select the relevant customer to open the Customer Profile page.
Click Payment Methods on the Customer Profile left menu.
Select the Token value from the page to view the payment method information.

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

Using the API

There are five 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 card present terminal 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 card not present online 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 use the GET /tokens method mentioned above and append the endpoint with `/{id}` request with the specific ID of that customer. Format: `t1_cus_123abc4d567890efg1h2i3``

Use Omnitokens for New Transactions

After minting a new Omnitoken, you can 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):

Use Omnitokens for Card Present Payments

Complete the following steps to reuse an Omnitoken in a card present transaction.

Note
This process uses the triPOS Cloud Transaction API service for triPOS card present transactions. See the triPOS Cloud Transaction API Specification for comprehensive details on the request and response parameters.

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 is not returned by the Omnitoken service.

Use Omnitokens for Card Not Present Payments

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 with 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 does 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 updates 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 does not meet the criteria for Merchant fees.

Omnitoken Fees

Using the robust Payrix Pro fee engine, Omnitoken-based actions can generate fees collected from your Merchants. 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.

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 MIDs.

Chain Requirements

Upon boarding the platform, your portfolio is 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 using the Omnitoken Vault, you can securely manage and use Omnitokens for various payment transactions, aligning with industry standards and supporting advanced payment technologies.