API Core Principles
This page includes the following info:
Introduction to APIs and Signup
NymCard provides a set of APIs that empower you to build and manage your card programs. NymCards API Platform, nCore, offers RESTful APIs, it uses HTTPS methods (GET, POST, PUT, DELETE) to perform operations on resources and object instances.
Let's suppose to create a new user, you send a POST method to the /users endpoint. There are some request messages which incorporate data in their message body, for example, to define the attributes of the instance being created or modified, and the nCore API requires that this data be in JSON format.
Understanding API resources
The nCore API includes resources on which you can call procedures and get the desired result, for example, you can perform card issuance and customize them as requested by your customer.
Some notable API resource includes:
users – represents a person who has a payment card
cards – represents a payment card (e.g. virtual card or physical card) used for performing transactions
cardproducts – represents a template defining product features and characteristics
balancelimits – represents a limit a user can have on his/her card account balance
velocitylimits – represents a limit on the amount and number of transactions a cardholder can perform using his/her card
Sign up to get the API key
Please click the ‘sign-up’ link below to create an account and get access to the nCore platform.
Authentication
The nCore API applies standard authentication, which means that the authorization field in the message header is used to hold the API key. Authentication usually refers to proving the API user’s correct identity.
After signing up on nCore platform, you will receive an API key. The API key value does not change and will be used for accessing the API. Please make sure to include the api key in your message request header as given below.
Note: It is recommended not to share your API key with anyone.
Version Controlling
The nCore API version is added in each endpoint resource path. For example, in this endpoint https://api.nymcard.com/v1/cardproducts 'v1' indicates the API version. The API version is incremented whenever a major change is introduced. Minor changes, including patches and bug fixes are released periodically without version increments. Whenever a new major version of the API is released, you can choose either to continue with the existing version or migrate to the new one until the old API versions are deprecated. nCore users shall be informed in advance about the version deprecation timelines and will be given sufficient time to smoothly upgrade their systems to use higher API versions.
Error Handling
This page provides a guide for nCore API error codes and its handling as there might be scenarios where you have to deal with errors at any stage when making requests to the APIs.
You can use these details to rectify failed API requests and optimize your exception-handling. These error codes are based on HTTP response codes. The nCore API uses standard HTTP response codes to identify the status of requests.
HTTP response Code 200 commonly specify a successful response
HTTP response Codes like 4XX commonly specify an error in the client request
HTTP response codes like 5XX commonly specify an error in the nCore platform
The following table shows some common response codes.
Response Code | Description |
200 - OK | Your request was successfully completed |
401 - Unauthorized | Indicates that the authentication is invalid or has expired |
403 - Forbidden | Client was forbidden to execute the operation often due to lack of permissions |
404 - Resource Not Exist | The resource you are trying to find does not exist |
408 - Request Timeout | The request has timed out |
409 - Duplicate Request | The request is conflicting with another one |
429 - Request Attempt Exceed | User has reached his request attempt limits and will need to wait for a certain time before retrying |
500 - Internal Server Error | The server is unable to handle this request at the moment |
501 - Implementation Error | Contracts were defined but haven’t been implemented |
502 - Service Unavailable | An external infrastructure has crashed |
503 - Internet Issue | Poor internet connection |
504 - Gateway Timeout | The server timed out while attempting to complete this request |
Transaction status codes
The full list of error codes you can find in the below document:
Below you can find the list of most common transaction statuses. It is related to response messages which nCore platform sends when showing the status of transaction. You can use these details to rectify failed API requests and optimize your exception- handling.
Status_Code | Status_Description |
0000 | Transaction approved |
0001 | Honor with identification |
0002 | Partially approved |
0003 | Approved (VIP) |
0885 | Not Declined |
1003 | Card suspended |
1006 | Maximum PIN tries exceeded |
1010 | Invalid amount |
1018 | No card record |
1019 | Transaction not permitted to cardholder |
1020 | Transaction not permitted to terminal |
1021 | Exceeds withdrawal amount limit |
1022 | Security Violation |
1804 | Card expiry mismatch |
1806 | Card not active |
1809 | Card Permanently Closed |
1810 | Incorrect ARQC |
1816 | Card Terminated by Issuer |
1829 | Max Amount Limit Reached |
1832 | ATM transaction is not allowed |
1837 | Transaction is not allowed because of absence of PIN |
1838 | E-commerce Non 3DS transaction is not allowed |
1839 | E-commerce 3DS transaction is not allowed |
1840 | E-commerce without CVV2 transaction is not allowed |
1841 | Quasi Cash transaction not allowed |
1842 | Scheme Account Funding transaction is not allowed |
1843 | Scheme Credit transaction is not allowed |
1844 | Account Verification without CVV2 transaction is not allowed |
1845 | Card Product is not configured |
1846 | POS Data Code is not received in transaction |
1847 | Card Product not found |
1848 | Invalid service code defined in CardSettings |
1849 | Incoming transfers are not allowed on this card product |
1850 | Outgoing transfers are not allowed on this card product |
1851 | Fraud engine check has rejected the transaction |
1852 | Fraud check was not successful |
1853 | Pan generation error |
1854 | Completion amount greater than original |
1855 | Completion amount greater than threshold |
1856 | Non-approved STIP advice |
1857 | Presentment not found |
1858 | Transaction type does not match |
1859 | Transaction is not allowed from this MCC |
1860 | Transaction is not allowed from this country |
1862 | ATM transaction is not allowed (Card Level) |
1863 | POS transaction is not allowed (Card Level) |
1864 | Chip transaction is not allowed (Card Level) |
1865 | Magstripe transaction is not allowed (Card Level) |
1866 | Chip Fallback transaction is not allowed (Card Level) |
1867 | Transaction is not allowed because of absence of PIN (Card Level) |
1868 | E-commerce Non 3DS transaction is not allowed (Card Level) |
1869 | E-commerce 3DS transaction is not allowed (Card Level) |
1870 | E-commerce without CVV2 transaction is not allowed (Card Level) |
1871 | Quasi Cash transaction not allowed (Card Level) |
1872 | Scheme Account Funding transaction is not allowed (Card Level) |
1873 | Scheme Credit transaction is not allowed (Card Level) |
1874 | Account Verification without CVV2 transaction is not allowed (Card Level) |
1875 | Maximum account balance limit reached |
1876 | Minimum account balance limit reached |
1877 | Maximum user balance limit reached |
1878 | Minimum user balance limit reached |
1879 | Transaction is not allowed from this MCC (Card Level) |
1880 | Transaction is not allowed from this country (Card Level) |
1881 | Min Amount Limit Reached |
1882 | Min Amount Limit Reached (Card Level) |
1883 | Max Amount Limit Reached (Card Level) |
1888 | Illegal operation request |
1889 | Transaction timed out |
1890 | Wallet not active |
1892 | Cardholder not valid |
1893 | Cardholder Phone not present |
1894 | Previously Cancelled |
1895 | Stop Recurring Payment |
1896 | advance velocity per transaction limit was exceeded |
1897 | advance velocity cumulative amount limit was exceeded |
1898 | advance velocity transaction frequency limit was exceeded |
1899 | Cash.in.not.allowed.card |
1900 | Cash.out.not.allowed.card |
1901 | atm.deposit.not.allowed.card |
1902 | atm deposit transaction is not allowed(tenant level) |
9114 | Original not found |
9115 | Original declined |
Pagination and Sorting
The nCore API supports pagination and sorting for the endpoints that return a list of entities. The sorting operation locates the entities in order whereas the pagination operation then returns a specific range of those ordered entities. In nCore platform you can control pagination through URL query parameters, whereas by default the sorting is performed on the object creation date in descending order.
For example, a GET request to the /users endpoint returns a list of all users. The default sorting operation on this endpoint is based on the object creation date in descending order and the pagination can be controlled through the use of limit and after query parameters.
The following sample request returns the most recently created two users
Example # 01: GET /users?limit=2&after=
The following sample request returns the next 5 users after the provided cursor
Example # 02: GET /users?limit=5&after=a213fe
Parameter Details:
Parameter | Description | Data Type |
Request Parameter | ||
limit | Limit | Integer |
after | Maximum number of objects might be returned | String |
Response Parameter | ||
paging | It indicates whether there are more data to load | Boolean |
after | Returns current results that can be used on the next load | String |
has more | This parameter indicates whether there are more data to load | Boolean |
Idempotency
An idempotent operation is one that has no additional effect if it is called more than once with the same idempotent key. In nCore platform all POST requests are idempotent capable.
For example, if you send a POST request to create a resource and do not receive a response due to any reason (e.g. host network timed out) then you can resend the same call with identical content along with the same idempotent key.
To implement the idempotency, please make sure to include the idempotency key in your message request header as given below.
API Security
The nCore is PCI DSS level 1 certified and is scrutinized by a PCI-certified auditor. This is the most arduous level of certification available in the payments industry. Industry best practices and robust security mechanisms are used to maintain high level of security across nCore platform.
HTTPS for secure connections
nCore encourages and pushes HTTPS for all services using TLS (formally known as SSL)
APIs are available only over TLS
nCore regularly audits the details of its system integration and implementation, including the certificates it provides, the ciphers it validates, and the third-party certificate authorities it uses.
Last updated
