The AuricVault® Service

The AuricVault® service provides APIs for three PCI/HIPAA compliant functions:

  • Tokenization (protect credit cards and other sensitive personally identifiable information)

  • Token Swap (obtain native tokens from multiple payment processors)

  • Payments Passthrough (payment processing through multiple payment processors)

Status

Auric maintains a service status page. Please sign up for the notification service.

Tokenization

What is tokenization?
Tokenization, when applied to data security, is the process of substituting a sensitive data element with a non-sensitive equivalent, referred to as a token, that has no extrinsic or exploitable meaning or value.
— Wikipedia

The AuricVault® service is designed to store more than just sensitive payment information (credit card account numbers). Each token can store up to 2,000 bytes of data including private information such as tax IDs, addresses, etc.

Token Swap

The Token Swap service allows you to convert stored tokens into payment processor specific tokens. This is useful if you need to support multiple payment processors for your clients. A standard interface allows you to obtain payment tokens from various payment processors.

Payments Passthrough

The AuricVault® service can pass payment transactions through to multiple payment processors. Payment transactions can use the native AuricVault® token or payment processor-specific tokens.

Custom Solutions

Auric Systems International develops custom solutions around our core tokenization and payment services. Services are tailored to meet your tokenization and payments requirements.

Contact sales@AuricSystems.com to discuss.

Custom solutions we’ve built and manage:

  • Batch tokenization and detokenization.

  • SOAP tokenization proxy (intercept SOAP web messages and replace sensitive data with tokens).

  • Transferring encrypted batch files among multiple parties.

  • Custom API calls to meet legacy requirements.

Test Credentials

Sign up at Auric Systems for your free test credentials to try out any of the following services.

Tokenization

The AuricVault® tokenization service is a PCI and HIPAA compliant data storage service that associates tokens with secure encrypted data. The encrypted data can be stored, retrieved, updated, and deleted. A tiered permission system provides controlled sharing of sensitive information with third parties while tracking access to the data by user and date/time. Retention policies allow automatic aging-out of data when it is no longer accessed.

The tokenization service is an ideal storage solution for any sensitive data:

  • credit/debit card numbers

  • bank accounts

  • Personally Identifiable Information

    • Names

    • Addresses

    • License/certificate numbers

    • Vehicle identifiers and serial numbers — license plates.

    • Birth dates

    • Phone/Fax numbers

    • Email address

    • Health insurance beneficiary numbers

    • Policy Numbers

    • Social Security Numbers

    • Tax Ids

  • passwords hashes

  • Security tokens (such as OAUTH2)

  • Protected Health Information

    • Medical Id

    • Addresses

    • Names

Tokenization creates data separation. Your sensitive data is stored separately from your general business data. Data separation is an active component of any security plan.

Preparing For A Break In

No system is entirely safe from malicious intrusion. Regardless of the care taken to secure systems, you must plan on how to deal with an intruder.

Tokenization is a vital factor in preparing for that break-in. Thieves cannot steal what you do not have. Tokenization moves your vitally important sensitive personal and financial data out of your environment and into Auric’s PCI and HIPAA compliant hosting environment.

AuricVault® tokens are randomly-generated strings of numbers and letters that have no relationship to the stored data. If someone were to steal all your tokens, they still would not have any of your sensitive data.

This is an important fact to consider if you decide to generate your own token IDs vs. using the auto-generated IDs from the service. The method by which you generate the token ID needs to be unrelated to the stored data. For example, the token should not be a cryptographic hash of the stored data. Nor should it be some sort of scrambling or letter/number substitution scheme. If you calculate a token based on the data provided, it could be possible for someone else to calculate the data from the token. Sequence or time based token IDs are also not secure.

It is your responsibility to safeguard any sensitive stored data and to defend against malicious intrusion.

Auric Also Prepares

The concept that "Nothing is 100% secure." also applies to the AuricVault® service. When implementing your tokenization strategy, you need to keep in mind what would happen if the AuricVault® storage is breached.

Consider this scenario when determining what data to store in a single token. If you store a credit card number in a token, and the service was compromised to the point where someone could decrypt that data, the credit card account number by itself is useless. However, if you store the credit card account number and the expiration date (or billing address information) in the same token, then you have a situation where the compromised data is useful to the intruder. Similarly, a taxpayer ID number by itself is not particularly useful, but a taxpayer ID number stored in the same token with a name and address is informative and helpful to the attackers.

Any combination of PCI DSS (PCI Data Security Standard) or Protected Health Information (defined by the Health Insurance Portability and Accountability Act — HIPAA) accessed by non-authorized entities presents substantial legal and financial ramifications. Such infringements cannot be taken lightly as the liability is considerable.

Auric takes prudent measures to ensure our environment is secure as well as being both PCI and HIPAA compliant. Auric Systems International, as well as our hosting providers Flexential and Armor Defense, Inc. are all Level 1 PCI Validated Service Providers and undergo third-party reviews on a regular basis.

Auric maintains their encryption key management system in a separate facility from the tokenized data storage.

Following prudent practices and thinking carefully about the stored data ensures your sensitive data remains safe at all times.

Tokenize What Matters®

There are several options to consider before starting your AuricVault® tokenization service implementation:

  • Contents: What data will you store in each token?

  • Encryption Management: Will you let the service handle your encryption and key management (recommended), or will you encrypt the data yourself?

  • Integration Method: Will you tokenize from your server or a browser?

  • Retention Policy: How long will you maintain the tokenized data?

  • Permission Policy: How many different services, clients, or partners need to store and access the tokenized data?

  • Segmentation: How should you segment/classify your tokens with different access permissions?

What Can You Store?

Each token can contain up to 2,000 bytes of ASCII or UTF-8 encoded data. Tokens you intend to use with the Token Swap or Payments Passthrough features must contain only the cardholder account number (PAN). Binary data must first be encoded into a text format such as Base64 or Hexadecimal.

Encryption Management

All data stored in the AuricVault® service must be encrypted. Most users allow the service to manage the data encryption (vault-managed encryption). There are also API calls that allow you to manage encryption on your servers.

Note
If you intend to use either the Token Swap or Payments Passthrough feature in the future, you must choose the vault-managed approach.

Vault-Managed Encryption

Vault-managed encryption performs all encryption/decryption and key management tasks within the AuricVault® service. You send plaintext (unencrypted) data to the AuricVault® service. The service encrypts and then stores the data. The AuricVault® encryption keys are rotated at least every 90 days.

Vault-managed encryption methods include both server-side and browser-side tokenization and de-tokenization methods. The browser-side methods allow any sensitive data to be tokenized/encrypted directly from a browser over secure HTTPS connections without the sensitive information ever touching your servers. These browser-side methods referred to as session-based.

The vault-managed encryption token API calls are:

  • encrypt

  • decrypt

  • reencrypt

  • session_encrypt

  • session_decrypt

  • delete_token

  • token_info

  • touch_token

  • get_session

Locally-Managed Encryption

Locally-managed encryption requires you to control the encryption and decryption process, key management, and key rotation. You send pre-encrypted data to the AuricVault® service, and the vault returns that same data for you to decrypt. With this method, the service does not have access to the encryption/decryption keys. You may use any encryption method that aligns with your security policies.

The AuricVault® tokenization API for locally-managed encryption requires all calls to originate from your server’s web application. Browser-based encryption is not available with locally-managed encryption. Sharing data with third parties is problematic since it implies shared encryption keys, this includes payment processors. Neither Token Swap nor Payment Pass-Through is available when using locally-managed encryption.

Locally-managed encryption is ideal for environments that need to internally manage their custom encryption policies and maintain access to the tokenized data within a locally limited environment.

The locally-managed encryption token API calls are:

  • store_token

  • generate_token

  • retrieve_token

  • update_token

  • delete_token

  • token_info

  • touch_token

Converting Between Methods

Tokens can be converted from locally-managed to vault-managed (or vault to locally). You need to write a small program to read each token that is currently stored with one method and then store it back with the other. For example, call retrieve_token to retrieve the encrypted data, decrypt it on your local server, then either encrypt (to create a new token) or reencrypt (to re-use the same token). The token_info method can be used to determine a token’s encryption management method.

Integration Methods

The AuricVault® tokenization API supports three integration methods:

  • Server-Side from any programming language capable of generating JSON and HTTPS POST calls.

  • Browser-Side JavaScript.

  • Custom Embedded iFrame.

Server-Side

Server-side integration allows both modern servers and legacy systems to integrate with the AuricVault® service. The integration method is a simple HTTPS POST call using JSON-RPC. Any current programming language can easily integrate with the service.

Server-side integration API calls include:

  • encrypt

  • decrypt

  • delete_token

  • token_info

  • touch_token

  • get_session

  • payment

  • store_token

  • generate_token

  • retrieve_token

  • update_token

Note
get_session is a direct connectivity method, but only useful in conjunction with the browser-side JavaScript session based calls.

Browser-Side Integration

Browser-side integration is typically JavaScript based, but you can use any browser-side programming technology. Browser-side API calls include:

  • session_encrypt

  • session_decrypt

Before using the session_encrypt and session_decrypt methods, your server must first make a server-side API call (get_session) to the AuricVault® service and obtain a sessionId.

When you make the get_session call, you pass your credentials to the AuricVault® service and receive back a sessionId. This sessionId is associated your credentials. The sessionId acts as your credentials for the session-based encrypt and decrypt calls.

Note
The sessionId can only be used once and must be used within ten (10) minutes of being created.

The browser-side token integration is an open API using industry-standard AJAX calls. It does not require a custom script from Auric. This gives you complete flexibility in how you design your form and how you store the sessionId needed by the session_encrypt or session_decrypt call.

Prudent Browser-Side Practice

Some browser-based tokenization services show an example input form such as this:

    <form action="./submit/" method="POST">
        <label for="fullname">Full Name</label>
        <input type="text" name="fullname"> <br>

        <label for="ccnum">Credit Card Number</label>
        <input type="text" name="ccnum"><br>

        <input type="submit" value="Pay Now">
    </form>

A JavaScript function is then attached to the Submit event. This function copies the credit card number, tokenizes it, and then either clear the credit card number field and replaces it with a token, or deletes the credit card field and inserts a new token field.

But what if your JavaScript is broken? What if a network failure caused a script load failure, or a browser update breaks your JavaScript on this page? Suddenly, the JavaScript no longer overrides the submit button’s default behavior and a credit card number is submitted to your server when the user clicks on the button — breaking your PCI compliance.

The AuricVault® service’s approach is to break the data entry form into multiple pieces and then have the JavaScript put the pieces back together. For example.

    <form id="ccnum-form">
        <label for="ccnum">Credit Card Number</label>
        <input type="text" name="ccnum"><br>
    </form>


    <form id="main" action="./submit/" method="POST">
        <label for="fullname">Full Name</label>
        <input type="text" name="fullname"> <br>

        <input type="submit" value="Pay Now">
    </form>
Note
The form for entering your credit card number does not have a submit button. The JavaScript triggered by your submit button can find the ccnum field in the ccnum-form form, tokenize it, add a token field to the main field, and ensure that only the token is ever submitted to your server. In this example, a credit card number can never be sent to your server in the case where your JavaScript is broken or failed to load.
Custom Embedded iFrame

