PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

PayConex™ API Introduction

Welcome to Bluefin's PayConex™ V4 API Documentation

Overview

The PayConex™ Gateway is a comprehensive, PCI compliant, full-service payment solution. By integrating the security features of Bluefin ShieldConex® and Decryptx®, our powerful API suite offers a wide range of functionalities that streamline and secure your payment processing.

As a web service, our API is designed to be cross-platform, enabling seamless integration with various operating systems and devices.

Bluefin introduces the PayConex™ V4 API, a versatile REST API providing a variety of endpoints and standard HTTP methods that connect to various PayConex™ services, thus serving as an HTTPS communication bridge. This API offers merchants as well as developers a flexible solution for integrating the PayConex™ Gateway into their applications. Below, we highlight the most notable key features of the PayConex™ REST API and the PayConex™ Gateway.

📘

Beta API

The PayConex™ REST API is a Bluefin's new beta PayConex™ API built as a collection of various Bluefin Services constituting a comprehensive payment solution. If you are looking for our legacy APIs, please refer to PayConex™ API SUITE.

Key Features

Integration with ShieldConex® and Decryptx®

  • Enhanced Security and Reduced PCI Scope: Implementing these Bluefin services within our payment gateway offers numerous benefits, from enhanced security through efficient data flow to reduced PCI scope. The PayConex™ APIs implement these by default without subjecting merchants to directly use them. This eliminates security dependencies within your organization and allows everyone to use our API more efficiently.
  • Compliance: Helps in maintaining compliance with various data protection regulations, such as PCI DSS, GDPR and CCPA.
  • Efficiency: Streamline payment processes while maintaining high levels of security and data protection.

Bluefin Hosted Checkout Components

  • Easy Integration: Use our secure, pre-built Checkout Component UI via our SDK, designed for seamless integration into your existing systems.
  • Security: These components are hosted on Bluefin's servers and handle all payment data input through an HTML iframe, ensuring that no sensitive credit card data reaches your servers.
  • Flexible Management and Configuration: With a set of API endpoints, you can easily configure and create iframe payment instances, and effectively overwrite the configuration for a specific instance per customer. See Creating an Instance.
  • Tokenization: Once the form is completed, it securely tokenizes the information for CNP transactions by communicating with the ShieldConex® tokenization service and utilizes a payment authentication service based on the type of payment method, e.g. 3DS(Credit or Debit Card), Google Authentication Methods(Google Pay), ACH(Bank Information), Mastercard Click to Pay. After tokenization, a transaction is supposed to be processed during the PayConex™ token life-span (within 10 minutes).
  • Saved Cards: The Checkout Component enables the customer to securely save their card data by checking the Save payment method. During the initialization of the iframe instance, the merchant supplies the saved token references, which facilitates faster checkout. The customer is still required to confirm their CVV.
  • Reference Documentation: Comprehensive documentation and reference materials are available to assist and support you with the integration.

Tokenization/Encryption

  • ShieldConex® does not store any sensitive cardholder data. Instead, it uses tokenization/detokenization on its vaultless tokens for online PII, PHI, payments and ACH account data. These tokens can be securely utilized or stored on the merchant's server, significantly reducing the vendor's or merchant's PCI footprint. However, if the merchant loses these tokens, they cannot be recovered.

  • Decryptx® employs point-to-point encryption (P2PE) solution with SRED at POS (hardware-based encryption at the terminal).

  • Auto Tokenization

    • Obtain tokens for cardholder data from both card present CP and card not present CP/CNP P2PE transactions. These tokens can be used later for reissuing.

    • Processing CP and CNP transactions using PayConex™ V4 API makes it simple to receive ShieldConex® and PayConex™ tokens, which merchants can use for recurring payments.

  • Bluefin Identifier Token Subscription: The account updater API gives merchants the ability to create a ShieldConex® subscription using a bfid token. This token is detokenized securely for the card issuers to issue a notification via webhooks.

Versatile Transaction Processing

  • Security: Bluefin ShieldConex® ensures that no sensitive card information is ever stored on your servers. Meanwhile, Bluefin's Decryptx® incorporates the point-to-point encryption (P2PE) solution with both significantly reducing the PCI scope.
  • Credit Card Transactions: Before processing, CNP transactions primarily rely on ShieldConex® for security, while CP transactions use the Decryptx® P2PE solution to extract and decrypt the sensitive card data information. This data is encrypted at the terminal on the hardware level using SRED. CNP transactions include eCommerce and MOTO, whereas CP ones encompass SWIPE, NFC, CONTACTLESS and CONTACT. Make sure to check out the exception of P2PE MOTO transaction.
  • Transaction Types: Our gateway supports a variety of the most common transaction types used on a day-to-day basis such as sale, authorization, store, capture, refund and credit.
  • Store & Convert: Bluefin offers a STORE transaction type, enabling vendors and merchants to convert all stored credit card and ACH numbers into secure tokens through the API.
  • Level 2/3 Data: PayConex™ transaction processing also facilitates Level 2 and Level 3 data as additional fields of a transaction.
  • Dynamic Descriptors: PayConex™ V4 API adds managing dynamic descriptors with using them in a transaction.
  • Data Projection: PayConex™ V4 API implements projection, which means selecting and returning only the necessary fields from a JSON object instead of sending the entire dataset. Thereby, we are reducing the network bandwidth and memory usage for the merchant's integrations as their applications scale. For more information and examples, see Get a Transaction Metadata | Data Projection
  • Detailed Guides: Comprehensive examples are provided to help you make various transaction requests.

