Rendering the Hosted Payment Form

A guide to rendering the PayConex Hosted Payment Form (HPF) using default and custom form fields.

Below is a “typical” Hosted Payment Form (HPF) using the default color/font palette, a custom logo, and a required Amount field. Each standard input field makes use of HTML5 placeholders to assist users in completing the form. Required fields are marked with an asterisk in the label. Real-time field level form validation is performed on each relevant form field, and the form itself will not submit until it is validated, ensuring that the data sent through to the PayConex API is as complete and accurate as possible.


Rendering Hosted Payment Forms

The Hosted Payment Forms can be accessed via a direct HTTP request using either GET or POST methods.

The base URL to the Hosted Payment Pages:

These parameters must be sent with your request:

actionstringRequiredThe API method name for rendering HPFs.
aidintegerRequiredYour PayConex Account ID (Zero-padded 12-digit).
idintegerRequiredThe Hosted Payment Form numerical ID.

These parameters are optional, depending upon the settings of your payment page:

amountstringconditionalRequired for display_only & hidden fields. Default amount can be sent for required & optional. If form uses multiple amounts both must be sent, delimited by a colon, e.g., 123.45:1.57)
first_namestringconditionalPayer/customer First Name. Required if display_only or hidden.
last_namestringconditionalPayer/customer Last Name. Required if display_only or hidden.
street_address1stringconditionalPayer/customer street address. Required if display_only or hidden.
citystringconditionalPayer/customer city. Required if display_only or hidden.
statestringconditionalPayer/customer state (2-character). Required if display_only or hidden.
zipstringconditionalPayer/customer postal (zip) code. Required if display_only or hidden.
countrystringconditionalPayer/customer Country. Required if display_only or hidden.
phonestringconditionalPayer/customer phone number. Required if display_only or hidden.
emailstringconditionalPayer/customer e-mail address. Required if display_only or hidden.
token_idintegeroptionalA valid payment token ID (transaction ID from previous successful AUTH, SALE, or STORE). Setting this disables the Payment Inputs for Card & ACH data.

Custom Form Fields

In addition to the pre-defined fields listed above, merchants can pass their own user-defined custom parameters. These parameters are defined when creating the hosted form. To submit data to be passed through the system via custom form fields simply send key/value pairs representing each custom field’s name, and its value. For example, if one of your custom fields is capturing customer account numbers you might define that as customer\_number and in the API request transmit it as &customer\_number=1035468857.

If a custom field is defined as either display_only or hidden, it must be passed with the request, even if its value is blank/null.

Sample Code

<a href="">
  Make a Payment</a>
<iframe src=""

The same form request via HTTP POST could be done with this HTML snippet:

<body onload="submitForm()">
<form action="" method="post" id="autoPostForm" hidden="hidden" style="visibility:hidden;">
<input type="hidden" name="action" value="view"/>
<input type="hidden" name="aid" value="123456789012"/>
<input type="hidden" name="id" value="21"/>
<input type="hidden" name="amount" value="123.45:3.95"/>
<input type="hidden" name="customer_number" value="1234-ABCD-001-B"/> <!-- Custom Field -->
<script type="text/javascript">
function submitForm() {
var myform = document.getElementById('autoPostForm');