Other Operations

Overview

These are some common operations for iframe configurations. Here we provide some sample requests and responses. For the more comprehensive section, refer to the API Reference.

Editing a Configuration

Editing a configuration doesn't need to involve all the required fields as we are changing and updating an iframe configuration.

For example, let's say we want to omit the threeDSecure. We want only to allow the card payment method and increase the timeout.

🚧
Note
After you edit a configuration, the changes are not applied to the existing iframe instance and the bearerToken needs to be re-created. For this reason, we support Overwriting a Configuration as a feature to the instance creation process.

PATCH /api/v4/accounts/{accountId}/payment-iframe/{resourceId}

{
  "allowedPaymentMethods": [
    "CARD"
  ],
  "cardSettings": {
    "cvv": "required",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "capturePhone": "omit",
    "threeDSecure": "omit",
    "captureEmail": "omit",
    "captureShippingAddress": false
  },
  "timeout": 1800
}

*Required Scopes: pcx:iframe:*, pcx:iframe:update

In response, we get the updated configuration in the same format as in Getting a Configuration.

Deleting a Configuration

📘
Note

{resourceId} value in the path is the id of the iframe configuration to delete.

DELETE /api/v4/accounts/{accountId}/payment-iframe/{resourceId}

*Required Scopes: pcx:iframe:*, pcx:iframe:delete

Getting a Configuration

📘
Note

{accountId} value in the path is the PayConex™ account ID number.

{resourceId} value in the path is the ID of an iframe configuration. See also Getting a List of Configurations.

GET /api/v4/accounts/{accountId}/payment-iframe/{resourceId}

*Required Scopes: pcx:iframe:*, pcx:iframe:read

Response

{
  "id": "ifr_*****212ac994d79a2b8fac5ace93809",
  "label": "Card only iframe",
  "language": "ENGLISH",
  "timeout": 800,
  "currency": "USD",
  "allowedPaymentMethods": [
    "CARD"
  ],
  "allowedParentDomains": [
    "*.payconex.net"
  ],
  "cardSettings": {
    "capturePhone": "omit",
    "captureEmail": "omit",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "cvv": "required",
    "captureShippingAddress": false,
    "threeDSecure": "required"
  },
  "clickToPaySettings": {
    "captureShippingAddress": false
  },
  "achSettings": {
    "captureShippingAddress": false
  },
  "savePaymentOption": "omit"
}

📘

Data Projection

The PayConex™ V4 API implements projection, which means selecting and returning only the necessary fields from a JSON object instead of sending the entire dataset.

For example, If the other payments methods are not allowed, they are considered unused and are filtered out altogether.

Data Projection applies for the entire V4 API to reduce the network bandwidth and memory usage of an ISV's integration. Also, see Get a Transaction Metadata | Data Projection.

This response contains all the payment methods.

{
"id": "ifr_*****a0f468f46438ba773686f12f5ce",
"label": "Multi-Payment iframe",
"language": "ENGLISH",
"timeout": 600,
"currency": "USD",
"allowedPaymentMethods": [
 "CLICK_TO_PAY",
 "GOOGLE_PAY",
 "CARD",
 "ACH"
],
"allowedParentDomains": [
 "*"
],
"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": "Testing",
 "emailRequired": true,
 "billingAddressRequired": false,
 "billingAddressParameters": {
   "phoneNumberRequired": false,
   "format": "MIN"
 },
 "shippingAddressRequired": false,
 "shippingAddressParameters": {
   "phoneNumberRequired": false,
   "allowedCountryCodes": [
     "US"
   ]
 },
 "allowedAuthMethods": [
   "PAN_ONLY",
   "CRYPTOGRAM_3DS"
 ],
 "allowedCardBrands": [
   "VISA",
   "MASTERCARD",
   "AMERICAN_EXPRESS",
   "DISCOVER",
   "JCB",
   "INTERAC"
 ]
},
"savePaymentOption": "required"
}

Getting a List of Configurations

Getting a configuration individually by their identifiers can be resource-intensive and slow with a high volume of configurations.

To address this, we recommend using the this endpoint for bulk retrieval of your iframe configurations. This endpoint is optimized for performance and supports efficient filtering and pagination.

Query Parameters

Parameter	Type	Description	Example
`page`	`integer`	The page number for the limit.	Default: `1`
`limit`	`integer`	The number of items to return in response. The `limit` is required to be within the range between `1` and `100`.	Default: `25`
`query`	`string`	A query parameter that filters the dataset.	`"Card+only+iframe"`
`createdAfter`	`string`	Filter for the records created after the date. The default is `1970-01-01`	`2026-07-14`
`createdBefore`	`string`	Filter for the records created after the date. The default is today.	`2026-07-14`
`orderBy`	`string`	The name of the property where to apply the order command on.	`label`, or `id`
`direction`	`string`	The sort direction for the order command. Enumeration values: `asc`, `ASC`, `desc`, `DESC`	`ASC`

