The NCR Counterpoint API is a REST API server designed to be hosted on premises or in the cloud. It is built in pure .NET (C#) using the ServiceStack framework and uses basic authentication using existing NCR Counterpoint user credentials. Some key features of the API are:
DB_CTL.DB_VER
from the Counterpoint database, and executes the proper set of business rules for the target version of Counterpoint.Any instance of the NCR Counterpoint API server can connect to multiple NCR Counterpoint installations and companies. In order for the server to work against an NCR Counterpoint company, the following requirements must be met:
Version 2.4 of the NCR Counterpoint API is tested and supported with the following Counterpoint versions:
Please note that the API relies on the database version value in DB_CTL.DB_VER
for versioning information, and thus it cannot distinguish between multiple Counteproint versions that share a given value for DB_CTL.DB_VER
. There are also no restrictions preventing the API from working with some other versions of Counterpoint Databases. It's very likely that the Counterpoint API will work with other versions of Counterpoint, but the versions listed above are the only versions that the API has been fully tested and is supported on. If there is sufficient demand for support of additional versions, then the scope of supported Counterpoint versions may be expanded.
Installation of the API Server is simple, you essentially just run the .exe to install. See the Installing page for more details.
The API server allows fine grained configuring over the companies, users, and API calls each user can make. See the Configuring the NCR Counterpoint API Server page for information on how to configure the server properly for your environment.
Most, but not all calls to the API will require a free API License key (for the client application or script), and a paid registration.ini option for the Counterpoint merchant. The endpoint chart below indicates which endpoints require each piece of data. See the API Keys and licensing page for more details.
The API has endpoints that can be used to replace card on file records with tokens from Secure Pay, as well as a web UI to allow for easy conversion of card on file data. Details can be found here.
Automated testing is used to validate the operation and accuracy of the API calls. It is highly recommended that consumers of the API review the automated tests to ensure the API provides the needed capabilities. In short, if it's not covered by our automated tests, there's no guarantee that a given usage of the API will continue to work as expected.
To report a defect in the API, an automated test that illustrates the defect, using Postman, is required to be submitted as a pull request to our API Tests project. The test should follow the structure of the other tests in the repository as closely as possible. Hardcoded values may be used if needed. NCR will use your test case to reproduce the issue. If NCR deems the issue to be a defect, it will be resolved and the test will be added to our test suites (the test may be modified to better fit our structure, etc.). This method ensures we build a robust automated test suite, and ensures that your needed functionality is always tested and ensured to work in future releases of the API.
In addition, if there is a usage of the API that is working as expected, but not yet covered by an automated test, and you want to ensure it continues to work as expected, you should submit a pull request with an automated test case for us to consider including in the test suite.
We use and recommend the Postman (Packaged app). It's a chrome web app that allows creating and saving REST requests. We also recommend the "Jetpacks" addon, which is very affordable and allows automated test scripting. These tools are required to create and submit additional test cases to NCR.
You can find all the automated tests we run for the API here. They are written to run against a standard Counterpoint test database and TLD (coming soon). The tests are published not only as reference examples of API usage, but also in hopes the community will contribute to the test cases as well, to help reproduce bugs and improve test coverage. The preferable way to get an improvement to tests or documentation is for users to submit pull requests containing tests to illustrate issues or provide new test coverage. Please submit tests that will work against the standard test database and are structured similarly to our existing conventions. Test databases can be downloaded via ftp from:
files165.cyberlynk.net
Using credentials provided from NCR.
Calls to the API Server are made in the form of http requests. See the page on API requests for specifics on how to form http requests for the NCR Counterpoint API. See documentation on the language or script being used to make the request for details on how to properly create the request in your code.
Calls to the API Server issue http responses similarly to other REST APIs. See the page on API responses for specifics on how to work with http responses. See documentation on the language or script being used to handle the response for details on how to properly work with the response in your code.
The endpoints below each represent individual REST API calls/requests that the API server supports. Each endpoint is either for system administrative functions or company functions, as categorized below. System administrative functions require a system username and password to be included in the Authorization header, while company functions require a counterpoint username (with a company prefix:
Endpoint | Operation (Verb) | APIKey | CP Registration | Description |
---|---|---|---|---|
/AdminUsers |
GET |
X | Gets a list of admins for the API. | |
/AdminUser/{UserId} |
DELETE |
Deletes the provided administrator. | ||
/APIKey |
GET |
Gets information on a single API Key. | ||
/APIKey |
POST |
Post a new APIKey file and updates the APIKey cache. | ||
/APIKeys |
GET |
Gets a list of all API Keys installed on the server. | ||
/CompanyAdmin/{CompanyName}/{AdminUser} |
DELETE |
Delete a company admin by user id. | ||
CompanyAdmins/{CompanyName} |
GET |
Gets a list of Company Admins for the company. | ||
CompanyAdmins/{CompanyName} |
POST |
Adds a list of Company Admins. | ||
CompanyAdmins/{CompanyName} |
PUT |
Sets a list of Company Admins for the company. | ||
/Database/{Id} |
GET |
Gets information about a Database (Company) configured for use by the API Server. | ||
/Database/{Id} |
PUT |
Updates information about a Database (Company) configured for use by the API Server. | ||
/Database/{Id} |
DELETE |
Deletes a Database (Company) so it can no longer be used by the API Server. | ||
/Databases |
GET |
Gets a list of all Databases (Companies) the API is able to interact with. | ||
/Databases |
POST |
Adds one or more Databases (Companies) the API can interact with. | ||
/Databases/ini |
GET |
Gets a list of company DB information from a companies.ini file | ||
/SystemInfo |
GET |
Gets information about the API server and hardware environment. |
Endpoint | Operation (Verb) | APIKey | CP Registration | Description |
---|---|---|---|---|
/Company |
GET |
X | X | Gets information about the given company (from SY_COMP & DB_CTL). |
/Customer |
POST |
X | X | Adds a new customer record. |
/Customer/{CustNo} |
GET |
X | X | Gets information about a customer. |
/Customer/{CustNo} |
PATCH |
X | X | Updates information about a customer. |
/Customer/{CustNo}/Address |
POST |
X | X | Adds a new shipping address to an existing customer. |
/Customer/{CustNo}/Address |
PATCH |
X | X | Updates an existing shipping address for an existing customer. |
/Customer/{CustNo}/Address |
DELETE |
X | X | Deletes a shipping address from an existing customer. |
/Customer/{CustNo}/Card |
POST |
X | X | Adds a credit card on file to an existing customer. |
/Customer/{CustNo}/Card |
PATCH |
X | X | Updates an existing credit card on file for an existing customer. |
/Customer/{CustNo}/Card |
DELETE |
X | X | Deletes a credit card on file for an existing customer. |
/Customer/{CustNo}/Note |
POST |
X | X | Adds a new note to an existing customer. |
/Customer/{CustNo}/Note |
PATCH |
X | X | Updates an existing note on an existing customer. |
/Customer/{CustNo}/Note |
DELETE |
X | X | Deletes a note from an existing customer. |
/Customer/{CustNo}/OpenItems |
GET |
X | X | Gets customer AR Open Item information. |
/CustomerControl |
GET |
X | X | Gets customer control information. |
/Customers |
GET |
X | X | Gets information on customers in bulk. |
/Customers/EC |
GET |
X | X | Gets information on eCommerce customers in bulk. |
/Document |
POST |
X | X | Adds a new document (ticket). |
/Document/{DocId} |
GET |
X | X | Gets information on an existing document (ticket) that hasn't been posted yet. |
/Document/{DocId}/Contact |
POST |
X | X | Adds a contact to an existing document. |
/Document/{DocId}/Contact |
PATCH |
X | X | Updates a contact on an existing document. |
/Document/{DocId}/Contact |
DELETE |
X | X | Deletes a contact from an existing document. |
/Document/{DocId}/Lines |
POST |
X | X | Adds Lines to a document. |
/Document/{DocId}/Note |
POST |
X | X | Adds a note to an existing document. |
/Document/{DocId}/Note |
PATCH |
X | X | Updates a note on an existing document. |
/Document/{DocId}/Note |
DELETE |
X | X | Deletes a note from an existing document. |
/Document/{DocId}/Payments |
POST |
X | X | Adds Payments to a document. |
/EC |
GET |
X | X | Gets eCommerce settings. |
/ECCategories |
GET |
X | X | Gets eCommerce Categories and items. |
/GiftCard/{GiftCardNo} |
GET |
X | X | Gets gift card information. |
/GiftCardCode/{GiftCardCode} |
GET |
X | X | Gets gift card code information. |
/GiftCardCodes |
GET |
X | X | Gets information on gift card codes in bulk. |
/GiftCards |
GET |
X | X | Gets information of Gift Cards in bulk. |
/Inventory/{LocId} |
GET |
X | X | Gets inventory information for all items for a given location. Can be filtered further by category or subcategory |
/InventoryControl |
GET |
X | X | Gets inventory control information. |
/Inventory/EC |
GET |
X | X | Gets eCommerce inventory information for all eCommerce items. |
/Item/Images/{Filename} |
GET |
X | X | Gets an item image for the given item and filename. |
/Item/{ItemNo} |
GET |
X | X | Methods to get item and item inventory information. |
/Item/{ItemNo}/Images |
GET |
X | X | Gets a list of available item images for a given item. |
/Item/{ItemNo}/Inventory/{LocId} |
GET |
X | X | Gets item inventory information for a given item and location. |
/Item/{ItemNo}/InventoryCost/{LocId} |
GET |
X | X | Gets item inventory information for a given item and location. |
/Item/{ItemNo}/Serial/{SerialNo} |
GET |
X | Gets serial information for the given item & serial number. | |
/Item/{ItemNo}/Serials/Location/{LocId} |
GET |
X | Gets serials that are active for the given item at the given location. | |
/ItemCategories |
GET |
X | X | Gets item Categories in bulk. |
/ItemCategory/{CategoryCode} |
GET |
X | X | Gets item category information for the given category code. |
/Items |
GET |
X | X | Gets item information in bulk. Can be further filtered by category or subcategory. |
/Items/{LocId} |
GET |
X | X | Gets item information for a given location in bulk. Can be further filtered by category or subcategory. |
/NSPTransaction |
POST |
POSTs a list of secure pay transactions from Monetra to the db. | ||
/PayCode/{Paycode} |
GET |
X | X | Gets information about a given Paycode. |
/PayCode/{Paycode} |
PATCH |
X | X | Updates information about a Paycode. |
/PayCodes |
GET |
X | X | Gets information on Paycodes in bulk. |
/Role/Endpoints |
GET |
Gets a list of endpoints that can be made available to any role. | ||
/Role/{RoleName} |
DELETE |
Delete a role. | ||
/Role/{RoleName} |
GET |
Gets endpoint information for a role. | ||
/Role/{RoleName} |
PUT |
Update or insert a role. | ||
/Role/{RoleName}/Users |
GET |
Gets a list of users assigned to the role. | ||
/Role/{RoleName}/Users |
PUT |
Add or update the users list belonging to the role. | ||
/Roles |
GET |
Gets a list of roles with endpoint data. | ||
/Roles/Names |
GET |
Gets a list of role names. | ||
/Roles/Users |
GET |
Gets a list of all roles with permissions and assigned users. | ||
/Store/{StoreID} |
GET |
X | X | Gets information on a store. |
/Store/{StoreID}/Station/{StationID} |
GET |
X | X | Gets information on a station. |
/Store/{StoreId}/Tokenize |
POST |
X | Tokenizes the cards for the store. | |
/Store/{StoreId}/Tokenize |
GET |
X | Gets tokenization information for the store. | |
/Stores/Tokenized |
GET |
X | Gets the tokenized count of customer cards on file for each secure pay store. | |
/TaxCodes |
GET |
X | X | Gets information on Tax Codes. |
/User/Admin |
POST |
X | Adds a new sysadmin user. | |
/User/Password |
PUT |
Updates the authenticated user's password. | ||
/User/{UserID} |
GET |
X | X | Gets information on a User. |
/User/{UserID}/Roles |
DELETE |
Deletes a user's assigned roles. | ||
/User/{UserID}/Roles |
GET |
Get a list of roles for the user. | ||
/User/{UserID}/Roles |
PUT |
Update a user's assigned roles. | ||
/Users |
GET |
Gets a list of users. | ||
/Users/{CompanyName} |
GET |
Gets a list of users for the company. | ||
/Users/Roles |
GET |
Get a list of users and their assigned roles. | ||
/VendorItem/{VendorNo}/Item/{ItemNo} |
GET |
X | X | Retrieves information about Vendor Item. |
/Workgroup/{WorkgroupID} |
GET |
X | X | Gets workgroup information. |