The AuricVault® service encourages you to develop your own custom embedded iFrames that smoothly integrate into your existing site. You can host the final implementation hosted on Auric’s secure servers.

The custom iFrame can be multiple files consisting of:

  • HTML

  • CSS

  • Javascript

  • images

Your iFrame implementation can include any static file.

Contact Auric sales or support for more information about custom iFrame hosting.

Retention Policies

The AuricVault® service supports multiple retention policies. This allows you to set different retention policies for different types of data.

Retention policies define the number of days the token is retained after the last time it is accessed (read, updated, decrypted, touched, or used for payment).

There are two default retention policies:

  • big-year: approximately 14 months (14 * 31 days)

  • forever: never deleted

The big-year policy is approximately 14 months. This is suitable for credit card account numbers used in a repeat billing scenario. A big-year retention allows you to maintain tokens you use only once per year.

The forever policy is suitable for passwords, financial and medical identification numbers, names, etc.

You can request a custom retention policy when you sign up for your AuricVault® account. Retention policies can as short as 31 days.

Once a token exceeds the retention policy it is marked as expired and is no longer retrievable.

Note
The service tracks the last time a token was accessed. Retention policies are based on the last time a token was accessed, not on the time a token was created. Tokens accessed regularly never expire.

Permissions

The AuricVault® API allows you to define multiple credentials for access to the tokenized data. Each set of credentials has an associated set of permissions. Permissions control what actions a set of credentials can perform. Permissions include:

  • read

  • write

  • delete

  • encrypt

  • decrypt

  • update

  • reencrypt

  • info

  • touch

  • session (browser) based decrypt

  • token swap

  • payments

One or two credentials are sufficient to meet most situations. If you have a web service and a billing system, Auric recommends that the web service have permission to encrypt using the session_encrypt method, but not have the ability to do any decryption. Your back-office billing system could have the ability to decrypt data, but perhaps not update or delete it.

Note
session_decrypt (or browser-side decryption) is a unique feature that allows you to return decrypted data directly to a user’s browser without having the decrypted information touch your servers. By default, this feature is disabled.

Information Segmentation

Information segmentation allows you to divide your information into different categories (segments). The AuricVault® service can tokenize and isolate a wide range of data with varying levels of sensitivity.

For example, suppose you use the service to store both credit card numbers and passwords. Giving a service access to passwords should not mean that service automatically has access to the credit card numbers as well. Or perhaps you are tokenizing passwords from two different websites. Segmentation allows you to categorize which tokens are associated with which web site. With segmentation, you can store tokenized credit card numbers in one segment and tokenized passwords with another segment.

You can also provide permissions based on that segmentation. This makes segmentation useful when sharing information with other companies or clients.

Token Swap

The Token Swap feature requires you have credentials for the payment processor for which you want to obtain tokens.

The Token Swap APIs are within the Payment Processor section.

An AuricVault® token is independent of any payment processor. The AuricVault® service has the unique ability to translate this independent token into a processor-specific token. We call this Token Swap.

The Token Swap service has numerous advantages:

  • Ability to use the same credit card data with multiple payment processors.

  • Simplify front-end development (capture one type of token) and allow a back-end system to handle specific payment processor targeting.

  • Integrating new front-end system with legacy systems already capable of communicating with various payment processors.

  • Allowing future migration between payment processors.

The AuricVault® Token Swap capability allows you to capture and tokenize the credit card using the AuricVault® tokenization service and then translate that token into a payment processor specific token. Refer to the tokenize payments API call for each supported payment processor.

Bulk Tokenization

Custom bulk tokenization services are available. The AuricVault® service can accept a batch-upload of all your existing credit card accounts and return a file with AuricVault® tokens and/or processor-specific tokens.

Switching Payment Processors

Auric can help move your previously tokenized credit cards from one payment processor to another.

Auric provides a secure PCI-compliant intermediate to coordinate extraction of your existing cardholder data from your current payment processor and then tokenizing it for another payment processor.

Contact Auric at support@AuricSystems.com for details on bulk tokenization and switching payment processors.

Tokenization API

JSON-RPC

The AuricVault® tokenization API uses the JSON-RPC protocol. Client software POSTs a JSON-RPC formatted request object to the service. The AuricVault® service returns a JSON response object that describes the result of the transaction.

JSON-RPC Request Notes

  • The params value in the JSON-RPC request is a single-element list containing a dictionary of parameters specific to the method being called.

  • The id parameter is used to track asynchronous transactions. This is typically only used from browser-side connections. The id does not need to be unique.

  • All HTTPS calls to the service must verify the authenticity of the presented HTTPS certificate. Not validating the certificate’s authenticity leaves your system open to a Man in the Middle attack.

  • All HTTPS communications must use TLSv1.2.

JSON-RPC Response Notes

  • The id sent in the request is returned in the response.

  • If the returned error value is null, then no failures occurred during the request. (You still need to check lastActionSucceeded to determine if everything is successful, even if the error value is null.)

  • elapsedTime is the time taken for the service to process the request. It does not time the network latency to connect.

  • The version returned is the version of the AuricVault® API. This value will be 2.x where x changes over time. Do not interpret this value.

Note
Always use the object returned by the standard JSON decoding package for your language. Do not try to interpret the returned values. Do not assume that the parameters documented here are the only parameters returned. Do not expect the parameters are always returned in the same order. Auric reserves the right to return additional parameters or change the order in which parameters are returned at any time.

Character Encoding

The AuricVault® service supports UTF-8 encoded token values and stored data. All maximum data sizes are given in bytes.

Maximum Data Sizes

The maximum data sizes for the AuricVault® tokenization are: * token ID: 40 bytes * stored data: 2,000 bytes

Attempting to store token IDs or data larger than the maximum size causes the operation to fail.

Note
Token IDs generated by the service are 19 printable ASCII characters and can include numbers and upper/lower case letters. Token IDs created by the user can contain UTF-8 characters. Token IDs using UTF-8 characters must be 40 bytes or smaller.
Note
Stored data can contain UTF-8 characters. When using UTF-8 characters, check that your data is less than 2,000 bytes.

Custom HTTP Headers

The AuricVault® service uses two custom HTTP headers:

  • X-VAULT-HMAC (required*)

  • X-VAULT-TRACE-UID (optional)

Note
The browser side session_encrypt and session_decrypt API calls do not use the X-VAULT-HMAC header.

X-VAULT-HMAC

An HMAC (Hash-based Message Authentication Code) is a calculated value used to establish the authenticity and data integrity of a message. HMAC authentication uses a shared secret between sender and receiver. You receive your shared secret string as part of your credentials.

The HMAC is calculated on the full body of the message being delivered. This ensures that your data was not modified en route.

The service uses SHA-512 hashing to calculate the HMAC. Most languages have a cryptographic library module that contains an HMAC function. In Python, for example, you can use the hmac module as follows:

HMAC Calculation
    calculated_hmac = hmac.new(secret, message_body,
                               hashlib.sha512).hexdigest().lower()

Parameters:

  • secret: the shared secret from your credentials.

  • message_body: serialized (i.e., 'stringified') version of the JSON object being posted. Always calculate the HMAC on the full message body.

Note
The resulting HMAC hex string is always lowercased.

See HMAC Examples for sample data and code snippets.

X-VAULT-TRACE-UID

This optional HTTP header value is used for debugging purposes. When available, the AuricVault® service uses this value in all its logs. If sent, this value is also returned in the response.

Note
X-VAULT-TRACE-UID must be printable ASCII characters no longer than 64 characters.

Unix Timestamp

All the JSON-RPC calls except session_encrypt and session_decrypt require a Unix timestamp parameter. The service requires that time stamps be reasonably close to the time at which the transaction is received. Since the timestamp parameter is included in the HMAC calculation, this reduces the opportunity for a malicious play-back attack on your transactions. If the time stamp is much earlier or later than expected, you receive a response saying the transaction time is not correct. The response shows how the service interpreted the timestamp parameter and what it sees as the current time. This is a helpful debugging device if you are running into problems with time zones.

Note
Please refer to your specific programming language for details on generating a Unix time stamp. The service requires the timestamp parameter be an integer (some libraries return fractions of a second as well). Also be aware of languages such as JavaScript that return the time stamp in milliseconds, not seconds.

+ The Unix time stamp must be generated for the UTC time zone, not your local time zone.

+ When working with the AuricVault® service it is important to keep your own server properly synchronized to a network time server. Your call to the service will fail if the time stamp on your message is more than five (5) seconds into the future or 30 seconds into the past.

last4 Parameter

The following methods have an optional last4 parameter:

  • generate-token

  • encrypt

  • session-encrypt

When storing credit card account numbers, the returned token typically ends with the last four digits of the plaintext card number. This allows you to display the last four digits of a credit card number on a website or data entry screen.

The encrypt and session_encrypt methods automatically extract the last four characters of the plaintext and use that as the last four characters of the token. You can override this default behavior by providing the last four characters to be used.

Since the generate_token method stores already encrypted data, the method cannot automatically extract the last four digits of the plaintext. If you do not include a last4 parameter in the call, the generated token will end with four 'x' characters.

Note
That last4 data is four characters, not four digits. You can include any four printable UTF-8 encoded characters.
Note
The last four characters are automatically extracted only when the plaintext data to be encrypted is longer than eight characters. If the plaintext data is less than eight characters, and you do not provide a last4 value, the last four characters of the generated token are set to 'xxxx'.

Credentials

Programmatic access to the AuricVault® tokenization service API requires the following three credentials:

configurationId

The primary identifier for the business.

mtid

The Merchant’s Tokenization Id associated with the account.

secret

A shared secret between you and the service.

Configurations may have more than one mtid. You can think of the mtid value as representing a role — roles define permissions.

The secret is never transmitted. It is used to calculate the HMAC value used for authentication. The HMAC must be submitted with all transactions that originate from your server. Only browser-side tokenization calls do not require HMAC (because that would require the secret to be exposed in the browser).

Retention and Segment Parameters

Every JSON-RPC method that stores tokens has mandatory retention and segment parameters. See Retention Policies and Information Segmentation sections for usage.

When using sessions, the retention and segment parameters are sent with the get_session method. This stores your desired retention period for use by the session_encrypt method and allows you to control the retention period and segmentation in your server-side code vs. the browser-side.

Vault-Managed Encryption Methods

These methods allow the service to handle all the encryption and key management requirements. Support is provided for browser-side tokenization/encryption.

  • encrypt

  • reencrypt

  • decrypt

  • session-encrypt

  • session-decrypt

encrypt

Encrypt a plaintext value and return a generated token. The generated token is stored in the vault. The last4 parameter is optional.

Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "utcTimestamp": "1401309530",
        "retention": "big-year",
        "segment": "543",
        "last4": "",
        "plaintextValue": "4111111111111111"}],
     "id": 1,
     "method": "encrypt"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "token":"Jyhj3GfKZv0F7Vb1111",
        "elapsedTime":"0.0117"},
    "error":null}

encrypt (with an existing token)

Encrypt a plaintext value and store it using the passed-in token identifier. This allows you to migrate tokens you already have to the AuricVault® service and maintain the same token identifier in your databases.

Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "utcTimestamp": "1401309530",
        "retention": "big-year",
        "segment": "543",
        "token": "SBLIQRPSCBNYQRBFYMH",
        "plaintextValue": "4111111111111111"}],
     "id": 1,
     "method": "encrypt"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "token":"SBLIQRPSCBNYQRBFYMH",
        "elapsedTime":"0.0115"},
    "error":null}

