PayConex™ and ShieldConex®

📘

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.

Auto Tokenization and Vaulting

Card Not Present and Card Present P2PE transactions employ the ShieldConex® Auto Tokenization feature which, in response, generates the ShieldConex® token with the PayConex™ services vaulting the Bluefin token reference both for the purposes of reissuing payments. These ShieldConex® tokens can also be used to share with business affiliates.

📘

Note

During this process, it is important that savePaymentOption is set to true. This can be accomplished by setting the iframe configuration to either contain "savePaymentOption": "required" or "savePaymentOption": "optional". This indicates whether the user has permitted the merchant to store the token for reuse and to enable auto-tokenization and vaulting.

1. Transaction Payload: The merchant server or ECR app makes a transaction request via the V4 API using the PayConex™ token generated securely by the Checkout Component.

   • See Checkout Component Workflow

2. Detokenization: The ShieldConex® Token Engine identifies and detokenizes the necessary tokens - be it the ShieldConex® or PayConex™ token.

3. Forwarding: ShieldConex® forwards the detokenized elements to the PayConex™ services, in this case the PayConex™ Gateway with the PCI-compliant environment in place.

   As mentioned in the Introduction, our systems never store the raw sensitive data. It is only forwarded to the Processor for authorization.

4. Processor Authorization: The Processor authorizes the message payload and communicates with the PayConex™ services on an approval or decline status. This is where the transaction is processed for the PayConex™ system, assigning the transaction type, transaction status, transaction report, reissuing tokens along with the other transaction metadata and much more. This enables various operations within the PayConex™ system via the V4 API or the Portal UI.

5. Auto-Tokenization: If approved, the Auto-Tokenization is performed in sync. If a reissuing token is used instead, Auto-Tokenization does not apply, as it only applies to the token generated for a CIT transaction from the Checkout Component or when a transaction is processed as Card Present. In other words, a reissuing token cannot generate and vault another. For example, the response excludes both "bfTokenReference" "shieldConexToken".

6. Vaulting: With savePaymentOption set to true and another reissuing token is not being used, the PayConex™ services vault it on the way back.

7. Response: The V4 API sends the response back to the merchant server.

📘

Compare

In comparison to this diagram, see PayConex™ and Decryptx® diagram

Checkout Component Tokenization

Once the Checkout Component is loaded and the user completes the form, the SDK interacts with PayConex™ V4 API to securely tokenize the card information. This process, driven by ShieldConex®, ensures the sensitive data is replaced with secure tokens. The V4 API returns these tokens to the application for use in future transaction processing.

This approach not only enhances security by leveraging ShieldConex® robust tokenization capabilities but also simplifies compliance with data protection regulations such as PCI DSS. By following these steps and using ShieldConex® templates, organizations can effectively safeguard sensitive information and streamline their payment processing workflows.

ShieldConex® is capable of tokenizing the following payment methods:

See Creating a Configuration.

Checkout Component Workflow

The following diagram illustrates the Checkout Component workflow with the PayConex™ V4 API and all of the payment methods available to the merchant/customer.

1. Iframe Configuration and Instance: The merchant sets up the iframe configuration and instance creation via the V4 API in accordance with the customer's preferred payment method.
2. Instance Initialization: The client side, where the Checkout Component is, fetches bearerToken from the merchant's back-end in order to load the component. It is preferable for the merchant to do this. See our use cases for guidance.
3. Payment Authentication: Based on the selected payment method, the Checkout Component establishes the communication bridge with a type of payment service for authentication that can incorporate one of these workflows:
   • Credit card, with 3DS optionally: Bluefin 3DS solution
   • ACH network
   • Google Authentication Methods, with 3DS optionally: Bluefin 3DS solution for PAN_ONLY.
   • Mastercard Click to Pay: EMV® Secure Remote Commerce (SRC) standards
4. Tokenization: Upon successful authentication, the ShieldConex® Engine tokenizes the data inputted from the Checkout Component.
5. Vaulting: The token is prepared for vaulting with savePaymentOption set to true.
6. Token Retrieval: The PayConex™ V4 API sends the PayConex™ token back to the Checkout Component. The browser Fetch API sends this token over to the Merchant's Server-Side for transaction processing.

📘

Note

Usually, the merchant creates one global iframe configuration and re-uses it to create multiple instances per customer opting for Overwriting Configuration.

📘

Note

It is crucial to highlight that the ShieldConex® template used at hand to tokenize the Checkout Component form is a template provided by Bluefin as the default template for the merchant. This way, the merchant does not need to create their own ShieldConex® templates, which helps effectively avoid data schema collisions that could occur if merchants are not careful.

However, a merchant can request their own ShieldConex® template for more customized settings with the help of Bluefin Technical Support.

PayConex™ Token vs ShieldConex® Token

Naming Convention

Throughout this documentation, we refer to Bluefin token references as PayConex™ tokens to distinguish them from ShieldConex® tokens. However, either PayConex™ or ShieldConex® token is required as part of the transaction request.

When performing transactions, these tokens ensure the security of sensitive data by keeping it protected throughout the transaction process. This differentiation is crucial for understanding the specific context and usage of tokens within the PayConex™ system versus the ShieldConex® system.

PayConex™ Token

POST /api/v4/accounts/{accountId}/payments/sale

{
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "bfTokenReference": "bft_aab...",
  ...
}

There are four kinds of PayConex™ tokens, each of which has a different purpose:

• Checkout Component: Generated via the Checkout Component. It can process one-time transactions with savePaymentOption set to false or multiple recurring transactions if set to true and processing a CNP sale as pointed out next

• Vaulted

  • Vaulted by processing a CNP sale for subsequent recurring payments with savePaymentOption enabled

  • Vaulted by Storing a card on file or Zero Amount Authorization for reissuing/recurring payments

    📘

    Reminder

    To ensure the recurring functionality, the iframe configuration has to check the savePaymentOption setting. This setting indicates whether or not the user has permitted the merchant to store the token for reuse. For instance, the value can be either "savePaymentOption": "required" or "savePaymentOption": "optional".

• Card Present: Generated by Card Present Sale with savePayment enabled

When processing transactions using this token with savePaymentOption set to true during tokenization or CP processing, the following cycle takes place:

• Tokenization and Generation: The Auto Tokenization feature tokenizes the required template fields and generates the ShieldConex® token and Bluefin token reference (PayConex™ token) for the CIT transaction.

• Vaulting and Reissuing: After vaulting, the PayConex™ token then becomes a reissuing token included in the response. Any other time the now-reissuing token is used for recurring payments, the "bfTokenReference" and "shieldConexToken" are excluded in response since a reissuing token cannot generate and trigger vaulting another reissuing token.

On the other hand, with savePaymentOption set to false (disabling the recurring functionality for CNP transactions) - this token can be used for transactions until it expires; it excludes both of the tokens in response.

Note that this type of token will expire unless it is used within 10 minutes for the first time as a CIT. Check out Processing an Authorization if you are not able to process the transaction with 10 minutes.

🚧

Note

For CNP transactions, the reissuing token is enabled via savePaymentOption whereas for CP transactions it is savePayment that determines this.

ShieldConex® Token

The ShieldConex® Token promotes two use cases for transaction processing:

• PayConex™ Use Case: Once the V4 API processes a sale/store/zero authorization with the PayConex™ token, we get a bfid with the tokenized data, which can be used as another way to perform recurring payments (MITs). In practice, this type of token can be generated with a CIT transaction using a PayConex™ token.

  • See Merchant Initiated Transactions with ShieldConex® Token for more examples.

• ShieldConex® Integrations: This token can also be used for PayConex™ transactions in case the merchant sets up an ShieldConex® iframe and tokenizes the sensitive data only through ShieldConex®, or other direct ShieldConex® integrations. A merchant can decide to store a raw ShieldConex® token if they move to a different Processor or similar. In that case, they can interact with ShieldConex® to detokenize the values and send it to a new Processor.

POST /api/v4/accounts/{accountId}/payments/sale

{
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "refundObject": {
    "refundBalance": "0.00",
    "refundIds": []
  },
  "shieldConexToken": {
    "bfid": "djI6MT...",
    "cardNumber": "5850459886792406",
    "cardExpiration": "9527"
  },
  ...
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:sale

📘

Response Format and Idempotence

The CIT transaction response automatically includes all of the values that are needed with bfid for recurring payments using the ShieldConex® token.

This token is, by default, idempotent unless the merchant wishes to reach out to the Bluefin team to create and customize their own ShieldConex® templates as mentioned above.

As the reissuing token, the ShieldConex® token only contains the tokenized cardholder data so it does not populate fields such as billingAddress and shippingAddress as transaction metadata.

The ShieldConex® bfid is also typically used to automatically update cardholder data through participating card issuers via The Account Updater API.

🚧

Note

Either bfTokenReference or shieldConexToken can be used at a time but not both as V4 API call allows the use of only one kind of token for each transaction request.

shieldConexToken

Depending on the type of payment, this property contains the sensitive data tokenized into values and the Bluefin identifier by ShieldConex®.

Credit/Debit Card Transactions

ACH Transactions