Creating a Configuration

Overview

Making an API call to create a Checkout Component configuration is an important step in setting up your integration with the PayConex™ V4 API. These configurations define the default behavior of a Checkout Component in your application.

This guide is intended to give you a deeper understanding of the different configuration options at your disposal. It also contains sections explaining the JSON request body parameters, and ends with request and response examples.

API Request

The request body for configuring a Checkout Component consists of general settings with specific settings for each available payment method.

📘
Note
These options can be customized when each instance is created, allowing developers to set up settings specifically for each customer’s iframe instance. This approach provides you with the flexibility to configure unique settings for different customer needs without the need for repetitive PATCH operations on the iframe configuration. By setting these options at the time of instance creation stage, developers ensure that each iframe instance is precisely configured, reducing the need for any ongoing adjustments.

General Settings

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

📘
Note
To find out which parameters are "required" in a setting and which can be "optional" or "omitted", see the comprehensive API Reference.

Parameter	Type	Description	Example
`label`	`string`	A friendly name for the Checkout Component configuration.	`"Card only iframe"`
`language`	`string`	The language setting for the form.	`"ENGLISH"`
`timeout`	`integer`	The user interaction limit timeout in seconds. This timeout kicks off as soon as an iframe instance is created.	`600`
`allowedPaymentMethods`	`array`	List of payment methods to support. Enumerations include: `"CARD"`, `"ACH"`, `"GOOGLE_PAY"`, `"CLICK_TO_PAY"`.	`["CARD", "ACH"]`
`allowedParentDomains`	`array`	List of domains allowed to embed the Checkout Component within an HTML iframe. Note that a domain must use HTTPS.	`["example.com"]`
`achSettings`	`object`	ACH Payment settings.	See below.
`cardSettings`	`object`	Card payment settings.	See below.
`clickToPaySettings`	`object`	Mastercard Click to Pay settings.	See below.
`googlePaySettings`	`object`	Google Pay settings.	See below.
`currency`	`string`	The currency for transactions.	`"USD"`
`savePaymentOption`	`string`	Specifies if saving payment is allowed. If set to `"required"`, the transaction returns the reissuing token. Enumerations: - `"required"`: Payment must be saved - `"optional"`: The user has the option to save the payment - `"omit"`: There is no option to save the payment	`"required"`

`cardSettings`

The card settings object is a set of configuration options that define specific behaviors of the Checkout Component when a user selects the credit card option ("CARD") as their preferred payment method via allowedPaymentMethods.

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

Parameter	Type	Description	Example
`cvv`	`string`	Specifies whether CVV is required.	`"required"`
`billingAddress.address1`	`string`	Specifies whether address line 1 is required.	`"required"`
`billingAddress.address2`	`string`	Specifies whether address line 2 is required.	`"optional"`
`billingAddress.city`	`string`	Specifies whether city is required.	`"required"`
`billingAddress.state`	`string`	Specifies whether state is required.	`"required"`
`billingAddress.zip`	`string`	Specifies whether zip code is required.	`"required"`
`capturePhone`	`string`	Specifies whether contact information is required.	`"required"`
`captureEmail`	`string`	Specifies whether email is required.	`"required"`
`captureShippingAddress`	`boolean`	Specifies whether shipping address should be captured.	`false`
`threeDSecure`	`string`	Specifies whether the 3DS attempt is required. `[ "required", "omit" ]`. For more on 3D Secure and how to set it up, check out Bluefin 3DS Support.	`"required"`

`achSettings`

The ACH settings are 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 field is required only if ACH is one of the items in the allowedPaymentMethods array.

Parameter	Type	Description	Example
`billingAddress.address1`	`string`	Specifies whether address line 1 is required.	`"required"`
`billingAddress.address2`	`string`	Specifies whether address line 2 is required.	`"optional"`
`billingAddress.city`	`string`	Specifies whether city is required.	`"required"`
`billingAddress.state`	`string`	Specifies whether state is required.	`"required"`
`billingAddress.zip`	`string`	Specifies whether zip code is required.	`"required"`
`capturePhone`	`string`	Specifies whether contact information is required.	`"required"`
`captureEmail`	`string`	Specifies whether email is required.	`"required"`
`captureShippingAddress`	`boolean`	Specifies whether shipping address should be captured.	`false`

`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 field 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.

Parameter	Type	Description	Example
`srcDpaId`	`string`	ID of the digital payment app being used.	`"3fa85f64-5717-4562-b3fc-2c963f66afa6"`
`dpaName`	`string`	Name of the digital payment app.	`"PayConex"`
`dpaPresentationName`	`string`	Presentation name of the digital payment app.	`"PayConex App"`
`allowedCardBrands`	`array`	List of card brands to accept. Enumerations include: `"VISA"`, `"MASTERCARD"`, `"AMERICAN_EXPRESS"`, `"DISCOVER"`, `"CHINA_UNION_PAY"`.	`["VISA", "MASTERCARD"]`
`captureShippingAddress`	`boolean`	Specifies whether shipping address should be captured.	`false`

`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 field 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.

