ShieldConex on PayConex

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.

ParameterPopulatedDescription
bfidALLAn identifier for ShieldConex tokenized data. It must be included with the token data when processing future payments.
scx_token_card_numberCHDShieldConex tokenized card_number data.
scx_token_card_expirationCHDShieldConex tokenized card_expiration data.
scx_token_bank_account_numberACHShieldConex tokenized bank_account_number data.
scx_token_bank_routing_numberACHShieldConex tokenized bank_routing_number data.

PayConex Configuration options

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

OptionDescription
SHIELDCONEX TOKENIZATIONThis 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 POSTBACKSetting 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 RSAPISetting 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:

OptionDescription
SHIELDCONEX TOKEN PAYMENTSThis option enables/disables token payments on your account.
TOKEN DATA IN POSTBACKSetting this option to yes will add the tokenized pan, expiry, bank account, routing data to the body of the postback webhook.
TOKEN DATA IN RSAPISetting 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.

ParameterRequiredRSAPITypeLengthDescription
bfidALLyesString30-150An 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.
reissueRInoBoolean1Marks the payment as a reissue.
scx_token_card_numberCHDyesNumeric14-19ShieldConex tokenized card_number data.
scx_token_card_expirationCHDyesNumeric4ShieldConex tokenized card_expiration data.
scx_token_card_verificationnonoNumeric3-4ShieldConex tokenized card_verification data.
scx_token_bank_account_numberACHyesNumeric4-17ShieldConex tokenized bank_account_number data.
scx_token_bank_routing_numberACHyesNumeric9ShieldConex tokenized bank_routing_number data.
scx_token_emailnonoString5-100ShieldConex tokenized email data.
scx_token_first_namenonoString2-50ShieldConex tokenized first_name data.
scx_token_last_namenonoString2-50ShieldConex tokenized last_name data.
scx_token_phonenonoString2-20ShieldConex tokenized phone data.
scx_token_street_address1nonoString2-100ShieldConex tokenized street_address1 data.
scx_token_zipnonoString3-10ShieldConex 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.

BrowserMerchant ServerPayConexShieldConexShieldConex capture Card Holder Data (CHD)PII & CHD sent to for tokenizationbfidInit Transaction (with bfid)QSAPI call (with bfid)Lookup Token Data by bfidToken DataRequest data detokenizationPlaintext dataProcess transactionStore CHD token and bfid. Available through RSAPI.Postback (with CHD tokens)Postback responseopt[if postback enabled]QSAPI responseTransaction ResultBrowserMerchant ServerPayConexShieldConex

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.

Browser Merchant ServerPayConexShieldConexMerchant Reads From SCXPII & payment data sent to for tokenizationTokenisation statusInit Transaction (with bfid)Lookup Token Data by bfidToken DataStore Tokens or share with networkProcess TransactionRequest data detokenizationPlaintext dataProcess transactionStore CHD token and bfid. Available through RSAPI.Postback (with CHD tokens)Postback responseopt[if postback enabled]Transaction responseBrowserMerchant ServerPayConexShieldConex

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 NamePlaintext ValueTokenized Value
scx_token_card_number41111111111111114111118041111111
scx_token_card_expiration12224755
scx_token_card_verification555n5p
scx_token_email[email protected][email protected]
scx_token_first_nameJohnssXB
scx_token_last_nameSmithiuFSF
scx_token_phone41512344326908926159
scx_token_street_address12 Main St.v LRzG 05.
scx_token_zip90210nbB50

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"
        }
      ]
    }