API Core Principles

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.


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

Below you can find the list of 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.
Transaction approved
Partially approved
Transaction is not allowed because of absence of PIN
E-commerce Non 3DS transaction is not allowed
E-commerce 3DS transaction is not allowed
E-commerce without CVV2 transaction is not allowed
Quasi Cash transaction not allowed
Scheme Account Funding transaction is not allowed
Scheme Credit transaction is not allowed
Account Verification without CVV2 transaction is not allowed
Card Product is not configured
POS Data Code is not received in transaction
Card Product not found
Invalid service code defined in CardSettings
Incoming transfers are not allowed on this card product
Outgoing transfers are not allowed on this card product
Fraud engine check has rejected the transaction
Fraud check was not successful
Pan generation error

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:
Data Type
Request Parameter
Maximum number of objects might be returned
Response Parameter
It indicates whether there are more data to load
Returns current results that can be used on the next load
has more
This parameter indicates whether there are more data to load


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.