Tokenize Pull Response

The AuvProxy service can tokenize sensitive data in responses received from the target web service. The tokenized response is then returned to your web server.

Example Dataflow

../../_images/pass-tokenize.svg

An application on your server POSTs a transaction to the AuvProxy service. The AuvProxy service then:

  • Validates the AccessID.

  • Validates the target domain.

  • Forwards the request to the target.

  • Receives the target’s response.

  • Scans the response for sensitive data fields.

  • Requests a token from the AuricVault® service for each piece of sensitive data found.

  • Receives a token (after the AuricVault® encrypts and stores the data).

  • Replaces the sensitive data with a token.

  • Responds to your server.

Each response can have multiple sensitive fields to tokenize.

Booking.com Example

The following Booking.com response fragment shows the cardholder account number and card security code replaced by tokens.

Before
<reservations>
  <reservation>
    <commissionamount>8.85</commissionamount>
    <currencycode>EUR</currencycode>
    <customer>
      <cc_cvc>835</cc_cvc>
      <cc_expiration_date>02/2029</cc_expiration_date>
      <cc_name>Joey Smith</cc_name>
      <cc_number>4111111111111111</cc_number>
      <cc_type>MasterCard</cc_type>
    </customer>
    <status>new</status>
    <time>08:52:00</time>
    <totalprice>59</totalprice>
  </reservation>
</reservations>
After
<reservations>
  <reservation>
    <commissionamount>8.85</commissionamount>
    <currencycode>EUR</currencycode>
    <customer>
      <cc_cvc>L3Sd554370ZQB3Nxxxx</cc_cvc>
      <cc_expiration_date>02/2029</cc_expiration_date>
      <cc_name>Joey Smith</cc_name>
      <cc_number>NtVH5Lfh370ZQBN1111</cc_number>
      <cc_type>MasterCard</cc_type>
    </customer>
    <status>new</status>
    <time>08:52:00</time>
    <totalprice>59</totalprice>
  </reservation>
</reservations>

Warning

It is your responsibility to manage the card security code (cc_cvc in this Booking.com example) according to PCI data security requirements. PCI (and the card brands) require you to delete the card security code immediately after it is used for authorization.

You are responsible for determining when authorization occurs.

Once the card security code is used for authorization, your server must send a token delete message through the AuricVault® service API. Auric recommends discussing card security code handling with your PCI QSA.

Supported Targets

The response tokenization can work with any web service API.

Auric ensures the pertinent HTTP response headers returned from the target web service are passed through in the response.

Auric whitelists and tests each new target service before deploying it to production.

Contact sales@AuricSystems.com to discuss adding the target web services you need for your environment.

Whitelisted Domains

Whitelisting the target domains (and limiting the service’s outbound firewall access) ensures your sensitive data is sent to a controlled set of targets.

Agoda Booking Service

  • Website:

  • Formats: XML

  • Test:

  • Production:

<payment
    card_type="MasterCard"
    card_number="Tokenized"
    card_name="Sample Agoda Client"
    card_exp="02/2025"
    card_cvv="Tokenized"/>

Booking.com Booking Service

<customer>
  <address></address>
  <cc_cvc>Tokenized</cc_cvc>
  <cc_expiration_date>02/2031</cc_expiration_date>
  <cc_name>Joey Smith</cc_name>
  <cc_number>Tokenized</cc_number>
  <cc_type>MasterCard</cc_type>
</customer>

Expedia Booking Service

<PaymentCard
    cardCode="VI"
    cardNumber="Tokenized"
    seriesCode="Tokenized"
    expireDate="MMYY">

More Than Booking Engines and Credit Cards

It is simple to add support for targets other than booking engines to the proxy service. The service can also support tokenizing non-PCI data such as driver licenses, birthdates, etc.

Submitting Requests

All requests to the proxy service are via HTTPS POSTs. The body of the POST contains the normal data you would usually send to the target web service.

HTTP Request Headers

The Content-Type header for the POSTed data must be the content type expected by the target web service.

