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.
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.
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:
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
