Payment Configuration API

Most checkout integrations only need the instance operations described in Payment Form Instance and Rendering.

Use the endpoints on this page when your application must also create or manage Hosted Payment Form configurations via API.

Create a configuration

The request body parameters are required:

label
amountLabel
pageType
savePaymentOption
allowedPaymentMethods

📘
Checkout Setup
The API does not cover all conditional business rules. In practice, the merchant should configure the settings needed by the selected page type and enable at least one payment method.
To put together the most optimal set of rules as required by your integration, refer to the API Definition Reference.

Example request

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

{
  "label": "Invoice payments",
  "amountLabel": "Invoice amount",
  "paused": false,
  "pageType": "ecommerce",
  "directUrlAccess": "DISABLED",
  "savePaymentOption": "omit",
  "allowedPaymentMethods": [
    "CARD",
    "ACH"
  ],
  "confirmationPage": {
    "useCustomPage": false,
    "customTextStyle": "Thank you for your payment."
  },
  "ecommerceSettings": {
    "amountType": "OPEN",
    "minAmount": 1,
    "maxAmount": 5000
  },
  "customer": {
    "captureName": "required",
    "captureEmail": "required",
    "capturePhone": "optional",
    "captureShippingAddress": false,
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "state": "required",
      "zip": "required",
      "country": "optional",
      "company": "omit"
    }
  },
  "style": {
    "primaryColor": "#0D6EFD",
    "buttonTextColor": "#FFFFFF",
    "font": "roboto",
    "fieldStyle": "outlined"
  },
  "termsAndCond": {
    "required": false
  }
}

Required scopes: pcx:hosted_payment_form:* or pcx:hosted_payment_form:create

Example successful response

PayConex returns 201 Created. The response can include the generated configuration ID and public URL in addition to the saved settings:

{
  "accountId": "220615031547",
  "allowedPaymentMethods": [
    "CARD",
    "ACH"
  ],
  "amountLabel": "Invoice amount",
  "confirmationPage": {
    "confirmationUrl": "",
    "customTextStyle": "Thank you for your payment.",
    "useCustomPage": false
  },
  "createdAt": "2026-11-04T06:48:12-06:00",
  "customFields": [],
  "customer": {
    "billingAddress": {
      "address1": "required",
      "address2": "optional",
      "city": "required",
      "company": "omit",
      "country": "optional",
      "state": "required",
      "zip": "required"
    },
    "captureEmail": "required",
    "captureName": "required",
    "capturePhone": "optional",
    "captureShippingAddress": false
  },
  "directUrlAccess": "DISABLED",
  "ecommerceSettings": {
    "amountType": "OPEN",
    "maxAmount": 5000,
    "minAmount": 1
  },
  "googlePaySettings": {
    "merchantId": "220615031547",
    "merchantName": "TestMerchant"
  },
  "id": "hpf_2d53bfd87f374c178851e65d643cab98",
  "label": "Invoice payments",
  "pageType": "ecommerce",
  "paused": false,
  "savePaymentOption": "omit",
  "style": {
    "buttonTextColor": "#FFFFFF",
    "fieldStyle": "outlined",
    "font": "roboto",
    "primaryColor": "#0D6EFD"
  },
  "termsAndCond": {
    "redirectToUrl": false,
    "required": false
  },
  "timeout": 1800,
  "updatedAt": "2026-11-04T06:48:12-06:00"
}

For a payment configuration form, url can be distributed only when Direct URL Access is enabled. When it is disabled, initialize an instance and use the instance url instead. For example, we get the following url in response depending on the PayConex environment:

{
  ...
  "url": "https://checkout-cert.paymentpage.com/c_197791d1b79447e3b1c915f172a77be6"
}

🚧
timeout Value
Note that this setting can be set at the payment-configuration-level to define the default value for all the newly created instances but does not affect the payment configuration itself given that a payment configuration with direct URL access does not implement the timeout expiry and remains reusable for multiple payments until the configuration is paused or deleted. However, it does specify the real-time timeout value that determines when the session should expire before the page reloads.
This validates the fact as to why there is no expiresAt in the response of the newly created payment configuration.

List configurations

GET /api/v4/accounts/{accountId}/payment-form

Required scopes: pcx:hosted_payment_form:* or pcx:hosted_payment_form:read

The response body is an array of PaymentFormResponse objects. Pagination details are returned in response headers such as X-Current_page, X-Last-Page, X-Per-Page, X-Total, and next/previous page URL headers.

Supported query parameters are:

Parameter	Type	Description
`page`	integer	Page number; default `1`.
`query`	string	General search text, at least two permitted characters.
`paused`	boolean	Filter by paused state.
`limit`	integer	Results per page; default `25`, minimum `1`, maximum `100`.
`pageType`	string	`donation` or `ecommerce`.
`orderBy`	string	Property to sort by. The allowed property list is not defined.
`direction`	string	`asc`, `ASC`, `desc`, or `DESC`.

Example:

curl --request GET \
  'https://api-cert.payconex.net/api/v4/accounts/180000027666/payment-form?page=1&limit=25&pageType=ecommerce&paused=false' \
  --header 'Authorization: Basic <base64-encoded credentials>'

Get one configuration

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

Required scope: pcx:hosted_payment_form:* or pcx:hosted_payment_form:read

Returns 200 OK with the complete PaymentFormResponse for the form owned by the account.

curl --request GET \
  'https://api-cert.payconex.net/api/v4/accounts/180000027666/payment-form/hpf_5249941f13564471b3be9f96a6d532c1' \
  --header 'Authorization: Basic <base64-encoded credentials>'

Update a configuration

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

Required scopes: pcx:hosted_payment_form:* or pcx:hosted_payment_form:update

Send the PaymentForm properties that should change. A successful request returns 200 OK with a PaymentFormResponse.

Example: enable Direct URL Access and change the upper limit for an open-amount form.

curl --request PATCH \
  'https://api-cert.payconex.net/api/v4/accounts/180000027666/payment-form/hpf_5249941f13564471b3be9f96a6d532c1' \
  --header 'Authorization: Basic <base64-encoded credentials>' \
  --header 'Content-Type: application/json' \
  --data '{
    "directUrlAccess": "ENABLED",
    "ecommerceSettings": {
      "amountType": "OPEN",
      "minAmount": 1,
      "maxAmount": 10000
    }
  }'

After an update, test both newly initialized checkouts and direct access as applicable. The changes don't come through until the customer reloads their page.

🚧
Existing Payment Instances
It is important to note that a configuration update does not change its (child) payment form instances that were already created, so do not rely on existing instances inheriting new settings.

Delete a configuration

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

Required scopes: pcx:hosted_payment_form:* or pcx:hosted_payment_form:delete

A successful delete returns 204 No Content.

curl --request DELETE \
  'https://api-cert.payconex.net/api/v4/accounts/180000027666/payment-form/hpf_5249941f13564471b3be9f96a6d532c1' \
  --header 'Authorization: Basic <base64-encoded credentials>'

Deletion makes the configuration unavailable for normal list and retrieval operations and prevents continued use of its public page. Preserve the ID in your own audit or integration records when it is needed to understand historical activity.

Common responses

All configuration operations can return PayConex ApiViolation errors. Common status codes are:

400 — malformed request;
401 — authentication is invalid;
403 — credentials lack access to the account, form, or operation;
404 — account or form not found;
422 — API validation failure; and
500 — unexpected server error.

Log the response traceId for support, but do not log credentials, payment information, or sensitive customer data.

For the complete guide on response codes and errors, refer to API Endpoint Overview.