reencrypt

Submit new plaintext data to be encrypted for an existing token.

Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "utcTimestamp": "1401309530",
        "retention": "big-year",
        "segment": "543",
        "token": "JVY1hlZ9qQ0UsJf1111"
        "plaintextValue": "4111111111111111"}],
     "id": 1,
     "method": "reencrypt"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "elapsedTime":"0.0117"},
    "error":null}

decrypt

Retrieve the decrypted plaintext.

Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "token": "DAiO2uurxd0GllMrld!",
        "utcTimestamp": "1401310050"}],
     "id": 1,
     "method": "decrypt"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "plaintextValue":"Sample Unicode: Héllø World!",
        "elapsedTime":"0.0106"},
     "error":null}

session_encrypt

The session_encrypt method is similar to the encrypt method. The only difference is the use of a sessionId vs. configurationId, mtid, retention and segment parameters. This method is designed to be called from a browser-based JavaScript AJAX call. Refer to the get_session call for details.

As with the standard encrypt call, the last4 parameter is optional.

Sample Request
    {"params": [{
        "last4": "",
        "sessionId": "5Bc4zG5u3ABBTAlr0",
        "utcTimestamp": "1401310376",
        "plaintextValue": "4111111111111111"}],
     "id": 1,
     "method": "session_encrypt"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "token":"6Q1LzVTCOk07TA1111",
        "elapsedTime":"0.0125"},
     "error":null}

session_decrypt

This method is the browser-side equivalent of the standard decrypt method. The only difference is the use of a sessionId vs. configurationId, mtid, retention and segment parameters. This method is designed to be called from a browser-based JavaScript AJAX call. Refer to the get_session call for details.

Sample Request
    {"params": [{
        "sessionId": "SLdqjhGPTc0qvXIms",
        "token": "e2KuSQXMyT0T6Gtrld!",
        "utcTimestamp": "1401310860"}],
     "id": 1,
     "method": "session_decrypt"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "plaintextValue":"4111111111111111",
        "elapsedTime":"0.0075"},
     "error":null}

Token Management Methods

  • delete-token

  • token-info

  • touch-token

delete_token

Delete previously-stored tokens.

Note
Deleting an already-deleted token returns a "Token not found…​" error (VLT-176). The reason this is an error is that the token might be there, but you might not have access to the segment within which the token is stored.

The service returns the same message for both a not-found token and a token that exists, but to which you do not have permission. This ensures the existence of the token does not leakto a third party that should not have access to the data.

Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "token": "e7c469cf-45fa-4d29-9b36-054cabe40e67",
        "utcTimestamp": "1401311686"}],
     "id": 1,
     "method": "delete_token"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "elapsedTime":"0.0125"},
     "error":null}

token_info

Retrieve information about a token. Useful for finding out if a token exists in the system without needing to retrieve the actual data.

An isVaultEncrypted return value of "t" indicates the information associated with this token is encrypted by the AuricVault® service.

Requesting information on a non-existant token returns in an error message and a lastActionSucceeded value of 0 (zero).

Note
token_info does not update the token’s last accessed value.
Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "token": "Uvsr6MLnPb0G5E7rypt",
        "utcTimestamp": "1401311914"}],
     "id": 1,
     "method": "token_info"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "elapsedTime":"0.0059",
        "tokenExists":"t",
        "tokenCreatedDate":"2014-05-28 11:22:55-0400",
        "lastAccessedDate":"2014-05-29 21:22:55-0400",
        "segment":"543"
        "retention":"big-year",
        "isVaultEncrypted":"t"},
     "error":null}

touch_token

The touch_token method is similar to the token_info method except that it does update the token’s last accessed date time stamp. This method is used to reset the start of the retention period to the current date/time.

Touching a non-existing token results in an error message and lastActionSucceeded of 0.

Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "token": "e5f8ab2a-c8b5-4ab8-acbd-d2501a30b617",
        "utcTimestamp": "1401312848"}],
     "id": 1, "method":
     "touch_token"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "elapsedTime":"0.0045",
        "tokenExists":"t",
        "tokenCreatedDate":"2014-05-28 11:22:55-0400",
        "lastAccessedDate":"2014-05-29 21:32:55-0400",
        "segment":"543"
        "retention":"big-year",
        "isVaultEncrypted":"f"},
     "error":null}

Locally-Managed Encryption Methods

These methods are used to store and retrieve data that is encrypted/decrypted on your local server. All encryption and key management services must be maintained locally to meet your security policy requirements.

Auric has no knowledge of your plaintext and cannot decrypt under any circumstances.

  • store-token

  • generate-token

  • retrieve-token

  • update-token

Note
These methods are provided for integration with some Auric legacy products and services. Auric recommends not using locally-managed encryption unless you are integrating with a legacy system.

store_token

The store_token method allows you to create and store your own tokens. Use when you need to maintain token values in a specific format.

Sample Request
    {"params": [
        {"mtid": "123",
         "configurationId": "abc",
         "utcTimestamp": "1401306940",
         "retention": "big-year",
         "segment": "543",
         "encryptedValue": "38xljsAlkwxo3x==",
         "token": "90809171-7740-4a19-a87f-4b6cb6181871"}],
     "id": 1,
     "method": "store_token"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "elapsedTime":"0.0102"},
     "error":null}

generate_token

The generate_token method requires that only the encryptedValue be provided. The response contains the token randomly generated by the service.

Sample Request
    {"params": [
        {"mtid": "123",
         "last4": "1111",
         "configurationId": "abc",
         "retention": "big-year",
         "segment": "543",
         "encryptedValue": "38xljsAlkwxo3x==",
         "utcTimestamp": "1401308418"}],
     "id": 1,
     "method": "generate_token"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "token":"UZR15fciED0bPr51111",
        "elapsedTime":"0.0091"},
     "error":null}

retrieve_token

Retrieve the stored encrypted data.

Sample Request
    {"params": [
        {"mtid": "123",
         "configurationId": "abc",
         "token": "0a6cede7-c833-4f38-8eea-bf729f13a05d",
         "utcTimestamp": "1401309061"}],
     "id": 1,
     "method": "retrieve_token"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "encryptedValue":"8E2jej....b33",
        "elapsedTime":"0.0055"},
     "error":null}

update_token

Update the encrypted data for a previously stored token.

Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "retention": "big-year",
        "segment": "543",
        "utcTimestamp": "1401414119",
        "encryptedValue": "xxxENCRYPTEDVALUExxx",
        "token": "JVY1hlZ9qQ0UsJf1111"}],
     "id": 1,
     "method": "update_token"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "elapsedTime":"0.0120"},
     "error":null}

Session Management Methods

The vault-managed encryption management supports browser-side tokenization. This allows sensitive data to be tokenized/encrypted directly from your browser without ever touching your server.

Before using any of the session methods, your server first obtains a session identifier from the service and then passes this session identifier to the specific session call.

The API call for doing this is:

  • get_session

The returned sessionId can only be used once and must be used within ten (10) minutes.

get_session

The session-encrypt and session-decrypt methods designed to run in the browser require that the server first obtain a sessionId. This sessionId is then included in the HTML page presented to the user. The sessionId is used by the browser-side methods in lieu of explicit credentials. This allows API access from the browser without exposing credentials.

Note
The sessionId can only be used once and must be used within ten (10) minutes of being created.
Sample Request
    {"params": [{
        "mtid": "123",
        "configurationId": "abc",
        "utcTimestamp": "1401313120",
        "retention": "big-year",
        "segment": "543"}],
     "id": 1,
     "method": "get_session"}
Sample Response
    {"id":1,
     "result":{
        "version":"2.0",
        "lastActionSucceeded":1,
        "sessionId":"TsclZ0cU27g2poWLr",
        "elapsedTime":"0.0078"},
     "error":null}

Payment Processing Simplified®

Payments Passthrough Service

Note
The Payments Passthrough feature is new service currently under development and will be released formally in 2018. We’re working with selected clients to implement a consistent programming API to specific payment processors of interest. Please contact us as sales@AuricSystems.com if you are looking to use the Payments Passthrough functionality.

The AuricVault® Payments Passthrough service converts a generic API into payment processor specific transactions while providing you with access to detailed payment processor response information.

A generic API provides you with a consistent interface into multiple payment processors. Responses are standardized across all payment processors. Auric’s Generic+Plus API returns processor-specific information in addition to the standardized responses. This gives you access to the full set of processor responses if you need them. This capability is vital for businesses looking to take full advantage of services provided by each payment processor.

Another unique feature of the Generic+Plus API is the ability to see what data was sent to/received from the payment processor. This data (properly sanitized for PCI compliance before being returned) simplifies support discussions you may have directly with your payment processor. No other gateway allows you to track the actual conversation with the payment processor.

This Generic+Plus philosophy is an outgrowth of our 20 years of building payment applications and services.

Supported Payment Processors

The AuricVault® Payments Passthrough service supports the following payment processors:

  • Braintree Payments

  • Chase Paymentech Orbital Gateway (Salem)

  • Merchant e-Solutions

  • Transfirst Transaction Express

  • Tsys Multipass

  • Vantiv® (formerly Litle & Co.)

Payments Passthrough API

JSON-RPC

The AuricVault® Payments Passthrough API uses a JSON-RPC structure similar to the Token interface. Refer to the Custom HTTP Headers section for generating X-VAULT-HMAC and X-VAULT-TRACE-UID headers.

The X-VAULT-TRACE-UID header value submitted with the request is returned in the traceUid response code.

Standard Request Fields

The following tables describe the standard AuricVault® request field names for the payments API. Not all processors support all fields. Please refer to the specific section for your payment processor.

Table 1. Processor Credentials
Field Description

processorId

Which payment processor to use (see processorId field table).

processorUserId

UserId or username.

processorPassword

Processor password.

processorAccessKey

Processor access key.

processorDivision

Division when multiple divisions supported.

Note
The service passes through your payment processor merchant account credentials.
Table 2. Common Fields
Field Description

action

(see action table)

affiliate

Merchant affiliate.

amount

Decimal amount for transaction.

authorizationCode

For settlement

auvToken

AuricVault® token.

commerceIndicator

(see ECI table.)

currency

Three-character currency code (see ISO Currency Codes table).

cvv2

Card security code.

expirationDate

YYYY-MM.

mop

(see Method of Payment table)

processorToken

Processor-specific Token.

processorTransactionId

Usually returned by an Auth or Sale transaction.

requestPartialAuthorization

Allow partial auth or sale authorization.

requestProcessorTransaction

true/false. Return processor transaction.

Table 3. Bill To Fields
Field

billToAddress_1

billToAddress_2

billToAddress_3

billToCity

billToCompany

billToCountry

billToEmail

billtoFax

billToFirstName

billToMiddleInitial

billToLastName

billToPhoneNumber

billToPostalCode

billToStateProvince

Table 4. Ship To Fields
Field Description

shippingMethod

(see shipping method table)

shipToAddress_1

shipToAddress_2

shipToAddress_3

shipToCity

shipToCountry

shiptoFax

shipToFirstName

shipToLastName

shipToPhoneNumber

shipToPostalCode

shipToStateProvince

Table 5. Order-Related Fields
Field Description

clientReferenceNumber

invoiceNumber

Invoice being paid.

orderNumber

productSku

recurringPaymentCount

recurringPaymentNumber

taxAmount

Portion of amount that is tax.

Table 6. Enhanced Data Fields
Field Hospitality and car rental data.

enhDailyRate

enhIndustryCode

enhIsNoShow

enhNameOfPlace

enhRequestorName

enhStatementEndDate

enhStatementStartDate

Table 7. 3D Secure Fields
Field Description

mcssAuthData

ucafCollectionIndicator

vbvCavv

vbvId

Table 8. Additional Fields
Field Description

campaign

TODO Vantiv description

customerBrowserType

customerHostname

customerId

Merchant identifier for customer.

customerIp

processorReportGroup

Declare reporting group for this transaction.

reversalReason

TODO Vantiv reversal Reason

Table 9. Dynamic Merchant Data Fields
Field Description

merchantCategoryCode

merchantCity

merchantEmail

merchantName

merchantPhone

merchantPostalCode

merchantProfileId

merchantState

merchantUrl

Standard Request Field Values

Table 10. processorId field
Value Description

braintree

Braintree Payments

cps-orbital

Chase Paymentech Solutions Orbital Gateway/Salem

mes-trident

Merchant e-Solutions/Trident Gateway

tsys-transit

Tsys/Transit Multipass Gateway

vantivLitle

Vantiv (formerly Litle & Co.)

Table 11. action field
Value Description

auth

authorize only (pre-auth)

credit

return funds using token

refund

with transaction ID or account number

sale

auth and settle

capture

capture all funds for settlement

multi-capture

capture some of the funds for settlement

offline

capture voice authorized transaction

verify

verify card account info without auth

void_auth

void authorization using transaction id

void_capture

void capture using transaction id

void_refund

void refund using transaction id

void_sale

void sale using transaction id

void_credit

void credit using transaction id

tokenize

generate processor-specific token

Table 12. mop field
Value Method of Payment

AX

American Express

DI

Discover

JC

JCB

MC

MasterCard

VI

Visa

Table 13. commerceIndicator field
Value Description

3dsAttempted

Attempted 3DSecure, but not completed.

3dsAuthenticated

3DSecure authentication successful.

ecommerce

E-commerce transaction.

installment

Installment.

mailorder

Mail order.

recurring

Recurring (i.e. monthly vs. 3 payments)

retail

Manually keyed.

telephone

Telephone order.

Table 14. shippingMethod field

Value

same_day

overnight

priority

ground

electronic

Standard Response Fields

Table 15. Standard response fields.
Field Description

responseCode

Generalized Response Code

responseText

Generalized Response Text

authorizationCode

Auth code from the Payment Processor

authorizationDateTime

Authorization date/time

avsResponse

Generalized Address Verification response

cvv2Response

Generalized card security code response

cardType

Card type (if requested)

partialAuthAmount

Amount actually authorized.

processorToken

Processor-specific token.

processorTransactionId

Processor transaction ID.

processorAvsResponse

AVS Response from Processor

processorCvv2Response

Card security code response from Processor.

processorResponseCode

Processor response code.

processorResponseText

Processor response text.

elapsedProcessorTime

Elapsed time spent at payment processor.

toProcessor

Sanitized Transaction sent to payment processor.

fromProcessor

Sanitized Transaction received from payment processor.

TODO
  • Document response fields specifics.

Braintree Payments

Notes

  • The processorTransactionId is used to:

    • settle authorized transactions

    • refund sales

    • void authorizations

  • expirationDate is mapped into expiration_year and expiration_month.

  • billToFirstName and billToLastName are mapped into cardholder_name.

  • Braintree API has same fields in different sections. For example, street_address occurs in billing and shipping.

  • Braintree returns avs_error_code, avs_postal_code, and avs_street_address response codes. The AuricVault® service maps these into the standardized response.

The X-VAULT-HMAC HTTP header is required for all calls.

Field Maps

Table 16. Supported request fields.
AuricVault® Field Name Braintree Field Name

action

<selects Braintree API call>

amount

amount

billToAddress_1

street_address

billToAddress_2

extended_address

billToCity

locality

billToCompany

company

billToCountry

country_code_alpha3

billToEmail

email

billToFax

fax

billToFirstName

cardholder_name

billToLastName

cardholder_name

billToPhoneNumber

phone

billToPostalCode

postal_code

billToStateProvince

region

cvv2

cvv

expirationDate

expiration_year and expiration_month

invoiceNumber

invoice_number (custom field)

merchantName

name

merchantPhone

phone

merchantUrl

url

orderNumber

order_id

processorDivision

merchant_id

processorSubdivision

merchant_account_id

processorPublicKey

public_key

processorPrivateKey

private_key

processorToken

token

processorTransactionId

id

shipToAddress_1

street_address

shipToAddress_2

extended_address

shipToCity

locality

shipToCountry

country_code_alpha3

shipToCompany

company

shipToFirstName

first_name

shipToLastName

last_name

shipToPostalCode

postal_code

shipToStateProvince

region

taxAmount

tax_amount

taxExempt

tax_exempt

Table 17. Supported response fields.
Braintree Field Name AuricVault® Field Name

authorizationCode

processor_authorization_code

authorizationDateTime

<generated by AuricVault® service>

avsResponse

<standardized>

ctiAffluentCard

<unmapped>

ctiCommercialCard

commercial

ctiDurbinExemptionCard

durbin_regulated

ctiHealthcareCard

healthcare

ctiIssuingCountry

country_of_issuance

ctiLevel3EligibleCard

<unmapped>

ctiPayrollCard

payroll

ctiPinlessDebitCard

debit

ctiPrepaidCard

prepaid

ctiSignatureDebitCard

<unmapped>

cvv2Response

<standardized>

extendedAvs

<unmapped>

processorAvsResponse

error:street:postal

processorCvv2Response

cvv

processorResponseCode

processor_response_code

processorResponseText

processor_response_text

processorToken

token

processorTransactionId

id

responseCode

<standardized>

responseText

<standardized>

traceUid

<unmapped>

Processor-Specific Information

Table 18. action values
Accepted Actions Braintree Action

sale

sale (submit_for_settlement = True)

auth

sale (submit_for_settlement = False)

reauth

<not available>

offline

<not available>

void auth

void

capture

submit_for_settlement

multi-capture

submit_for_settlement

refund

refund

credit

credit

tokenize

Not Implemented

delete token

Not Implemented

verify

Not Implemented

Sample Transactions

Authorization

Request
    {"transaction": {
    },
    "configurationId": "ABC123",
    "id": 228,
    "method": "process_payment",
    "mtid": "1111xxxx",
    "utcTimestamp": "1424798417"
    }
----
Response
    {"response":{
    },
    "elapsedTime":"1.0896",
    "error":null,"traceUid":"817c8c59-b450-4fce-827e-c0bd22b4134a",
    "id":228,
    "version":"2.0"
    }
----

Settlement

Request
    {"transaction": {
        },
    "configurationId": "TestConfiguration",
    "id": 233,
    "method": "process_payment",
    "mtid": "12345678",
    "utcTimestamp": "1424798423"
    }
----
Response
    {"response":{
        },
    "elapsedTime":"0.3728",
    "error":null,
    "id":233,
    "traceUid":"edee4809-c01b-4802-bfef-2b8822c5c197",
    "version":"2.0"
    }
----

Sale

Request
    {"transaction": {
        },
     "configurationId": "ABC123",
     "method": "process_payment",
     "mtid": "1111xxxx",
     "utcTimestamp": "1424798394",
     "id": 118
    }
Response
    {"response":{
        },
    "elapsedTime":"1.0397",
    "error":null,
    "id":118,
    "traceUid":"11bf7608-b693-4b12-be5c-9d1dd60083bc",
    "version":"2.0"
    }

Merchant e-Solutions: Trident

Notes

  • The processorTransactionId is used to:

    • capture authorized transactions

    • refund sales

    • void authorizations

  • MES tokens are the transaction ID.

  • The 'enh' fields are for hotel and car rentals.

TODO
  • Document length of transaction ID.

Field Maps

Table 19. Supported request fields.
AuricVault® Field Name Merchant e-Solutions Field Name

account

card_number

action

transaction_type

amount

transaction_amount

authorizationCode

auth_code

billToAddress_1

cardholder_street_address

billToCountry

cardholder_country_code

billToEmail

cardholder_email

billToFirstName

cardholder_first_name

billToLastName

cardholder_last_name

billToPhoneNumber

cardholder_phone

billToPostalCode

cardholder_zip

clientReferenceNumber

client_reference_number

commerceIndicator

moto_ecommerce_ind

currency

currency_code

customerBrowserType

http_browser_type

customerHostname

cust_host_name

customerIp

ip_address

cvv2

cvv2

enhDailyRate

rate_daily

enhIndustryCode

industry_code

enhIsNoShow

no_show_ind

enhNameOfPlace

name_of_place

enhRequesterName

requester_name

enhStatementEndDate

statement_end_date

enhStatementStartDate

statement_start_date

expirationDate

card_exp_date

invoiceNumber

invoice_number

mcssAuthData

ucaf_auth_data

merchantCategoryCode

merchant_category_code

merchantEmail

dm_contact_info

merchantName

merchant_name

merchantPhone

merchant_phone

merchantUrl

dm_contact_info

processorAccessKey

profile_key

processorTransactionId

transaction_id

processorUserId

profile_id

productSku

prod_sku

recurringPaymentCount

recurring_pmt_count

recurringPaymentNumber

recurring_pmt_num

reqCardType

rctl_commercial_card

reqExtendedAvs

rctl_extended_avs

reqPartialAuth

rctl_partial_auth

shippingMethod

ship_method

shipToAddress_1

ship_to_address

shipToCountry

dest_country_code

shipToFirstName

ship_to_first_name

shipToLastName

ship_to_last_name

shipToPhoneNumber

ship_to_phone

shipToPostalCode

ship_to_zip

taxAmount

tax_amount

token

card_id

ucafCollectionIndicator

ucaf_collection_ind

vbvCavv

cavv

vbvId

xid

Table 20. Supported response fields.
Merchant e-Solutions Field Name AuricVault® Field Name

auth_code

authorizationCode

auth_response_text

processorResponseText

avs_result

processorAvsResponse

card_id

token

commercial_card

cardType

cvv2_result

processorCvv2Response

error_code

processorResponseCode

partial_auth

partialAuthAmount

transaction_id

processorTransactionId

Processor-Specific Information

Table 21. mop field
mop Method of Payment

AX

American Express

DI

Discover

JC

JCB

MC

MasterCard

VI

Visa

Table 22. action field
Accepted Actions Merchant e-Solutions Action

sale

D

auth

P

reauth

J

offline

O

void auth

V

capture

S

multi-capture

S

refund

U

credit

C

tokenize

T

delete token

X

verify

A

Sample Transactions

Authorization

