Bluefin 3D Secure SDK

Overview

📘
Bluefin 3DS Solution
Before reviewing this section, ensure you are familiar with the Bluefin 3DS solution and have met all prerequisites and requirements - in terms of setup, background knowledge, and understanding of our 3DS workflows.

3DS Protocol

3D Secure Workflow

3D Secure Requirements

Our iFrame SDK uses a 3DS SDK built-in behind the scenes.

This 3DS SDK communicates with our proprietary 3DS solution, simplifying integration for merchants with a ready-to-use tool.

For merchants who prefer to use their own iFrame or form (handling raw PAN data), our JavaScript SDK supports initiating the 3DS workflow. After the customer completes the challenge (if requested) and continues with the payment, the SDK provides the necessary 3DS parameters for transaction authorization.

These parameters should be included in a QSAPI transaction, which is recommended to be processed on the server side as shown in the sample application.

📘
Note
This use case is usually common for large ISVs with their own PCI-compliant environment where they can directly integrate with Bluefin 3DS and make use of the 3DS SDK.
Given that the SDK communicates with the 3DS endpoints from the browser, this approach is considered to be client-side 3DS integration. For the server-side(server-to-server) 3DS integration, please refer to Server-Side 3DS Integration.
The requirement is that the user must enable the 3D Secure option in the PayConex™ Portal settings as it can be seen here.

SDK Environments

Environment Name	Script Source
Testing/Certification environment	`https://cert.payconex.net/bluefin3DSSDK/bluefin3DS-SDK.js`
Staging environment	`https://staging.payconex.net/bluefin3DSSDK/bluefin3DS-SDK.js`
Production environment	`https://secure.payconex.net/bluefin3DSSDK/bluefin3DS-SDK.js`

Quick Start

The following three steps are essential and serve as a quick start guide for the developer. For the full sample application written in JavaScript and PHP, check out our Github repository.

In this quick start, we are using the certification environment for testing purposes.

Certification environment is used to:

Conduct thorough testing in the certification environment.
Simulate various transaction scenarios to ensure reliability and security.
Perform end-to-end testing, from 3DS MPI Simulation to transaction completion.

Generate Bearer Token

First, the bearer token is generated via PayConex API in the merchant's server.

The following example is in PHP.

<?php

require '../../vendor/autoload.php';

use GuzzleHttp\Client;

define("ACCOUNT_ID", "<ACCOUNT_ID>");
define("API_KEY", "<API_KEY>");

function generate3DSBearer(string $accountId, string $apiKey, string $apiHost) {
    if (empty($accountId)) {
        return "";
    }

    $clientOpts = [
        'headers' => [
            'Accept' => 'application/json',
            'Authorization' => "Basic " . $apiKey
        ]
    ];

    $httpClient = new Client($clientOpts);

    try {
        $response = $httpClient->post(
            "$apiHost/api/v4/accounts/$accountId/auth/token",
            [
                'json' => [
                    "timeout" => 1800,
                    "scopes" => ["pcx:three_d_secure:*"]
                ],
            ]
        );

        $data = json_decode($response->getBody()->getContents(), true);
	echo json_encode($data);

    } catch (\Throwable $th) {
	    echo $th;

    }
}

generate3DSBearer(ACCOUNT_ID, API_KEY, "https://api-cert.payconex.net");

?>

The API_KEY is base64-encoded API key for communicating with the PayConex API. For how to generate it and use it in this request, revisit API Authentication and Generating Bearer Token.

The $apiHost is the PayConex API environment, which can be production, certification, or staging. For more, see Environment URLs.

Load SDK

🚧
Note
For simplicity's sake, the data below is hard-coded. This data is supposed to come from the merchant form/iframe as we can see in the sample application.

Now, the merchant is load the 3DS SDK on their page.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Bluefin 3DS SDK</title>
</head>
<body>
<h1>Bluefin 3DS SDK</h1>

<!-- Include the SDK -->
<script src="https://cert.payconex.net/bluefin3DSSDK/bluefin3DS-SDK.js"></script>
<script>
    const data = {
        "card": {
            "pan": "4124939999999990",
            "expiry": "1225",
            "cvv": "111"
        },
        "purchase": {
            "currency": 'USD',
            "date": "20240628111208", // Compact timestamp
            "amount": "27.50",
            "reorderIndicator": "FIRST_TIME_ORDERED"
        },
        "challengeIndicator": "PREFER_A_CHALLENGE",
        "customer": {
            "name": "Jane Smith",
            "email": "[email protected]",
            "phone": "+14441234321",
            "billingAddress": {
                "address1": "123 Plain St",
                "address2": "West Side",
                "city": "Atlanta",
                "state": "GA",
                "zip": "90210",
                "country": "USA",
                "company": "Acme Inc."
            }
        },
        "shipping": {
            "indicator": "BILLING_ADDRESS",
            "address": {
                "address1": "123 Plain St",
                "address2": "West Side",
                "city": "Atlanta",
                "state": "GA",
                "zip": "90210",
                "country": "USA",
                "company": "Acme Inc."
            }
        }
    }
    const token = '<TOKEN HERE>'; // Note: bearer token retrieved from the back end above.
    const accountId = '<ACCOUNT ID>';
    const iFrameId = 'my_frame_id'; // the html iframe for presenting the challenge to the customer for completion - if requested.
    const apiUrl = "https://api-cert.payconex.net/api/v4";
    const sdkOptions = {};

    const bluefin3DSSDK = new Bluefin3DSSDK(token, accountId, iFrameId, apiUrl, sdkOptions);
</script>

<iframe id="my_frame_id" height="300px" width="300px"></iframe>

</body>
</html>

📘
Where does the challenge pop up if requested?
The SDK takes the iFrameId parameter where that iframe id is used to inject the challenge HTML form for the customer to authenticate and complete it.

Initiate 3DS Process

To initiate the 3DS process, the merchant simply calls the init method of a 3DS SDK instance.

    bluefin3DSSDK.init(data.card, data.purchase, data.challengeIndicator, data.customer, data.shipping, data.trace)
            .then((data) => console.log(data))
            .catch((error) => console.log(error));

let threeDS_data = await bluefin3DSSDK.init(data.card, data.purchase, data.challengeIndicator, data.customer, data.shipping)

Response

Once the 3DS workflow is completed, the init call returns the following object in response.

{
  "threeDSecureId": "tds_e65f3d6d1498440bb0e2e9f84e215f89",
  "status": "PROCESS_DONE",
  "serverTransactionID": "0fcc1fa9-f7ee-4a31-a018-ab9332614df0",
  "threeDSecure": {
    "eci": "05",
    "version": "2.2.0",
    "authenticationValue": "ji+A0S72pd/RFOrr1fwCKXKqDno=",
    "dsTransId": "2abe7b65-45cd-4a58-bcd3-8b10b8f8f50e",
    "status": "Y"
  },
  "info": {
    "cardBrand": "VISA",
    "transactionOutcomeMessage": "3DS authentication and account verification were successful.",
    "threeDSecureServerTransactionId": "0fcc1fa9-f7ee-4a31-a018-ab9332614df0",
    "challenged": false,
    "enrolled": false
  },
  "paymentDetailsReference": "pdd_99cff2d92ede47fcaae3cdf0e00356ed"
}

📘
Note
If any errors occur, the responses are driven by the 3DS set of endpoints. For all the responses, check out 3DS API Reference or SDK Reference.

Authorizing QSAPI Transaction with 3DS Data

Finally, the server processes a QSAPI transaction using the returned threeDSecure parameters from the bluefin3DSSDK.init function. These response parameters correspond to the following fields required in the QSAPI transaction.