Parameter	Type	Description	Example
`merchantId`	`string`	Merchant ID for Google Pay.	`"12345678901234567890"`
`merchantName`	`string`	Merchant name for Google Pay.	"Demo Merchant"
`billingAddressRequired`	`bool`	Specifies whether the billing address is required. If set to `false`, it is optional.	`true`
`billingAddressParameters.format`	`string`	Enable either minimal or full billing address parameters: `"MIN"`, `"FULL"`. Minimal parameters would include `address1`, `city`, `zip`.	`"FULL"`
`billingAddressParameters.phoneNumberRequired`	`bool`	In addition to specifying a minimal or full billing address, it also indicates whether a phone number is required.	`true`
`shippingAddressRequired`	`bool`	Specifies whether the shipping address is required. If set to `false`, it is optional.	`true`
`shippingAddressParameters.allowedCountryCodes`	`array`	Country codes allowed for the shipping address, e.g. `"US"`.	`[ "US" ]`
`shippingAddressParameters.phoneNumberRequired`	`bool`	Specifies whether the phone number is required as part of the shipping address.	`true`
`emailRequired`	`bool`	Whether the user has the option to save the email address.	`true`
`allowedAuthMethods`	`array`	List of allowed authentication methods. Enumerations include: `"PAN_ONLY"`, `"CRYPTOGRAM_3DS"`. For more, see Payment data cryptography for merchants \|`CRYPTOGRAM_3DS`.	`["PAN_ONLY", "CRYPTOGRAM_3DS"]`
`allowedCardBrands`	`array`	List of allowed card brands. Enumerations include: `"VISA"`, `"MASTERCARD"`, `"AMERICAN_EXPRESS"`, `"DISCOVER"`, `"JCB"`, `"INTERAC"`.	`["VISA", "MASTERCARD"]`
`threeDSecure`	`string`	Specifies whether the 3DS attempt is required. `[ "required", "omit" ]`. This option allows for Bluefin 3DS Solution as a step-up authentication for Google Pay `PAN_ONLY` transactions. As a result, the threeDSecureInitSettings are reused for this feature. For more on 3D Secure and how to set it up, check out Bluefin 3DS Support.	`"required"`

🚧
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

{
  "label": "Multi-Payment iframe",
  "language": "ENGLISH",
  "timeout": 600,
  "allowedPaymentMethods": [
    "CARD",
    "ACH",
    "GOOGLE_PAY",
    "CLICK_TO_PAY"
  ],
  "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
  },
  "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"
  },
  "currency": "USD",
  "savePaymentOption": "required"
}

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

Example Response

{
  "id": "ifr_f00bc120eaee45aca4a4d686c643a0df",
  "label": "Multi-Payment iframe",
  "language": "ENGLISH",
  "timeout": 600,
  "currency": "USD",
  "allowedPaymentMethods": [
    "CLICK_TO_PAY",
    "GOOGLE_PAY",
    "CARD",
    "ACH"
  ],
  "allowedParentDomains": [
    "tools.bluefin.com"
  ],
  "cardSettings": {
    "capturePhone": "omit",
    "captureEmail": "omit",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "cvv": "required",
    "captureShippingAddress": false,
    "threeDSecure": "required"
  },
  "clickToPaySettings": {
    "srcDpaId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "dpaName": "PayConex",
    "dpaPresentationName": "PayConex App",
    "allowedCardBrands": [
      "VISA",
      "MASTERCARD",
      "AMERICAN_EXPRESS",
      "DISCOVER",
      "CHINA_UNION_PAY"
    ],
    "captureShippingAddress": false
  },
  "achSettings": {
    "capturePhone": "omit",
    "captureEmail": "omit",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "captureShippingAddress": false
  },
  "googlePaySettings": {
    "merchantId": "12345678901234567890",
    "merchantName": "Demo Merchant",
    "emailRequired": true,
    "billingAddressRequired": true,
    "billingAddressParameters": {
      "phoneNumberRequired": true,
      "format": "MIN"
    },
    "shippingAddressRequired": true,
    "shippingAddressParameters": {
      "phoneNumberRequired": true,
      "allowedCountryCodes": [
        "US"
      ]
    },
    "allowedAuthMethods": [
      "PAN_ONLY",
      "CRYPTOGRAM_3DS"
    ],
    "allowedCardBrands": [
      "VISA",
      "MASTERCARD",
      "AMERICAN_EXPRESS",
      "DISCOVER",
      "JCB",
      "INTERAC"
    ],
    "threeDSecure": "omit"
  },
  "savePaymentOption": "required"
}

Creating a Configuration

Overview

API Request

📘
Note

General Settings

📘
Note

`cardSettings`

`achSettings`

`clickToPaySettings`

📘
Note

`googlePaySettings`

📘
Note

🚧
Important

Example Request Body

Example Response

Overview

API Request

📘Note

General Settings

📘Note

cardSettings

achSettings

clickToPaySettings

📘Note

googlePaySettings

📘Note

🚧Important

Example Request Body

Example Response

📘
Note

📘
Note

`cardSettings`

`achSettings`

`clickToPaySettings`

📘
Note

`googlePaySettings`

📘
Note

🚧
Important