PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

Quick Start

Overview

This quick start guide demonstrates the Integration Steps in action and provides a practical example of each request. This ensures that you understand the sequence of actions and how to effectively use the API endpoints provided. By reading each page of this documentation, you can expand on these steps to decide on the most effective way you are integrating with the PayConex™ V4 API.

API Key Creation

🚧

Note

If you don't have a key that you can use to create another API key, you can start by creating the first key from the PayConex™ Portal or Bluefin support will pre-create it for you.

POST /api/v4/accounts/{accountId}/api-keys

{
  "scopes": [
    "pcx:payments:card_not_present:sale",
    "pcx:iframe:*"
  ],
  "label": "My key"
}

*Required Scopes: pcx:api_key:*, pcx:api_key:create

📘

Note

You can add as many scopes as you would like as long as it is allowed by your PayConex™ account.

This is what we do here:

  1. Use the initial API key created either by Bluefin support or the PayConex™ Portal.
  2. Add the necessary scopes in order to process sale transactions and handle Checkout Component configurations.
  3. Specify the label that represents the name of the key.
  4. In response, the id and secret are returned for the newly created key (we use these in the remaining requests as the header configuration).

Also see API Key Management.

Creating Checkout Component configuration and initializing instance

In this case, we configure the settings for different payment methods (Card, ACH, Google Pay, or Mastercard Click to Pay) for our Checkout Component instance.

Checkout Component Configuration

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

{
  "label": "Card/ACH Iframe",
  "language": "ENGLISH",
  "timeout": 800,
  "allowedPaymentMethods": [
    "CARD",
    "ACH"
  ],
  "allowedParentDomains": [
    "*"
  ],
  "achSettings": {
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "capturePhone": "omit",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  "cardSettings": {
    "cvv": "required",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "capturePhone": "omit",
    "threeDSecure": "required",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  "savePaymentOption": "required",
  "currency": "USD"
}

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

For the advanced guide, see Creating a Configuration.

Initializing Instance

📘

Note

  • The {resourceId} value in the path is the id we get in the Checkout Component configuration response.

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

{
  "label": "my-instance-1",
  "reference": "shieldconex_template_reference",
  "initializeTransaction": true,
  "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

As you can see, we can also initialize a transaction at the same time and get the transactionId. To see the purposes of this transaction and how to generate it manually, refer to Initializing a Transaction.

This is an example of a response:

{
  "id": "ifri_0b3e1f98a729479581add92ec6ee6ead",
  "bearerToken": "redacted",
  "transactionId": "000000011466"
}

For more settings and details, see the following:

Loading the Checkout Component

You can quickly test the bearerToken and Checkout Component configuration using the simple client-side configuration of the component.

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

  <body>
		
    <div id="my-iframe-container"></div>
    <script type="text/javascript">

      const iframeConfig = {
        parentDivId: 'my-iframe-container',
        width: '800px',
        height: '600px'
      };

      // Assume the bearer token is obtained from your server
      const bearerToken = `bearerToken from the previous step`

      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') // NOTE: the last parameter is only for the cert environment.
    </script>
  </body>

</html>

Once the form is completed, the checkoutComplete event is triggered and we can receive the PayConex™ token for processing transactions. For more, see PayConex™ Token.

checkoutComplete Data

📘

Note

By using the Credit/Debit Test Cards based on the payment processor, we get a successful tokenization response.

{
  "reference": "iframe_instance_merchant_reference",
  "bfTokenReference": "PAYCONEX_TOKEN",
  "data": {
    "source": "PCX_IFRAME_V2",
    "accountId": "redacted",
    "type": "CARD",
    "meta": {
      "verified": false,
      "savePaymentOption": true,
      "label": "Alice's Card",
      "last4": "1111",
      "brand": "VISA",
      "reference": "iframe_instance_merchant_reference"
    },
    "resourceId": "iframe_id",
    "cvvRef": "cvvRef_redacted"
  }
}

📘

Note

For the merchant, it is bfTokenReference that is 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.

The iframe_instance_merchant_reference is replaced by the merchant reference specified at the time of iframe instance initialization.

Processing a Transaction

Now that we have the PAYCONEX_TOKEN in place, we can process a simple sale transaction using the ECOMMERCE DigitalPosProfile.

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

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

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

📘

Note

We are using the same amount as in Initializing Instance.

See Credit Card Processing for a full list of transaction types.

Use Cases as Sample Apps

See the use cases below for more structured examples that combine all these steps into separate applications, along with additional features: