Newtek Gateway Api 2.0
The Newtek Gateway rest api is awesome. You should use it.
Endpoint URL
The base url for the production api is:
http://secure.newtekgateway.com/api/v2/
The base url for the sandbox api is:
https://sandbox.newtekgateway.com/api/v2/
The hostname "newtekgateway.com" can be swapped out for any of the other gateway hostnames (see the High Availability Guide). During development, "sandbox.newtekgateway.com" should be used. For more information on the development sandbox see the Sandbox Guide.
The "v2" refers to 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 merchant use cases, 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.
Other features available with developer registered endpoints include the ability to restrict the use of the endpoint by IP address and list contact information for support. The endpoint keys are independent of the merchant api keys. An endpoint can be used with any merchant account.
Quick Example
Request
curl -X POST https://sandbox.newtekgateway.com/api/v2/transactions
-H "User-Agent: uelib v6.8"
-H "Content-Type: application/json"
-H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
-d
'{
"command": "cc:sale",
"amount": "5.00",
"amount_detail": {
"tax": "1.00",
"tip": "0.50"
},
"creditcard": {
"cardholder": "John doe",
"number": "4000100011112224",
"expiration": "0919",
"cvc": "123",
"avs_street": "1234 Main",
"avs_zip": "12345"
},
"invoice": "12356"
}'
This cURL request is an example of a merchant who is trying to charge a customer via a credit card sale.
Response
{
"type": "transaction",
"key": "bnf17whjvqqpj2s",
"refnum": "124444201",
"is_duplicate": "N",
"result_code": "A",
"result": "Approved",
"authcode": "147598",
"creditcard": {
"number": "4000xxxxxxxx2224",
"category_code": "A"
},
"invoice": "12356",
"avs": {
"result_code": "YYY",
"result": "Address: Match & 5 Digit Zip: Match"
},
"cvc": {
"result_code": "M",
"result": "Match"
},
"batch": {
"type": "batch",
"key": "0t1k3yx5xs37cvb",
"sequence": "1"
},
"auth_amount": "5"
}
This is the sample response object sent back from the server.
Authentication
All api calls requires an apikey (sourcekey) and an api hash. The api hash is built by hashing a random seed, the api key, and the private api pin. The general concept of generating the authorization header is detailed below. Please note, this is not a real implementation. Real implementations can be found in the Example Section.
var seed = random_value();
var prehash = apikey + seed + apipin;
var apihash = 's2/'+ seed + '/' + sha256(prehash);
var authKey = base64Encode(apikey + ':' + apihash)
The api key and api hash must be sent in a basic auth http header, and sent as a base64 encoded representation of the following string concatenation: (apiKey:apiHash). An HTTP header is then sent with the following structure:
Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2
Examples
Nodejs
var sha256 = require('sha256');
var seed = "abcdefghijklmnop"
var apikey = "_V87Qtb513Cd3vabM7RC0TbtJWeSo8p7"
var apipin = "123456"
var prehash = apikey + seed + apipin;
var apihash = 's2/'+ seed + '/' + sha256(prehash);
var authKey = new Buffer(apikey + ":" + apihash).toString('base64')
console.log("Authorization: Basic " + authKey);
PHP
$seed = "abcdefghijklmnop";
$apikey = "_V87Qtb513Cd3vabM7RC0TbtJWeSo8p7";
$apipin = "123456";
$prehash = $apikey . $seed . $apipin;
$apihash = "s2/" . $seed . "/" . hash("sha256",$prehash);
$authKey = base64_encode($apikey . ':' . $apihash);
print("Authorization: Basic " . $authKey);
API Rate Limits
To prevent abuse, the api implements per minute and daily rate limits. These are counted per endpoint key (see above) 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 registering an endpoint in the Dev Portal. Further increases to rate 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.newtekgateway.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 addresses. To test the IP access restriction, you can use the url: https://sandbox.newtekgateway.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}
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. For 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 include a "key" which is the primary public key for the object and a "type" which is the type of object (i.e. customer, transaction, product, etc.). For example:
{
"key": "a8ai3k7i77tw",
"type": "customer",
"firstname": "John",
"lastname": "Doe",
...
}