¶ Introduction
The new PayForm is designed to present a highly flexible and secure payment form to your users with minimal effort.
Collecting a payment or saving a card on file is a two step process.
- A call is made to our API to initialize the payment parameters
- A payment link is generated
You control all the operational and design parameters of the PayForm such as:
- Form styling
- Field visibility and Read-Only parameters
- Initial data such as cardholder names and dollar amounts
- User defined data such as Patient ID or Reference ID
- Defined methods for receiving realtime data after transactions are authorized
You can then present the PayForm URL to your users in several ways:
- Load an IFRAME on your current website
- Direct your users to a convenient PayForm URL
- Send the Link to your users in email or text
¶ The Request
see https://easypayconfig.com/Restdocumentation/Index?id=65
{
"InitParams": {
"MerchID": 1,
"WTYPE": "PF",
"PostURL": "https://easypay7.com/swidget/JsonGet.aspx",
"RedirectURL": "https://easypay8.com/CYWidget/",
"REF_ID": "A97689#",
"RPGUID": "92e1e15c-f64a-466b-8733-9b518b9f374c",
"EndPoint": "PayForm/PF.aspx",
"EINDEX": "300",
"Amounts": {
"Amount": 20,
"Surcharge": 0,
"TotalAmt": 20
},
"Payer": {
"Firstname": "John Doe",
"Lastname": "",
"BillingAddress": {
"StreetAddress": "",
"City": "",
"State": "",
"ZIP": "04048",
"Country": ""
},
"Email": "",
"Phone": ""
},
"WidOptions": {
"eVisible": "0665",
"eReadOnly": "0040",
"eStyles": "0001",
"eSubmission": "0A01",
"eColors": "#ffffff,#428bca,#007bff,#212121,#ffffff,#212121,#ffffff"
}
}
}
¶ The Response
{
"PaymentInitResult":{
"ErrCode":0,
"ErrMsg":"",
"FunctionOk":true,
"PaymentUrl":"https://easypay5.com/swidget/?eGUID=239F97C4&CS=021&Digest=tru49A2ncbyvHoaIa6T81Q",
"RespMsg":"successfully returned payment Url"
}
}
Important : In order to properly utilize Form Styles, Please remove any escape characters [ \ ] from the PaymentUrl prior to Loading the Payform.
¶ Description of Fields
| Parameter | Description |
| MerchID | Use Value 1 unless your account has multiple merchant records |
| WTYPE | This will reflect the PayForm Type, EasyPay will provide Guidance |
| PostURL | Here you can enter a Valid URL where we can POST realtime values after payment is completed |
| RedirectURL | Here you can enter a Valid URL where we can Redirect after we process the payment |
| REF_ID | User defined field which you can attach to the transaction either in the background or as part of the PayForm |
| RPGUID | User defined field which you can attach to the transaction either in the background |
| EndPoint | This will point to a specific web application on our web servers and EasyPay will provide guidance |
| EINDEX | This is an optional 3 digit code which refers to a particular AES256 encryption key ( when used ) |
| Amount | Enter an amount to be displayed at the PayForm. This can be setup as readonly or editable |
| Surcharge | Enter an surcharge amount if your merchant has been approved for this feature |
| TotalAmt | Enter a Total amount to be displayed at the PayForm. |
| Firstname | Enter an optional cardholder name |
| Lastname | Enter an optional cardholder name |
| StreetAddress | Enter a cardholder street address |
| City | Enter an optional cardolder City |
| State | Enter an optional cardholder State |
| ZIP | Enter an optional cardholder ZipCode |
| Country | Enter an optional cardholder Country |
| Enter an optional cardholder Email | |
| Phone | Enter an optional cardholder Phone |
| eVisible | Enter 4 Hex Digits which control which fields are visible ( see note below ) |
| eReadOnly | Enter 4 Hex Digits which dictate the fields that are Readonly ( see note below ) |
| eStyles | Enter 4 Hex Digits which control the form styling ( see note below ) |
| eSubmission | Enter 4 Hex Digits which control various submission options ( see note below ) |
| eColors | Enter a string which control optional color schemes ( see note below ) |
Note : In order to determine Various options for styling and visibility please refer to the following tool: https://easypay8.com/byopayform/
The tool will generate fields as follows:
|VISIBLE|1667|READONLY|0100|STYLES|0001|OPTIONS|0601|COLORS|#ffffff,#428bca,#007bff,#212121,#ffffff,#212121,#ffffff
¶ Typical PayForm
See how payform can integrate with your exisiting portal: https://easypay8.com/iFramePayForm/
¶ Consuming Real-Time Data from PayForm
After the payment form has been submitted and credit card authorization is completed, you can opt to gather real – time relevant information in a number of ways. The most important information to gather would be a Transaction ID or a Consent ID if the card was saved.
- Json Post
- Redirect with QueryString appended to URL (with Optional encrypted parameters)
- Post Message (EasyPay IFrame content will send a message to Parent Page)
The first method allows you to provide a POST Url where we can directly stream data to the URL or Page of your choice. You can directly tap into the Request.InputStream to receive your Json string.
We allow you to provide one or both of the following URLs:
- POST URL (Here we Post values as either Json Stream or by adding Querystring to your supplied URL)
- REDIRECT URL (we will redirect to the page of your choice after transaction is completed, with optional query string appended)
If you choose Json Post this is a direct post to the Page or URL of your choice. If you don’t choose Json Post we will simply webrequest your page and add some querystring parameters to the URL. It is important to note that in order for you to validate information you can choose from the following:
- We can provide you a Unique AES 256 encryption key and you can read query string Values as encrypted paramatets (m,i). In this case you will supply an EINDEX value when calling the API. We will supply both a AES 256 key and a 3 digit code to send to us which identifies your Key.
- We can supply querystring Values directly with no encryption and you will query our Api to ensure those values exist and were created in the last few moments.
Here are some typical Json results:
{
"ConsentID": 33,
"TransactionID": 21008,
"CardNumber": "4511",
"CardType": "Visa",
"ExpireDate": "12/24",
"Amount": 56.20,
"Surcharge": 0.0,
"CardholderFirstName": "Nancy",
"CardholderLastName": "Draper",
"CustomerFirstName": "",
"CustomerLastName": "",
"Email": "ndraper@easypaysolutions.com",
"REFID": "764532#1",
"RPGUID": "38976345",
"ApprovalCode": "OK5013"
}
Here is some sample C# code which would read the InputStream to consume the Json:
protected void Page_Load(object sender, EventArgs e)
{
string json;
using (var reader = new StreamReader(Request.InputStream))
{
json = reader.ReadToEnd();
}
}
¶ Post Message
In this method the EasyPay Content which you have rendered in your IFrame will message your Parent Page Directly. If your implementation is using encryption, you will get an encrypted string that looks like the following:
TRANSACTIONID|174|CONSENTID|213|CARDNO|5339|CARDTYPE|Amex|FIRSTNAME|Bob|LASTNAME|smith|REFID|7899
If you are not using encryption, you will receive a message like this:
TXID|174|CID|213 Which provides a Transaction ID and possibly a Consent ID if the Card was Saved.
This abbreviated info allows you to use the API to gather additional information concerning the Sale and/or provide a receipt.
The following script can be used in your Parent Page to Listen for the message provided by the EasyPay content in your IFrame:
// 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;
// alert(e.data);
});
¶ Validating Information using the API
The second method described above (Redirect with QueryString) allows you to consume data when we redirect to your page simply by looking at the query string appended to URL. In this case you wouldn’t necessarily need to supply a POST URL since all is done when we redirect back to your site.
An example would be as follows where we simply redirect to your page of choice and append the Transaction ID: https://yoursite.com/yourpage.php?TxID=124
As your page gets loaded you can consume the TxID which is 124 in this case. You can call our API with the following request (passing us the TxID):
https://easypay5.com/APIcardProcREST/v1.0.0/Query/Transaction_FullDetail
See https://easypayconfig.com/Restdocumentation/Index?id=8
The goal is to confirm that the Transaction ID presented exists and has a CreatedOn date which is expected.
If we save a Card on file you may also see a ConsentID appended which you will need if you intend to charge the Card at a later time.
https://yoursite.com/yourpage.php?CID=12
As your page gets loaded you can consume the CID which is 12 in this case. You can call our API with the following request (passing us the CID):
https://easypay5.com/APIcardProcREST/v1.0.0 /Query/ConsentAnnual_FullDetail
See https://easypayconfig.com/Restdocumentation/Index?id=5
The goal is to confirm that the Consent ID presented exists and has a CreatedOn date with is expected.
Using our API to validate all the relevant information is fine if you don't want to have to decrypt the Querystring Parameters. One concern is to ensure that only VALID transactions are consumed by your page in this manner. We recommend that when you execute the API method for Transaction Full Detail or Consent Full Detail that you inspect the following date to ensure that it was within the last moments.
"Transaction": {
"CreatedOn": "\/Date(1549967861213-0500)\/", ( note Unix Format )
}
If you plan to consume information as we redirect back to your site you should be aware that you may see the following:
- TxID ( Transaction ID ) -> https://yoursite.com/yourpage.php?TxID=124
- CID ( ConsentID ) -> https://yoursite.com/yourpage.php?CID=34
- Both TxID and CID -> https://yoursite.com/yourpage.php?TxID=124&CID=34
Note: CID represents the saved Card On File if relevant
Final Notes: Whether you plan to consume the Json Post or consume the query string as we redirect to your destination page is your choice. You can certainly provide both a Post URL and a Redirect URL if you wish. You MUST provide a redirect URL in any case as that is how we pass control over your process after each interaction with EasyPay. You also should decide on how you plan to Validate the info you consume. This is to avoid malicious actors filling your database with unqualified transaction data. If you want us to encrypt the Query string Parameters, we can also do that. In this case you would see something like this:
https://yoursite.com/yourpage.php?m=xxxxxxxxx&i=yyyyyyyyy - where m is the encrypted message and I is the Initialization vector
See https://easypayconfig.com/DocumentationPublish/Encryption.aspx for encryption information.
