¶ Introduction
Easy Pay maintains both REST and SOAP APIs.
For SOAP API, discovery can be found: HERE
The SOAP API has a particular web Service Contract found: HERE
REST API documentation can be found: HERE
¶ Easy Pay Vocabulary Terms
¶ Account Code or AcctCode
Example Value: EP3422629 (9 Alpha Numeric Chars)
The ACCOUNT CODE is the unique key which represents an Easy Pay account. This code will never change throughout the life of your account. Our account code is comprised of two letters and seven numbers (such as EP1234567). This code is used when authenticating using one of our API’s (along with a token). You can use this code when communicating with Easy Pay staff in order to describe your account.
¶ Token
Example Value: E4C7DBEC464946DBA32DEAE70D332665 (32 Hex Chars)
The TOKEN (like a password) will be used when authenticating using one of our API’s. The token will be good for TWO years and then it will expire and you will need to generate a new one. The token is a 32 character hexadecimal string (such as F30AA02DFCC54B428F5F43C83F8F6A8D). You can log in to our Client Admin Portal site to generate tokens for the accounts which you manage. Please keep your tokens stored safely and securely, and do not email them directly without some extra layers of security (encrypted e-mail).
¶ Virtual Terminal Username
Example value: VT4914533 (9 Alpha Numeric Chars)
This is your username for our web based application the Virtual Terminal.
¶ 3DES Encryption Key
Example value: 35DADA12A1D86513090D85C5D3C731A1BBF8786226C48296 (48 Hex Chars)
This is used in conjunction with 3DES cryptography classes to encrypt data for use in our Web Widgets. This is symmetrical encryption meaning the same key used to encrypt is also used to decrypt. Each Easy Pay integrator is assigned a unique key and an index number. When we receive an encrypted message, you will also append your index number which lets us know which key we need to use.
¶ AES Encryption Key
Example value: D00DEF018FB2648697341BC7E3A8EDC4BCB55F8103CD8EE23E66BD09910F400B (64 Hex Chars)
This is used in conjunction with AES Cryptography classes to encrypt data for use in our Web Widgets. This is symmetrical encryption meaning the same key used to encrypt is also used to decrypt. Each Easypay Integrator is assigned a Unique Key and an Index Number. When we receive an encrypted message, you will also Append your Index number which lets us know which Key we need to use.
¶ Client Admin Username
Example value: CA6911695 (9 Alpha Numeric Chars)
This is the username for our web based application the Client Admin Portal.
¶ Merchant Record or MerchID
Each Easy Pay account can support multiple merchant records. Each merchant record can be a separate location center which will generate a separate daily settlement report. One example of having multiple merchant records in your account might be the following:
Example: MERCHID = 1 for in-house (Practice-Facing) transactions and MERCHID = 2 for online (Public-Facing) transactions.
This allows two separate cost centers and nightly settlement reports.
Many of our API calls require that you specify which MERCHID when executing a particular function. When requesting a report you can also filter by this parameter.
¶ Session Key or SessKey
Example Value: AABAF6C95552447D8B303031353341303032303634 (42 Hex Chars)
A SESSION KEY is granted when you successfully AUTHENTICATE with our API. Sending an ACCOUNT CODE and TOKEN with the AUTHENTICATE command will return a response which includes a SESSION KEY. Once a key is obtained, it proves you are a valid authenticated user and you will need to pass it to us as you make any and all subsequent API calls. Session keys can be used for a full 25-hour period (the extra hour allows you to be comfortable programming for a 24-hour daily authentication task)
Terms relevant for Easy Pay API:
- Account Code (Like a user name) (never expires as long as account is active)
- Token (like a password) (two year lifetime, needs to managed and renewed)
- Session Key (used as authentication and is generated once a day using the above two items. This limits exposure to your master credentials (account code and token) (expires every 25 hours)
¶ Authentication
[OperationContract]
api_AuthResponse Authenticate (string AcctCode, string Token);
In order to use the Easy Pay API you will need to first understand the AUTHENTICATION method. In this method you will pass us TWO values:
- Account Code (never changes throughout the lifetime of your account)
- Token (expires every two years, similar to a password)
The return object will contain your SESSION KEY. All of our API methods require you send a session key. This key will be honored for 25-hours as long as it is sent from the same IP address which was originally used for AUTHENTICATION. Sometimes it happens that your IP (as seen by Easy Pay) can change during any given 24-hour period and in that case, you may receive an ERROR CODE 5050 from our API. If that happens you will simply run the AUTHENTICATE method once again to obtain a new session key.
¶ Managing a Session Key
We recommend that you simply obtain a session key and continue to use that session key until you receive one of the following error codes:
- 5030: Expired Session Key (session key has expired after 25 hours)
- 5050: Unauthorized Session Key (your IP has changed since you last authenticated)
¶ Lockouts
When you AUTHENTICATE you will be returned two Boolean flags:
- FunctionOK (indicates that no unexpected errors were encountered)
- AuthSuccess (indicates that your credentials were accepted and a session key will be provided)
The workflow should be as follows:
- Check FunctionOK flag, If False, read error message, error code, and abort
- If True, read AuthSuccess flag: If AuthSuccess flag is False, read RspMsg and abort: If True, obtain session key
It is important that unsuccessful authentication attempts be ABORTED and NOT retried. The Easy Pay system will LOCK your IP address if you continue to send us unsuccessful authentication attempts (6 in a row). This can cause serious problems for your merchants if they are locked out. Since it will require someone in our support department to manually audit the lockout and determine if it is safe to remove the lock. The better approach is to simply STOP and NOTIFY the user that there is a need for new Easy Pay credentials be applied to the product. Once the new credentials are applied and the AUTHENTICATE method is executed then card processing can continue without the need to perform an additional step to UNLOCK the account.
¶ Digital Signature
Easy Pay now supports digital signature for the below mentioned receipts/agreements. To use this feature, the integrator needs to send the TransactionID (TXID) or ConsentID obtained from Easy Pay along with the ReceiptType and signature byte array. Our system would append the receipt or consent agreement with the signature and returns back the entire signed copy as shown below. The signature pad which we use currently is TOPAZ-Model T-S461-HSB-R.
|
Transaction Receipt |
Consent Receipt |
|
|
|
Recurring Consent Receipt |
Subscription Receipt |
|
|
¶ Payment Reminder
[OperationContract]
api_SMSPaymentResponse SMSPayment(string SessKey, api_SMSPayment param);
The above API call enables the integrator to send a payment reminder to the client through a text or e-mail. Once the client receives the reminder, they can simply click the link that is sent along with the text or e-mail, which upon clicking opens the payment widget allowing the client to make a payment. Once the payment is submitted, a transaction receipt would be e-mailed to the e-mail address that is on file.
Sample Reminder:
You have a payment due to Merchant Name of $125.00 due on 10/4/2018. Please follow the link below to make the payment. https://easypay5.com/PaymentReminder/?AT=GzNHZXXXXo=sNLs0gh3I9xMKALxwGCjQsXnFycTXV0htipN92dAbU4IIl7E9rFb6YKosbakwUOapfwtQODMdT0=&Z=1
Upon clicking the link opens our Web Widget (Mobile-friendly) as shown below:
On submitting the payment, the receipt would be shown as below: Also if there is a valid email on file, the Receipt would be emailed.
¶ Sample Authentication Key Values
Account Code: EP4799974 (9 ALPHA NUMERIC) (never changes)
Token: 1A4901153DEA4CF6A8BAB1999FA36C34 (32 HEX) (expires every two years)
SESSION KEY: F9F3C25C9A1247F2AD303030363541303030353230 (42 HEX) (expires every 25-hours)
¶ API Token Renewal
Easy Pay provides a web site which allows you to manage and create new tokens. You are free to create as many tokens as you require for your credit card processing requirements. We recommend that you create a API token for each individual processing location (IP address). Every API token has a lifespan of two years. When you create a new token, this does not affect the tokens that were previously generated. When you log Into our Client Admin Portal, you will be able to view your active/expiring tokens, create new tokens, and we also allow you to post tokens to your web site. This provides a degree of automation to the renewal process.
¶ API Input Validation:
The following Typical string values are validated within the API and will only allow a finite set of characters. If you send characters which are not allowed, you can receive an ERROR CODE : 7123
public string Firstname
public string Lastname
public string Company
public string Title
public string Url validated as URL
public string Address1
public string Address2
public string City
public string State
public string ZIP
public stringCountry
public string Email ( validated as email )
public string Phone ( validated as phone; maximum 16 digits )
public string ServiceDescrip
public string ClientRefID
public string RPGUID
---Only strings are restricted---
Firstname and Lastname allow ( single quote, alpha, numeric, minus sign, period, space, ampersand, comma, question mark, forward slash )
Company and Title allow ( alpha, numeric, minus sign, period, Pound sign, underscore, comma, ampersand, forward slash )
Address allows (single quotes are stripped out, alpha, numeric, minus sign, period, Pound sign, underscore, comma, forward slash )
City allows ( alpha, space, period )
State allows ( alpha, space )
Zip allows ( alpha, space, numeric, dash )
Country allows ( alpha, space )
ClientRefID allows ( single quotes are stripped out, alpha, numeric, minus sign, period, pound sign, comma, underscore, space, equal sign, ampersand )
RPGUID allows ( single quotes are stripped out, alpha, numeric, minus sign, period, pound sign, comma, underscore, space, equal sign, ampersand )
ServiceDescription allows ( alpha, numeric, space, underscore, period, pound sign, minus sign )