Request
    {"transaction": {
        "action": "auth",
        "amount": "100.00",
        "auvToken": "JpBHkyFJId0cNYN3010",
        "currency": "USD",
        "cvv2": "123",
        "expirationDate": "2020-12",
        "invoiceNumber": "Inv42"
        "processorAccessKey": "gvQzgKXOTEoDzpzJzROrQQzoKLaEqxjf",
        "processorId": "mes-trident",
        "processorUserId": "94100008043900000016",
        "uniqueTrackingId": "Unique42",
    },
    "configurationId": "ABC123",
    "id": 228,
    "method": "process_payment",
    "mtid": "1111xxxx",
    "utcTimestamp": "1424798417"
    }
Response
    {"response":{
        "authorizationCode":"T2117H",
        "avsResponse":"0",
        "cvv2Response":"M",
        "elapsedProcessorTime":"1.065s"
        "processorAvsResponse":"0",
        "processorCvv2Response":"M",
        "processorResponseCode":"000",
        "processorResponseText":"Approval T2117H",
        "processorTransactionId":"6590af62ce633de3bd2272010d69d7bd",
        "responseCode":"100",
        "responseText":"Approved",
    },
    "elapsedTime":"1.0896",
    "error":null,"traceUid":"817c8c59-b450-4fce-827e-c0bd22b4134a",
    "id":228,
    "version":"2.0"
    }

Capture

Request
    {"transaction": {
        "action": "capture",
        "amount": "100.00",
        "auvToken": "JpBHkyFJId0cNYN3010",
        "debugRawData": "true",
        "processorAccessKey": "gvQzgKXOTEoDzpzJzROrQQzoKLaEqxjf",
        "processorId": "mes-trident",
        "processorTransactionId": "6590af62ce633de3bd2272010d69d7bd",
        "processorUserId": "94100008043900000016",
        },
    "configurationId": "TestConfiguration",
    "id": 233,
    "method": "process_payment",
    "mtid": "12345678",
    "utcTimestamp": "1424798423"
    }
Response
    {"response":{
        "elapsedProcessorTime":"0.369s"
        "processorResponseCode":"000",
        "processorResponseText":"Settle Request Accepted",
        "processorTransactionId":"6590af62ce633de3bd2272010d69d7bd",
        "responseCode":"100",
        "responseText":"Approved",
        },
    "elapsedTime":"0.3728",
    "error":null,
    "id":233,
    "traceUid":"edee4809-c01b-4802-bfef-2b8822c5c197",
    "version":"2.0"
    }

Sale

Request
    {"transaction": {
        "action": "sale"
        "amount": "100.00",
        "billToAddress_1": "85 Main Street",
        "billToCity": "Eureka",
        "billToCountry": "USA",
        "billToFirstName": "Susan",
        "billToLastName": "Jones",
        "billToPostalCode": "03458",
        "billToStateProvince": "NH",
        "currency": "USD",
        "expirationDate": "2020-12",
        "processorAccessKey": "gvQzgKXOTEoDzpzJzROrQQzoKLaEqxjf",
        "processorId": "mes-trident",
        "processorToken": "fbe41db71c9a3a1eadbd771b8871bcaf",
        "processorUserId": "94100008043900000016",
        "uniqueTrackingId": "TrackingId",
        },
     "configurationId": "ABC123",
     "method": "process_payment",
     "mtid": "1111xxxx",
     "utcTimestamp": "1424798394",
     "id": 118
    }
Response
    {"response":{
        "authorizationCode":"T20942",
        "avsResponse":"N",
        "elapsedProcessorTime":"1.038s"
        "processorAvsResponse":"N",
        "processorResponseCode":"000",
        "processorResponseText":"No Match",
        "processorTransactionId":"cf77e0073b06353ca1b06fec5a353351",
        "responseCode":"100",
        "responseText":"Approved",
        },
    "elapsedTime":"1.0397",
    "error":null,
    "id":118,
    "traceUid":"11bf7608-b693-4b12-be5c-9d1dd60083bc",
    "version":"2.0"
    }

Vantiv® (Litle&Co.)

Note
Preliminary documentation.

The processorTransactionId is used to:

  • capture authorized transactions

  • refund sales

  • void transactions

Field Maps

Table 23. Request field map.
AuricVault® Field Name Vantiv® Field Name

account

card:number

action

action

affiliate

merchantData:affiliate

amount

amount

authorizationCode

authInformation:authCode

billToAddress_1

billToAddress:addressLine1

billToAddress_2

billToAddress:addressLine2

billToAddress_3

billToAddress:addressLine3

billToCity

billToAddress:city

billToCompany

billToAddress:companyName

billToCountry

billToAddress:country

billToEmail

billToAddress:email

billToFirstName

billToAddress:firstName

billToLastName

billToAddress:lastName

billToMiddleInitial

billToAddress:middleInitial

billToPhoneNumber

billToAddress:phone

billToPostalCode

billToAddress:zip

billToStateProvince

billToAddress:state

campaign

campaign

clientReferenceNumber

enhancedData:customerReference

commerceIndicator

orderSource

customerId

customerId

customerIp

cardholderAuthentication:customerIpAddress

cvv2

card:cardValidationNumber

expirationDate

card:expDate

invoiceNumber

invoiceReferenceNumber

mop

card:type

orderNumber

orderId

processorDivision

merchantId

processorId

authentication:user

processorPassword

authentication:password

processorReportGroup

reportGroup

processorToken

litleToken

processorTransactionId

litleTxnId

processorUserId

authentication:user

requestPartialAuthorization

allowPartialAuth

requestProcessorTransaction

requestProcessorTransaction

reversalReason

authReversal:actionReason

shipToAddress_1

shipToAddress:addressLine1

shipToAddress_2

shipToAddress:addressLine2

shipToAddress_3

shipToAddress:addressLine3

shipToCity

shipToAddress:city

shipToCountry

shipToAddress:country

shipToEmail

shipToAddress:email

shipToPhoneNumber

shipToAddress:phone

shipToPostalCode

shipToAddress:zip

shipToStateProvince

shipToAddress:state

Table 24. Response field map.
Vantiv® Field Name AuricVault® Field Name

auth_code

authorizationCode

auth_response_text

processorResponseText

TBD

processorAvsResponse

TBD

processorCvv2Response

TBD

processorResponseCode

TBD

partialAuthAmount

TBD

processorResponseCode

TBD

processorResponseText

litleToken

processorTransactionId

litleTxnId

processorTransactionId

Processor-Specific Information

Table 25. Supported methods of payment (mop).
mop Method of Payment

AX

American Express

DI

Discover

JC

JCB

MC

MasterCard

VI

Visa

Table 26. Supported actions.
AuricVault® action Vantiv® Action

sale

sale

auth

authorization

offline

captureGivenAuth

capture

capture (full amount)

multi-capture

capture (requested amount)

refund

credit

credit

credit

tokenize

create token

verify

verify

void auth

authReversal

void capture

void

void refund

void

void sale

void

void credit

void

void force capture

void

Note
The capture action captures the entire authorized amount. Any passed-in amount is ignored. The multi-capture action captures the requested amount, up to the full amount originally authorized.
Table 27. Supported card type indicator responses.
Vantiv® Field Name AuricVault® Field Name

commercial

ctiCommercialCard

durbin_regulated

ctiDurbinExemptionCard

healthcare

ctiHealthcareCard

country_of_issuance

ctiIssuingCountry

payroll

ctiPayrollCard

debit

ctiPinlessDebitCard

prepaid

ctiPrepaidCard

Sample Transactions

Authorization

Request
    {
        "id": 37,
        "method": "process_payment",
        "configurationId": "xyz",
        "mtid": "123",
        "utcTimestamp": "1477321809",
        "transaction": {
            "action": "auth",
            "amount": "101",
            "auvToken": "jQiI2m0Ii10ZAHW0009",
            "billToAddress_1": "1 Main St.",
            "billToCity": "Burlington",
            "billToCountry": "US",
            "billToFirstName": "John & Mary",
            "billToLastName": "Smith",
            "billToPostalCode": "01803-3747",
            "billToStateProvince": "MA",
            "commerceIndicator": "ecommerce",
            "currency": "USD",
            "cvv2": "349",
            "expirationDate": "2021-01",
            "mop": "VI",
            "orderNumber": "auth-sample",
            "processorDivision": "7103111",
            "processorId": "vantivLitle",
            "processorPassword": "certzg3y",
            "processorUserId": "AURIC",
            "requestProcessorTransaction": "true"
        }
    }
Response:
    {
        "error": null,
        "elapsedTime": "2.2487",
        "id": 37,
        "version": "2.0",
        "traceUid": "Trace5X8hen1",
        "response": {
            "processorCvv2Response": "M",
            "avsResponse": "M01",
            "processorToken": "1111000274130009",
            "processorAvsResponse": "01",
            "cvv2Response": "M",
            "responseText": "Approved",
            "authorizationCode": "11111",
            "authorizationDateTime": "2016-10-24T15:10:11",
            "processorResponseCode": "000",
            "processorTransactionId": "82919144492728757",
            "processorResponseText": "Approved",
            "responseCode": "100",
            "elapsedProcessorTime": "2.1969"
        }
    }

Capture

Capture entire amount originally authorized.

Request
    {
        "id": 41,
        "method": "process_payment",
        "mtid": "12345678",
        "utcTimestamp": "1477321811",
        "configurationId": "TestConfiguration",
        "transaction": {
            "processorUserId": "AURIC",
            "processorPassword": "certzg3y",
            "requestProcessorTransaction": "true",
            "processorDivision": "7103111",
            "processorTransactionId": "82919144492728757",
            "action": "capture",
            "processorId": "vantivLitle"
        }
    }
Response
    {
        "error": null,
        "elapsedTime": "0.2883",
        "id": 41,
        "version": "2.0",
        "traceUid": "TraceR6CmlU1",
        "response": {
            "processorTransactionId": "82919144492728864",
            "processorResponseText": "Approved",
            "responseCode": "100",
            "responseText": "Approved",
            "elapsedProcessorTime": "0.2580",
            "processorResponseCode": "000"
        }
    }

Multi-Capture

Capture part of amount originally authorized. Amount can be up to full original amount authorized.

Request
    {
        "id": 41,
        "method": "process_payment",
        "mtid": "12345678",
        "utcTimestamp": "1477321811",
        "configurationId": "TestConfiguration",
        "transaction": {
            "processorUserId": "AURIC",
            "processorPassword": "certzg3y",
            "requestProcessorTransaction": "true",
            "processorDivision": "7103111",
            "processorTransactionId": "82919144492728757",
            "action": "multi-capture",
            "amount": "10.00",
            "processorId": "vantivLitle"
        }
    }
Response
    {
        "error": null,
        "elapsedTime": "0.2883",
        "id": 41,
        "version": "2.0",
        "traceUid": "TraceR6CmlU1",
        "response": {
            "processorTransactionId": "82919144492728864",
            "processorResponseText": "Approved",
            "responseCode": "100",
            "responseText": "Approved",
            "elapsedProcessorTime": "0.2580",
            "processorResponseCode": "000"
        }
    }

Refund

Refund a sale or capture transaction. If the amount field is blank, the entire transaction is refunded. If the request includes the amount field then only that amount is refunded. Refunds require a processorTransactionId from a sale or capture transaction.

