# PayForm The PayForm is designed to be a highly flexible and secure payment form for your users. It is designed to rendered in the browser and integrated with your existing web content. Collecting a payment or saving a card on file is a two-step process: a call is made to our REST API to initialize the payment parameters, and a payment link is generated. You control all of the operational and design parameters of the PayForm: 1. Form styling 2. Field visibility and read-only parameters 3. Initial data (cardholder names, $ amounts, etc.) 4. User-defined data (ReferenceID, etc.) 5. Defined methods for receiving a real-time update after transactions are authorized **You can then present the PayForm in one of two ways:**


	As an iFrame on your website
	As a direct link to the PayForm

{% hint style="info" %} **To generate a PayForm**, you can make a call to our REST API using a request body generated on the PayForm builder website. {% endhint %} *** ## PayForm builder

It might be difficult to prepare a PayForm request by yourself at first. **To make it easy and to get started, we've prepared a tool which can generate your form for you**. This is the PayForm wizard tool: {% embed url="" %} PayForm Builder {% endembed %} This is a second option for creating PayForm configuration: {% embed url="" %} Legacy Builder {% endembed %} ### Transaction types There are three operation types you can choose from: * Collect an instant payment using credit cards, ACH, Google Pay or Apple Pay; * Save accountholder data to be charged later (card-on-file, account on file); * Both saving the accountholder data and collecting instant payment. This choice will also pre-determine some of the required fields and submission options for you. ### Visible and read-only fields There is a number of fields you can have added to your form. For some of the fields, you can choose to provide a default value, and to mark them as read-only.

Field name	Description	Read-only option
First Name	Cardholder first name. If only `First Name` is visible, field will be changed to `Full Name`.	yes
Last Name	Cardholder last name. If only `Last Name` is visible, field will be changed to `Full Name`.	yes
Address	Cardholder street address.	yes
City	Cardholder city.	yes
State	Cardholder state.	yes
Zip Code	Cardholder zip code.	yes
Amount	A total $ amount to charge, when applicable to the chosen transaction type.	yes
REFID	A user-defined custom field	yes
RPGUID	A hidden user-defined custom field	yes
Expiration	Expiration date on the card, required.	-
CVV	Security code on the back of the card, required.	-
Agree to Pay confirmation	Adds a checkbox that will be required to submit and complete the instant card payment.	-
Agree to Save Card on File confirmation	Adds a checkbox that will be required to successfully save the card on file.	-
Email	Cardholder email address.	yes
Auth to Email	Permission to send an email.	-
Logos	Adds EasyPay Solutions, PCI Certified, and Digicert Secured logos to the form.	-

### Submission options Based on your requirements, you can choose from many submission options explained below.

Submission option	Description
Redirect external	After submitting, the user will be redirected to a provided external URL. An encrypted string containing the POST data is appended to the URL to be consumed by the merchant.
Redirect internal - receipt combo	After submitting, the user will be redirected to an internal page displaying a combination receipt for merchant and customer. An encrypted string containing the POST data is appended to the URL to be consumed by the merchant. This can also be used in conjunction with `Silent Post` for the purpose of transmitting data.
Redirect internal - receipt customer	After submitting, the user will be redirected to an internal page displaying a receipt for the customer. An encrypted string containing the POST data is appended to the URL to be consumed by the merchant. This can also be used in conjunction with `Silent Post` for the purpose of transmitting data.
Redirect internal - success message	After submitting, the user will be redirected to an internal page displaying a success message and a check mark image. An encrypted string containing the POST data is appended to the URL to be consumed by the merchant. Sometimes used with desktop apps which use embedded browsers.
Silent post	After submitting, an encrypted string containing the POST data is sent to the provided URL to be consumed by the merchant. The data is transmitted in the background. The user is not redirected.
Post message	When the PayForm is inside of an iFrame, after submitting, an encrypted string containing the POST data is sent to the parent page to be consumed by the merchant. The user is not redirected.
Require AVS full match	To submit the PayForm, a full AVS match must be submitted. This requires the `Address` and `Zip Code` to match exactly what is on record with the issuer for the card.
Require AVS partial match	To submit the PayForm, a partial AVS match must be submitted. This requires that, at a minimum, there is a `Zip Code` match achieved.
Require CVV match	To submit the PayForm, a full CVV match must be achieved. The transaction will be voided if the `CVV` does not fully match what is on file with the card issuer.
Payment widget	This PayForm will collect a one-time payment. Automatically set when choosing the transaction type.
Save Card on File widget	This PayForm will save the card on file for future use. Automatically set when choosing the transaction type.
JSON post	Replace the encrypted POST data with a JSON object to be consumed.
Send only Transaction ID / Consent ID	Only include the `TxID` and `ConsentID` in the data to be consumed.

