Detokenization Proxy

Overview

The Forter Detokenization Proxy is a forward HTTP proxy designed to facilitate detokenization for merchants interacting with third-party APIs that require sensitive PCI data. This enables you to process transactions securely without handling or storing sensitive cardholder information.

Forter APIs can be called with Forter token directly, there is no need to go through the Forter Detokenization Proxy

Key Benefits

Securely retrieve tokenized PCI data

Avoid direct PCI data handling

Compatible with standard HTTP libraries and tools

Pass PCI tokenized authorization payloads to any PSP from a single card vault vendor

Proxy Environments

Sandbox: https://pci-proxy-sandbox.checkouttools.com

Production: https://pci-proxy.checkouttools.com

Authentication

The Forter Detokenization Proxy requires HTTP Basic Authentication using the proxy-authorization header in the following format:

proxy-authorization: Basic TO_BASE64(site_id:site_secret)

The same credentials are used for both the Detokenization Proxy and the Tokenization API.

Trusted CA Certificate

To establish a secure connection, you must trust Forter’s CA root certificate.

Setup

Download and store the certificate.

In your HTTP framework, add it as a trusted CA without overriding the default CA list.

Using the Detokenization Proxy

To use the proxy, replace sensitive PCI data in the request payload with placeholders, and include the Forter token in the request header.

Token Types

Payment Method Token: A Forter-issued PCI token for payment credentials.

CVC-Only Token: A specialized token for periodic CVC authentication.

Required headers

For Payment Method Tokens

When using a Payment Method Token issued by Forter, you have two integration options:

Using the Forter Token Directly: This requires including the forter-token header with the token string.

Using a Token Alias: If a token alias was previously specified in a /tokenize request to the Forter Tokenization API, you must provide the alias information via the following headers:

forter-token-alias-key The alias key assigned in the tokenization request.

forter-token-alias-value The corresponding alias value.

For CVC-Only Tokens

When using the CVC-Only Token, the following headers must be included:

The primary Forter token string forter-tokenOR forter-token-alias-keyand forter-token-alias-value

The CVC-specific token issued by Forter forter-cvc-token OR forter-cvc-token-alias-keyand forter-cvc-token-alias-value

Request Placeholders

Placeholders are strings enclosed in double curly brackets ({{ }}). These placeholders should be inserted into the request payload sent to the Detokenization Proxy to ensure the correct request body format for the final third-party target.

Standard Placeholders

Placeholder	Description
{{card_number}}	The full credit card Primary Account Number (PAN).
{{expiration_m}}	The expiration month as a single-digit number (e.g., 8).
{{expiration_mm}}	The expiration month as a two-digit number (e.g., 08).
{{expiration_yy}}	The expiration year as a two-digit number (e.g., 28).
{{expiration_yyyy}}	The expiration year as a four-digit number (e.g., 2028).
{{cvc}}	The card’s security code (CVV/CVC). Note: The CVC is only available when using a single-use token.
{{card_holder_name}}	The name of the cardholder.
{{card_bin}}	The card’s Bank Identification Number (BIN).
{{card_last_four}}	The last four digits of the card number.

Network Tokenization Placeholders

Placeholder	Description
{{network_token}}	The PAN's associated network token.
{{network_token_cryptogram}}	A one-time cryptogram used with the network token.
{{network_token_eci}}	The network token’s Electronic Commerce Indicator (ECI).
{{network_token_par}}	The Payment Account Reference (PAR) associated with the network token.
{{network_token_expiration_m}}	The expiration month of the network token as a single-digit number (e.g., 8).
{{network_token_expiration_mm}}	The expiration month of the network token as a two-digit number (e.g., 08).
{{network_token_expiration_yy}}	The expiration year of the network token as a two-digit number (e.g., 28).
{{network_token_expiration_yyyy}}	The expiration year of the network token as a four-digit number (e.g., 2028).

Custom Placeholder Fields

Placeholder	Description
{{ text_field }}	Extra fields from the tokenization API can be included. Ensure the placeholder name must match the original casing and wording.

Handling Errors

The Detokenization Proxy uses special status codes to distinguish its own errors from third-party API responses.

HTTP Status Code	Description
407	Proxy authentication error (check credentials)
502	Network error while reaching the third-party API
555	Token not found
556	Validation error (check inputs)
565	Unexpected internal error
Other Codes	Relayed directly from the third-party API

HMAC Request Signing

Some Payment Service Providers (PSPs) require HMAC signing to verify request integrity. Forter supports multiple hashing algorithms and allows you to sign requests seamlessly.

Supported HMAC Algorithms

sha256

sha512

sha1

HMAC Headers

Header Name	Description
forter-hmac-algo	HMAC algorithm (e.g., sha256)
forter-hmac-target-header	Name of the header storing the computed signature
forter-hmac-secret	Shared secret for signing
forter-hmac-payload-template	Template for the signed payload.

For the forter-hmac-payload-template special placeholder values denoted in curly braces are supported:

{{ request-body }} - The full outgoing request body, after detokenization, as a single string.

{{ http-method }} - The HTTP method used in the request

{{ http-path }} - The relative path used in the request

{{ header-name }} - Any header sent along the request can be used to construct the signing payload. The header name must be converted to lowercase.

PSP specific signing methods

Disclaimer: Payment Service Providers (PSPs) employ various signing algorithms, and we can support a range of them. For assistance with your specific requirements, please reach out to us.

Ixopay

To implement signing for Ixopay, include the following header: Forter-Ixopay-Signature: SHARED_IXOPAY_KEY This will generate X-Signature and Date headers in the proxied request to Ixopay.

PayNearMe

For PayNearMe, signing is applied automatically to JSON requests sent to PayNearMe's API hosts (api.paynearme.com and api.paynearme-sandbox.com) — no payload template is required. Provide your PayNearMe API Secret Key via the forter-hmac-secret header. The proxy computes the HMAC-SHA256 signature over your detokenized request parameters (sorted alphabetically by name, excluding format, signature, and call) and injects the resulting signature field into the request body.

Onerway

For Onerway, signing is applied automatically to JSON requests sent to Onerway's API hosts (acq.onerway.com and sandbox-acq.onerway.com) — no payload template is required. Provide your Onerway merchant secret key via the forter-hmac-secret header. Note that Onerway's scheme is not an HMAC: the proxy concatenates your detokenized request parameter values (sorted by parameter name, excluding sign and any empty or null fields), appends the secret key, computes SHA-256 over the result, and injects the resulting lowercase hex string as a sign field in the request body.

Onerway signs a flat payload, so any nested object or array must already be JSON-encoded as a string in the body you send to the proxy — as Onerway's own examples show for fields such as billingInformation and txnOrderMsg. A request containing a nested value that has not been stringified is rejected with a validation error rather than signed.

CyberSource

For CyberSource, signing is applied automatically to requests sent to CyberSource's REST API hosts (api.cybersource.com and apitest.cybersource.com) — no payload template is required. CyberSource uses the HTTP Signature scheme, which is not a single signature header but a set of headers that must agree with one another, so the proxy generates all of them for you.

Provide the following headers:

Header Name	Description
forter-hmac-secret	Your CyberSource shared secret key, exactly as issued (a Base64 string)
forter-cybersource-key-id	The key ID issued alongside the shared secret
v-c-merchant-id	Your CyberSource merchant ID

v-c-merchant-id is CyberSource's own header rather than a Forter one: it identifies the merchant account the request is billed against, it is part of the signed payload, and it is forwarded to CyberSource unchanged. The first two headers are consumed by the proxy and never forwarded.

The proxy adds the following headers to the proxied request:

Signature — the HMAC-SHA256 signature, together with the key ID, algorithm, and the list of signed fields.

Date — an RFC 7231 HTTP-date. The proxy generates this value and signs the same one, so do not send your own.

Digest — a Base64 SHA-256 hash of the detokenized request body, prefixed with SHA-256=. Added for POST, PUT, and PATCH only; CyberSource does not expect it on GET or DELETE, and the proxy omits it from the signature for those methods accordingly.

Examples

Sending a request to a PSP

Securely paying using a newly collected CVC token

// NOTE: We must trust the required proxy CA certificate. In NodeJS this must be done via the
// NODE_EXTRA_CA_CERTS environment variable, which is read once at startup and must therefore
// be set BEFORE the application starts (it cannot be applied dynamically at runtime). Passing
// the CA via the proxy agent's "ca" option does not reliably work:
//   export NODE_EXTRA_CA_CERTS=[your CA certificate file path]

import {HttpsProxyAgent} from "https-proxy-agent";  
import url from "url";  
import Stripe from "stripe";  

const stripe = Stripe("sk_test_********************");

const secureProxyHttpsAgent = new HttpsProxyAgent("https://pci-proxy-sandbox.checkouttools.com",{  
  headers: {  
    "proxy-authorization": `Basic ${btoa('site_id:site_secret')}`,  
    "forter-token": "ftr1df95272f9e204c5791427722cc4ef407",  
  },  
});

stripe.setHttpAgent(secureProxyHttpsAgent);