🚧
Note
It is important to note that the maximum number of transactions returned per page is limited to 100. By combining the limit and page query parameters, you can reliably retrieve large volumes of transactions without performance bottlenecks.

GET /api/v4/accounts/{accountId}/payment-iframe?limit=20
*Required Scopes: pcx:iframe:*, pcx:iframe:read

This request allows a developer to get a list of configurations including their metadata and IDs, but never the instances, assigned to them for enhanced security.

Response

[  
  {
    "id": "ifr_*****774f70a49188fa199a6d4a09668",
    "label": "Card only iframe",
    "language": "ENGLISH",
    "timeout": 800,
    "currency": "USD",
    "allowedPaymentMethods": [
      "CARD",
      "ACH"
    ],
    "allowedParentDomains": [
      "*.payconex.net"
    ],
    "cardSettings": {
      "capturePhone": "omit",
      "captureEmail": "omit",
      "billingAddress": {
        "address1": "required",
        "address2": "optional",
        "city": "required",
        "state": "required",
        "zip": "required"
      },
      "cvv": "required",
      "captureShippingAddress": false,
      "threeDSecure": "required"
    },
    "clickToPaySettings": {
      "captureShippingAddress": false
    },
    "achSettings": {
      "capturePhone": "omit",
      "captureEmail": "omit",
      "billingAddress": {
        "address1": "required",
        "address2": "optional",
        "city": "required",
        "state": "required",
        "zip": "required"
      },
      "captureShippingAddress": false
    },
    "savePaymentOption": "required"
  },
  {
    "id": "ifr_*****46a69f54f82a6b5b98920f98cb0",
    "label": "Card only iframe",
    "language": "ENGLISH",
    "timeout": 800,
    "currency": "USD",
    "allowedPaymentMethods": [
      "CARD",
      "ACH"
    ],
    "allowedParentDomains": [
      "*.payconex.net"
    ],
    "cardSettings": {
      "capturePhone": "omit",
      "captureEmail": "omit",
      "billingAddress": {
        "address1": "required",
        "address2": "optional",
        "city": "required",
        "state": "required",
        "zip": "required"
      },
      "cvv": "required",
      "captureShippingAddress": false,
      "threeDSecure": "required"
    },
    "clickToPaySettings": {
      "captureShippingAddress": false
    },
    "achSettings": {
      "capturePhone": "omit",
      "captureEmail": "omit",
      "billingAddress": {
        "address1": "required",
        "address2": "optional",
        "city": "required",
        "state": "required",
        "zip": "required"
      },
      "captureShippingAddress": false
    },
    "savePaymentOption": "required"
  }
]

📘
Did you know?
The ID of the iframe starts with ifr_ where r stands for resource, whereas the ID of the instance starts with ifri standing for iframe resource instance.

Getting Instance Details

A developer can also get instance details that are defined by Creating an Instance. These parameters include threeDSecureInitSettings, currency, amount, and so on, in combination with the iframe configuration parameters such as allowedPaymentMethods, savePaymentOption and timeout.

📘
Note

{accountId} value in the path is the PayConex™ account ID number.

{resourceId} value in the path is the ID of an iframe configuration. See Getting a List of Configurations.

{resourceId} value in the path is the ID of an iframe instance.

GET /api/v4/accounts/{accountId}/payment-iframe/{resourceId}/instance/{resourceInstanceId}

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

Response

{
  "id": "ifri_*****ecfef0e4af385efbd0e681be854",
  "label": "my-instance-1",
  "reference": "redacted",
  "timeout": 1800,
  "language": "ENGLISH",
  "amount": "20",
  "currency": "USD",
  "threeDSecureInitSettings": {
    "transactionType": "GOODS_SERVICE_PURCHASE",
    "reorderIndicator": "FIRST_TIME_ORDERED",
    "deliveryTimeFrame": "ELECTRONIC_DELIVERY",
    "shippingIndicator": "BILLING_ADDRESS",
    "threeDSecureChallengeIndicator": "NO_PREFERENCE"
  },
  "achSettings": {
    "captureShippingAddress": false
  },
  "cardSettings": {
    "capturePhone": "omit",
    "captureEmail": "omit",
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required"
    },
    "cvv": "required",
    "captureShippingAddress": false,
    "threeDSecure": "omit"
  },
  "clickToPaySettings": {
    "captureShippingAddress": false
  },
  "allowedPaymentMethods": [
    "CARD"
  ],
  "savePaymentOption": "omit"
}