PayConexDecryptxShieldConexTECS Platform
API Reference
Request SandboxContact Us

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

Query Parameters

ParameterTypeDescriptionExample
pageintegerThe page number for the limit.Default: 1
limitintegerThe number of items to return in responseDefault: 25
querystringA query parameter that filters the dataset."Card+only+iframe"

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

This request allows a developer to get a list of configurations including their metadata and IDs, but not 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"
}