3DS Response Parameter	QSAPI Parameter
`threeDSecure.dsTransId`	`ddds_dstransid`
`threeDSecure.authenticationValue`	`ddds_authenticationvalue`
`threeDSecure.eci`	`ddds_eci`
`threeDSecure.status`	`ddds_status`
`threeDSecure.version`	`ddds_version`

For the comprehensive descriptions of these, refer to 3D Secure | 3DS Data Parameters.

curl --location --request POST 'https://secure.payconex.net/api/qsapi/3.8' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'account_id=180000005402' \
--data-urlencode 'api_accesskey=5d7849b64dc5639d6bbac8dd44b385be' \
--data-urlencode 'response_format=JSON' \
--data-urlencode 'transaction_type=SALE' \
--data-urlencode 'tender_type=CARD' \
--data-urlencode 'card_verification=555' \
--data-urlencode 'card_expiration=1225' \
--data-urlencode 'transaction_amount=1.00' \
--data-urlencode 'card_number=4124939999999990' \
# 3DS-Authenticated Parameters
--data-urlencode 'ddds_dstransid=2abe7b65-45cd-4a58-bcd3-8b10b8f8f50e' \
--data-urlencode 'ddds_authenticationvalue=ji+A0S72pd/RFOrr1fwCKXKqDno=' \
--data-urlencode 'ddds_eci=05' \
--data-urlencode 'ddds_status=Y' \
--data-urlencode 'ddds_version=2.2.0'

🚧
ddds_dstransid and Amex cards
For Amex cards, usually a separate amexDsTransId is used. Its value has to be passed on in the ddds_dstransid field.

API Reference

Below are the main TypeScript types, interfaces, and enums used by the SDK. These define the structure of requests and responses.

SDK Initialization

The main method to initialize the SDK and start the 3DS authentication process.

Parameter	Type	Description
`card`	`Model3DSInitCardDetailsBody`	Card details
`purchase`	`ThreeDSecureBrowserAuthenticatePurchase`	Purchase details
`challengeIndicator`	`ThreeDSecureChallengeIndicator (optional)`	Challenge preference
`customer`	`Customer (optional)`	Customer details
`shippingAddress`	`ThreeDSecureBrowserAuthenticateShipping (optional)`	Shipping details
`trace`	`ThreeDSecureBrowserAuthenticateTrace (optional)`	Trace information

async init(
    card: Model3DSInitCardDetailsBody,
    purchase: ThreeDSecureBrowserAuthenticatePurchase,
    challengeIndicator?: ThreeDSecureChallengeIndicator,
    customer?: Customer,
    shippingAddress?: ThreeDSecureBrowserAuthenticateShipping,
    trace?: ThreeDSecureBrowserAuthenticateTrace,
): Promise<ThreeDSecureStatusResponse | undefined>

Card Details

Card details required for 3DS authentication.

Property	Type	Description
`pan`	`string`	Primary Account Number
`expiry`	`string`	Card expiration date (MMYY)
`cvv`	`string`	Card verification value

export interface Model3DSInitCardDetailsBody { 
    pan: string;
    /** The expiration date of the card */
    expiry: string;
    cvv?: string;
}

Purchase

Details about the purchase being authenticated.

Property	Type	Description
`currency`	`Currency`	Purchase currency (e.g., 'USD')
`date`	`string`	Purchase date/time (YYYYMMDDhhmmss)
`amount`	`string`	Purchase amount
`reorderIndicator`	`ThreeDSecureReorderIndicator`	First time or reorder
`transactionType`	`ThreeDSecureTransactionType`	Type of transaction
`deliveryTimeFrame`	`ThreeDSecureDeliveryTimeFrame`	Delivery time frame

export interface ThreeDSecureBrowserAuthenticatePurchase { 
    currency: Currency;
    date: string;
    amount: string;
    reorderIndicator?: ThreeDSecureReorderIndicator;
    transactionType?: ThreeDSecureTransactionType;
    deliveryTimeFrame?: ThreeDSecureDeliveryTimeFrame;
}

Enums

Various enums used in the SDK for currency, transaction type, and more.

