Results and Webhooks Notifications

Use the authenticated instance endpoint to reconcile a checkout when your application already knows the instance ID.

Webhook events can notify your server about Hosted Payment Form lifecycle changes without continuous polling.

Retrieve the authoritative instance

Request

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

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

Response

{
  "accountId": "220615031547",
  "allowedPaymentMethods": [
    "CARD",
    "ACH"
  ],
  "amountLabel": "Invoice amount",
  "customFields": [],
  "ecommerceSettings": {
    "amountType": "OPEN",
    "maxAmount": 5000,
    "minAmount": 1
  },
  "expiresAt": "2026-10-23T10:07:27-05:00",
  "hpfResourceId": "hpf_cc40cf66a9484a219902a03deecd3fe0",
  "id": "hpfi_78b735fbe63b4a02a876accdb3cdd9a2",
  "label": "Invoice payments",
  "pageType": "ecommerce",
  "reference": "6566cf98-a5b0-40c9-97d9-5b9d9c702fab",
  "savePaymentOption": "omit",
  "status": "PENDING",
  "style": {
    "buttonTextColor": "#FFFFFF",
    "fieldStyle": "outlined",
    "font": "roboto",
    "primaryColor": "#0D6EFD"
  },
  "termsAndCond": {
    "redirectToUrl": false,
    "required": false
  },
  "url": "https://checkout-cert.paymentpage.com/i_78b735fbe63b4a02a876accdb3cdd9a2"
}

Review these fields when present:

• status — PENDING, PROCESSING, COMPLETED, EXPIRED, or FAILED;
• transactionId — the PayConex transaction identifier for the payment attempt;
• amount — the submitted amount, represented as a string;
• reference — the merchant-generated reference provided at initialization; and
• customFieldValues — values associated with the initialized checkout.

Hosted Payment Form Webhook Events

The V4 API supports the following Hosted Payment Form events that trigger a webhook:

Treat events as notifications to retrieve or reconcile your system state, not as a reason to charge the customer again.

Create a webhook subscription

The request requires url and a single event value. Create a subscription for each event your integration needs.

The following event is set to trigger for both payment configuration and payment instance form - once a payment is submitted.

POST /api/v4/accounts/{accountId}/webhooks

{
  "url": "https://merchant.example.com/webhooks/payconex/hpf",
  "event": "HPF_PAYMENT_DECISION"
}

*Required Scopes: pcx:webhooks:* or pcx:webhooks:create

A successful request returns 201 Created:

{
  "id": "wbh_5249941f13564471b3be9f96a6d532c1",
  "url": "https://merchant.example.com/webhooks/payconex/hpf",
  "event": "HPF_PAYMENT_DECISION"
}

The webhook resource can then be retrieved, updated, deleted, or used with the standard webhook resend operation documented in the PayConex V4 API.

Webhook POST (Notification) Examples

Here are some examples of what the configured webhook receives as a POST request once a payment is submitted.

{
  "id": "not_78f8bb8c-b3de-4486-8b90-01d36ef11dcf",
  "webhookId": "wbh_f6b4acf4ef7143c398a23d674c42d623",
  "event": "HPF_PAYMENT_DECISION",
  "payload": {
    "accountId": "180010234034",
    "amount": 4,
    "configId": "hpf_417d818e7e234b7d899b3710cf04d092",
    "currency": "USD",
    "paymentMethod": "CARD",
    "sessionId": "hpfi_b0ff9c231ab44d779f8e3d5cb2d9aaed",
    "status": "DECLINED",
    "timestamp": "2026-10-12T09:22:20-05:00",
    "transactionId": "000000001054"
  }
}

{
  "id": "not_f17957d3-ce66-4a36-924e-8e92848809c5",
  "webhookId": "wbh_3e07634e80004cc2bf7ca21ebd22616a",
  "event": "HPF_PAYMENT_DECISION",
  "payload": {
    "accountId": "180010315906",
    "amount": 1.99,
    "configId": "hpf_58dfc3eaa3bc48c48c9cf8ec44a9931a",
    "currency": "USD",
    "paymentMethod": "CARD",
    "sessionId": "hpfi_d50bbd4534604c36a075f5737c87b26f",
    "status": "CAPTURED",
    "timestamp": "2026-10-12T09:13:22-05:00",
    "transactionId": "000000000474"
  }
}

Handle notifications safely

Your webhook endpoint should:

1. Accept the request quickly;
2. Validate it using the current PayConex webhook-authentication guidance;
3. Record the event identifier and ignore already-processed events;
4. Return a successful 2xx response only after safe receipt;
5. Process downstream work asynchronously when possible; and
6. Reconcile the referenced instance or transaction before fulfillment.

The development requirements describe a common structure containing id, webhookId, event, and payload. They also include relevant payload context such as:

• accountId
• session
• configuration
• account
• timestamp
• decision
• transaction
• amount
• status
• paymentMethod
• transactionId
• and custom fields when available.

Delivery expectations

Design your integration so that a missed webhook is recoverable through authenticated instance or transaction reconciliation. Confirm the delivery and resend policy before publication and production use.