Bluefin 3DS Support

Overview

This section is an addition to the 3D Secure page and it specifically targets the configuration and usage of 3D Secure for the PayConex™ V4 API.

To understand the basics and purposes of 3DS protocol and Bluefin 3DS support in the PayConex™ environment, we recommend that you first familiarise yourself with some background information in the following documentation:

• 3D Secure
• Fraud Prevention

Checkout Component 3DS flow

It is essential to understand the communication bridge that takes place between the Checkout Component and 3D Secure to efficiently use this feature.

🚧

Note

3DS feature is only supported for iframe configurations selecting card payments. For more, see Creating a Configuration and Creating an Instance.

1. Challenge Initiation: The Checkout Component is loaded with bearerToken. Once the customer fills out the initial form, and if the 3DS feature is enabled, a request is sent via the PayConex™ V4 API to the issuers to initiate a challenge. At this point, the communication bridge between the issuers and the Checkout Component is established.
2. Challenge Completion: The challenge is displayed to the customer, awaiting completion.
3. Tokenization: After the customer successfully completes the challenge, the Checkout Component again communicates with PayConex™ V4 API and ShieldConex® to tokenize the sensitive data and returned 3DS data.
4. Token for Transaction Processing: The token is returned to the Checkout Component and prepared for vaulting for reuse, completing the workflow.

📘

Did you know?

This 3DS solution is also integrated in the Bluefin TECS Web for all kinds of transactions including MITs, CITs, and COF transactions. To compare the PayConex™ system and TECS Web integrations, check out TECS 3D Secure Transaction.

Requirements

The user must enable the 3D Secure option in the PayConex™ Portal settings, under the Security Features section, using our Bluefin 3DS solution as the 3DS service. In the PayConex™ Portal, this service is labeled and referred to as BLUEFIN, as shown in the example below.

🚧

Note

The Bluefin Administrators must first enable this security feature for iframe configurations to support and integrate 3D Secure. If you do not see it in the Settings, please reach out to the Bluefin Technical Team for assistance.

Configuring 3D Secure

In the V4 API environment, 3D Secure is enabled and configured during the setup of the iframe configuration and instance. This can also be done at the time of iframe instance creation, where it is also possible to override a configuration. Once the bearerToken is generated, the Checkout Component instance is securely loaded.

🚧

Note

threeDSecureInitSettings are individual 3D Secure settings that are defined per instance.

The threeDSecureInitSettings parameter is required only with with threeDSecure set to "required" and one of the allowedPaymentMethods being "CARD" or "GOOGLE_PAY".

Iframe Configuration

To support 3D Secure, we must first set threeDSecure to "required" in our iframe configuration. Alternatively, it can be overwritten at the time of instance creation. This is defined in cardSettings.

POST /api/v4/accounts/{accountId}/payment-iframe

