Omnitoken

An Omnitoken is a unique digital token generated within a Merchant's chain that enhances security and traceability for transactions. It serves as a secure substitute for sensitive payment information, ensuring safe and seamless transactions. For Referrers, enabling Omnitoken for their Merchant Portfolio offers increased security, streamlined transactions, and future-proofing capabilities. By utilizing Omnitoken, Referrers 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 is used (provided by KIF).
Each relevant Merchant and Customer account is activated for Omnitoken.
VCORE is used as the processing platform since Omnitoken exclusively works with the VCORE Express gateway.
You are familiar with Worldpay Express Gateway APIs and Payrix 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. Let's explore how to enable the Omnitoken service through both the Portal and API methods.

Using the Portal

Enable OmniToken Parameter for your Referrers

Step 1: Click Divisions in the left-hand navigation panel and access the profile for the Division (Referrer Portfolio) you’d like to enable.
Step 2: Click Parameters from the left-hand Division Profile menu.
Step 3: Click the Add Parameters button in the top right-hand corner.
Step 4: Click the Edit icon in the upper right corner and scroll to Omnitoken Enabled
Step 5: Toggle Omnitoken Enabled on and select Enabled from the drop-down.
Step 6: Click the Confirm icon in the upper right corner of the page to complete the process.

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

Using the API

Enable OmniToken Parameter for your Referrers - /parameters

Parameters Headers

CODE

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

Available HTTP Methods
Create	`POST /parameters`
Retrieve All	`GET /parameters`
Retrieve by ID	`GET /entityCustomFields/{id}`
Update	`PUT /parameters/{id}`

Request Body

JSON

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

View the full endpoint reference here.

You must be logged in to the Portal to access this endpoint reference.

Parameter	Type	Required	Description	Valid Values
`login`	ID	Required	The ID of the Login (User) enabling the Omnitoken parameter.	This field is stored as a text string. Example Format: `t1_ent_123abc4d567890efg1h2i34`
`OmnitokenEnabled`	Boolean	Required	Whether or not the Omnitoken feature is enabled.	Valid Values: `0` - Disabled `1` - Enabled
`inactive`	Boolean	Required	Whether this parameter configuration is marked as inactive.	Valid Values: `0` - Active `1` - Inactive
`frozen`	Boolean	Required	Whether this parameter configuration is marked as frozen.	Valid Values: `0` - Not Frozen `1` - Frozen

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 Referrer and its subsequent Merchant portfolio (Division), the Omnitoken must be activated or “enabled” for each Merchant or Group. By activating Omnitokens, Referrers 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

Activate OmniToken for a Single Merchant - Merchant Profile page

Step 1: Click Settings in the left-hand navigation panel to open the Settings page.
Step 2: Click Omnitoken, under the Value-Added Services section of the page.
Step 3: Click the Enable button 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

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

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

Activate OmniToken for a Single Merchant - /omniTokens

Omnitokens Headers

CODE

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

Available HTTP Methods
Create	`POST /Omnitokens`
Retrieve All	`GET /Omnitokens`
Retrieve by ID	`GET /Omnitokens/{id}`
Update	`PUT /Omnitokens/{id}`
Delete	`DELETE /Omnitokens/{id}`

ID Format

t1_otk_123abc4d567890efg1h2i34

Request Body

JSON

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

View the full endpoint reference here.

