PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

Using the SDK

Overview

During the checkout process, the Checkout Component SDK is the main HTTP client between the customer and the Bluefin systems so that the customer passes the authentication process if required and the sensitive data is securely tokenized for further transaction processing.

📘

Also See

For the illustrated descriptions, see

SDK Setup and Loading the Checkout Component on the Page

To integrate the Checkout Component into your web application, you need to include the SDK in your HTML file. Use the appropriate script URL for either the certification environment or the production environment.

Certification Environment

<script src="https://cert.payconex.net/iframe-v2/iframe-v2.0.0.min.js"></script>

Production Environment

<script src="https://secure.payconex.net/iframe-v2/iframe-v2.0.0.min.js"></script>

Initialization

After the browser loads the SDK, you need to call the SDK init method to set up the HTML iframe. This method initializes the Checkout Component with your front-end configuration, authentication token and optional callback functions.

window.IframeV2.init(iframeConfig, bearerToken, callbacks, correlationId, devServer);

  • iframeConfig (object) (required)

    • This object contains the configuration settings for the iframe.
    • parentDivId (string) (required)
      • The ID of the parent div where the checkout component is loaded.
    • width (string) (optional)
    • height (string) (optional)

  • bearerToken (string) (required)

    • The bearer token generated by creating an iframe configuration and an iframe instance via the PayConexâ„¢ V4 API.

  • callbacks (object) (optional)

    • An object containing callback functions to handle various events. See Callback Example

  • correlationId (string) (optional)

    • The correlationId is used for debugging by our Bluefin team so we can easily spot any issues and provide better technical support. If this parameter is not passed, we generate one. For more on this field when merchant-specified, refer to API Endpoint Overview | Correlation Identifier.

  • devServer (string) (optional): default: "https://checkout.payconex.net".

    • The URL that the Checkout Component communicates with to load the static assets such as imgs, style, etc.
    • "https://checkout.payconex.net" | "https://checkout-cert.payconex.net".

Events

The SDK provides several events that enable you to to manage different stages of the checkout process:

Event NameDescription
iframeLoadedTriggered when the iframe is loaded and ready.
checkoutCompleteTriggered when the checkout process is completed.
errorTriggered when an error occurs.
timeoutTriggered when a timeout occurs.

Callback Example

const callbacks = {
  iframeLoaded: function () {
    console.log('Iframe loaded');
  },
  checkoutComplete: function (data) {
    console.log('Checkout complete:', data);
  },
  error: function (data) {
    console.log('Error:', data);
  },
  timeout: function (data) {
    console.log('Timeout:', data);
  },
};

checkoutComplete

This event is triggered once the Checkout Component successfully retrieves the PayConexâ„¢ token along with some other payment/checkout and tokenization-related metadata. Here are some samples of response data that this event picks up from the V4 API based on the respective payment method.

Credit/Debit Card

Here is an example of the checkoutComplete data with successful 3DS authentication.

{
    "reference": "3c8367296ae3391be1fdc0ca0bb8ea001111",
    "bfTokenReference": "bft_abfddede2a0b43b789ae570955fd5e9a",
    "data": {
        "source": "PCX_IFRAME_V2",
        "accountId": "111111111222",
        "type": "CARD",
        "meta": {
            "verified": false,
            "savePaymentOption": false,
            "last4": "9990",
            "brand": "VISA",
            "reference": "3c8367296ae3391be1fdc0ca0bb8ea001111",
            "threeDSecure": {
                "eci": "05",
                "version": "2.2.0",
                "authenticationValue": "ji+A0S72pd/RFOrr1fwCKXKqDno=",
                "dsTransId": "2abe7b65-45cd-4a58-bcd3-8b10b8f8f50e",
                "status": "Y"
            }
        },
        "resourceId": "ifr_24dcee1874bb44b18ad573d1becdd55d",
        "cvvRef": "cvv_9dfb5887-1ac8-440f-9c8a-1ff74241e634"
    }
}

📘

Note

Note that the reference is merchant-specified. See Creating an Instance | General Settings | reference.

