Introduction
Welcome to the EndelosPay Gateway API! We have language bindings in Shell, Ruby, Php and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
For Technical Integration docs, please see Technical Documentation
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: API_key: API_Secret"
<?php
require EndelosPay;
EndelosPay = new EndelosPay(API_KEY,API_SECRET);
?>
Make sure to replace
API_key: API_Secretwith your API keys.
You can find your keys on the dashboard under Credentials
EndelosPay uses API keys to allow access to the API.
EndelosPay expects for the API key and Secret to be included in all API requests to the server in a header that looks like the following:
Authorization: API_key: API_Secret
Testing Information
Test Mode
To toggle your acount between live/test mode, go to Settings on your dashboard, then choose which mode you want the account to be.
You will only view data that match your selected mode.
Your keys/secrets/tokens will not be changed when switching between test and live mode.
Keys and Credentials
You can find all your keys/secrets/tokens under the Credential tab of the menu (your menu options may differ from the screenshot)
Test Cards
Visa: 4111111111111111
Master Card: 5105105105105100
Discover: 6011111111111117
American Express: 371449635398431
Expiration date: 06/25
CVV: 123
You must format your phone number like so: xxxxxxxxxx
For test mode, you will need to input a valid area code but the rest of the digits can be randomized
Other fields like name or address can be filled with any information
An example US Address Format would be
"Address 1, Address 2"
"City", "XX (State code)" "XXXXX (Zipcode)"
Fails
To trigger a fail, you can put the account into test mode (found in your dashboard under settings) and use any card not on the list above.
Sample Fail cards
4000 0200 0000 0000 gives 'Micro payments are not accepted!'
4012 8888 8888 1881 gives 'The amount you entered exceeds the Maximum transaction limit!'
4347 6970 8119 3614 gives 'Daily Volume Limit Reached!'
5555 5555 5555 4444 gives 'Monthly Volume Limit Reached!'
5610 5910 8101 8250 gives 'Invalid Card.'
6011 6011 6011 6611 gives 'Decline'
6011 0009 9013 9424 gives 'CVV error'
Refunds/voids
You can test refunding transactions by going to Transaction Data->Transactions, click on the transaction you want to refund and click the void/refund button
Errors
Transaction error codes:
Duplicate Order
You can see the duplicate order message if you placed an order with the exact same card number
If the transaction was a success, it will take 1 hour before the card can be ran again
If there are 2 or more transaction fails with the card number, it will take 17 hours before the card can be ran again
| Error Code | Meaning |
|---|---|
| 5003 | Transaction amount is underneath the minimum limit |
| 5004 | Transaction amount is over the limit for a single transaction |
| 5005 | Processor's daily limit hit, please wait until 12:00 AM EST for it to reset |
| 5006 | Processor's monthly limit hit, please wait until the first of the next month for it to reset |
| 5007 | Internal Server Error - We had a problem with our server. Try again later. |
| 5008 | Invalid card number given |
| 5009 | All gateways unavailable |
| 5010 | Gateway error, please wait for our support team to fix the error |
| 5011 | Invalid service response, please wait for our support team to fix the error |
| 5013 | Velocity Limit, please wait 24 hours |
| 5014 | Refund limit reached for today, Please wait 24 hours before re-trying the refund |
| 5015 | Bad IP address. The IP address the transaction is coming from is bad, please try again with a different IP address. |
| 5016 | Unable to get ip from proxy, please wait for our support team to fix the error |
| 5017 | Transaction flag has been raised, Please use a different card number |
| 5018 | Card not whitelisted, please wait for our support team to fix the error |
| 5018 | Spam detected. Over 120 transactions received in less than a minute. Please slow down transaction requests. |
| 8005 | This is a blocked card, please use a different card |
API error codes:
| Error Code | Meaning |
|---|---|
| 401 | Unauthorized -- Your API key is wrong. |
| 404 | Not Found -- The specified Api can not be found. |
| 405 | Endpoint Not Allowed -- You did not have access to this Endpoint. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 422 | Failed Validation -- Requested parameter is not valid. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
VIrtual Terminal errors:
| Error Message | Meaning |
|---|---|
| Card limit reached. Please use a different form of payment | That card type limit has been reached, please wait until 12:00 AM EST for it to reset |
| Daily Volume Limit Reached! | Processor's daily limit hit, please wait until 12:00 AM EST for it to reset |
| Gateway Disabled. | All processors assigned to the client are disabled |
| Micro payments are not accepted! | Transaction amount is underneath the minimum limit |
| Monthly Volume Limit Reached! | Processor's monthly limit hit, please wait until the first of the next month for it to reset |
| Payment Processing Unavailable. | Your ability to run transactions has been disabled |
| Something went wrong. | Catch all error |
| The amount you entered exceeds the Maximum transaction limit! | Transaction amount is over the limit for a single transaction |
| You requested a format that isn't json. | You have put a number where there should have only been text, or you have placed text when there should have only been numbers |
| Velocity Limit Reached | You have reached the maximum amount of transaction attemmpts with that card number. |
Fraud Prevention
If you notice a bunch of your transctions stuck in pending, the fraud prevention system delays the transaction until manual review is done.
Instructions to run a transaction are as follows
Step 1
On your dashboard, go to Transaction Data -> Transactions
Step 2
Select the transaction you want to run from the table
Step 3
A hour after the transaction has been posted, these 2 buttons will appear on the right. Shipped runs the transaction as normal, Cancel results in a fail on the transaction
Adding a Printer
Step 1
Go to Add Printer
Step 2
Click the Add Printer Button
Step 3
Add your printer name in the field
Step 4
You can then adjust the position of the check up or down on the page using the slider to position where on the page the check needs to be positioned. (You may need to do some test printings to get the positioning correct)
Step 5
Save when things are adjusted properly
Step 6
When printing, select the proper printer settings to print
eCheck Printing
Step 1
To print echecks go to your print center
Step 2
Click the check box under the approve column to mark all the checks to be printed and select the printer, and the check paper
Under Paper Type there are 2 ways to print checks
- Plain Paper: this prints checks onto plain white paper
- Check Paper: if you bought the recommended check paper, please use this option, also select the correct printer settings
Then click print checks
To deny the check you can click decline
Risk is sorted into 3 categores, Low, Medium, and High risk, you can click on the status to get why it is sorted into that risk category
Step 3
If you accidently decline a check that you want to approve, mark the checks to go back to Step 2 and click approve
Wordpress Plugin
Step 1: Download plugin file from knox dashboard:
1. Log into client dashboard
2. On the dashboard menu on the left hand side select: Integrations > Plugins > Wordpress
3. Select the latest version of the wordpress plugin, a .zip file will automatically download onto your machine
Click here to download the .zip file for the Wordpress plugin
Step 2: Upload plugin on Wordpress Site
1. Log into your wordpress dashboard
2. Go to plugins > add new
Click on “Upload Plugin” at the top, Select “Choose File”. Choose the zipped wordpress file you just downloaded from the knox dashboard (no need to unzip).
3. Click Install Now, once installed click “Activate Plugin”
Step 3: Add API keys to Woocommerace plugin on wordpress
*Ensure woocommerce plugin is downloaded and active on your wordpress site
1. Within wordpress site go to WooCommerce > Settings and select the Payments tab
2. Under the payments tab, you will find a list of the various payment methods available through KnoxSecure. Enable the methods you wish to use and then click "manage" to set up each method.
3. Go to your knox dashboard to retrieve your Client Key and your API secret Key- they can be found at the very top of the page under the dashboard tab 4. Copy the API Key and paste it in the corresponding “client key” field on your wordpress site
5. Copy API Secret Key and paste it in the corresponding “API Secret” field on you wordpress site
Note: Your API Key and API secret key will have to be added indivudally to each payment method you have enabled.
Be sure to save!
Step 4: Set up additional Plugin Options:
Title - What our payment option will show as on checkout
Description - What shows as the short descriptor under the title upon checkout
API client Key: Can be found on your home knox dashboard or on knox->credentials (required)
API Secret: Can be found on your home knox dashboard or on knox->credentials (required)
Order Description - description of the order sent out in an email
Minimum Order - minimum amount to mark as VIP per transaction. Debugging option for EndelosPay developers.
Enable VIP-Once enabled, payment option doesn’t show unless there are 2 previous successful transactions with that email.
Show Descriptor - Check if you want to show the descriptor on the thank you page after check out
Show descriptor banner- Check if you want to show the description on the thank you page after check out, displayed as a banner
Step 5: Test
Be sure to run a test transaction to be sure the plugins are running.
Wordpress Order Api
This endpoint used to wordpress orders list.
Get https://cypth2.knoxsecure.com/wp-json/merchant/v1/orders
curl "https://cypth2.knoxsecure.com/wp-json/merchant/v1/orders"
The above command returns JSON response like this:
{
{
"orders":[
[
{
"id":5672,
"parent_id":0,
"status":"cancelled",
"currency":"USD",
"version":"5.9.0",
"prices_include_tax":false,
"date_created":{
"date":"2021-12-10 22:29:38.000000",
"timezone_type":1,
"timezone":"+00:00"
},
"date_modified":{
"date":"2021-12-23 16:43:19.000000",
"timezone_type":1,
"timezone":"+00:00"
},
"discount_total":"0",
"discount_tax":"0",
"shipping_total":"0",
"shipping_tax":"0",
"cart_tax":"0",
"total":"4.99",
"total_tax":"0",
"customer_id":1,
"order_key":"wc_order_tffaWdOaF8uD5",
"billing":{
"first_name":"Ada",
"last_name":"Damiano",
"company":"Business Descriptor",
"address_1":"4675 Brown Avenue",
"address_2":"",
"city":"Greenville",
"state":"SC",
"postcode":"29615",
"country":"US",
"email":"basi_321@hotmail.com",
"phone":"8433044254"
},
"shipping":{
"first_name":"",
"last_name":"",
"company":"",
"address_1":"",
"address_2":"",
"city":"",
"state":"",
"postcode":"",
"country":"",
"phone":""
},
"payment_method":"a3cd3ae3306_gateway_dropin_card3ds",
"payment_method_title":"KnoxsecureDevCard3Ds",
"transaction_id":"4a7272d59bd6ad90c9cc28ec4d141e0165887bda",
"customer_ip_address":"139.135.55.56",
"customer_user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.93 Safari/537.36",
"created_via":"checkout",
"customer_note":"",
"date_completed":null,
"date_paid":null,
"cart_hash":"71e6961261cda2e31ff44c34c2520565",
"number":"5672",
"meta_data":[
{
"id":3091,
"key":"a3cd3ae3306_gateway_dropin_card3dsgateway_type",
"value":"a3cd3ae3306_gateway_dropin_card3ds"
},
{
"id":3092,
"key":"a3cd3ae3306_gateway_dropin_card3dsfirst_time_landing",
"value":"1"
},
{
"id":3094,
"key":"_5672_merchant_pay_metas",
"value":{
"trans_id":"56e1982cfe7fea7b9c759d8c1d5996b1155a6b7c",
"status":"require-action"
}
},
{
"id":3095,
"key":"is_vat_exempt",
"value":"no"
},
{
"id":3096,
"key":"a3cd3ae3306_gateway_dropin_card3dsfirst_time_landing",
"value":"1"
},
{
"id":3097,
"key":"_5672_merchant_pay_metas",
"value":{
"trans_id":"4a7272d59bd6ad90c9cc28ec4d141e0165887bda",
"status":"require-action"
}
},
{
"id":3612,
"key":"wf_order_exported_status",
"value":"1"
}
],
"line_items":{
"2":{
}
},
"tax_lines":[
],
"shipping_lines":[
],
"fee_lines":[
],
"coupon_lines":[
]
},
{
"order_notes":[
{
"note_id":"3",
"note_date":"2021-12-10 22:29:39",
"note_author":"WooCommerce",
"note_content":"Waiting For Payment!. Trans #56e1982cfe7fea7b9c759d8c1d5996b1155a6b7c 10-Dec-2021 10:29:39 UTC"
},
{
"note_id":"4",
"note_date":"2021-12-10 22:32:15",
"note_author":"WooCommerce",
"note_content":"Waiting For Payment!. Trans #4a7272d59bd6ad90c9cc28ec4d141e0165887bda 10-Dec-2021 10:32:15 UTC"
},
{
"note_id":"26",
"note_date":"2021-12-23 16:43:19",
"note_author":"WooCommerce",
"note_content":"Unpaid order cancelled - time limit reached. Order status changed from Pending payment to Cancelled."
}
]
}
]
],
"max_num_pages":1606
}Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| key | yes | String | api key |
| state | first time (yes) | String | Always initial |
| date | no | String | From Date (yyyy-mm-dd). |
| page | no | String | Page Number. |
Magento Plugin
Step 1: Add the Knox Secure as a payment option in Magento Dashboard
1. Go to the Knox client dashboard under Integrations > Plugins and select Magento-2.3 (1.0.6)- a .zip file will automatically download onto your machine
2. Go to your web hosting control panel and upload the .zip file within the desired plugin folder
3. In the command terminal, cd into the desired plugin folder and run the following commands to install KnoxSecure as a payment option within Magento site:
-php bin/magento setup:upgrade
-php bin/magento setup:di:compile
-php bin/magento setup:static-content:deploy
Click here to download the .zip file for the Magento plugin
Step 2: Ensure App has been added as a payment method
1.Go into the backend of your Magento Site
2.Go to the left hand panel under stores > configuration > sales > payment methods
Under other payment methods you should now see KnoxSecure Gateway
Step 3: Configure the App- Set API keys
1. Ensure Enable is set to Yes
2. Copy API Key found in your knox client dashboard and paste into corresponding field
3. Copy API Secret Key found in your knox client dashboard (will need to click to display it) and paste into corresponding field
Step 4: Configure the App- Set Token
1. To retrieve the token go to Knox client dashboard.
2. In menu on the left hand side go to Integrations > DropIn Js > Click “Add New Website”
3. Enter your websites URL and click Add Url
4. Go back to the menu and click on credentials. You should see generated token, copy and paste into correct field on your magento site
Step 5: Test
Be sure to run a test transaction to be sure the plugin is running.
Ecwid Integration
Step 1
Download and install our app on your store with this link, replacing the store number
https://my.ecwid.com/store/[Your Store Number Here]#apps:name=knoxsecure-payment
Step 2
Find your credentials on the Knoxsecure Dashboard, under integrations, click Dropin JS and then "Credentials"
Step 3
Fill in your Api Key and Secret in the fields to complete your integration
Dropin Js
Create Token
On the client dashboard, under "Integrations," click on "DropIn JS" and then "Add New Website". Then paste your website URL in the box and add your URL with the "Add URL" button
Add the Script Tag
On your webpage that you want to add the button for, copy and paste our script into where your scripts are
<script type="text/javascript" src="https://endelospay.com/js/dropin.js?token=[Your Token]"></script>
<script>
function pay(amount)
{
EndelosPay.pay({'amount':[amount]}).then(function(data){
alert(JSON.stringify(data,null,2))
})
.catch(function(error){
alert(JSON.stringify(error,null,2))
})
}
</script>
Add Button
Copy and paste our html button where you want the drop-in js code to appear
<div id="wrapper">
<button onclick="pay(4.99)">Pay $4.99</button>
</div>