Introduction

Bluefin has taken our world-class ShieldConex data tokenization and have added it to our PayConex platform. This gives our PayConex merchants the ability to simultaneously process payments while tokenizing personally identifiable information (PII), personal health information (PHI), and cardholder data.

By integrating with ShieldConex, PayConex merchants will be able to:

Obtain tokens for cardholder data for both Card Present and Card Not Present P2PE transactions; these tokens can be used for reissue transactions in the future. See our Auto Tokenization Guide below for more details.
Use the ShieldConex iFrame to secure PII/PHI and cardholder information simultaneously; this will ensure that merchants never have to store, process, or transmit cardholder data in plaintext. See our Token Payment Guide below for more details.
Share tokens with affiliates for token-based payment processing.
Capture and tokenize cardholder data from a single integration and route transaction payloads to multiple backend processors.

Auto Tokenization

PayConex's auto tokenization feature allows merchants to obtain ShieldConex tokens for both Card Present and Card Not Present P2PE transactions. This mechanism can capture ACH and CHD tokens from a payment terminal, our Hosted Payment pages, our eToken iframe or standalone QSAPI calls. The merchant can use these tokens to either share within their network or for reissue transactions in the future.

The Auto Tokenization feature in PayConex gives PayConex users the ability to obtain ShieldConex tokens for both Card-Present and Card-Not-Present P2PE transactions.

📘
What is ShieldConex?
ShieldConex is Bluefin’s cloud-based data security platform that tokenizes sensitive cleartext data fields upon entry and at rest. ShieldConex tokens are vaultless, meaning they are generated cryptographically via an algorithm, and can only be detokenized via the ShieldConex platform itself.

The Auto Tokenization feature captures and tokenizes any ACH and/or cardholder data that passes through the PayConex gateway, regardless of whether that data is captured via a payment terminal, a Bluefin Hosted Payment Form, a Bluefin eToken iFrame, or via the PayConex QSAPI. These ShieldConex tokens can be used to share with business affiliates, or they can be used to process reissue transactions in the future.

Auto tokenization results in the creation of the following data elements. PayConex stores the data elements with the transaction data where they can be retrieved through our reporting APIs. PayConex also give merchants the option to send the token data in the body of the postback/webhook request.

Parameter	Populated	Description
bfid	ALL	An identifier for ShieldConex tokenized data. It must be included with the token data when processing future payments.
scx_token_card_number	CHD	ShieldConex tokenized card_number data.
scx_token_card_expiration	CHD	ShieldConex tokenized card_expiration data.
scx_token_bank_account_number	ACH	ShieldConex tokenized bank_account_number data.
scx_token_bank_routing_number	ACH	ShieldConex tokenized bank_routing_number data.

PayConex Configuration options

At the PayConex account level you can toggle the following settings:

Option	Description
SHIELDCONEX TOKENIZATION	This option enables/disables auto tokenization on your account. To enable this option the first time you will have to contact the Bluefin Operations to provision your ShieldConex account. When enabled all transactions that come through QSAPI will automatically be tokenized (unless the original transaction contained ShieldConex tokens to begin with).
TOKEN DATA IN POSTBACK	Setting this option to yes will add the tokenized pan, expiry, bank account, and routing data to the body of the postback webhook.
TOKEN DATA IN RSAPI	Setting this option to yes will automatically add the tokenized pan, expiry, bank account, routing data to the RSAPI response. If this options is set to No the token data can still be retrieved by specifying the field name in the include_fields parameter.

Auto Tokenization Flow

The following diagram describe the flow of data through PayConex when ShieldConex auto tokenization is enabled.

Payment TerminalMerchant ServerPayConexShieldConexSubmit transactionProcess TransactionRequest data tokenizationToken DataStore CHD and bfid. Available through RSAPIPostback (with CHD tokens)Postback responseopt[if postback enabled]Transaction responsePayment TerminalMerchant ServerPayConexShieldConex

Sample Reissue Transaction

The following example shows how to perform a reissue transaction with ShieldConex tokens.

curl --location --request POST 'https://cert.payconex.net/api/qsapi/3.8/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'account_id=180000000344' \
--data-urlencode 'api_accesskey=redacted' \
--data-urlencode 'transaction_type=SALE' \
--data-urlencode 'tender_type=CARD' \
--data-urlencode 'transaction_amount=10.00' \
--data-urlencode 'bfid=djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg==' \
--data-urlencode 'scx_token_card_number=4111118041111111' \
--data-urlencode 'scx_token_card_expiration=4755' \
--data-urlencode 'reissue=1'

