Detokenize Push Request

The AuvProxy service provides a generic detokenization option that replaces tagged tokens in the HTTPS request with the original plaintext. The detokenized request is then forwarded (pushed) to the target web service. This allows you to send arbitrary requests through the proxy without the proxy having to implement support for each request format.

Example Dataflow

../../_images/detokenize-pass.svg

An application on your server POSTs a transaction containing tokenized data to the AuvProxy service. The AuvProxy service:

  • Validates the AccessID.

  • Validates the target URL domain.

  • Locates one or more tokens to detokenize.

  • Retrieves each token’s plaintext from the AuricVault® service.

  • Replaces each token in the request with the proper plaintext.

  • Forwards the request to the payment processor.

  • Receives the payment processor response.

  • Returns the response to the client’s application.

Detokenize tagged tokens found in the POST request then forward the detokenized data to the destination.

Each request can have multiple tokens to be replaced.

Tagged Tokens

This is a generalized function that looks for tokens preceded by !!AuvToken! and followed by !AuvToken!! tags. For example:

!!AuvToken!KLt4J88Tx3k91zQ1111!AuvToken!!

The AuvProxy service recognizes this as the token ID KLt4J88Tx3k91zQ1111. The service replaces the tags and the token ID with the decrypted token value returned by the AuricVault® tokenization service.

Example

The following Authorize.NET JSON fragments show the token replaced by the cardholder account number.

Before
{
"payment":{
    "creditCard":{
        "cardNumber":"!!AuvToken!NtVH5Lfh370ZQBN1111!AuvToken!!",
        "expirationDate":"2025-02"
        }
    }
}
After
{
"payment":{
    "creditCard":{
        "cardNumber":"41111111111111111",
        "expirationDate":"2025-02"
        }
    }
}

The same example for Authorize.NET’s XML format.

Before
<payment>
  <creditCard>
    <cardNumber>:AuvToken:bqGYAP9IKT0L3Ei1111!AuvToken!!</cardNumber>
    <expirationDate>2025-12</expirationDate>
  </creditCard>
</payment>
After
<payment>
  <creditCard>
    <cardNumber>41111111111111111</cardNumber>
    <expirationDate>2025-12</expirationDate>
  </creditCard>
</payment>

Supported Targets

This generic detokenization works 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.

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

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

Whitelisted Domains

Authorize.NET

CCV Nederland

  • Website: https://www.ccv.eu/

  • Formats: JSON

  • Test: redirect.jforce.be

  • Production: redirect.jforce.be

Checkout.com

Evertec

  • Website: https://evertecinc.com

  • Formats: SOAP 1.1

  • Test: mmpaytest.evertecinc.com

  • Production: mmpay.evertecinc.com

Zift

  • Website: https://ZiftPay.com

  • Formats: Name/Value Pair

  • Test: sandbox-secure.ziftpay.com

  • Production: secure.ziftpay.com

Submitting Requests

All requests to the proxy service are via HTTPS POSTs. The body of the POST contains the data you would usually send to the target web service, with the addition of tagged tokens.

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, but does not examine any part of the URL beyond the domain. Include the entire URL, including protocol. For example:

https://apitest.authorize.net/xml/v1/request.api

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/detokenize/pass/hdr/<AccessID>/

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

HTTP Response Headers

The following HTTP response headers are always returned by the proxy service.

Content-Type

This is always the content type from the target.

Server

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

Note

All elapsed time values are in decimal seconds.

X-ELAPSED

Total time 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. Auric recommends you track the X-VAULT-TRACE-UID value in your logs as it is helpful when debugging issues across platforms.

X-PCI-PROXY-ERROR

Used to identify error codes returned by the proxy vs. error codes returned by the target (see below).

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

The proxy returns some headers that are specific to the target service.

Authorize.NET-Specific Response Headers

  • Access-Control-Allow-Credentials

  • Access-Control-Allow-Headers

  • X-OPNET-Transaction-Trace

Zift-Specific Response Headers

  • unibroker-code

  • unipay-code

Example

A Curl example shows how to POST tokenized JSON data to the Authorize.NET sandbox service.

#!/bin/bash

# Grab credentials from the environment.
#     ${authorizeNetApiName}
#     ${authorizeNetTransactionKey}

# Sandbox
url='https://proxy01-sb.auricsystems.com/v1/detokenize/pass/<AccessID>/'

data=$(cat <<EOF
{"createTransactionRequest":{
  "merchantAuthentication":{
    "name":"${authorizeNetApiName}",
    "transactionKey":"${authorizeNetTransactionKey}"},
    "refId":"ref1541606366",
    "transactionRequest":{
        "transactionType":"authCaptureTransaction",
        "amount":6.37,
        "payment":{"creditCard":{
            "cardNumber":"!!AuvToken!NtVH5Lfh370ZQBN1111!AuvToken!!",
            "expirationDate":"2020-02"
        }},
        "order":{
            "invoiceNumber":"inv-1541606366",
            "description":"Demo Order"},
            "customer":{"id":"demo"},
            "billTo":{
                "firstName":"Janet",
                "lastName":"Tester",
                "address":"1075077405 Main Street"}
}}}
EOF
)

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

curl -vvv \
    ${url} \
    -d "${one_line}" \
    -H "Content-type: application/json" \
    -H "X-AUV-PROXY-DEST: https://apitest.authorize.net/xml/v1/request.api" \
    -H "X-VAULT-TRACE-UID: `uuidgen`" \
    -X POST