Bank Account/ACH Payment Checkout

{
    "reference": "3c8367296ae3391be1fdc0ca0bb8ea001111",
    "bfTokenReference": "bft_1046abd967b34c2a924dd3537e7d5088",
    "data": {
        "source": "PCX_IFRAME_V2",
        "accountId": "111111111222",
        "type": "ACH",
        "meta": {
            "verified": false,
            "savePaymentOption": false,
            "last4": "7890",
            "brand": "ACH",
            "reference": "3c8367296ae3391be1fdc0ca0bb8ea001111"
        },
        "resourceId": "ifr_d4162587b72e4db08ec42017e9d4a8b4"
    }
}

Google Pay

{
  "reference": "c73bcdcc-2669-4bf6-81d3-e4ae73fb11fd",
  "bfTokenReference": "bft_fda0f58e4b5647cba75a21b7559e64f1",
  "data": {
    "source": "PCX_IFRAME_V2",
    "accountId": "120615523104",
    "iframeId": "ifr_2a08d8fc30b64a8a9d8b9f0ec37b59c9",
    "type": "GOOGLE_PAY",
    "meta": {
      "verified": false,
      "savePaymentOption": true,
      "label": "Jane's Card"
    },
    "googlePayCheckoutData": {
      "payload": "eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJFUzI1NiIsImtpZCI6Ijk4YjEwOThjMmY2OWYyYTE4MmY4OWQ2ZGEzMGRmMjhhIn0.eyJpc3MiOiJodHRwczovL2FwaS5wYXljb25leC5uZXQiLCJpYXQiOjE2NzA5MzUwMzAsInBheWxvYWQiOnsic291cmNlIjoiUENYX0lGUkFNRV9WMiIsImFjY291bnRJZCI6IjEyMDYxNTUyMzEwNCIsImlmcmFtZUlkIjoiaWZyXzJhMDhkOGZjMzBiNjRhOGE5ZDhiOWYwZWMzN2I1OWM5Iiwic2N4UGFydG5lciI6InN1YnBhcm50ZXIzIiwidHlwZSI6IlNISUVMRENPTkVYX0NBUkQiLCJtZXRhIjp7Imxhc3Q0IjoiMDIyMiIsImJyYW5kIjoiVklTQSIsInZlcmlmaWVkIjpmYWxzZX0sInRva2VuIjp7Im1lc3NhZ2VJZCI6IjEyMDIyMTAyMDE1MDgwOTEwMTE5MjQ0OTgiLCJyZWZlcmVuY2UiOiJtZXJjaGFudFJlZjEyMyIsImJmaWQiOiJkakk2TVRJd01qSXhNREl3TVRVd09EQTVNVEF4TVRreU5EUTVPSHhtTldKaU5XTmxNR1kxWmpJMVptSTRPRE15WlRSaVl6Y3paamcwTXpCbU9YeDhmQSIsInZhbHVlcyI6W3sibmFtZSI6InNjeF90b2tlbl9jYXJkX251bWJlciIsInZhbHVlIjoiNDExMTExMjIzMTYwMTExMSJ9XX19fQ.fblMeuL-Dbqm00sLhxyJPJaMYPiT-5ZeElsRcw_ZM8B2C4ajqLvyF0fSLwGevh8DOAdytmPW7Y8_YL_hQuJM0w"
    },
    "token": {
      "messageId": "1202210201508091011924498",
      "reference": "merchantRef123",
      "bfid": "djI6MTIwMjIxMDIwMTUwODA5MTAxMTkyNDQ5OHxmNWJiNWNlMGY1ZjI1ZmI4ODMyZTRiYzczZjg0MzBmOXx8fA",
      "values": [
        {
          "name": "scx_token_customer_name",
          "value": "5850459886792406"
        }
      ]
    }
  }
}

Mastercard Click to Pay