Parameter	Type	Required	Description	Valid Values
`entity`	ID	Required	The ID of the Entity that this Omnitoken is associated with.	This field is stored as a text string. Example Format: `t1_ent_123abc4d567890efg1h2i34`
`platform`	string	Required	The Platform to which an Omnitoken should be applied.	Valid Values: `VANTIV` - Vantiv VAP `VCORE`- Vantiv CORE `WORLDPAY` - Worldpay Express
`enablementDate`	date-time	Optional	The date and time when an entity will be enabled for Omnitoken.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z`
`inactive`	Boolean	Required	Whether this resource is marked as inactive.	Valid Values: `0` - Active `1` - Inactive
`frozen`	Boolean	Required	Whether this resource is marked as frozen.	Valid Values: `0` - Not Frozen `1` - Frozen

Response Body

CODE

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

Parameter	Type	Description	Valid Values
`id`	ID	The ID of the existing/ newly created Omnitoken	This field is stored as a text string. Example Format: `t1_otk_123abc4d567890efg1h2i34`
`created`	date-time	The date the Omnitoken was first created.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z`
`modified`	date-time	The date the Omnitoken was last modified, if applicable.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z`
`creator`	ID	The User (Login) ID for the user that created the Omnitoken.	This field is stored as a text string. Example Format: `t1_log_123abc4d567890efg1h2i34`
`modifier`	ID	The User (Login) ID for the user that last modified the Omnitoken.	This field is stored as a text string. Example Format: `t1_log_123abc4d567890efg1h2i34`
`entity`	ID	The ID of the Entity that this Omnitoken is associated with.	This field is stored as a text string. Example Format: `t1_ent_123abc4d567890efg1h2i34`
`platform`	string	The Platform to which an Omnitoken should be applied.	Valid Values `VANTIV` - Vantiv VAP `VCORE`- Vantiv CORE `WORLDPAY` - Worldpay Express
`org`	ID	The ID of the Orgs (group) that Omnitoken is associated with.	This field is stored as a text string. Example Format: `t1_org_123abc4d567890efg1h2i34` Will be `null` if not provided.
`division`	ID	The ID of the Division that Omnitoken is associated with.	This field is stored as a text string. Example Format: `t1_div_123abc4d567890efg1h2i34` Will be `null` if not provided.
`partition`	ID	The ID of the Partition that Omnitoken is associated with.	This field is stored as a text string. Example Format: `t1_ptn_123abc4d567890efg1h2i34` Will be `null` if not provided.
`enablementDate`	date-time	The date and time when an entity will be enabled for Omnitoken.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z`
`inactive`	Boolean	Whether this resource is marked as inactive.	Valid Values: `0` - Active `1` - Inactive
`frozen`	Boolean	Whether this resource is marked as frozen.	Valid Values: `0` - Not Frozen `1` - Frozen

Activate OmniTokens for a Merchant Group (Org) - /orgsVASOmniTokens

Omnitokens Headers

CODE

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

Available HTTP Methods
Create	`POST /orgsVASOmnitokens`
Retrieve All	`GET /orgsVASOmnitokens`
Retrieve by ID	`GET /orgsVASOmnitokens/{id}`
Update	`PUT /orgsVASOmnitokens/{id}`
Delete	`DELETE /orgsVASOmnitokens/{id}`

ID Format

t1_ovo_123abc4d567890efg1h2i34

Request Body

JSON

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

View the full endpoint reference here.

Parameter

Type

Required

Description

Valid Values

org

ID

Required

This field is stored as a text string.

Example Format:

t1_org_123abc4d567890efg1h2i34

Will be null if not provided.

inactive

Boolean

Required

Whether this resource is marked as inactive.

Valid Values:

0 - Active
1 - Inactive

frozen

Boolean

Required

Whether this resource is marked as frozen.

Valid Values:

0 - Not Frozen
1 - Frozen

Response Body

JSON

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

