# nCore API Quick Tutorial

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

<img src="https://3730541649-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ftelq9krTgSM8OvsHep7r%2Fuploads%2FKEpVcEcYL595vvLNg7yh%2Ffile.drawing.svg?alt=media&#x26;token=d26cd8ad-30f3-46b2-bac2-0cfa8ca31a54" alt="" class="gitbook-drawing">

### **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](https://portal.sand.platform.nymcard.com/default/login)&#x20;

*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***](https://docs.nymcard.com/api-core-principles#authentication)*.*

### **Run** the API collection in Postman

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

[![Run In Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/19938718-ce866362-3acf-4546-8ae4-9b5a15f99811?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D19938718-ce866362-3acf-4546-8ae4-9b5a15f99811%26entityType%3Dcollection%26workspaceId%3Da35ae74c-6160-4549-813e-78312747da79)

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

For more information refer to the Postman's documentation about [managing environments](https://learning.postman.com/docs/sending-requests/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.&#x20;

<details>

<summary><a href="https://nymcard.com/docs/api#operation/createUser">POST /users</a></summary>

**{**\
&#x20; &#x20;**&#x20;`"first_name": "John",`**\
`    `**`"last_name": “Smith”`**\
\&#xNAN;**`}`**

</details>

### **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**](https://nymcard.com/docs/api#tag/Card-Products/operation/listCardProducts)

*Note: The APIs support pagination and sorting features, please refer to section*[ ***PAGINATION AND SORTING.***](https://docs.nymcard.com/api-core-principles#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.

<details>

<summary><a href="https://nymcard.com/docs/api#tag/Cards/operation/createCard">POST /cards</a></summary>

**`{`**\
`    `**`"user_id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\
`    `**`"card_type": “VIRTUAL”,`**\
`    `**`"card_product_id": "b4eabfc-f839-4e51"`**\
\&#xNAN;**`}`**

</details>

### **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**](https://nymcard.com/docs/api#tag/Cards/operation/getCardAccounts)

{% hint style="info" %}
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'.
{% endhint %}

### **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.

<details>

<summary><a href="https://nymcard.com/docs/api#tag/Accounts/operation/loadAccountFunds">POST /accounts/{id}:loadfunds</a></summary>

**`{`**\
`    `**`"currency": "USD",`**\
`    `**`"amount": 123.45`**\
\&#xNAN;**`}`**

</details>

### **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}**](https://nymcard.com/docs/api#tag/Accounts/operation/getAccount)

### **Control spending**

You can control cardholder’s balance and spending using balance limits and velocity limits.&#x20;

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

<details>

<summary><a href="https://nymcard.com/docs/api#tag/Balance-Limits/operation/createBalanceLimit">POST /balancelimits</a></summary>

**`{`**\
`     `**`"description": "Some description of the balance limit",`**\
`     `**`"type": "PER_ACCOUNT",`**\
`     `**`"min_amount": 1500.1,`**\
`     `**`"max_amount": 1500.1,`**\
`     `**`"currency": "USD"`**\
\&#xNAN;**`}`**

</details>

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

<details>

<summary><a href="https://nymcard.com/docs/api#tag/Velocity-Limits/paths/~1v1~1velocitylimits/post">POST /velocitylimits</a></summary>

**`{`**\
`    `**`"description": "Some description of the velocity Limit",`**\
`    `**`"type": "PER_TRANSACTION",`**\
`    `**`"min_amount": 1500.1,`**\
`    `**`"max_amount": 1500.1,`**\
`    `**`"currency": “USD”,`**\
`    `**`"frequency": 0,`**\
`    `**`“period”: “DAILY”`**\
\&#xNAN;**`}`**

</details>

&#x20;