{
  "reference": "c73bcdcc-2669-4bf6-81d3-e4ae73fb11fd",
  "bfTokenReference": "bft_fda0f58e4b5647cba75a21b7559e64f1",
  "data": {
    "source": "PCX_IFRAME_V2",
    "accountId": "120615523104",
    "iframeId": "ifr_2a08d8fc30b64a8a9d8b9f0ec37b59c9",
    "type": "MC_CLICK_TO_PAY",
    "meta": {
      "verified": false,
      "savePaymentOption": true,
      "label": "Jane's Card"
    },
    "token": {
      "c2pCheckoutData": {
        "checkoutResponse": "eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJFUzI1NiIsImtpZCI6Ijk4YjEwOThjMmY2OWYyYTE4MmY4OWQ2ZGEzMGRmMjhhIn0.eyJpc3MiOiJodHRwczovL2FwaS5wYXljb25leC5uZXQiLCJpYXQiOjE2NzA5MzUwMzAsInBheWxvYWQiOnsic291cmNlIjoiUENYX0lGUkFNRV9WMiIsImFjY291bnRJZCI6IjEyMDYxNTUyMzEwNCIsImlmcmFtZUlkIjoiaWZyXzJhMDhkOGZjMzBiNjRhOGE5ZDhiOWYwZWMzN2I1OWM5Iiwic2N4UGFydG5lciI6InN1YnBhcm50ZXIzIiwidHlwZSI6IlNISUVMRENPTkVYX0NBUkQiLCJtZXRhIjp7Imxhc3Q0IjoiMDIyMiIsImJyYW5kIjoiVklTQSIsInZlcmlmaWVkIjpmYWxzZX0sInRva2VuIjp7Im1lc3NhZ2VJZCI6IjEyMDIyMTAyMDE1MDgwOTEwMTE5MjQ0OTgiLCJyZWZlcmVuY2UiOiJtZXJjaGFudFJlZjEyMyIsImJmaWQiOiJkakk2TVRJd01qSXhNREl3TVRVd09EQTVNVEF4TVRreU5EUTVPSHhtTldKaU5XTmxNR1kxWmpJMVptSTRPRE15WlRSaVl6Y3paamcwTXpCbU9YeDhmQSIsInZhbHVlcyI6W3sibmFtZSI6InNjeF90b2tlbl9jYXJkX251bWJlciIsInZhbHVlIjoiNDExMTExMjIzMTYwMTExMSJ9XX19fQ.fblMeuL-Dbqm00sLhxyJPJaMYPiT-5ZeElsRcw_ZM8B2C4ajqLvyF0fSLwGevh8DOAdytmPW7Y8_YL_hQuJM0w",
        "idToken": "N/A",
        "network": "mastercard",
        "headers": {
          "merchantTransactionId": "0a4e0d3.34f4a04b.484390fe23fa6378e6039fbf914958ae9e1ff98f",
          "xSrcCxFlowId": "34f4a04b.5ee6b49f-20e8-438e-9e89-59a837fcc6c7.1630307453"
        }
      }
    }
  }
}

📘

Note

For the merchant, it is bfTokenReference that is crucial and used for secure transaction processing. The merchant can also use data.meta.savePaymentOption to determine if they are allowed to pass this token on for recurring payments.

Example Usage

Here's a full example incorporating all the elements:

<!DOCTYPE html>
<html>
<head>
  <title>IframeV2 Example</title>
  <script src="https://secure.payconex.net/iframe-v2/iframe-v2.0.0.min.js"></script>
</head>
<body>
  <div id="my-iframe-container"></div>
  <script>
    const iframeConfig = {
      parentDivId: 'my-iframe-container',
      width: '800px',
      height: '600px'
    };
        
    // Assume the bearer token is obtained from your server
    const bearerToken = 'YOUR_BEARER_TOKEN';
        
    const callbacks = {
      iframeLoaded: function () {
        console.log('Iframe loaded');
      },
      checkoutComplete: function (data) {
        console.log('Checkout complete:', data);
      },
      error: function (data) {
        console.log('Error:', data);
      },
      timeout: function (data) {
        console.log('Timeout:', data);
      },
    };
        
     window.IframeV2.init(iframeConfig, bearerToken, callbacks, null, 'https://checkout-cert.payconex.net');
  </script>
</body>
</html>