Currency

Value	Description
`USD`	US Dollar

export enum Currency {
    USD = 'USD'
}

ThreeDSecureReorderIndicator

Value	Description
`FIRST_TIME_ORDERED`	First time ordered
`REORDER`	Reorder

export type ThreeDSecureReorderIndicator = 'FIRST_TIME_ORDERED' | 'REORDER';

ThreeDSecureTransactionType

Value	Description
`GOODS_SERVICE_PURCHASE`	Goods/service purchase
`CHECK_ACCEPTANCE`	Check acceptance
`ACCOUNT_FUNDING`	Account funding
`QUSAI_CASH_TRANSACTION`	Quasi cash transaction
`PREPAID_ACTIVATION`	Prepaid activation

export type ThreeDSecureTransactionType = 'GOODS_SERVICE_PURCHASE' | 'CHECK_ACCEPTANCE' | 'ACCOUNT_FUNDING' | 'QUSAI_CASH_TRANSACTION' | 'PREPAID_ACTIVATION';

ThreeDSecureDeliveryTimeFrame

Value	Description
`ELECTRONIC_DELIVERY`	Electronic delivery
`SAME_DAY_SHIPPING`	Same day shipping
`OVERNIGHT_SHIPPING`	Overnight shipping
`TWO_DAYS_OR_MOSRE_SHIPPING`	Two days or more shipping

export type ThreeDSecureDeliveryTimeFrame = 'ELECTRONIC_DELIVERY' | 'SAME_DAY_SHIPPING' | 'OVERNIGHT_SHIPPING' | 'TWO_DAYS_OR_MOSRE_SHIPPING';

ThreeDSecureChallengeIndicator

Value	Description
`NO_PREFERENCE`	No preference
`PREFER_NO_CHALLENGE`	Prefer no challenge
`PREFER_A_CHALLENGE`	Prefer a challenge
`REQUIRES_MANDATE_CHALLENGE`	Requires mandate challenge
`OVERWRITE_NO_CHALLENGE`	Overwrite no challenge

export type ThreeDSecureChallengeIndicator = 'NO_PREFERENCE' | 'PREFER_NO_CHALLENGE' | 'PREFER_A_CHALLENGE' | 'REQUIRES_MANDATE_CHALLENGE' | 'OVERWRITE_NO_CHALLENGE';

Customer and Address

Customer and billing address details.

Customer

Property	Type	Description
`name`	`string`	Customer name
`email`	`string`	Customer email
`phone`	`string`	Customer phone
`billingAddress`	`Address`	Billing address info

export interface Customer {
    name?: string;
    email?: string;
    phone?: string;
    billingAddress?: Address;
}

Address

Property	Type	Description
`address1`	`string`	Address line 1
`address2`	`string`	Address line 2
`city`	`string`	City
`state`	`string`	State
`zip`	`string`	ZIP code
`country`	`string`	Country
`company`	`string`	Company name

export interface Address {
    address1?: string;
    address2?: string;
    city?: string;
    state?: string;
    zip?: string;
    country?: string;
    company?: string;
}

Shipping

Shipping address and indicator for the transaction.

Property	Type	Description
`indicator`	`ThreeDSecureShippingIndicator`	Shipping indicator
`address`	`Address`	Shipping address info

export interface ThreeDSecureBrowserAuthenticateShipping { 
    indicator: ThreeDSecureShippingIndicator;
    address?: Address;
}

ThreeDSecureShippingIndicator

Value	Description
`BILLING_ADDRESS`	Billing address
`MERCHANT_VERIFIED_ADDRESS`	Merchant verified address
`NOT_BILLING_ADDRESS`	Not billing address
`SHIP_TO_STORE`	Ship to store
`DIGITAL_GOODS`	Digital goods
`TRAVEL_AND_EVENT_TICKETS`	Travel/event tickets
`OTHER`	Other
`PICK_UP_AND_GO_DELIVERY`	Pick up and go delivery
`LOCKER_DELIVERY`	Locker delivery