{
    "transaction_id": "000000000013",
    "tender_type": "CARD",
    "transaction_timestamp": "2020-10-06 08:18:06",
    "card_brand": "VISA",
    "transaction_type": "SALE",
    "last4": "1111",
    "card_expiration": "1222",
    "authorization_code": "833186",
    "authorization_message": "APPROVED",
    "request_amount": 10,
    "transaction_amount": 10,
    "keyed": true,
    "swiped": false,
    "entry_mode": "keyed",
    "transaction_approved": true,
    "currency": "USD",
    "error": false,
    "error_code": 0,
    "error_message": null,
    "error_msg": null
}

The postback/webhook sends the following data to the configured endpoint:

{
      "account_id": "180000000344",
      "timestamp": 1601990354,
      "count": 1,
      "hash": "0a925938ebf9f715efd38bbbeafc23a1be9f41babda1b088c5dcecbb4852d004",
      "responses": [
        {
          "transaction_id": "000000000013",
          "tender_type": "CARD",
          "transaction_timestamp": "2020-10-06 08:18:06",
          "card_brand": "VISA",
          "transaction_type": "SALE",
          "last4": "1111",
          "card_expiration": "1222",
          "authorization_code": "833186",
          "authorization_message": "APPROVED",
          "request_amount": 10,
          "transaction_amount": 10,
          "keyed": true,
          "swiped": false,
          "entry_mode": "keyed",
          "transaction_approved": true,
          "currency": "USD",
          "error": false,
          "error_code": 0,
          "error_message": null,
          "error_msg": null,
          "bfid": "djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg==",
          "scx_token_bank_account_number": "",
          "scx_token_bank_routing_number": "",
          "scx_token_card_expiration": "4755",
          "scx_token_card_number": "4111118041111111",
          "account_id": "180000000344",
          "reissue": "1"
        }
      ]
    }

Payments with ShieldConex Tokens

Using ShieldConex tokens on PayConex the ability to simultaneously process payments while tokenizing personally identifiable information (PII), personal health information (PHI), and cardholder data. It also allows ISVs adopt a number of novel integration solutions that aren't possible using our other card holder data (CHD) capture mechanism. For example a merchant can capture CHD using a single ShieldConex iframe integration and use those tokens to route transactions to one of many backend processors. Additionally the merchant can configure the tokens to allow sharing with trusted partners.

This guide describes how ShieldConex Token Payments work, describes the configuration options and includes an sample Token Payment.

Bluefin Developer Portal: Payconex Shieldconex Token Payments

Configuration options

At the PayConex account level you can toggle the following settings:

Option	Description
SHIELDCONEX TOKEN PAYMENTS	This option enables/disables token payments on your account.
TOKEN DATA IN POSTBACK	Setting this option to yes will add the tokenized pan, expiry, bank account, routing data to the body of the postback webhook.
TOKEN DATA IN RSAPI	Setting this option to yes will automatically add the tokenized pan, expiry, bank account, routing data to the RSAPI response. If this options is set to No the token data can still be retrieved by specifying the field name in the include_fields parameter.

QSAPI

The following table describes the ShieldConex related parameters that QSAPI can consume.

Parameter	Required	RSAPI	Type	Length	Description
bfid	ALL	yes	String	30-150	An identifier for ShieldConex tokenized data. When processing recently captured data a payment can be completed by passing the bfid to QSAPI on it's own. The bfid is still required if processing payments with stored tokens.
reissue	RI	no	Boolean	1	Marks the payment as a reissue.
scx_token_card_number	CHD	yes	Numeric	14-19	ShieldConex tokenized card_number data.
scx_token_card_expiration	CHD	yes	Numeric	4	ShieldConex tokenized card_expiration data.
scx_token_card_verification	no	no	Numeric	3-4	ShieldConex tokenized card_verification data.
scx_token_bank_account_number	ACH	yes	Numeric	4-17	ShieldConex tokenized bank_account_number data.
scx_token_bank_routing_number	ACH	yes	Numeric	9	ShieldConex tokenized bank_routing_number data.
scx_token_email	no	no	String	5-100	ShieldConex tokenized email data.
scx_token_first_name	no	no	String	2-50	ShieldConex tokenized first_name data.
scx_token_last_name	no	no	String	2-50	ShieldConex tokenized last_name data.
scx_token_phone	no	no	String	2-20	ShieldConex tokenized phone data.
scx_token_street_address1	no	no	String	2-100	ShieldConex tokenized street_address1 data.
scx_token_zip	no	no	String	3-10	ShieldConex tokenized zip data.