Transaction Management

  • Endpoint Access: Access a set of endpoints for transaction management, including initializing, retrieving or modifying transaction metadata, viewing transaction history, and issuing refunds and captures.
  • Real-Time Monitoring: Monitor transactions in real time with detailed transaction status.

API Key Management

  • Security: Efficiently manage your PayConex™ account's API keys for enhanced security and control.
  • Roles and Permissions: Assign roles and permissions, both referred to as scopes, to ensure that only authorized personnel can access and manage API keys. This helps in building and maintaining a secure and well-organized merchant business.
  • Documentation: Step-by-step instructions on how to generate, rotate, and manage API keys.

3DS Support

  • Security Backbone: Besides the vaultless tokenization solution by ShieldConex®, Bluefin provides one of the security backbones for processing online CNP transactions, with iframe configurations that can fully integrate 3DS as a feature of PayConex™.
  • Fraud Prevention: Implement 3DS to enhance fraud prevention and secure customer authentication.
  • User Experience: Ensure a smooth user experience while maintaining high security standards.
  • 3DS MPI Simulation: Bluefin 3DS Solution can be simulated in the certification environment for testing purposes.

Account Updater API

  • Allows developers and merchants to automatically update cardholder data through participating card issuers. This ensures that recurring transactions use the most recent account information, thus reducing the risk of declined transactions due to outdated card details.

Webhooks API

  • Enables developers to set up webhooks to receive real-time updates on cardholder data changes set up via the Account Updater API. Thus, instead of continuously issuing API requests on a time interval to check for updates, webhooks notify you instantly when specific events occur, ensuring that you always have the latest information.

BluePOS API

  • Equips an ISV with a set of REST API endpoints for controlling PCI-Validated P2PE PAX devices by triggering commands for managing the state of a device or for transaction processing remotely in the Semi-Integrated Mode. This workflow is securely facilitated via HTTP and the WebSocket protocol.

PCI Scope

The Checkout Component reduces PCI scope by enabling a merchant to outsource the capture of sensitive credit and debit card payment data to Bluefin.

With our Checkout Component solution, the merchant never handles card payment data directly. The merchant server creates iframe configuration and initiates iframe instance to load the Checkout Component SDK with bearerToken. The SDK captures the data, communicates with V4 API, sends it for encryption(tokenization) to ShieldConex®, and releases an encrypted token (bfTokenReference) to the browser and the JavaScript controller (by triggering the checkoutComplete event), which is then used with the PayConex™ V4 API for further payment processing.

🚧

HTTPS Required

The Checkout Component iframe must be hosted on an HTTPS domain.

Online Transaction Flow with Checkout Component and the V4 API

Online Transaction Flow with Checkout Component and the V4 API

📘

Note

This diagram introduces you to the Online Payments workflow and the PCI Scope Reduction. For more detailed diagrams, see Checkout Component Overview and PayConex™ and ShieldConex®.

Different Environments Impacted by PCI Scope

In the diagram above, the following container names represent the different environments impacted by PCI scope:

  • The V4 API allows creating an iframe configuration and instance for loading the Checkout Component (SDK). The API also handles transaction processing. This is exclusively controlled by Bluefin, and thus fully PCI-compliant.
  • The Merchant Server handles the encrypted PayConex™ tokens(bfTokenReferences) to process a transaction. The last four digits of the card number, card brand, and expiration data are included as transaction metadata with plenty of other non-sensitive data/information. This part is controlled by the merchant but still PCI-compliant in this case as Bluefin encrypts/tokenizes the sensitive data and returns it as a PayConex™ token.
  • The User's Browser is the end user's environment which is beyond the control of both the merchant and Bluefin. This is where the JavaScript SDK and Controller live.

Integration and Usage

Our documentation walks you through:

  • Integration Steps: Instructions and requirements to get started with integrating the PayConex™ Gateway and V4 API.
  • API Authentication: Comprehensive details on how to authenticate API requests.
  • Practical Tutorials and Guides: Sample code, tutorials, and guidelines for rendering Checkout Components, initializing transactions and processing transactions, helping you effectively make the most use of PayConex™ V4 API functionalities based on your needs.
  • Use Cases: Describes the most common real-world use case scenarios in great detail and provides some sample applications.
  • Reference Guides: If you are looking for more functionalities, these guides go into even more features of the V4 API including Level 3 Profiles, Processing Level 2 and Level 3 data, Customer and Merchant Initiated Transaction as well as others.

Explore these resources to fully harness the capabilities of Bluefin's PayConex™ Gateway and optimize your payment processing operations through the V4 API.

Summary

By leveraging the powerful features of the PayConex™ Gateway and the security of ShieldConex® and Decryptx®, you can streamline your payment processes, enhance security and reduce compliance burdens.

Start integrating today to take full advantage of our comprehensive payment solution and take your transaction processing to the next level.

See the following for more introductory information on ShieldConex® and Decryptx®: