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.

nCore Platform sign-up

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.

POST /cards

Headers: apikey: 2baeed-234fe-2323acf { "user_id": "d089a80f-e641-4045-8a80-54841e4a7458", "card_type": "VIRTUAL", "card_product_id": "b4eabfc-f839-4e51" }

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:

64KB

Status codes.pdf

pdf

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.

POST /cards

Headers: x-nymos-idempotency-key: 1baa3b8f-e4f96-4f96-9a6c-7dc075

{ "user_id": "d089a80f-e641-4045-8a80-54841e4a7458", "card_type": "VIRTUAL", "card_product_id": "b4eabfc-f839-4e51" }

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.