If any one of the parameters beginning with scx_token or the bfid is included in a QSAPI call it automatically triggers the ShieldConex Token Payment logic. Once triggerred PayConex will make an API call to ShieldConex to detokenize the incoming data; in cases where only the bfid is included in the QSAPI call we will also call the ShieldConex read endpoint to retieve the data. The output data will automatically be mapped to the corresponding plaintext parameters.

Fields that are stored for retrieval through the RSAPI are also included in the Postback webhook.

Required Parameters: Detokenize Only

Once any ShieldConex parameter other than bfid is included in the QSAPI call the ShieldConex read step is skipped and a detokenization API call is executed with the data contained within the QSAPI call. Once a single ShieldConex token is included, we assume that the merchant has sent all the data that they wish to associate with the transaction.

For detokenize-only Payment Card transactions the minimum required ShieldConex parameters are: bfid, scx_token_card_number, and scx_token_card_expiration. All other parameters are optional.
For detokenize-only ACH transactions the minimum required ShieldConex parameters are: bfid, scx_token_bank_account_number, and scx_token_bank_routing_number.

Required Parameters: Read and Detokenize

In a read and detokenize ShieldConex payment transaction, the bfid is the only parameter that is necessary in the QSAPI call. Internally PayConex will retrieve the token data from ShieldConex and complete the payment with the detokenized result. Read and detokenize payments can only be performed within an hour of data capture. After that point the ShieldConex read API call will fail resulting in a transaction failure.

Once the data is read and detokenized the rules for required parameters as described in the Detokenize only section above apply.

Mixing tokens with plaintext parameters

It is possible to mix plaintext data with CHD tokens. For example if a merchant has the card holder's zip code stored in a database in plaintext they can send that using the zip parameter. The zip value will be used unless a scx_token_zip is also included in the API call; in that case the detokenized value of scx_token_zip will be used over the zip.

Reissue Transactions:

When processing a reissue transaction it is important thay the reissue parameter is set to 1. Omitting this parameter can impact the Payment's interchange rate.

ShieldConex Token Payment Flow

The following diagrams describe the flow of data when processing a payment through PayConex using ShieldConex tokens. The first diagram specifically describes the Read and Detokenize flow. In this example the merchant executes a QSAPI call with a bfid. PayConex performs the read a detokenization.

This diagram outlines a typical flow of a read and detokenize Payment iFrame transaction.

The following flow diagram shows an alternative approach that can be adopted in cases where the merchant wants to store all the tokenized PII on their server. Instead of PayConex performing the token read the merchant makes that API call from their server. Once they've finished storing the data they make an API call to QSAPI with the bfid and the other token parameters. This flow allows the merchant to store the data for an extended period before completing the payment. This is not an option when performing bfid only QSAPI calls.

This diagram outlines a typical flow of a detokenize only Payment iFrame transaction.

Sample End to End Transaction

The following example outlines the steps involved in processing an auth and capture payment using ShieldConex tokens. In the example we include cURL commands, the API response and where relevant the postback webhook content.

The following table outlines the mock data used in our example. The plaintext value represents the values that the user entered on the iframe and the token values that were generated and stored on ShieldConex.

Field Name	Plaintext Value	Tokenized Value
scx_token_card_number	4111111111111111	4111118041111111
scx_token_card_expiration	1222	4755
scx_token_card_verification	555	n5p
scx_token_email	[email protected]	[email protected]
scx_token_first_name	John	ssXB
scx_token_last_name	Smith	iuFSF
scx_token_phone	4151234432	6908926159
scx_token_street_address1	2 Main St.	v LRzG 05.
scx_token_zip	90210	nbB50

1) Capture data with ShieldConex

The first step is to capture the CHD with ShieldConex. The ShieldConex API Guide outlines the steps (1-5) that need to be followed in order to load a ShieldConex template in a card capture iframe.

For our example, we assume the ShieldConex iframe outputs the following data which was passed from the user's browser to the merchant's server environment:

{ 
      "bfid" : "djE6MTIwMjAxMDA2MTIwMDE1MTAzMzIzNTg3MXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHxtN1JzaUdDWDlNdz18U1ZUMjAxOTA0MTgxMkRFVg==" 
 }

