API Core Principles
Last updated
Last updated
This page includes the following info:
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.
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.
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.
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
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
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
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.
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.