### Style and colors We care about making sure that the PayForm can match the style of your branding. You'll notice that some options are mutually exclusive. Here is a list of all non-default customization options that can affect the look of the PayForm:

Customization element	Options
Label position	Left of the text box, above the text box, within the text box.
Text box corners	Semiround, round, semiround subtle.
Font family	Serif Font, Roboto font.
Required field indicators	Show.
Hide buttons	Hide both buttons, hide cancel button.
Text box size	Tall text boxes, short text boxes.
Background color Button background color Button border color Button text color Label text color Text box text color Text box background color	Any RGB value (can be selected using the color picker).

### Pre-filled values Depending on your needs, you might want to have some of the values pre-filled with defaults. This will allow you to provide a default for the `First Name`, `Last Name`, `Address`, `City`, `State`, `Zip`, `Amount`, `REFID`, `RPGUID`, and `Email`. Additionally, in this part of the builder, you can set values for the hidden config fields used by the form: `Endpoint`, `Redirect URL`, `Post URL`, and `EIndex`.

Hidden config field	Description
Endpoint	Points to specific web application on our server. Number will provide guidance.
Redirect URL	A URL to redirect the user after the payment is processed, if applicable.
Post URL	A URL to POST the real-time values after the payment is completed, if applicable.
EIndex	Integrator key index for encryption assigned when integrator account is first created, received with the initial login credentials

*** ## PayForm API request Once you have the request ready, you can call our REST API to generate the PayForm and the `PaymentURL` that you can use to access it. See the reference to [#payform-initialize](https://docs.number.tech/api-reference/rest-api-alt/payform#payform-initialize "mention") endpoint. Here's an example PayForm generated using the endpoint:

### Consuming data from the PayForm After the payment form has been submitted and credit card authorization is completed, **you can opt to gather real-time information using JSON post, redirect with query string, or a post message to your parent page.** When configuring the form, you may provide one or both of the following URLs: * `POST URL` where we will POST values as either JSON stream or by appending a query string, * `Redirect URL` to redirect to the page of your choice after transaction is completed, with or without a query string appended. #### JSON post Using `JSON post`, you'll be able to provide a `POST URL` for our servers to stream the data to. Then, you can tap into the request input stream to receive your JSON string. Here's an example of the result and how to tap into the input stream: {% tabs %} {% tab title="JSON" %} ```json { "ConsentID": 33, "TransactionID": 21008, "CardNumber": "4511", "CardType": "Visa", "ExpireDate": "12/28", "Amount": 56.20, "Surcharge": 0.0, "CardholderFirstName": "Nancy", "CardholderLastName": "Draper", "CustomerFirstName": "", "CustomerLastName": "", "Email": "ndraper@easypaysolutions.com", "REFID": "764532#1", "RPGUID": "38976345", "ApprovalCode": "OK5013" } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="C#" %} ```csharp public void ProcessPayFormInput(object sender, EventArgs e) { string json; using (var reader = new StreamReader(Request.InputStream)) { json = reader.ReadToEnd(); } // Process the input } ``` {% endtab %} {% endtabs %} #### Redirect with query string If you don't choose to use `JSON post`, we will web request your page and add query parameters to the URL. In order for you to validate the information, when configuring the form, you can choose from the following: * If you supply `EIndex`, which is a value that defines your unique AES 256 encryption key as described above, you can read query string values as encrypted parameters (the encrypted message `m`, and the initialization vector `i`); * Otherwise, we will supply the query parameters with **no encryption** and you will be able to query our API to ensure that **1. those values exist** and **2. they were created in the last few moments**. {% hint style="danger" %} **When you are receiving transaction data that is not encrypted, you should validate it before storing any details to avoid malicious actors creating unqualified data.** {% endhint %} In case you're not using encryption, we recommend **validating the information**. {% stepper %} {% step %} #### Retrieve and validate the transaction details Using the `TransactionID` returned by the PayForm, you can call our REST API to [retrieve full transaction details](https://docs.number.tech/api-reference/rest-api-alt/query#apicardprocrest-v1.0.0-query-transaction_fulldetail) to get all of the information regarding the transaction. Then, you can confirm if a transaction with the selected ID exists, and if the `CreatedOn` date roughly matches the current time or the time the PayForm was submitted. {% endstep %} {% step %} #### Retrieve and validate the consent details (if the card was saved) If `ConsentID` was returned alongside the `TransactionID`, you can use the REST API to [get full detail of annual consent](https://docs.number.tech/api-reference/rest-api-alt/query#apicardprocrest-v1.0.0-query-consentannual_fulldetail) to get all of the information regarding the consent. Then, you can confirm if a consent with the selected ID exists, and if the `CreatedOn` date roughly matches the current time or the time the PayForm was submitted. {% endstep %} {% endstepper %} With this, **you can avoid malicious actors filling your database with unqualified transaction data**. #### Post message In this method, the PayForm you have rendered in your iFrame will message your parent page directly. Here are example scripts for your parent page to listen for the message provided by the PayForm: {% tabs %} {% tab title="JavaScript (example 1)" %} ```javascript // Listen for post messages from an iFrame window.addEventListener('message', (event) => { const resultsMessage = document.getElementById('results'); // Ensure the message is from a trusted origin const trustedOrigin = 'https://easypay5.com'; // use PayForm origin if (event.origin !== trustedOrigin) { console.warn('Received message from untrusted origin:', event.origin); return; } // Update the innerHTML with the message data resultsMessage.innerHTML = event.data; // Optionally, handle the message data further // alert(event.data); }); ``` {% endtab %} {% tab title="JavaScript (example 2)" %} ```javascript // addEventListener support for IE8 function bindEvent(element, eventName, eventHandler) { if (element.addEventListener) { element.addEventListener(eventName, eventHandler, false); } else if (element.attachEvent) { element.attachEvent('on' + eventName, eventHandler); } } // Listen to message from child window bindEvent(window, 'message', function(e) { var resultsMessage = document.getElementById('results'); resultsMessage.innerHTML = e.data; // Optionally, handle the message data further // alert(e.data); }); ``` {% endtab %} {% endtabs %} If your implementation is using encryption, after decrypting, you'll get a string which can look like this: ``` TXID|174|CONSENTID|213|CARDNO|5339|CARDTYPE|Amex|FIRSTNAME|Bob|LASTNAME|smith|REFID|7899 ``` If you are not using encryption, it will contain 2 URL parameters instead, and can look like this: ``` ?txid=123&cid=321 ``` #### Requesting additional transaction and consent details Having the `TransactionID` (`TxID`) and `ConsentID`, you can use our REST API to: * Gather additional informating concerning the sale; * For the REST API, you can use [full transaction details](https://docs.number.tech/api-reference/rest-api-alt/query#apicardprocrest-v1.0.0-query-transaction_fulldetail), and [full consent details](https://docs.number.tech/api-reference/rest-api-alt/query#apicardprocrest-v1.0.0-query-consentannual_fulldetail) methods; * Provide a receipt; * For the REST API, you can use [generate a transaction receipt](https://docs.number.tech/api-reference/rest-api-alt/receipt#apicardprocrest-v1.0.0-receipt-receiptgenerate) method; --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.number.tech/documentation/getting-started/integration-options/payform.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.