2) Auth API call

The sample authorization API call should be executed from the merchant's server. It should include the bfid passed from the user's browser.

curl --location --request POST 'https://cert.payconex.net/api/qsapi/3.8/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'account_id=180000000344' \
--data-urlencode 'api_accesskey=redacted' \
--data-urlencode 'transaction_type=AUTHORIZATION' \
--data-urlencode 'transaction_amount=10.00' \
--data-urlencode 'tender_type=card' \
--data-urlencode 'bfid=djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg=='

{
    "transaction_id": "000000000012",
    "tender_type": "CARD",
    "transaction_timestamp": "2020-10-06 08:05:16",
    "card_brand": "VISA",
    "transaction_type": "AUTHORIZATION",
    "last4": "1111",
    "card_expiration": "1222",
    "authorization_code": "832940",
    "authorization_message": "APPROVED",
    "request_amount": 10,
    "transaction_amount": 10,
    "first_name": "John",
    "last_name": "Smith",
    "keyed": true,
    "swiped": false,
    "entry_mode": "keyed",
    "transaction_approved": true,
    "avs_response": "N",
    "currency": "USD",
    "error": false,
    "error_code": 0,
    "error_message": null,
    "error_msg": null
}

The postback/webhook sends the following data to the endpoint on PayConex:

{
      "account_id": "180000000344",
      "timestamp": 1601989540,
      "count": 1,
      "hash": "0f05347e028eca259d72a1832f0803de8bf21c9272ee3690eee454a243c42d26",
      "responses": [
        {
          "transaction_id": "000000000012",
          "tender_type": "CARD",
          "transaction_timestamp": "2020-10-06 08:05:16",
          "card_brand": "VISA",
          "transaction_type": "AUTHORIZATION",
          "last4": "1111",
          "card_expiration": "1222",
          "authorization_code": "832940",
          "authorization_message": "APPROVED",
          "request_amount": 10,
          "transaction_amount": 10,
          "first_name": "John",
          "last_name": "Smith",
          "keyed": true,
          "swiped": false,
          "entry_mode": "keyed",
          "transaction_approved": true,
          "avs_response": "N",
          "currency": "USD",
          "error": false,
          "error_code": 0,
          "error_message": null,
          "error_msg": null,
          "bfid": "djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg==",
          "scx_token_bank_account_number": "",
          "scx_token_bank_routing_number": "",
          "scx_token_card_expiration": "4755",
          "scx_token_card_number": "4111118041111111",
          "account_id": "180000000344"
        }
      ]
    }

3) Capture API call

To capture the payment, the token_id parameter must be set to the id from the auth transaction's response.

curl --location --request POST 'https://cert.payconex.net/api/qsapi/3.8/' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'account_id=180000000344' \
    --data-urlencode 'api_accesskey=redacted' \
    --data-urlencode 'transaction_type=CAPTURE' \
    --data-urlencode 'transaction_amount=10.00' \
    --data-urlencode 'token_id=000000000012'

{
        "transaction_id": "000000000012",
        "tender_type": "CARD",
        "transaction_timestamp": "2020-10-06 08:11:56",
        "card_brand": "VISA",
        "transaction_type": "CAPTURE",
        "last4": "1111",
        "card_expiration": "1222",
        "authorization_code": "832940",
        "authorization_message": "CAPTURED",
        "request_amount": 10,
        "transaction_amount": 10,
        "first_name": "John Smith",
        "keyed": true,
        "swiped": false,
        "entry_mode": "keyed",
        "transaction_approved": true,
        "currency": "USD",
        "error": false,
        "error_code": 0,
        "error_message": null,
        "error_msg": null
    }

The postback/webhook sends the following data to the configured endpoint:

{
      "account_id": "180000000344",
      "timestamp": 1601989968,
      "count": 1,
      "hash": "f3cb0d679e7ed92241173420124f743686a4547c1410a5945c1602244b4a2835",
      "responses": [
        {
          "transaction_id": "000000000012",
          "tender_type": "CARD",
          "transaction_timestamp": "2020-10-06 08:11:56",
          "card_brand": "VISA",
          "transaction_type": "CAPTURE",
          "last4": "1111",
          "card_expiration": "1222",
          "authorization_code": "832940",
          "authorization_message": "CAPTURED",
          "request_amount": 10,
          "transaction_amount": 10,
          "first_name": "John Smith",
          "keyed": true,
          "swiped": false,
          "entry_mode": "keyed",
          "transaction_approved": true,
          "currency": "USD",
          "error": false,
          "error_code": 0,
          "error_message": null,
          "error_msg": null,
          "account_id": "180000000344",
          "token_id": "000000000012"
        }
      ]
    }