Request
    {
        "method": "process_payment",
        "id": 64,
        "transaction": {
            "amount": "100.22",
            "processorId": "vantivLitle",
            "processorUserId": "AURIC",
            "processorPassword": "certzg3y",
            "action": "refund",
            "requestProcessorTransaction": "true",
            "processorTransactionId": "82919144548435712",
            "processorDivision": "7103111"
        },
        "utcTimestamp": "1477322497",
        "mtid": "12345678",
        "configurationId": "TestConfiguration"
    }
Response
    {
        "error": null,
        "id": 64,
        "traceUid": "TraceiKhyhh1",
        "elapsedTime": "0.2644",
        "version": "2.0",
        "response": {
            "responseCode": "100",
            "processorResponseText": "Approved",
            "processorResponseCode": "000",
            "elapsedProcessorTime": "0.2399",
            "responseText": "Approved",
            "processorTransactionId": "82919144548435753"
        }
    }

Void

Since different payment processors have different void mappings, the service requires each type of transaction be voided by type. Refer to your Vantiv® representative regarding time limits on any of these transactions.

Acceptable void transactions are:

  • void auth

  • void sale

  • void refund

  • void capture

  • void credit

  • void force capture

Request
    {
        "method": "process_payment",
        "id": 68,
        "transaction": {
            "amount": "100",
            "processorId": "vantivLitle",
            "processorUserId": "AURIC",
            "processorPassword": "certzg3y",
            "action": "void refund",
            "requestProcessorTransaction": "true",
            "processorTransactionId": "82919144548435753",
            "processorDivision": "7103111"
        },
        "utcTimestamp": "1477322497",
        "mtid": "12345678",
        "configurationId": "TestConfiguration"
    }
Response.
    {
        "error": null,
        "id": 68,
        "traceUid": "TraceIruABP1",
        "elapsedTime": "0.3824",
        "version": "2.0",
        "response": {
            "responseCode": "100",
            "processorResponseText": "Approved",
            "processorResponseCode": "000",
            "elapsedProcessorTime": "0.3580",
            "responseText": "Approved",
            "processorTransactionId": "82919144548435829"
        }
    }

Void Authorization

Also called Authorization Reversal. Send only the processorTransactionId without an amount to void the entire authorization.

Request.
    {
        "utcTimestamp": "1477324018",
        "configurationId": "TestConfiguration",
        "method": "process_payment",
        "mtid": "12345678",
        "id": 78,
        "transaction": {
            "requestProcessorTransaction": "true",
            "processorUserId": "AURIC",
            "processorPassword": "certzg3y",
            "processorTransactionId": "82919144668120243",
            "action": "void auth",
            "processorDivision": "7103111",
            "processorId": "vantivLitle"
        }
    }
Response
    {
        "response": {
            "processorResponseText": "Approved",
            "responseText": "Approved",
            "elapsedProcessorTime": "0.8331",
            "processorTransactionId": "82919144672134461",
            "responseCode": "100",
            "processorResponseCode": "000"
        },
        "elapsedTime": "0.8567",
        "traceUid": "TraceQxlSOK1",
        "version": "2.0",
        "id": 78,
        "error": null
    }

Partial Void

Also called Partial Authorization Reversal. Voids (reverses) the amount included in the transaction.

Request
    {
        "transaction": {
            "processorPassword": "certzg3y",
            "processorTransactionId": "82919144692778255",
            "processorUserId": "AURIC",
            "processorId": "vantivLitle",
            "amount": "12.00",
            "requestProcessorTransaction": "true",
            "processorDivision": "7103111",
            "action": "void auth"
        },
        "configurationId": "TestConfiguration",
        "mtid": "12345678",
        "id": 88,
        "utcTimestamp": "1477324322",
        "method": "process_payment"
    }
Response
    {
        "error": null,
        "response": {
            "processorTransactionId": "82919144697202582",
            "elapsedProcessorTime": "2.0680",
            "processorResponseText": "Approved",
            "responseCode": "100",
            "responseText": "Approved",
            "processorResponseCode": "000"
        },
        "version": "2.0",
        "id": 88,
        "traceUid": "TraceLytbLO1",
        "elapsedTime": "2.0908"
    }

Verify Only

Request
    {
        "mtid": "12345678",
        "configurationId": "TestConfiguration",
        "method": "process_payment",
        "id": 94,
        "utcTimestamp": "1477326370",
        "transaction": {
            "processorPassword": "certzg3y",
            "currency": "USD",
            "cvv2": "349",
            "processorUserId": "AURIC",
            "auvToken": "f2jSkxXZBi0EiFj0009",
            "orderNumber": "verify",
            "expirationDate": "2021-01",
            "processorId": "vantivLitle",
            "processorDivision": "7103111",
            "billToCity": "Burlington",
            "billToAddress_1": "1 Main St.",
            "billToStateProvince": "MA",
            "billToCountry": "US",
            "billToPostalCode": "01803-3747",
            "billToLastName": "Smith",
            "action": "verify",
            "mop": "VI",
            "billToFirstName": "John & Mary",
            "commerceIndicator": "ecommerce",
            "requestProcessorTransaction": "true",
            "amount": "101"
        }
    }
Response
    {
        "error": null,
        "elapsedTime": "1.6844",
        "id": 94,
        "traceUid": "TraceWfRK1v1",
        "version": "2.0",
        "response": {
            "cvv2Response": "M",
            "processorCvv2Response": "M",
            "elapsedProcessorTime": "1.6329",
            "processorTransactionId": "82919144865875060",
            "authorizationCode": "11111",
            "processorResponseCode": "000",
            "processorAvsResponse": "01",
            "authorizationDateTime": "2016-10-24T16:26:12",
            "responseText": "Approved",
            "processorResponseText": "Approved",
            "processorToken": "1111000274130009",
            "avsResponse": "M01",
            "responseCode": "100"
        }
    }

Token Swap

