Errors and Troubleshooting

Use the HTTP status, response errorType, response details, and traceId to diagnose API failures. Do not show raw PayConex or processor details to customers.

API error format

Payment Form endpoints commonly return an ApiViolation response shaped like:

{
  "message": "Invalid Input",
  "traceId": "a3692f21-950b-453c-9216-88198e84b5a6",
  "errorType": "invalid_request",
  "errorCode": "40001",
  "value": "The request contained invalid data",
  "source": "request",
  "details": [
    {
      "message": "Payload schema violation",
      "source": "fieldName",
      "value": null
    }
  ]
}

Capture traceId when contacting Bluefin support.

HTTP errors

Initialization problems

Configuration cannot be found

Verify that:

• accountId is 12 digits;
• resourceId is the saved configuration ID, not an instance ID;
• the configuration belongs to the account;
• you are using the same environment in which the configuration was created; and
• the form has not been deleted.

Initialization is rejected even though the ID is correct

Verify that the form is not paused or locked and that your API key has pcx:hosted_payment_form:instance:create or a corresponding wildcard scope.

Initialization creates multiple instances

The V4 API operation does not document an idempotency header. Do not blindly retry a request after an ambiguous network failure. Reconcile your stored instance ID or create a deliberate replacement and invalidate the older customer link operationally.

Hosted URL opens the wrong environment

Always redirect to the complete url returned by initialization. Do not hard-code or replace the hostname.

If the URL is not registered by the PayConex gateway, it will be rejected via 404 not-found. PayConex can return a different host or route for the environment.

Direct URL problems

Direct link shows Page not found

Verify that:

• Direct URL Access is enabled;
• You copied the current url from the form configuration;
• The form is not paused, locked, or deleted; and
• The URL belongs to the current environment.

Disabled direct access intentionally uses not-found behavior, so the public response does not reveal whether the form exists.

Direct link loads, but order-specific data is missing

PayConex API does not support direct-URL query parameters for the payment configuration with Direct URL Access. Use Payment Form Instance and Rendering when you need a reference, prefilled customer information, custom-field values, per-checkout amount settings, or per-checkout confirmation URL.

Configuration problems

Form cannot be saved

Check:

• The five required top-level create fields: label, amountLabel, pageType, savePaymentOption, and allowedPaymentMethods;
• At least one supported payment method is selected;
• Amount settings match the selected pageType and amount model;
• Terms content or URL is present when agreement is required;
• Confirmation URL is present when merchant redirect is selected;
• Colors use a supported hex format;
• All referenced custom fields and branding assets belong to the account; and
• Enum values use the exact case defined by the API.

ACH or Google Pay is unavailable

The account must be enabled for the payment method. Select another supported method or contact the appropriate PayConex administrator or Bluefin support to confirm account capabilities.

Branding image is rejected

The merchant UI requirements allow PNG, JPG, and WEBP. Keep cover images at or below 2 MB and logos at or below 512 KB. If the file still fails, verify that it is a valid image rather than a renamed file and review the returned validation details.

Customer checkout problems

Customer cannot submit

Ask the customer to check:

• Required amount, customer, address, and custom fields;
• Terms acceptance;
• Payment information validation; and
• Any visible reCAPTCHA challenge.

The form preserves entered values when a correctable validation error is shown.

Verification service unavailable

The hosted runtime blocks payment when it cannot complete required bot verification. The customer can retry after network, browser-extension, or temporary service issues are resolved. Do not bypass the hosted verification flow.

Session timed out

Create and send a new initialized instance. The original instance should not be reused.

Form already used

The instance completed and is single-use and is "expirable". Verify the result through the authenticated instance endpoint before creating a new checkout; this avoids charging again when the first attempt was successful.

Page is temporarily unavailable

Account-level IP blocking or payment-page auto-lock controls may block page load or payment submission after suspicious traffic or decline patterns. Merchant administrators should review the account's existing risk-control settings and contact Bluefin support when the lock reason or unlock procedure is not available in PayConex.

Unexpected Error

This is considered a payment Processor or PayConex gateway -level error. If this error occurs, please thoroughly verify your payment configurations and, if you make no progress, consider contacting the Bluefin Integrations team via [email protected].

Reconcile uncertain outcomes

If the customer closes the browser, loses connectivity, or reports an unclear result, do not assume failure and immediately retry the charge. Retrieve the initialized instance and review its status, transactionId, and amount when present. Use the merchant's normal PayConex transaction reporting as the final operational reconciliation source.