const cvcToken = await stripe.tokens.create({  
  cvc_update: { cvc: "{{ cvc }}" },  
});

const paymentIntent = await stripe.paymentIntents.create({  
  payment_method: 'abcd',  
  customer: '1234',  
  amount: 1099,  
  currency: 'usd',  
  confirmation_method: 'manual',  
  confirm: true,  
  payment_method_options: {card: {cvc_token: cvcToken}},  
});

Authorizing a transaction using authorizations api and a token alias

  // NOTE: We must trust the required proxy CA certificate. In NodeJS this must be done via the
  // NODE_EXTRA_CA_CERTS environment variable, which is read once at startup and must therefore
  // be set BEFORE the application starts (it cannot be applied dynamically at runtime). Passing
  // the CA via the proxy agent's "ca" option does not reliably work:
  //   export NODE_EXTRA_CA_CERTS=[your CA certificate file path]

  import {HttpsProxyAgent} from "https-proxy-agent";  
  import url from "url";  
  import axios from "axios";  
  import fs from "fs/promises";

  const secureProxyHttpsAgent = new HttpsProxyAgent("https://pci-proxy-sandbox.checkouttools.com", {  
    headers: {  
      "proxy-authorization": `Basic ${btoa('site_id:site_secret')}`,  
      "forter-token-alias-key": "zooz",  
      "forter-token-alias-value": "ABCABC123",  
    },  
  });

  // Securely calling worldpay's authorizations API  
  axios.post(  
   "https://try.access.worldpay.com/payments/authorizations",

    // Note: we are using a stringified payload as worldpay uses integers to represent dates which becomes  
    // invalid JSON when replaced with our placeholders  
    `{
      "transactionReference": "Memory265-13/08/1876",
      "merchant": {
        "entity": "MindPalaceLtd"
      },
      "instruction": {
        "narrative": {
          "line1": "Mind Palace"
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "paymentInstrument": {
          "type": "card/plain",
          "cardNumber": "{{ card_number }}",
          "cardExpiryDate": {
            "month": {{ expiration_month }},
            "year": {{ expiration_year }}
          }
        }
      }
    }`,  
    { httpsAgent: secureProxyHttpsAgent }  
  );

  curl 'https://prod.emea.api.fiservapps.com/sandbox/ipp/payments-gateway/v2/payments/' \
 -x 'https://SITE_ID:[email protected]' \
 --proxy-header 'forter-token: ftr1df95272f9e204c5791427722cc4ef407' \
 -X POST \
 -H 'Content-type: application/json' \
 -H 'client-request-id: 123456' \
 -H 'api-key: FISERV_API_KEY' \
 -H 'timestamp: 655846200000' \
 -H 'forter-hmac-target-header: message-signature' \
 -H 'forter-hmac-algo: sha256' \
 -H 'forter-hmac-secret: signing-secret' \
 -H 'forter-hmac-payload-template: {{ api-key }}{{ client-request-id }}{{ timestamp }}{{ request-body }}' \
 -d '
   {
     fullCreditCard: "{{ card_number }}",
     nameOnCard: "{{ card_holder_name }}",
     expirationMM: "{{ expiration_mm }}",
     expirationYY: "{{ expiration_yy }}",
   }'

  curl 'https://apitest.cybersource.com/pts/v2/payments' \
 -x 'https://SITE_ID:[email protected]' \
 --proxy-header 'forter-token: ftr1df95272f9e204c5791427722cc4ef407' \
 -X POST \
 -H 'Content-type: application/json' \
 -H 'v-c-merchant-id: CYBERSOURCE_MERCHANT_ID' \
 -H 'forter-cybersource-key-id: CYBERSOURCE_KEY_ID' \
 -H 'forter-hmac-secret: CYBERSOURCE_SHARED_SECRET' \
 -d '
   {
     "clientReferenceInformation": { "code": "TC50171_3" },
     "processingInformation": { "capture": false },
     "paymentInformation": {
       "card": {
         "number": "{{ card_number }}",
         "expirationMonth": "{{ expiration_mm }}",
         "expirationYear": "{{ expiration_yyyy }}",
         "securityCode": "{{ cvc }}"
       }
     },
     "orderInformation": {
       "amountDetails": { "totalAmount": "102.21", "currency": "USD" },
       "billTo": {
         "firstName": "John",
         "lastName": "Doe",
         "address1": "1 Market St",
         "locality": "San Francisco",
         "administrativeArea": "CA",
         "postalCode": "94105",
         "country": "US",
         "email": "[email protected]",
         "phoneNumber": "4158880000"
       }
     }
   }'