Sample Reissue Transaction

The following example shows how to perform a reissue transaction with ShieldConex tokens.

curl --location --request POST 'https://cert.payconex.net/api/qsapi/3.8/' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'account_id=180000000344' \
    --data-urlencode 'api_accesskey=redacted' \
    --data-urlencode 'transaction_type=SALE' \
    --data-urlencode 'tender_type=CARD' \
    --data-urlencode 'transaction_amount=10.00' \
    --data-urlencode 'bfid=djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg==' \
    --data-urlencode 'scx_token_card_number=4111118041111111' \
    --data-urlencode 'scx_token_card_expiration=4755' \
    --data-urlencode 'reissue=1'

{
        "transaction_id": "000000000013",
        "tender_type": "CARD",
        "transaction_timestamp": "2020-10-06 08:18:06",
        "card_brand": "VISA",
        "transaction_type": "SALE",
        "last4": "1111",
        "card_expiration": "1222",
        "authorization_code": "833186",
        "authorization_message": "APPROVED",
        "request_amount": 10,
        "transaction_amount": 10,
        "keyed": true,
        "swiped": false,
        "entry_mode": "keyed",
        "transaction_approved": true,
        "currency": "USD",
        "error": false,
        "error_code": 0,
        "error_message": null,
        "error_msg": null
    }

The postback/webhook sends the following data to the configured endpoint:

{
      "account_id": "180000000344",
      "timestamp": 1601990354,
      "count": 1,
      "hash": "0a925938ebf9f715efd38bbbeafc23a1be9f41babda1b088c5dcecbb4852d004",
      "responses": [
        {
          "transaction_id": "000000000013",
          "tender_type": "CARD",
          "transaction_timestamp": "2020-10-06 08:18:06",
          "card_brand": "VISA",
          "transaction_type": "SALE",
          "last4": "1111",
          "card_expiration": "1222",
          "authorization_code": "833186",
          "authorization_message": "APPROVED",
          "request_amount": 10,
          "transaction_amount": 10,
          "keyed": true,
          "swiped": false,
          "entry_mode": "keyed",
          "transaction_approved": true,
          "currency": "USD",
          "error": false,
          "error_code": 0,
          "error_message": null,
          "error_msg": null,
          "bfid": "djE6MTIwMjAxMTEzMTE1NTA1MTAzMTAzMDQyMXxhZDhkNDQzNDhjNWVhNzc5NmMxMjVmNjZkY2Q1MDIxNHw2czdyYXp5djIvMD18U1ZUMjAxOTA0MTgxMkRFVg==",
          "scx_token_bank_account_number": "",
          "scx_token_bank_routing_number": "",
          "scx_token_card_expiration": "4755",
          "scx_token_card_number": "4111118041111111",
          "account_id": "180000000344",
          "reissue": "1"
        }
      ]
    }

ShieldConex on PayConex

Introduction

Auto Tokenization

📘
What is ShieldConex?

PayConex Configuration options

Auto Tokenization Flow

Sample Reissue Transaction

Payments with ShieldConex Tokens

Bluefin Developer Portal: Payconex Shieldconex Token Payments

Configuration options

QSAPI

Required Parameters: Detokenize Only

Required Parameters: Read and Detokenize

Mixing tokens with plaintext parameters

Reissue Transactions:

ShieldConex Token Payment Flow

Sample End to End Transaction

1) Capture data with ShieldConex

2) Auth API call

3) Capture API call

Sample Reissue Transaction

Introduction

Auto Tokenization

📘What is ShieldConex?

PayConex Configuration options

Auto Tokenization Flow

Sample Reissue Transaction

Payments with ShieldConex Tokens

Bluefin Developer Portal: Payconex Shieldconex Token Payments

Configuration options

QSAPI

Required Parameters: Detokenize Only

Required Parameters: Read and Detokenize

Mixing tokens with plaintext parameters

Reissue Transactions:

ShieldConex Token Payment Flow

Sample End to End Transaction

1) Capture data with ShieldConex

2) Auth API call

3) Capture API call

Sample Reissue Transaction

📘
What is ShieldConex?