nCore API Quick Tutorial

By using this quick tutorial in our Getting Started Guide, you should understand how to:

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

Note: If you want to use APIs from your client application or by directly using the URLs, then a valid API key is required. For reference on how to use this API key, please refer to section AUTHENTICATION.

Run the API collection in Postman

You can run the NymCard API collection in Postman by clicking the following button:

In your Postman environment, you'll need to define the ‘apikey’ variable.

For more information refer to the Postman's documentation about managing environments.

Create a user

You can create a user by sending a POST request to /users endpoint. After the user is created, save the received API response including the 'ID' field.

POST /users

{ "first_name": "John", "last_name": “Smith” }

Retrieve a card product

The card product acts as a template that defines general features and behaviors that are applicable to the cards belonging to that card product. Card product defines currency, PIN, authorization & other card characteristics.

Before creating a card, you must select the card product for which you want to create the card. Send a GET request to /cardproducts endpoint to retrieve card products.

GET /cardproducts

Note: The APIs support pagination and sorting features, please refer to section PAGINATION AND SORTING.

Create a card

A card generally refers to a payment instrument that allows its user to perform payment transactions at merchants. For example, a card type could be referred to as a virtual card or a physical card.

You can create a card by sending a POST request to /cards endpoint. You are required to include below details in your POST message body.

• User ID - A unique ID of the user for whom you want to create a card

• Card Product ID - A unique ID of the card product for which you want to create a card

After the card is created save the received API response, including the 'ID' field, as this is the card's unique Identification.

The code sample below is a request that creates a card.

POST /cards

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

Get card account

When you create a card, an account is usually automatically created and linked to that card. This account is where the balance is maintained. You need a Card ID to retrieve this card account.

GET /cards/{id}/accounts

Note, that you can create a card without an account. It is configured on the card product level, where you have to set the 'link_account_to_card' parameter as 'false'.

Fund a card account

This account needs to be funded before the card can be used for transactions. You can load funds to the card account by sending a POST request to the /accounts/{id}:loadfunds endpoint. This will load funds from the program funding account to the card account.

POST /accounts/{id}:loadfunds

{ "currency": "USD", "amount": 123.45 }

Check card account balance

After loading funds into the card account, you can check your balance by sending a GET request to the /accounts/{id} endpoint.

GET /accounts/{id}

Control spending

You can control cardholder’s balance and spending using balance limits and velocity limits.

Balance limits controls how much balance the user can have in his/her account. Create a balance limit through sending a POST request to /balancelimits endpoint.

The code sample below is a request that creates a balance limit.

POST /balancelimits

{ "description": "Some description of the balance limit", "type": "PER_ACCOUNT", "min_amount": 1500.1, "max_amount": 1500.1, "currency": "USD" }

Velocity limits controls how much the cardholder can spend in one transaction. It also controls how much and/or how many transactions the cardholder can perform in a certain time period (daily, monthly, yearly or all time). Create a velocity limit by sending a POST request to /velocitylimits endpoint.

POST /velocitylimits

{ "description": "Some description of the velocity Limit", "type": "PER_TRANSACTION", "min_amount": 1500.1, "max_amount": 1500.1, "currency": “USD”, "frequency": 0, “period”: “DAILY” }