Request.
    {
        "mtid": "12345678",
        "configurationId": "TestConfiguration",
        "method": "process_payment",
        "id": 100,
        "utcTimestamp": "1477326372",
        "transaction": {
            "processorPassword": "certzg3y",
            "currency": "USD",
            "cvv2": "349",
            "processorUserId": "AURIC",
            "auvToken": "mFVnZVihW00O1fU0009",
            "orderNumber": "tokenize",
            "expirationDate": "2021-01",
            "processorId": "vantivLitle",
            "processorDivision": "7103111",
            "billToCity": "Burlington",
            "billToAddress_1": "1 Main St.",
            "billToStateProvince": "MA",
            "billToCountry": "US",
            "billToPostalCode": "01803-3747",
            "billToLastName": "Smith",
            "action": "tokenize",
            "mop": "VI",
            "billToFirstName": "John & Mary"
        }
Response
    {"elapsedTime": "0.3589",
     "error": null,
     "id": 100,
     "response": {"elapsedProcessorTime": "0.3237",
                  "processorResponseCode": "802",
                  "processorResponseText": "Account number was previously registered",
                  "processorToken": "1111000274130009",
                  "processorTransactionId": "82919144865875276",
                  "responseCode": "100",
                  "responseText": "Approved"},
     "traceUid": "TraceJn0XXq1",
     "version": "2.0"}

Appendix A: Compliance

Auric Systems International, and the AuricVault® tokenization and AuricVault® services, are compliant with the following standards:

  • PCI Level 1 Service Provider

  • HIPAA

  • U.S-EU Safe Harbor Framework

  • U.S.-Swiss Safe Harbor Framework

  • General Data Protection Regulation (GDPR)
    (In progress for May 2018.)

Appendix B: High Availability

The AuricVault® data centers are deployed in both the eastern and western US. Data is replicated within each facility and between both facilities in near real-time (typically within a few seconds). Load balancers manage multiple Internet-facing servers.

When you go into production, you will receive two production URLs. One for the eastern US servers and one for the western. Your configuration is active on both of them and you can choose to default to whichever of them is geographically closer to you.

In the case of communication failure, or the receipt of an HTTP 50x error, your application should switch over to the alternate facility.

Dynamic DNS Failover?

We’ve explored using automated dynamic DNS fail-over to automatically switch from one facility to another. Our research uncovered various shortcomings with this approach.

  1. It can take up to five minutes for the DNS to switch over. This is the amount of time it takes to:

    • detect the site is down

    • update the central DNS

    • propagate through the distributed DNS servers

    • wait for the Time To Live for DNS Queries to expire.

      Five minutes is a long time to wait during the holiday rush.

  2. The majority of our clients are running PCI-compliant environments. Many of them have disabled DNS lookup on their servers in order to more easily meet PCI requirements. Dynamic DNS is of no use to these servers because they are not looking up the address in the first place.

Coding your application to handle the manual fail-over between the two facilities is the most robust way to handle the fail-over in the event of catastrophic failure (or simply the inability to reach) one of the facilities.

Note
Although we do not use dynamic DNS, we do occasionally route all our traffic into one facility during maintenance tasks.

Test URL

If you want to test your fail-over code, you can send a test transaction to the AuricVault® sandbox implementation. Instead of using the standard/proper URL, send your transaction to:

https://vault01-sb.auricsytems.com/50x/

or

https://vault02-sb.auricsystems.com/50x/

either one of those URLs will return a 50x error you can use for testing.

Appendix C: HMAC Examples

Data and code examples for AuricVault®-compliant HMAC generation.

  • Encode the generated HMAC as hexadecimal.

  • Force the encoded hexadecimal to lowercase.

  • A hexadecimal-encoded SHA512 HMAC is always 128 characters long.

Input
secret = "vQrHr8%1Dvr5HQ9nv8jGew*y5*UpH7br"
payload = '{"params":[{"mtid":"12321","configurationId":"SAMPLESAMPLE","utcTimestamp":"1474978163","token":"9aO1Kb0qgN0B9Q95100"}],"id":1,"method":"encrypt"}'
Output Snippet (first and last 10 characters)
1caaeeb3dc....83ffd5a925
NodeJS
var crypto = require('crypto');
var hash = crypto.createHmac('sha512', secret);
hash.update(payload);

// Hex digest is lowercase.
var the_hmac = hash.digest('hex');
PHP
// Default output is hexadecimal.
$hmac = hash_hmac('sha512', $payload, $secret);
Python
def calc_hmac(payload, secret):
    calculated_hmac = hmac.new(
        secret.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha512).hexdigest()
    return calculated_hmac.lower()

Appendix D: Response Codes

The AuricVault® standardizes payment processor response codes. Not all processors return all response codes.

AVS Response Codes

The AuricVault® service returns either three-character or one-character AVS response codes. If you are checking response codes you should check for both of them.

The three-digit response is the more "modern" response code and will eventually be migrated to all existing payment processors.

The three-character standardized response codes provide both general and detailed information. You can check just the leading character to see if the AVS data match fully (M), partially (P), not at all (N), or an returned an error (E). The U code indicates an unexpected AVS response code from the payment processor.

Table 28. Standardized Three-Character AVS Responses

M00

5-Digit zip and address match

M01

9-Digit zip and address match

M02

Postal code and address match — International.

P00

5-Digit ZIP matches, address does not match

P01

9-Digit ZIP matches, address does not match

P02

ZIP does not match, address matches

P03

Postal code does not match, address matches

P04

Postal code matches, address not verified

N00

Neither ZIP nor address match

W00

AVS service not supported by issuer

E01

AVS system not available

E02

Address unavailable

E03

General error

E04

AVS not performed

E05

Address failed edit checks

U99

Unrecognized response code.

Table 29. Standardized One-Character AVS Responses

0

APPROVED

A

ADDRESS MATCH

B

STREET MATCH — NOT POSTAL CODE

E

ERROR INELIGIBLE

N

NO MATCH

R

RETRY

S

SERVICE. UNAVAILABLE

U

VERSION. UNAVAILABLE

W

ZIP MATCH

X

EXACT MATCH

Y

EXACT MATCH

Z

ZIP MATCH

Standardized CVV Responses

M

Match

N

No Match

P

Not Processed

S

Not Present

U

Not Certified

<blank>

Not Done for unspecified reason.

Appendix E: Error Messages

Table 30. AuricVault® Error Messages
Error What to Check

VLT-100: JSON validation error:

VLT-102: Missing Required Field; One or More of

Messages lists missing field(s).

VLT-103: Authentication Failure.

Improperly calculated HMAC.

VLT-104: Authentication Failure.

Invalid credentials.

VLT-105: Authentication Failure.

Invalid credentials.

VLT-106: JSON Encode Error:

Review JSON formatting against documentation. Check the returned error message for specifics.

VLT-107: JSON Decode Error:

A frequent error is sending the "id" parameter as a string vs. an integer. The "id" parameter is the only integer in the tokenization API.

VLT-108: Submitted JSON missing 'params' value.

VLT-109: 'token' parameter length > 40 bytes.

Occurs when generating your own token IDs.

VLT-110: Header X-VAULT-TRACE-ID length > 64 bytes.

Reduce size of unique tracking ID.

VLT-111: 'last4' parameter larger than four UTF-8 characters.

Reduce size of string when manually setting 'last4' parameter.

VLT-112: This method is missing the following fields. Method:

Modify the API call to send the required field(s).

VLT-113: 'last4' parameter is not a valid four character UTF-8 string.

Possibly sending non UTF-8 encoded string.

VLT-114: Invalid Request.

Unable to understand what was sent via POST.

VLT-115: This method has parameters that are non valid UTF-8 strings. Method:

VLT-116: 'encryptedValue' parameter length > 2,000 bytes.

Occurs when using the store (vs. encrypt) methods. Maximum storable value length is 2,000 bytes, not 2,000 characters.

VLT-117: Invalid request. Does not have 'params' array.

VLT-118: Invalid request. Does not contain 'transaction' element, or it is not complete.

VLT-120: Request header X-VAULT-HMAC is missing.

VLT-121: Header 'X-VAULT-TRACE-UID' contains non-ASCII characters.

VLT-122: Unsupported HTTP Method.

POST is the only supported action.

VLT-130: Unknown Method:

VLT-132: Invalid Method:

VLT-133: Invalid Action:

The AuricVault® service does not recognize the requested payment action.

VLT-134: Processor does not support action:

The payment processor does not support the requested action.

VLT-139: Invalid Parameter Format.

VLT-153: JSON Decode error

VLT-154: Invalid JSON request:

VLT-155: Invalid amount:

VLT-160: Database Connection Failure.

VLT-171: 'plainText' parameter length > 2,000 bytes.

Occurs when using the encrypt, session_encrypt, or reencrypt requests. Maximum storable value length is 2,000 bytes, not 2,000 characters.

VLT-172: Invalid or expired session.

Sessions expire after 10 minutes.

VLT-173: 'store_token' attempted to overwrite existing token. Use 'update_token' to overwrite.

VLT-174: 'update_token' attempted to update non-existing token. Use 'store_token' instead.

VLT-175: 'retrieve_token' method cannot decrypt stored data. Use 'decrypt'.

VLT-176: Token not found, or user does not have segment access privilege.

VLT-177: 'decrypt' method cannot decrypt user-encrypted data. Use 'retrieve_token'.

VLT-178: Unable to validate session credentials.

The sessionID sent in with the session_encrypt or session_decrypt request is invalid.

  • Session ID has expired. The IDs are only good for 10 minutes.

  • Session ID used more than once. We’ve seen instances where the data flow causes the sessionID to be used twice.

  • Used too quickly from different vault. We maintain the vault01 and vault02 servers. It takes a few seconds for the session ID to replicate between the two. If you are generating a session in vault01 then quickly trying to use it in vault02 you can see this error.

  • In rare occasions, people have left their debug code turned on, so they are getting session IDs from the sandbox and trying to use them in production.

VLT-179: Token already exists.

VLT-181: No 'Read' privilege.

VLT-182: No 'Write' privilege.

VLT-183: No 'Delete' privilege.

VLT-184: No 'Encrypt' privilege.

VLT-185: No 'Decrypt' privilege.

VLT-186: No 'Token Info' privilege.

VLT-187: No 'Touch Token' privilege.

VLT-188: Need 'Encrypt' or 'Session Decrypt' privilege to obtain a session.

VLT-189: No 'Session Decrypt' privilege.

VLT-190: Message timestamp is more than 30 seconds older than server time.

Messages must be within a few seconds of current time. This reduces chance of a replay attack. Maintain an accurate time service (NTP) on your server. Browser-side requests do not check time.

VLT-191: Message timestamp is more than 5 seconds newer than server time.

VLT-193: No 'Process Payment' privilege.

VLT-194: No 'Token Swap' privilege.

VLT-195: Both token and auvToken fields are set. Use only one.

VLT-196: Unknown payment processor:

VLT-197: Specified both an account and a token. Use one or the other.

VLT-200: Unknown segment:

VLT-201: Unknown retention policy:

VLT-202: Invalid date; expected format is YYYY-MM-DD

VLT-203: Session token list limited to 5 tokens.

VLT-204: Requested token not in session decrypt token list.

VLT-205: Session contains decrypt token list. Cannot be used for encrypt.

VLT-206: Session request cannot have both 'token list' and 'store-only' parameters.

VLT-207: Decrypt session request must have 'token list' parameter.

VLT-208: Decrypt request for store-only token.

VLT-209: Requesting decrypt but session is encrypt-only.

VLT-210: Requesting encrypt but session is decrypt-only.

VLT-211: Need 'Encrypt' privilege to obtain a session.

VLT-212: Need 'Session Decrypt' privilege to obtain a session.

VLT-220: Need 'storage attributes' param to obtain a multi-encrypt session.

VLT-221: Cannot specify both a token list and storage attribute list.

VLT-222: 'session_multi_encrypt' call requires a multi-encrypt session.

VLT-223: 'session_encrypt' call cannot be used with a multi-encrypt session.

VLT-224: multi-encrypt plaintext list is longer than storage attributes list in session.

VLT-225: each element of multi-encrypt session storage attributes list must have 3 items.

VLT-300: Problem connecting to payment processor:

VLT-301: Internal error at payment processor:

VLT-513: Invalid or unsupported commerce indicator:

VLT-997: Accessed unknown field:

VLT-998: Unable to parse configuration file:

VLT-999: Unexpected error. Contact Auric Systems if this persists.

Appendix F: Card Security Code Presence Indicator

Value must be passed as a string, not a numeric digit.

Table 31. cscPresenceIndicator
Code Meaning

0

You are not submitting a Card Security Code.

1

Code is included in the Auth/Sale trnsaction.

2

Card holder has stated the code is illegible

9

Card holder has stated the code is not on the card.

Appendix G: ISO Currency Codes

Not all payment processors support all currency codes. Contact your specific payment processor to determine which currency codes are supported.

  • Currency codes accepted within a country are subject to change.

  • Country designations are subject to change.

  • Countries and Currencies are listed in alphabetic order.

Table 32. ISO Currency Codes by Country
Country Alpha Code Numeric Code Decimals Currency

Afganistan

AFA

004

2

Afghanistan Afghani

Albania

ALL

008

2

Albanian Lek

Algeria

DZD

012

2

Algerian Dinar

American Samoa

USD

840

2

US Dollar

Andorra

ADP

020

0

Andorran Peseta

Andorra

ESP

724

0

Spanish Peseta

Andorra

FRF

250

2

French Franc

Angola

AOA

973

2

Kwanza

Anguilla

XCD

951

2

East Caribbean Dollar

Antigua and Barbuda

XCD

951

2

East Caribbean Dollar

Argentina

ARS

032

2

Argentine Peso

Armenia

AMD

051

2

Armenian Dram

Aruba

AWG

533

2

Aruban Guilder

Australia

AUD

036

2

Australian Dollar

Austria

ATS

040

2

Austrian Schilling

Azerbaijan

AZM

031

2

Azerbaijanian Manat

Bahamas

BSD

044

2

Bahamian Dollar

Bahrain

BHD

048

3

Bahraini Dinar

Bangladesh

BDT

050

2

Bangladeshi Taka

Barbados

BBD

052

2

Barbados Dollar

Belarus

BYB

112

0

Belarussian Ruble

Belarus

RYR

974

0

Belarussian Ruble

Belgium

BEF

056

0

Belgian Franc

Belize

BZD

084

2

Belize Dollar

Benin

XOF

952

0

CFA Franc (BCEAO)

Bermuda

BMD

060

2

Bermuda Dollar

Bhutan

BTN

064

2

Ngultrum

Bhutan

INR

356

2

Indian Rupee

Bolivia

BOB

068

2

Boliviano

Bolivia

BOV

984

2

Mvdol

Bosnia & Herzegovina

BAM

977

2

Convertible Marks

Botswana

BWP

072

2

Pula

Bouvet Island

NOK

578

2

Norwegian Krone

Brazil

BRL

986

2

Brazil Real

British Indian Ocean Territory

USD

840

2

US Dollar

Brunei Darrusslam

BND

096

2

Brunei Dollar

Bulgaria

BGL

100

2

Lev

Bulgaria

BGN

975

2

Bulgarian Lev

Burkina Faso

XOF

952

0

CFA Franc BCEAO

Burundi

BIF

108

0

Burundi Franc

Cambodia

KHR

116

2

Cambodian Riel

Cameroon

XAF

950

0

CFA Franc (BEAC)

Canada

CAD

124

2

Canadian Dollar

Cape Verde

CVE

132

2

Cape Verde Escudo

Cayman Islands

KYD

136

2

Cayman Islands Dollar

Central African Republic

XAF

950

0

CFA Franc (BEAC)

Chad

XAF

950

0

CFA Franc (BEAC)

Chile

CLF

990

0

Unidates de fomento

Chile

CLP

152

0

Chilean Peso

China (Hong Kong S.A.R.)

HKD

344

2

Hong Kong Dollar

China (Macau S.A.R.)

MOP

446

2

Pataca

China

CNY

156

2

Yuan Renminbi

Christmas Island

AUD

036

2

Australian Dollar

Cocos (Keeling) Islands

AUD

036

2

Australian Dollar

Colombia

COP

170

2

Colombian Peso

Comoros

KMF

174

0

Comoro Franc

Congo, Democratic Republic of

CDF

976

2

Franc Congolais

Congo

XAF

950

0

CFA Franc (BEAC)

Cook Islands

NZD

554

2

New Zealand Dollar

Costa Rica

CRC

188

2

Costa Rican Colon

Côte D’Ivoire

XOF

952

0

CFA Franc (BCEAO)

Croatia

HRK

191

2

Croatian Kuna

Cuba

CUP

192

2

Cuban Peso

Cyprus

CYP

196

2

Cyprus Pound

Czech Republic

CZK

203

2

Czech Koruna

Denmark

DKK

208

2

Danish Krone

Djibouti

DJF

262

0

Djibouti Franc

Dominica

XCD

951

2

East Caribbean Dollar

Dominican Republic

DOP

214

2

Dominican Peso

East Timor

IDE

360

2

Rupiah

East Timor

TPE

626

0

Timor Escudo

Ecuador

ECS

218

2

Sucre

Ecuador

ECV

983

2

Unidad de Valor Constante (UVC)

Egypt

EGP

818

2

Egyptian Pound

El Salvador

SVC

222

2

El Salvador Colon

Equatorial Guinea

XAF

950

0

CFA Franc (BEAC)

Eritrea

ERN

232

2

Nafka

Estonia

EEK

233

2

Kroon

Ethiopia

ETB

230

2

Ethiopian Birr

European Union (ECU)

XEU

954

2

euro

European Union (Euro)

EUR

978

2

European Currency Unit

Falkland Islands

FKP

238

2

Falkland Islands Pound

Faroe Islands

DKK

208

2

Danish Krone

Fiji

FJD

242

2

Fiji Dollar

Finland

FIM

246

2

Finnish Markka

France

FRF

250

2

French Franc

French Guiana

FRF

250

2

French Franc

French Polynesia

XPF

953

0

CFP Franc

French Southern Territories

XPF

953

0

CFP Franc

Gabon

XAF

950

0

CFA Franc (BEAC)

Gambia

GMD

270

2

Dalasi

Georgia

GEL

981

2

Lari

Germany

DEM

276

2

Deutsche Mark

Ghana

GHC

288

2

Ghana Cedi

Gibraltar

GIP

292

2

Gibraltar Pound

Granada

XCD

951

2

East Caribbean Dollar

Greece

GRD

300

0

Drachma

Greenland

DKK

208

2

Danish Krone

Guadaloupe

FRF

250

2

French Franc

Guam

USD

840

2

US Dollar

Guatemala

GTQ

320

2

Guatemalan Quetzal

Guinea-Bissau

GWP

624

2

Guinea-Bissau Peso

Guinea-Bissau

XOF

952

0

CFA Franc (BCEAO)

Guinea

GNF

324

0

Guinea Franc

Guyana

GYD

328

2

Guyana Dollar

Haiti

HTG

332

2

Haiti Gourde

Haiti

USD

840

2

US Dollar

Heard Island and McDonald Islands

AUD

036

2

Australian Dollar

Holy See (Vatican City State)

ITL

380

0

Italian Lira

Honduras

HNL

340

2

Honduran Lempira

Hungary

HUF

348

2

Forint

Iceland

ISK

352

2

Iceland Krona

India

INR

356

2

Indian Rupee

Indonesia

IDR

360

2

Indonesian Rupiah

International Monetary Fund

XDR

960

N.A.

SDR

Iran

IRR

364

2

Iranian Rial

Iraq

IQD

368

3

Iraqi Dinar

Ireland

IEP

372

2

Irish Pound

Israel

ILS

376

2

New Israeli Sheqel

Italy

ITL

380

0

Italian Lira

Jamaica

JMD

388

2

Jamaican Dollar

Japan

JPY

392

0

Yen

Jordan

JOD

400

3

Jordanian Dinar

Kazakhstan

KZT

398

2

Kazakhstan Tenge

Kenya

KES

404

2

Kenyan Shilling

Kiribati

AUD

036

2

Australian Dollar

Korea, Democratic People’s Republic of

KPW

408

2

North Korean Won

Korea, Republic of

KRW

410

0

South Korean Won

Kuwait

KWD

414

3

Kuwaiti Dinar

Kyrgyzstan

KGS

417

2

Kyrgyzstan Som

Lao People’s Democratic Republic

LAK

418

2

Laos Kip

Latvia

LVL

428

2

Latvian Lats

Lebanon

LBP

422

2

Lebanese Pound

Lesotho

LSL

426

2

Loti

Lesotho

ZAR

710

2

Rand

Liberia

LRD

430

2

Liberian Dollar

Libyan Arab Jamahirya

LYD

434

3

Libyan Dinar

Liechtenstein

CHF

756

2

Swiss Franc

Lithuania

LTL

440

2

Lithuanian Litas

Luxembourg

LUF

442

0

Luxembourg Franc

Macedonia (Former Yug. Rep.)

MKD

807

2

Macedonian Denar

Madagascar

MGF

450

0

Malagasy Franc

Malawi

MWK

454

2

Kwacha

Malaysia

MYR

458

2

Malaysian Ringgit

Maldives

MVR

462

2

Maldives Rufiyaa

Mali

XOF

952

0

CFA Franc BCEAO

Malta

MTL

470

2

Maltese Lira

Marshall Islands

USD

840

2

US Dollar

Martinique

FRF

250

2

French Franc

Mauritania

MRO

478

2

Mauritanian Ouguiya

Mauritius

MUR

480

2

Mauritius Rupee

Mexico

MXN

484

2

Mexican Peso

Mexico

MXV

979

2

Mexican Unidad de Inversion (UDI)

Micronesia

USD

840

2

US Dollar

Moldova, Republic of

MDL

498

2

Moldovan Leu

Monaco

FRF

250

2

French Franc

Mongolia

MNT

496

2

Mongolian Tugrik

Montserrat

XCD

951

2

East Caribbean Dollar

Morocco

MAD

504

2

Moroccan Dirham

Mozambique

MZM

508

2

Mozambique Metical

Myanmar

MMK

104

2

Myanmar Kyat

Namibia

NAD

516

2

Namibia Dollar

Namibia

ZAR

710

2

Rand

Nauru

AUD

036

2

Australian Dollar

Nepal

NPR

524

2

Nepalese Rupee

Netherlands Antilles

ANG

532

2

Netherlands Antillian Guilder

Netherlands

NLG

528

2

Netherlands Gulder

New Caledonia

XPF

953

0

CFP Franc

New Zealand

NZD

554

2

New Zealand Dollar

Nicaragua

NIO

558

2

Nicaraguan Cordoba Oro

Niger

XOF

952

0

CFA Franc BCEAO

Nigeria

NGN

566

2

Nigerian Naira

Niue

NZD

554

2

New Zealand Dollar

Norfolk Island

AUD

036

2

Australian Dollar

Northern Mariana Islands

USD

840

2

US Dollar

Norway

NOK

578

2

Norwegian Krone

Oman

OMR

512

3

Rial Omani

Pakistan

PKR

586

2

Pakistan Rupee

Palau

USD

840

2

US Dollar

Panama

PAB

590

2

Balboa

Panama

USD

840

2

US Dollar

Papua New Guinea

PGK

598

2

Papua New Guinea Kina

Paraguay

PYG

600

0

Paraguay Guarani

Peru

PEN

604

2

Peru Nuevo Sol

Philippines

PHP

608

2

Philippine Peso

Pitcairn

NZD

554

2

New Zealand Dollar

Poland

PLN

985

2

Poland Zloty

Portugal

PTE

620

0

Portuguese Escudo

Puerto Rico

USD

840

2

US Dollar

Qatar

QAR

634

2

Qatari Rial

Reunion

FRF

250

2

French Franc

Romania

ROL

642

2

Romanian Leu

Russian Federation

RUB

643

2

Russian Ruble

Russian Federation

RUR

810

2

Russian Ruble

Rwanda

RWF

646

0

Rwanda Franc

Saint Helena

SHP

654

2

St. Helena Pound

Saint Kitts and Nevis

XCD

951

2

East Caribbean Dollar

Saint Lucia

FRF

951

2

East Caribbean Dollar

Saint Pierre and Miquelon

XCD

250

2

French Franc

Saint Vincent and the Grenadines

XCD

951

2

East Caribbean Dollar

Samoa

WST

882

2

Tala

San Marino

ITL

380

0

Italian Lira

Sao Tome and Principe

STD

678

2

Sao Tome and Principe Dobra

Saudi Arabia

SAR

682

2

Saudi Riyal

Senegal

XOF

952

0

CFA Franc BCEAO

Seychelles

SCR

690

2

Seychelles Rupee

Sierra Leone

SLL

694

2

Sierra Leone Leone

Singapore

SGD

702

2

Singapore Dollar

Slovakia

SKK

703

2

Slovak Koruna

Slovenia

SIT

705

2

Slovenia Tolar

Solomon Island

SBD

090

2

Solomon Islands Dollar

Somalia

SOS

706

2

Somalia Shilling

South Africa

ZAR

710

2

South African Rand

Spain

ESP

724

0

Spanish Peseta

Sri Lanka

LKR

144

2

Sri Lanka Rupee

Sudan

SDP

736

2

Sudanese Dinar

Suriname

SRG

740

2

Suriname Guilder

Svalbard and Jan Mayen

NOK

578

2

Norwegian Krone

Swaziland

SZL

748

2

Swaziland Lilangeni

Sweden

SEK

752

2

Swedish Krona

Switzerland

CHF

756

2

Swiss Franc

Syrian Arab Republic

SYP

760

2

Syrian Pound

Taiwan

TWD

901

2

New Taiwan Dollar

Tajikistan

TJR

762

0

Tajik Ruble

Tanzania, United Republic of

TZS

834

2

Tanzanian Shilling

Thailand

THB

764

2

Thai Baht

Togo

XOF

952

0

CFA Franc BCEAO

Tokelau

NZD

554

2

New Zealand Dollar

Tonga

TOP

776

2

Tonga Pa’anga

Trinidad and Tobago

TTD

780

2

Trinidad and Tobago Dollar

Tunisia

TND

788

3

Tunisian Dinar

Turkey

TRL

792

0

Turkish Lira

Turkmenistan

TMM

795

2

Manat

Turks and Caicos Islands

USD

840

2

US Dollar

Tuvalu

AUD

036

2

AUD

Uganda

UGX

800

2

Ugandan Shilling

Ukraine

UAH

980

2

Hryvnia

United Arab Emirates

AED

784

2

UAE Dirham

United Kingdom

GBP

826

2

Pound Sterling

United States Minor Outlying Islands

USD

840

2

US Dollar

United States of America

USD

840

2

US Dollar

Uruguay

UYU

858

2

Peso Uruguayo

Uzbekistan

UZS

860

2

Uzbekistan Sum

Vanuatu

VUV

548

0

Vanuatu Vatu

Venezuela

VEB

862

2

Venezuela Bolivar

Viet Nam

VND

704

2

Viet Nam Dong

Virgin Islands (British)

USD

840

2

US Dollar

Virgin Islands (US)

USD

840

2

US Dollar

Wallis and Futuna

XPF

953

0

CFP Franc

Western Sahara

MAD

504

2

Moroccan Dirham

Yemen

YER

886

2

Yemeni Rial

Yugoslavia

YUN

891

2

Yugoslavian Dinar

Zaire

ZRN

180

2

Unknown

Zambia

ZMK

894

2

Zambia Kwacha

Zimbabwe

ZWD

716

2

Zimbabwe Dollar

Appendix H: Firewall Rules

Inbound

  • vault01: 74.85.138.146

  • vault02: 74.85.142.166

Outbound to Payment Processors

Use these IP addresses if your payment processor needs to know from what IP address you will be submitting transactions.

  • vault01: 74.85.138.162

  • vault02: 74.85.142.50