Parameter	Type	Description	Valid Values
`id`	ID	The ID of the existing/ newly created Omnitoken	This field is stored as a text string. Example Format: `t1_otk_123abc4d567890efg1h2i34`
`created`	date-time	The date the Omnitoken was first created.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z`
`modified`	date-time	The date the Omnitoken was last modified, if applicable.	Format: YYYY-MM-DD HH:MM:SS (UTC) Example: `2024-03-29T21:26:55.016Z`
`creator`	ID	The User (Login) ID for the user that created the Omnitoken.	This field is stored as a text string. Example Format: `t1_log_123abc4d567890efg1h2i34`
`modifier`	ID	The User (Login) ID for the user that last modified the Omnitoken.	This field is stored as a text string. Example Format: `t1_log_123abc4d567890efg1h2i34`
`org`	ID	The ID of the Orgs (group) that Omnitoken is associated with.	This field is stored as a text string. Example Format: `t1_org_123abc4d567890efg1h2i34` Will be `null` if not provided.
`inactive`	Boolean	Whether this resource is marked as inactive.	Valid Values: `0` - Active `1` - Inactive
`frozen`	Boolean	Whether this resource is marked as frozen.	Valid Values: `0` - Not Frozen `1` - Frozen

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.

Omnitoken Fees

Using the robust Payrix fee engine, Omnitoken-based actions can generate fees for Merchants to their Referrers and Facilitators, 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 Token.
Lookup of an existing Omnitoken using the original Payment 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

Fees are incurred for both minting new tokens and looking up existing tokens based on the Payment Account Number (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.

Note: To avoid unnecessary lookup charges, Merchants can use the actual token value instead of the PAN information in a new transaction.

Tip: 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 Referrers. 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 & Payrix 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 Authroization, or Refund transaction.

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) 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 payment acceptance options available through the /txns endpoint, such as Sale or $0 Authorization types.

Mint a new OmniToken through online Sale, $0 Authorization or Refund transaction.

Step 1: 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:

CODE

{
    "merchant": "t1_mer_6695a6b295d1faadecfce52",
    "origin": "2",
    "type": "1",
    "first": "John",
    "last": "Doe",
    
    "token": {
        "customer": {
            "first": "John",
            "last": "Doe",
            "email": "john@examplemail.com"
            },
        "payment": {
            "number": "4111111111111111",
            "cvv": "123"
        },
        "expiration": "1234",
        "inactive": "0",
        "frozen": "0" 
    }
}

Step 2: 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 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.

CODE

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

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

Transaction Headers

CODE

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

Available HTTP Methods
Retrieve All	`GET /tokenResults`
Retrieve by ID	`GET /tokenResults/{id}`

ID Format	`t1_tkr_123abc4d567890efg1h2i34`

Path Parameter	`{id}`	The ID for the `tokenResults` record being retrieved.

Response Body

JSON

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

Parameter	Type	Description	Notes / Valid Values
`id`	ID	The ID of the `tokenResults` record.	Format: `t1_tkr_123abc4d567890efg1h2i34`
`created`	date-time	The date and time the `tokenResults` record was first created.	Format: `YYYY-MM-DD HH:MM:SS.SSSS`
`modified`	date-time	The date and time the `tokenResults` record was last modified.	Format: `YYYY-MM-DD HH:MM:SS.SSSS`
`creator`	ID	The login ID of the user that first created the `tokenResults` record through an Omnitoken-based action.	Format: `t1_log_ 123abc4d567890efg1h2i34`
`modifier`	ID	The login ID of the user that last modified the `tokenResults` record through an Omnitoken-based action.	Format: `t1_log_ 123abc4d567890efg1h2i34`
`txn`	ID	The ID of the transaction record associated with the Omnitoken-based action.	Format: `t1_txn_ 123abc4d567890efg1h2i34`
`token`	ID	The ID of the token record for the Omnitoken on file within the Payrix platform.	Format: `t1_tok_123abc4d567890efg1h2i34` Note: This is sometimes called the “Hash Value” for the Omnitoken.
`merchant`	ID	The ID of the Merchant account that processed the transaction associated with the Omnitoken-based action.	Format: `t1_mer_123abc4d567890efg1h2i34`
`code`	string	The type of Omnitoken action that occurred through the Payrix platform.	Valid Values: `OmnitokenMinting` - The Omnitoken was minted. `OmnitokenLookup` - A Merchant looked up the Omnitoken `OmnitokenUsage` - The Omnitoken was used in a transaction.
`Omnitoken`	numeric string	The actual value of the Omnitoken itself.	Format: `1234567890123456` This is not the actual card data, but a single 16-digit numeric string representing the individual Omnitoken.

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

Convert a Payrix Token to Minted Omnitoken

Merchants with pre-existing customer records likely have Payrix 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 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 Importing Tokens from Another Processor to Payrix, then use the Omnitoken service to re-tokenize from Payrix Tokens for a streamlined process.

Click here for steps to convert a Payrix Token to Minted OmniToken

Step 1: A sale, refund or $0 auth transaction is sent using the Payrix /txns endpoint and a pre-existing customer payment token in the token field.
Step 2: The Primary Account Number (PAN) details associated with the Payrix 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.
Step 3: Worldpay will then process the transaction and mint the Omnitoken, returning the following response in the token object:

JSON

{
    "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: When the Omnitoken parameter displays null or no value, the token parameter indicates the Payrix token, created on the Payrix 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.

Step 4: 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 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

Click here for steps to retrieve an OmniToken value from the Portal

Method 1: Transaction Details or Terminal Transaction Details

Step 1: Click Payment History from the Dashboard.
Step 2: Locate the transaction listed on the table and click on the table listing to open the transaction details page.
Step 3: From the Transaction Details page, click Transaction from the left hand page menu.
Step 4: The Omnitoken and Omnitoken expiration dates will be displayed in the lower right portion of the details form.
Step 5: (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

Step 1: Access the Customers page from the Dashboard (under the Payments category).
Step 2: Click the listing the Omnitoken-associated customer to open the Customer Profile.
Step 3: Click Payment Methods from the left-hand menu of the Profile.
Step 4: 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

Click here for methods available to retrieve an OmniToken value with 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 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 online payment acceptance options (Card Not-Present):

Card-Present

Click here for steps to reuse an OmniToken in a Car-Present transaction.

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 reurned by the Omnitoken service.

Card Not-Present

Click here for steps to reuse an OmniToken in a Card Not-Present transaction.

Step 1: Configure a new POST /txns request, with a Type of Sale, $0 Auth, Refund, or Sale w/ Card-on-File.
Step 2: In the token object of the request body, add the Omnitoken token value returned from the minting process.

Warning: 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.

Step 3: 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.

Chains are activated by Payrix or another a Facilitator-level entity for each Referrer.

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.