{
  "label": "Multi-Payment iframe",
  "language": "ENGLISH",
  "timeout": 600,
  "allowedPaymentMethods": [
    "CARD"
  ],
  "allowedParentDomains": [
    "tools.bluefin.com"
  ],
  "cardSettings": {
    "cvv": "required",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "capturePhone": "omit",
    "threeDSecure": "required",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  "currency": "USD",
  "savePaymentOption": "required"
}

*Required Scopes: pcx:iframe:*, pcx:iframe:create

📘

Also See

Before digging into the iframe configuration request, make sure you have brushed up on Iframe Configuration.

Iframe Instance

When creating an iframe instance, along with many other options comes the main 3DS initialization settings that qualify for 3D Secure chargeback protections. The following endpoint returns the bearerToken that loads our Checkout Component.

POST /api/v4/accounts/{accountId}/payment-iframe/{resourceId}/instance/init

{
  "label": "my-instance-1",
  "amount": "20",
  "threeDSecureInitSettings": {
    "transactionType": "GOODS_SERVICE_PURCHASE",
    "deliveryTimeFrame": "ELECTRONIC_DELIVERY",
    "threeDSecureChallengeIndicator": "NO_PREFERENCE",
    "reorderIndicator": "FIRST_TIME_ORDERED",
    "shippingIndicator": "BILLING_ADDRESS"
  }
}

*Required Scopes: pcx:iframe:instance:*, pcx:iframe:instance:create

📘

Also See

Before digging into the iframe instance request, make sure you have brushed up on Iframe Instance Creation.

Iframe Instance Overwriting cardSettings

As mentioned above, it is possible to configure the 3DS settings during the iframe instance creation.

POST /api/v4/accounts/{accountId}/payment-iframe/{resourceId}/instance/init

{
  "label": "my-instance-1",
  "amount": "20",
  "cardSettings": {
    "cvv": "required",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "capturePhone": "omit",
    "threeDSecure": "required",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  "threeDSecureInitSettings": {
    "transactionType": "GOODS_SERVICE_PURCHASE",
    "deliveryTimeFrame": "ELECTRONIC_DELIVERY",
    "threeDSecureChallengeIndicator": "NO_PREFERENCE",
    "reorderIndicator": "FIRST_TIME_ORDERED",
    "shippingIndicator": "BILLING_ADDRESS"
  }
}

*Required Scopes: pcx:iframe:instance:*, pcx:iframe:instance:create

Here is a breakdown of the 3D Secure settings shown in the example request.

cardSettings.threeDSecure

threeDSecureInitSettings

transactionType

Each option provides context about the nature of the transaction, helping to ensure accurate processing and risk assessment.

deliveryTimeFrame

As the setting name suggests, this is the time for the goods to be delivered. The descriptions are pretty much self-explanatory given the options.

threeDSecureChallengeIndicator

reorderIndicator

This setting indicates whether the order is new or was ordered before.

shippingIndicator

3D Secure Transaction Processing

Finally, we include the token returned by the Checkout Component via the JavaScript SDK and we are set to make a transaction request. To see how to get this token, check out Using the SDK section and the checkoutComplete event.

📘

Note

The PayConex™ token already includes the 3DS-Authenticated data, so we simply use it in the transaction request.

Request

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

{
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5.00",
    "currency": "USD"
  }
}

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

Response

The transaction request generates a result similar to the following when it comes to 3D Secure metadata.

{
  "transactionId": "000000048726",
  "status": "CAPTURED",
  "timestamp": "2025-04-10T20:01:32.000000Z",
  "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"
    }
  },
  "trace": {
    "history": [
      {
        "action": "transaction",
        "requestId": "784232bb-e082-4701-a3bb-4f7a955577fc",
        "correlationId": "24c2269c-e8a9-49dc-99ba-a907e6a8a325",
        "timestamp": "2025-04-10T15:01:29-05:00"
      }
    ],
    "networkTransactionId": "015100666209509G467"
  },
  "amounts": {
    "currency": "USD",
    "approved": "5.00",
    "requested": "5.00",
    "balance": "5.00"
  },
  "auth": {
    "code": "OK5137",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Jane Smith",
    "last4": "9990",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "STANDARD"
  },
  "threeDSecure": {
    "protectionEnabled": true,
    "eci": "05",
    "status": "Y",
    "statusResult": "Authenticated",
    "version": "2.2.0",
    "token": "ji+A0S72pd/RFOrr1fwCKXKqDno=",
    "transactionId": "2abe7b65-45cd-4a58-bcd3-8b10b8f8f50e"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "5.00"
  }
}

threeDSecure

As part of the transaction metadata shown in the example response above, this is 3DS-related data indicating whether 3DS was enabled for that certain transaction including status, version, token, etc.

Here is a comprehensive breakdown.

Test Card Numbers

The following set of test card numbers can be used to evaluate the different ECI values and 3DS statuses. Where the status and ECI are a ? the card number is triggering a challenge, the results will depend on the option selected in the dropdown on the challenge dialog set in the iFrame options.

📘

Note

These cards are intended solely for testing purposes and should only be used in the Testing/Certification environment. They allow merchants and developers to simulate real-life scenarios to gain a better understanding of how 3D Secure operates.

3D Secure 2.0 Test Cards