Velocity Developer Resources

API Docs


API Docs


The NAB Velocity Tokenization Value-Added Service (VAS) 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.



Tokenization VAS 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.

Important! Tokens returned by the Tokenization Service are only valid for the services/serviceIds you are transacting against, and are not re-usable across 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:

Tokenization Service

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.



Tokenization VAS Implementation

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.

Implementation Guidelines

  • BankcardTenderData.PaymentAccountDataToken can be passed in lieu of the full CardData object in all requests. However, it is recommended that values for CardType, Expire, and PAN (MaskedPAN) be specified in CardData to facilitate production troubleshooting.

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.

Tokenization VAS Requirements

Service Overview

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


Integration to the NAB Velocity Tokenization Value-Added Service (VAS) requires a Commerce Web Services payment solution.


  • During the “Retrieving Service Information” process of a Commerce Web Services integration, a workflowId will be returned to the requesting application that must be passed with all subsequent payment transaction requests in order to trigger VAS processing.
  • The workflowId is included in the response to a GetServiceInformation request.

Updated: June 5, 2017

Need Help?


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