export type ThreeDSecureShippingIndicator = 'BILLING_ADDRESS' | 'MERCHANT_VERIFIED_ADDRESS' | 'NOT_BILLING_ADDRESS' | 'SHIP_TO_STORE' | 'DIGITAL_GOODS' | 'TRAVEL_AND_EVENT_TICKETS' | 'OTHER' | 'PICK_UP_AND_GO_DELIVERY' | 'LOCKER_DELIVERY';

Trace

Trace information for tracking the transaction.

Property	Type	Description
`source`	`string`	Source of the trace
`sourceRef`	`string`	Reference for the source
`sourceInstanceRef`	`string`	Instance reference for the source
`reference`	`string`	General reference
`transactionId`	`string`	Transaction ID

export interface ThreeDSecureBrowserAuthenticateTrace { 
    source?: ThreeDSecureBrowserAuthenticateTrace.SourceEnum;
    sourceRef?: string;
    sourceInstanceRef?: string;
    reference?: string;
    transactionId?: string;
}
export namespace ThreeDSecureBrowserAuthenticateTrace {
    export type SourceEnum = 'PCX_IFRAME_V2';
}

Response Types

Types returned by the SDK after authentication.

ThreeDSecureStatusResponse

Property	Type	Description
`threeDSecureId`	`string`	3DSecure transaction id
`status`	`ThreeDSecureInternalStatus`	Status of the transaction
`serverTransactionID`	`string`	Server transaction id
`threeDSecureData`	`ThreeDSecureDataResponse`	3DSecure data
`info`	`ThreeDSecureInfoResponse`	Additional info
`error`	`ThreeDSecureError`	Error details
`paymentDetailsReference`	`string`	Payment details reference

export interface ThreeDSecureStatusResponse { 
    threeDSecureId?: string;
    status?: ThreeDSecureInternalStatus;
    serverTransactionID?: string;
    threeDSecureData?: ThreeDSecureDataResponse;
    info?: ThreeDSecureInfoResponse;
    error?: ThreeDSecureError;
    paymentDetailsReference?: string;
}

ThreeDSecureInternalStatus

Value	Description
`INIT_STARTED`	Initialization started
`INIT_FAILED`	Initialization failed
`CARDHOLDER_ACCOUNT_ENROLLED`	Cardholder account enrolled
`READY_FOR_AUTH_REQUEST`	Ready for auth request
`AUTH_REQUEST_FAILED`	Auth request failed
`CHALLENGE_REQUIRED`	Challenge required
`CHALLENGE_FAILED`	Challenge failed
`CHALLENGE_DONE`	Challenge done
`PROCESS_DONE`	Process done

export type ThreeDSecureInternalStatus = 'INIT_STARTED' | 'INIT_FAILED' | 'CARDHOLDER_ACCOUNT_ENROLLED' | 'READY_FOR_AUTH_REQUEST' | 'AUTH_REQUEST_FAILED' | 'CHALLENGE_REQUIRED' | 'CHALLENGE_FAILED' | 'CHALLENGE_DONE' | 'PROCESS_DONE';

ThreeDSecureDataResponse

Property	Type	Description
`authenticationValue`	`string`	Payment system-specific value (28 chars)
`dsTransId`	`string`	Directory Server transaction ID (36 chars)
`amexDsTransId`	`string`	Amex DS transaction ID (40 chars)
`eci`	`string`	Electronic Commerce Indicator (2 chars)
`version`	`string`	Message version
`status`	`string`	3DS status from 3rd party

export interface ThreeDSecureDataResponse { 
    authenticationValue?: string;
    dsTransId?: string;
    amexDsTransId?: string;
    eci?: string;
    version?: string;
    status?: string;
}

ThreeDSecureInfoResponse

