Payment Engine API

The Payment Engine is a cloud based EMV middleware that point of sale developers can use to simplify their integration with various EMV capable payment terminals such as the Verifone MX series and the Castles MP200.

Endpoint URL

The base url for the production API is:

  https://sandbox.ebizCharge.com/api/v2/

The hostname "EBizCharge.com" can be swapped out for any of the other gateway hostnames (see the High Availability Guide. During development, "sandbox.EBizCharge.com" should be used. For more information on the development sandbox see the Sandbox Guide.

The "v2" refers the API version and can replaced with an endpoint key. The API limits the number of API calls allowed per minute and per day based on this key. Using "v2" is fine for development and smaller merchants, but could result in API rate limit errors for high traffic merchants. Larger merchants and developers should register their own software endpoint key in the Dev Portal. For more details, see the API Rate Limits section below.

There are other features available with developer registered endpoints including, restricting use of the end point by IP address and listing contact information for support. The endpoint keys are independent of the merchant API keys. An endpoint can be used with any merchant account.

API Index

Device Management

Payment Requests

API Rate Limits

To prevent abuse, the API implements per minute and daily rate limits. The limits are counted per endpoint key and IP address. When using the default endpoint url, the limits are 45/minute and 5000/day. When the limit is exceeded, the API will return HTTP error code 429:

  HTTP/1.1 429 API Rate Limit Exceed

The body of the response will be:

{"error":"API Rate Limit Exceed","errorcode":155}

Developers can utilize the "X-Rate-Limit" HTTP header to manage their API rate limit usage:

  X-Rate-Limit: "8 of 45/min; 8 of 5000/day"

Higher limits are immediately available by self registering an endpoint in the Dev Portal. Further increases to the limits are granted on a case by case basis. Contact the integration support team for further information. To test the API Rate Limit feature, use the API endpoint "https://sandbox.EBizCharge.com/api/RATELIMT/". Your second request will be rate limited.

IP Access Restrictions

By default, API endpoints are available to clients on any IP address. Developers can edit their API endpoint to restrict calls from a set list of IP addresses. To test the IP access restriction, you can use the url "https://sandbox.EBizCharge.com/api/IPACCESS/". When access is blocked HTTP error code 401 will be returned:

  HTTP/1.1 401 Access Denied

The body of the response will be:

{"error":"Access Denied","errorcode":156}

Authentication

All API calls require an APIkey (sourcekey) and API hash. The API hash is built by hashing a random seed, the API key, and the private API pin. 

var seed = random_value();
var prehash = apikey + seed + apipin;
var apihash = 's2/'+ seed + '/' + sha256(prehash);

The API key and API hash must be sent in a basic auth http header (base64 encode "apikey:apihash"):

Authorization: Basic
  OnMyL2YxYmFmMjE1OGQwNDQwYmI4N2U4OTRjOWU5MmQ4Mzk2L2ZhODgxNWNkYWMxZjY4M2VkNWQyY2Y5NmRhNmMzN2JlODRmNzNhNDA0ODYwNDU3YzNkZDdiNmM0NTc5NjA0YWY=

Common Formats

Lists

All API endpoints that return multi objects use a standard list format:

{
   "type": "list",
   "limit": 100,
   "offset": 0,
   "data": [
      {...},
      {...},
   ],
   "total": 200
 }

To change the number of objects returned in the result set, pass a "limit" variable in the request url (example: /api/customers?limit=1000). To retrieve the next group of objects, pass in "offset" with the item # to start with. "0" is the first item. For example, if there are 21 customers you could pull them in three calls:

/api/customers?limit=10&offset=0
... 10 customers returned ...
/api/customers?limit=10&offset=10
... 10 customers returned ...
/api/customers?limit=10&offset=20
... 1 customer returned ...

Objects

Single objects will all include a "key" (the primary public key for the object) and a "type" (the object type). For example:

{
  "key": "a8ai3k7i77tw",
  "type": "customer",
  "firstname": "John",
  "lastname": "Doe",
  ...
 }

Common Errors

Errorcode Message Troubleshooting
0 Valid authentication required Authorization header was missing.
21002 API authentication failed Authentication was not successful. Possible reasons could include: using the wrong PIN, using a sourcekey from sandbox in production mode, or that the authentication header was malformed.

Change Log

2018-03-19

  • Added description for device_name on Device Management pages.

2018-01-08

2017-08-28

2017-08-17

2017-01-17