PayForm

Getting started with PayForm for Number

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 of all the operational and design parameters of the PayForm:

1. From 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

To generate a PayForm, you can make a call to our REST API using a request body generated on the PayForm builder website.

---

PayForm builder

It might be difficult to prepare a PayForm request by yourself at first. To make it easy to get started, we've prepared a tool which can generate that for you.

https://easypay8.com/byopayform/

PayForm builder

Transaction types

There are three operation types you can choose from:

• Collecting an instant card payment;

• Saving cardholder data to be charged later (card-on-file);

• Both saving the cardholder data (card-on-file) and an instant card 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 POST /PayForm/Initialize 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:

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": "[e-mail]",
  "REFID": "764532#1",
  "RPGUID": "38976345",
  "ApprovalCode": "OK5013"
}

C#

public void ProcessPayFormInput(object sender, EventArgs e)
{
  string json;
  using (var reader = new StreamReader(Request.InputStream))
  {
    json = reader.ReadToEnd();
  }
  // Process the input
}

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.

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.

In case you're not using encryption, we recommend validating the information.

1

Retrieve and validate the transaction details

Using the TransactionID returned by the PayForm, you can call our REST API to retrieve full transaction details (or query transaction - full when using the SOAP API) 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.

2

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 (or query annual consent - full when using the SOAP API) 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.

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:

JavaScript (example 1)

// 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);
});

JavaScript (example 2)

// 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);
});

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

In the post message, ConsentID (CID) will only be included if the card was saved on file.

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, and full consent details methods;

  • For the SOAP API, you can use query transaction - full, and query annual consent - full;

• Provide a receipt;

  • For the REST API, you can use generate a transaction receipt method;

  • For the SOAP API, you can use generate receipt method.