Each POST transaction requires two non-standard HTTP headers be submitted:

  • X-VAULT-TRACE-UID

  • X-AUV-PROXY-DEST

X-VAULT-TRACE-UID

A unique tracking ID Auric and you can use to trace transactions through our services. Please track and store these values as it helps debug any issues that arise. The tracking ID should be unique for each request, though that is not enforced.

The value must be printable ASCII characters and no longer than 64 characters.

This header is passed through to the target web service.

X-AUV-PROXY-DEST

This is the full URL to which you want the transaction to be forwarded. The AuvProxy service maintains a whitelist of domains. No part of the URL beyond the domain is examined. Include the entire URL, including protocol. For example:

https://secure-supply-xml.booking.com/hotels/xml/reservations

Support for Basic Authentication

The proxy service supports Basic HTTP Authorization protocol using the standard Authorization header. The service passes this header directly through to the target web service.

URL Format

The URL to POST to has the following format:

/v1/pass/tokenize/hdr/<AccessID>/

Auric support provides your access identifier. The combination of the access identifier and your firewall restricted IP address identifies you.

The hdr segment tells the proxy to tokenize credit card and card security codes for PCI. Additional flags can be added to tokenize information such as:

  • Card expiration dates.

  • Personally Identifiable Information.

  • Personal Health Information.

  • Fully customized responses.

HTTP Response Headers

The following HTTP response headers are always returned by the proxy service. Auric recommends you track the X-VAULT-TRACE-UID in your own logs as the value is helpful when debugging issues. You can use the times to track response metrics.

Content-Type

This is always the content type from the target.

Server

The HTTP Server header returned by the target service. If the header is not present the proxy returns: |proxy| v<Version Number>.

Note

All elapsed time values are in decimal seconds.

X-ELAPSED

Total time required to process the request.

X-VAULT-ELAPSED

Time spent looking up tokens in the AuricVault® service.

X-DESTINATION-ELAPSED

Time spent waiting for the target to respond.

X-VAULT-TRACE-UID

The same trace ID submitted with the original request.

X-PCI-PROXY-ERROR

Used to identify error codes returned by the proxy vs. error codes returned by the target.

(All times are in decimal seconds.)

Using the X-PROXY-ERROR Header

This header is returned only when the proxy service encounters an internal problem or a communication problem with the target web service.

At present, the header value is always set to 1 when present, but it should be assumed there will be other values returned during future service enhancements.

Whenever you receive an unexpected non-200 HTTP status response, check if this header is present. The header allows you to distinguish between status codes returned by the proxy and those returned by the target.

For example, you should check this header if you receive an HTTP status code of 500. If the header is returned, then the proxy itself encountered a problem. If the header is not returned, then the target service itself generated the 500 status code.

Target-Specific HTTP Response Headers

Agoda-Specific Response Headers

Booking.com-Specific Response Headers

Expedia-Specific Response Headers

Example

A Curl example shows how to POST to the Expedia service through the AuvProxy service.

#!/bin/bash

# Grab credentials from the environment.
#     ${expediaUserName}
#     ${expediaPassword}

# Sandbox
url = 'https://proxy02-sb.auricsystems.com/v1/pass/tokenize/hdr/AccessID/'

data=$(cat <<EOF
<?xml version="1.0"?>
<BookingRetrievalRQ
    xmlns="http://www.expediaconnect.com/EQC/BR/2007/02"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Authentication username="${expediaUserName}" password="${expediaPassword}"/>
    <Hotel id="12345678"/>
</BookingRetrievalRQ>
EOF
)

# Convert data into a single line
one_line=$(echo ${data} | tr '\n' ' ')

curl \
    -vvv \
    ${url} \
    -d "${one_line}" \
    -H "Content-Type: text/xml" \
    -H "X-AUV-PROXY-DEST: https://services.expediapartnercentral.com/eqc/br" \
    -H "X-VAULT-TRACE-ID: `uuidgen`" \
    -X POST