Creating an Instance

Overview

Making an API call to create an instance of a Checkout Component is a crucial step in capitalizing on an iframe configuration. It is the call that returns the bearer token value that is used to render the Checkout Component within an HTML iframe.

However, getting the bearer token is just one of the features of this endpoint. Another important feature to note is that this endpoint also provides parameters you can use to pre-fill form fields, like billing and shipping address fields for your customers, and also the ability to change a configuration when the instance is being created. This may be required if you want a specific instance of the Checkout Component to be a bit different than the standard configuration that is set up. The purpose is to set up settings specific to the customer's own iframe instance, eliminating the need for repetitive PATCH operations on an iframe configuration. The PATCH operators may as well lead to a lot of conflicts.

Similar to our guide on creating a configuration, this guide is written to help you have a deeper understanding of the different options at your disposal when you create an instance of a Checkout Component.

📘

Note

To find out which parameters are required or optional and their values, see the comprehensive API Reference.

API Request

After you create a configuration, the only parameter required in the body when an instance is created is the label parameter in the general settings - see below.

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

📘

Note

The {accountId} value in the path would be the PayConex™ account ID number.

The {resourceId} value would be the id value of a previously created Checkout Component configuration.

{
  "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

🚧

Note

With no amount field specified, the transaction is considered zero-amount and is used with savePaymentOption checked.

The other request parameters provided by this API give you the ability to change the default behavior of the original Checkout Component configuration.

The threeDSecureInitSettings parameter is required only with threeDSecure set to "required" and one of the allowedPaymentMethods being "CARD" or "GOOGLE_PAY". For more on 3D Secure and how to use it, check out Bluefin 3DS Support.

General Settings

The general settings are a set of configuration options that define specific behaviors of a Checkout Component.

bfTokenReferences

A list of token references that are used as saved cards so that the customer doesn't need to re-input their card data during their next checkout in the future. This means a faster checkout - with only a few clicks to complete their purchase. The customer is still required to confirm their CVV.

The customer is required to check the Save payment method in order to have the token reference reusable as a saved card. This allows the customer to consent to the secure encryption and storage of their sensitive card data.

The merchant must ensure to process an authorization or sale transaction within 10 minutes (token's lifespan). Otherwise, the token cannot be used as a saved card and is ignored in the Checkout Component.

To see the Checkout Component interface with the saved cards, refer to Customer Checkout | Credit/Debit Card.

📘

PCI Scope

These tokens can be securely utilized or stored on the merchant's server, significantly reducing the vendor's or merchant's PCI footprint.

The merchant/developer must use data.meta.savePaymentOption to determine if they are allowed to store the token reference in their database as saved cards. See Using the SDK | Credit/Debit Card.

For more information, refer to PayConex™ API Introduction and PayConex™ and ShieldConex®.

🚧

Note

This feature is primarily used with the allowedPaymentMethods being Bluefin's CARD as Google Pay and Mastercard Click to Pay have their own implementation of saving card data and managing it.

Prior to the checkout, it is up to the merchant to indicate to the customer whether they are using their card reference for MIT recurring payments or saved cards.

Request Example

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

{
  "label": "my-instance-1",
  "amount": "20",
  "bfTokenReferences": [
    "bft_fda0f58e4b5647cba75a21b7559e64f1",
    "bft_3caf8413e99443d18c379399beff708c"
  ],
  "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

customer

The customer object allows you to pre-fill the Checkout Component form elements with your customer-related information such as name, email, phone, and billing address.

shippingAddress

The shippingAddress object allows you to pre-fill the Checkout Component form elements with the customer's shipping address information.

achSettings

The achSettings object is a set of configuration options that define specific behaviors of the Checkout Component when a user selects the ACH option as their preferred payment method.

This is required only if ACH is one of the items in the allowedPaymentMethods array.

cardSettings

The cardSettings object is a set of configuration options that define specific behaviors of the Checkout Component when a user selects the credit card option as their preferred payment method.

Like the rest of the individual payment settings, this setting is required only if CARD is one of the allowedPaymentMethods array.

threeDSecureInitSettings

The threeDSecureInitSettings object allows you to initialize the Checkout Component with information required to be sent when trying to qualify for 3D Secure chargeback protections.

🚧

Note

This setting is required only with threeDSecure set to "required" and one of the allowedPaymentMethods being "CARD" or "GOOGLE_PAY".

📘

Integrating 3D Secure

For more on 3D Secure and how to use it, check out Bluefin 3DS Support.

clickToPaySettings

The Click to Pay settings are a set of configuration options that define specific behaviors of the Checkout Component when a user selects Click to Pay as their preferred payment method.

This setting is required only if CLICK_TO_PAY is one of the items in the allowedPaymentMethods array.

📘

Note

These parameters are directly integrated as the essential Click to Pay parameters. See Mastercard Click to Pay JavaScript Methods.

googlePaySettings

The Google Pay settings are a set of configuration options that define specific behaviors of the Checkout Component when a user selects Google Pay as their preferred payment method.

This setting is required only if GOOGLE_PAY is one of the items in the allowedPaymentMethods array.

📘

Note

These parameters are directly integrated as the essential GPay parameters via the Google Pay web API. Also see Google Pay Setup.

🚧

Important

• Make sure that you apply your existing risk checks and controls for payment transactions to Google Pay transactions. Google Pay validation and fraud checks are not intended to replace your risk management processes.
• If you support PAN_ONLY, ensure that you trigger 3D Secure (step-up authentication) for Google Pay PAN_ONLY transactions in the same way that you trigger 3D Secure for normal card transactions.

Example Request Body

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

{
  "allowedPaymentMethods": [
    "CARD",
    "ACH",
    "GOOGLE_PAY",
    "CLICK_TO_PAY"
  ],
  "label": "Multi-Payment iframe instance",
  "reference": "c73bcdcc-2669-4bf6-81d3-e4ae73fb11fd",
  "initializeTransaction": true,
  "amount": "20",
  "timeout": 600,
  "currency": "USD",
  "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."
    }
  },
  "shippingAddress": {
    "address1": "123 Plain St",
    "address2": "West Side",
    "city": "Atlanta",
    "state": "GA",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Jane Smith",
    "recipientPhone": "1234567890"
  },

  "cardSettings": {
    "cvv": "required",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "capturePhone": "omit",
    "threeDSecure": "required",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  
  "achSettings": {
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "capturePhone": "omit",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  "clickToPaySettings": {
    "srcDpaId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "dpaName": "PayConex",
    "dpaPresentationName": "PayConex App",
    "allowedCardBrands": [
      "VISA",
      "MASTERCARD",
      "AMERICAN_EXPRESS",
      "DISCOVER",
      "CHINA_UNION_PAY"
    ]
  },
  "googlePaySettings": {
    "merchantId": "12345678901234567890",
    "merchantName": "Demo Merchant",
    "billingAddressRequired": true,
    "shippingAddressRequired": true,
    "emailRequired": true,
    "billingAddressParameters": {
      "format": "MIN",
      "phoneNumberRequired": true
    },
    "shippingAddressParameters": {
      "allowedCountryCodes": ["US"],
      "phoneNumberRequired": true
    },
    "allowedAuthMethods": [
      "PAN_ONLY",
      "CRYPTOGRAM_3DS"
    ],
    "allowedCardBrands": [
      "VISA",
      "MASTERCARD",
      "AMERICAN_EXPRESS",
      "DISCOVER",
      "JCB",
      "INTERAC"
    ],
    "threeDSecure": "omit"
  },

  "threeDSecureInitSettings": {
    "transactionType": "GOODS_SERVICE_PURCHASE",
    "deliveryTimeFrame": "ELECTRONIC_DELIVERY",
    "threeDSecureChallengeIndicator": "NO_PREFERENCE",
    "reorderIndicator": "FIRST_TIME_ORDERED",
    "shippingIndicator": "BILLING_ADDRESS"
  },

  "savePaymentOption": "required"
}

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

Example Response

{
  "id": "ifri_d193148ac2624de7b43a191682a8822f",
  "bearerToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "transactionId": "120615523104"
}

Overwriting Configuration

Take the following example: if our global iframe configuration enables all payment methods, but the customer requires strictly a subset or only needs some fields pre-filled because they are a returning customer, we can overwrite the settings accordingly. We can also set savePaymentOption to omit if the customer wants this to be only a one-time transaction. Alternatively, setting it to optional allows the customer to decide whether to check that box. For the illustrated workflow, see Checkout Component Tokenization.

Request Body

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

{
  "allowedPaymentMethods": [
    "CARD"
  ],
  "label": "Multi-Payment iframe instance",
  "reference": "c73bcdcc-2669-4bf6-81d3-e4ae73fb11fd",
  "initializeTransaction": true,
  "amount": "20",
  "timeout": 600,
  "currency": "USD",
  "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."
    }
  },
  "shippingAddress": {
    "address1": "123 Plain St",
    "address2": "West Side",
    "city": "Atlanta",
    "state": "GA",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Jane Smith",
    "recipientPhone": "1234567890"
  },

  "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"
  },

  "savePaymentOption": "optional"
}

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