Velocity Developer Resources

API Docs


API Docs

Tokenization Overview

About This Resource

This guide provides integration guidance associated with the NAB Velocity Tokenization Value-Added Service (VAS) supported by the Managed Commerce Services on merchants by eliminating the need to store cardholder account data locally with their commerce solutions.

Intended Audience

This guide is intended to provide software company developers with an overview of the NAB Velocity Tokenization Service and some important development considerations associated with the development of Commerce Web Services (CWS) applications that leverage this service.


The following prerequisites are required to leverage the Tokenization Value-Added Service on the Managed Commerce Services Platform:

Additional Resources

The following resources provide additional information that can be referenced as supplemental material to this online guide:

  • Commerce Web Services Developer’s Guide provides an overview of the components and concepts related to the development of client applications that communicate with Commerce Web Services, as well as a step-by-step guide for developing applications that implements the Commerce Web Services SOAP and REST APIs.
  • Integration Guidelines provides guidance associated with the integration to specific certified payment service providers and Value-Added Services (VAS) supported by the Managed Commerce Services Platform.




The NAB Velocity Tokenization Service reduces the complexity, time, and costs associated with protecting cardholder account data in their local database. For credit card transactions, tokenization can reduce the PCI-DSS compliance burden for merchants by eliminating the need to store cardholder account data in the merchant’s local payment processing environment.

What is Tokenization?

When a merchant sends a tokenization-enabled transaction authorization request, consumer account data is inserted into the authorization request message and sent to the Managed Commerce Services Platform. The Platform encrypts and securely stores the consumer account data and assigns a unique “token” that acts as a pointer to the consumer account data. This process is referred to as tokenization. The token is then returned to the requesting application in the transaction response message where it can be stored locally with other “non-sensitive” consumer data (such as name, card expiration date, etc) for use in subsequent transaction requests. The application simply sends the token in lieu of sensitive consumer account data with transaction requests that require this data. The Platform verifies the token, retrieves the consumer account data from the database, and sends the transaction request and all consumer account data associated with the token to the destination service provider for processing.

Note: CWS transactions are always assigned a token regardless of whether tokenization has been enabled for the merchant Service Key. However, the token is only returned to the merchant application when tokenization is enabled.

Tokenization Support

The Tokenization Service is supported by all Commerce Web Services (CWS) commerce solutions. CWS transaction data is stored for the merchant in the Managed Commerce Services Platform transaction database and does not need to be stored locally. For this reason, the application only needs to provide the consumer account data on the initial transaction, and does not need to retain it locally thereafter. As a result, these applications are not subject to PA-DSS requirements. However, there are business cases where the CWS application may wish to store transaction data locally, or may simply wish to store the consumer account data in their application for later use.

An example of such a use case would be a payment-enabled website where users can create and manage accounts with a variety of payment options available to them. This provides the user with a convenient way of purchasing new products or services without having to re-enter their information. In these cases, the creation and storage of a token is a great way to provide saved account consumer functionality without the increase in liability or cost associated with protecting the actual consumer account data.

PCI-DSS Requirements

All payment applications designed to capture, process, store, or transmit credit card data are required to comply with payment card industry security standards established by the PCI Security Standards Council. The Payment Card Industry – Data Security Standard (PCI-DSS) addresses the technical and operational system components included in, or connected to, consumer account data by establishing a comprehensive set of requirements for security management, policies, procedures, network architecture, software design, and other critical protective measures. This comprehensive standard is intended to help organizations proactively protect consumer account data.

According to PCI-DSS Requirement 3 (Protect Stored Cardholder Data), merchants must protect stored consumer account data by means of hashing, truncation, tokenization, or strong encryption. Failure to protect this sensitive data poses a significant security and compliance risk to merchants.

It is important to note that the Payment Application – Data Security Standard (PA-DSS) applies specifically to payment applications that store, process, or transmit consumer account data and are sold, distributed, or licensed to third-party entities. In-house application development by merchants or service providers that are not sold, distributed, or licensed to entities outside the company are not subject to PA-DSS requirements, but must still be secured in accordance with PCI-DSS.

Important! The Tokenization Service never completely eliminates PCI-DSS compliance obligations for software companies and their merchants.



Component Architecture

Tokenization runs as a hosted service on the Managed Commerce Services Platform. Therefore, the merchant’s service configuration ultimately determines whether they can take advantage of tokenization.

When tokenization is supported by the merchant application, the service configuration returned to the application in the response to the GetServiceInformation request tells the application that tokens will be returned in the response messages for all initial transaction requests. The application can then store the token for later transaction processing requests.

Tokens can be used across different applications and different services/serviceids.

This token can also be used for new authorization messages in saved account use cases where tokens are stored with customer account records, such as those typical of recurring payments.

A typical credit authorization workflow for a CWS POS application supporting the Tokenization Service is illustrated below:

Figure 1: Tokenization Workflow

  1. The merchant collects consumer account data, such as credit card number(s), expiration date, etc. using a Commerce Web Services (CWS) point-of-sale (POS) application.
  2. The POS application sends a credit authorization request to the CWS Transaction Processing Service (TPS) via the Transaction Processing endpoint.
  3. TPS routes the credit authorization request to the Transaction Broker (TB).
  4. TB validates the workflowId/serviceId passed in the request message and invokes the Tokenization VAS which extracts the cardholder account data from the message body, encrypts it, assigns a token, and stores the cardholder account data in the transaction database.
  5. The credit authorization request message is then sent to the appropriate destination service provider via the Adaptor Add-Ins for processing.
  6. Upon receiving a successful processing response from the service provider, a credit authorization response message is generated and the token is returned to the merchant’s POS application (6a).
  7. For new transactions where a token is available (such as saved account use cases), the application inserts the token in lieu of cardholder account data.
  8. TB performs a lookup for the provided token against the transaction database and retrieves the associated, encrypted cardholder account data from the database to complete the transaction request.




Additional development may be necessary to support saved account use cases, such as support for recurring payments where the application stores consumer account data within a customer’s account profile. In such use cases, the application simply sends a new authorization request message, such as those initiated by a returning customer, or when performing a recurring payment. With tokenization, all consumer account data associated with the customer is replaced by the secure token.

By their very nature, recurring payments and related use cases are for new transactions that use the Authorize and AuthorizeAndCapture operations. In these cases, tokenization allows the merchant application to store and send only the token rather than sending consumer account data.

Note: Tokens cannot be used for online PIN Debit transactions.

To support saved account payments using tokenization, software companies simply need to provide functionality that allows the application to store and retrieve tokens from the customer’s account profile stored in the local application database. Additionally, each token needs to be unique for each customer credit card. This allows the customer to store multiple credit cards within their account, providing the customer with multiple payment options.

For more information about the development of applications supporting saved account use cases, refer to Saved Accounts.

Saved Accounts

To implement saved account functionality, software companies must provide user interface elements such as a “Save Credit Card” option that allows the merchant (or customer) to save credit card information in their account profile, as well as a “Select a Credit Card” option that allows the user to select a specific credit card they wish to use for new transactions. These user interface controls are common methods of allowing customers to store credit card data in their account profile.

An example of a tokenization implementation for a saved account use case supporting “card not present” transactions is described below:

  • The first time a credit authorization request is initiated, all consumer account data is required, such as name, credit card number, expiration date, and AVS/CVV data. In addition to capturing this data, there must be an option to save the credit card data in their consumer account profile, such as a “Save Credit Card” option.
  • Note: Even if the application user does not select the Save Credit Card option, there is nothing you need to do to perform subsequent transactions related to an initial authorization when supporting tokenization.
  • If the application user selects the Save Credit Card option, the application must extract the token from the authorization response and store it with the consumer’s account profile in the application database. The card type and truncated credit card number should also be stored along with the token. This allows a customer to store and select multiple credit cards in their consumer account profile. A “Select a Credit Card” option allows the user to select a specific credit card when performing a recurring payment.
  • When submitting a new payment, instead of re-entering their credit card information (or entering and saving additional credit card information), the application user selects Card ending in XXXX using the “Select a Credit Card” option. Instead of setting all the properties of the CardData object, you simply set the CardDataToken property and the AVS/CVV data. Once received by the Platform, the token is replaced by the actual card data before it is decrypted and sent to the service provider.
  • Note: PCI-DSS (as well as the Tokenization Service) does not allow for the storage of CVV codes or Track data in any form. The software company can either prompt the user to re-enter the CVV code for subsequent transactions which use a PaymentAccountDataToken, or simply exclude CVV data for transactions that use a PaymentAccountDataToken in place of card data.

    AVS and billing data may be stored and should be set on subsequent transactions.

In addition to recurring payments, other saved account use cases include:

  • Convenience payments – Commonly supported by internet retailers and online shopping carts that allow loyal customers to store credit card information as part of their consumer account for “convenient” payments during return visits.
  • Installment payments – Transactions that begin with a fixed total amount. Each payment deducts from the total until the balance is paid. An example of an installment payment would be paying off a car.
  • Bill payments – Customer-authorized bill payment of a variable amount on a specific day of every month with no established end date. An example of a bill payment would be settling a monthly electricity bill.
  • Scheduled payments – Customer-authorized bill payment of a fixed amount at a later date. An example of a scheduled payment would be scheduling this month’s cable bill to be paid on a specific date next week.

Updated: June 5, 2017

Need Help?


Agent or a merchant? Contact NAB support at 866.485.8999 EXT 2341