Property	Type	Description
`cardBrand`	`string`	Card brand used for 3DS
`threeDSecureServerTransactionId`	`string`	3DS Server transaction ID (36 chars)
`transactionOutcomeMessage`	`string`	3DS status from 3rd party
`enrolled`	`boolean`	Enrollment occurred in 3DS Auth process
`challenged`	`boolean`	Challenge occurred in 3DS Auth process

export interface ThreeDSecureInfoResponse { 
    cardBrand?: string;
    threeDSecureServerTransactionId?: string;
    transactionOutcomeMessage?: string;
    enrolled?: boolean;
    challenged?: boolean;
}

ThreeDSecureError

Property	Type	Description
`dsTransactionId`	`string`	DS transaction ID (36 chars)
`acsTransactionId`	`string`	ACS transaction ID (36 chars)
`threeDSecureServerTransactionId`	`string`	3DS Server transaction ID (36 chars)
`sdkTransactionId`	`string`	SDK transaction ID (36 chars)
`errorCode`	`string`	Error code (3 chars)
`errorDescription`	`string`	Error description (max 2048 chars)
`errorDetails`	`string`	Additional error details (max 2048 chars)
`errorMessageType`	`string`	Message type identified as erroneous (4 chars)
`internalMessage`	`string`	Internal message about the 3DS process

export interface ThreeDSecureError { 
    dsTransactionId?: string;
    acsTransactionId?: string;
    threeDSecureServerTransactionId?: string;
    sdkTransactionId?: string;
    errorCode?: string;
    errorDescription?: string;
    errorDetails?: string;
    errorMessageType?: string;
    internalMessage?: string;
}

Error Reference

Below are common errors you may encounter when using the SDK:

Iframe not found: The iframe element was not found in the DOM.
Card is required: Card details are missing.
Errors from endpoints:
- /accounts/{accountId}/3DS/init-card-details
- /accounts/{accountId}/3DS/{threeDSecureId}/status
- /accounts/{accountId}/3DS/{threeDSecureId}/browser-authenticate
For a comprehensive API reference, see 3DS Endpoints | API Reference.

Bluefin 3D Secure SDK

Overview

📘
Bluefin 3DS Solution

📘
Note

SDK Environments

Quick Start

Generate Bearer Token

Load SDK

🚧
Note

📘
Where does the challenge pop up if requested?

Initiate 3DS Process

Response

📘
Note

Authorizing QSAPI Transaction with 3DS Data

🚧
ddds_dstransid and Amex cards

API Reference

SDK Initialization

Card Details

Purchase

Enums

Currency

ThreeDSecureReorderIndicator

ThreeDSecureTransactionType

ThreeDSecureDeliveryTimeFrame

ThreeDSecureChallengeIndicator

Customer and Address

Customer

Address

Shipping

ThreeDSecureShippingIndicator

Trace

Response Types

ThreeDSecureStatusResponse

ThreeDSecureInternalStatus

ThreeDSecureDataResponse

ThreeDSecureInfoResponse

ThreeDSecureError

Error Reference

Overview

📘Bluefin 3DS Solution

📘Note

SDK Environments

Quick Start

Generate Bearer Token

Load SDK

🚧Note

📘Where does the challenge pop up if requested?

Initiate 3DS Process

Response

📘Note

Authorizing QSAPI Transaction with 3DS Data

🚧ddds_dstransid and Amex cards

API Reference

SDK Initialization

Card Details

Purchase

Enums

Currency

ThreeDSecureReorderIndicator

ThreeDSecureTransactionType

ThreeDSecureDeliveryTimeFrame

ThreeDSecureChallengeIndicator

Customer and Address

Customer

Address

Shipping

ThreeDSecureShippingIndicator

Trace

Response Types

ThreeDSecureStatusResponse

ThreeDSecureInternalStatus

ThreeDSecureDataResponse

ThreeDSecureInfoResponse

ThreeDSecureError

Error Reference

📘
Bluefin 3DS Solution

📘
Note

🚧
Note

📘
Where does the challenge pop up if requested?

📘
Note

🚧
ddds_dstransid and Amex cards