# NYMCARD DOCUMENTATION This documentation contains all necessary information related to integration with nCore platform. ### **Get Started** This guide is designed to help you get started with nCore platform. Here you can find tips and instructions about card issuing, product management, funding, transactions and many more. {% content-ref url="/pages/O6EnKhfupVrsMos49akV" %} [nCore API Quick Tutorial](/get-started/quick-tutorial) {% endcontent-ref %} ### For Developers In this section you can be easily redirected to such important tools as Sandbox, API catalog and internal analytics. {% content-ref url="/pages/Cxv7qDH5jlCBGwCQDSPs" %} [Broken mention](broken://pages/Cxv7qDH5jlCBGwCQDSPs) {% endcontent-ref %} # 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](https://portal.sand.platform.nymcard.com/default/login) *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***](/get-started/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.
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**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/listCardProducts) *Note: The APIs support pagination and sorting features, please refer to section*[ ***PAGINATION AND SORTING.***](/get-started/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.
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**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#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.
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}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getAccount) ### **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”`**\ **`}`**
# 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](https://portal.sand.platform.nymcard.com/default/login) ### **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 ****** '***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: {% file src="/files/ktDOwhzE6Bi2McsfORl8" %} 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](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs) 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. # Program management # Manage documents by APIs nCore platform’s document management feature enables you to upload and manage user identification documents (passport, visa, national ID etc.) for identity verification. You can create and manage user’s supporting identification documents by using our following APIs available as nCore platform. * Create a user identification * Get a user identification * Get a specific user identification * Update a user identification * Upload a user identification * Upload a single image of a user identification * Return a file metadata * Return a file * Download a file * Delete a file ### **Create a user identification** You can create a user identification by sending a **POST** request to **/users/{user\_id}/identifications** endpoint as shown below.
POST /users/{user_id}/identifications **`{`**\ ` `**`"type": "PASSPORT",`**\ ` `**`"number": "132123123",`**\ ` `**`"expiration_date": "2021-09-20T10:10:40.182Z",`**\ **`}`**
### **Get a user identifications** You can retrieve a list of user identifications by sending a **GET** request to **/users/{user\_id}/identifications** endpoint as shown below. > [**GET /users/{user\_id}/identifications**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/getIdentifications) ### **Get a specific user identification** You can retrieve a specific user identification info by sending a **GET** request to **/users/{user\_id}/identifications/{identification\_id}** endpoint as shown below. > [**GET /users/{user\_id}/identifications/{identification\_id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/getIdentification) ### **Update a user identification** You can update any user identification by sending a **PUT** request **/users/{user\_id}/identifications/{identification\_id}** endpoint as shown below. > [**PUT /users/{user\_id}/identifications/{identification\_id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/updateIdentification) ### **Upload a user identification** You can upload more than one identification files by sending a **PUT** request to **/users/{user\_id}/identifications/{identification\_id}** endpoint as shown below. > [**PUT /users/{user\_id}/identifications/{identification\_id}/files**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/UploadIdentification) Please note: * Using this API, you can upload maximum 5 files at a time. * The maximum size of the file is 128 Mb. * Allowed extensions are .pdf, .jpg, .jpeg, .png, .bmp, .doc, and .docx. * A single user identification can have maximum 10 files. ### **Upload a single image of user identification** You can upload a single user identification file by sending a **PUT** request to **/users/{user\_id}/identifications/{identification\_id}/files** endpoint as shown below. > [**PUT /users/{user\_id}/identifications/{identification\_id}/files**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/uploadSingleFile) Please note: * Using this API, you can upload a single file at a time. * The maximum size of the file is 128 Mb. * Allowed extensions are .pdf, .jpg, .jpeg, .png, .bmp, .doc, and .docx. * A single user identification can have maximum 10 files. {% hint style="info" %} Note, that these APIs contain 'identification\_type' and 'identification\_document\_type' parameters, which can have the following values: a) identification\_type = NATIONAL\_ID identification\_document\_type = NATIONAL\_ID\_FRONT & NATIONAL\_ID\_BACK b) identification\_type = PASSPORT identification\_document\_type = PASSPORT\_PAGE1 & PASSPORT\_PAGE2 c) identification\_type = VISA identification\_document\_type = VISA d) identification\_type = TRADE\_LICENSE, COMMERCIAL\_LICENSE, INCORPORATION\_CERT, INCUMBENCY\_CERT, MEMORANDUM\_ARTICLES, BANK\_STATEMENT, ADDITIONAL identification\_document\_type = NOT APPLICABLE {% endhint %} ### **Return a file metadata** You can retrieve a specific file metadata info by sending a **GET** request to **/users/{user\_id}/identifications/{identification\_id}/files/{file\_id}** endpoint as shown below. > [**GET /users/{user\_id}/identifications/{identification\_id}/files/{file\_id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/getFile) ### **Return a file** You can browse a specific user identification file by sending a **GET** request to **/users/{user\_id}/identifications/{identification\_id}/files/{file\_id}:browse** endpoint as shown below. > [**GET /users/{user\_id}/identifications/{identification\_id}/files/{file\_id}:browse**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/browseFile) ### **Download a file** You can download a specific file by sending a **GET** request to **/users/{user\_id}/identifications/{identification\_id}/files/{file\_id}:download** endpoint as shown below. > [**GET /users/{user\_id}/identifications/{identification\_id}/files/{file\_id}:download**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/downloadFile) ### **Delete a file** You can delete a specific user identification file by sending a **DELETE** request to **/users/{user\_id}/identifications/{identification\_id}/files/{file\_id}** endpoint as shown below. > [**DELETE /users/{user\_id}/identifications/{identification\_id}/files/{file\_id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/deleteFile) # User KYB process nCore platform provides an automated feature to onboard SMEs ***(Small Medium Enterprises)*** under your business. With this feature you can create as many SMEs as you want under your business hub. As part of the SME onboarding process, the platform is required to automate the KYB (know your business) process through the APIs and the data is shown and validated by NymCard internally before making any decision to pass or fail the onboarding process. Below you can find **preliminary documents** required for onboarding a corporate entity:
For the KYB process, there are following sub-user types which are required to create and upload their supporting documents for the KYB process. The sub-users are given below: * Director * Signature * Shareholder * Shareholder\_business Once the users with such user types are created, then the system enables you to upload their identification documents. After that you can create a main business user (i.e. the SME), and provide the sub-user’s (Director, Signature, and Shareholder) IDs in the request. ***For example,*** you want to create a business user (SME) , whose name is “Test”. The SME **Test** has 3 Directors, 2 signatures and 5 shareholders. To create the use case, please follow the following steps: 1. Create all sub-users such as 3 Directors, 2 signatures and 5 shareholders one by one. 2. Then you should create identifications for each of 3 Directors, 2 signatures and 5 shareholders one by one. 3. After that you will be able to upload identification documents for each of 3 Directors, 2 signatures and 5 shareholders one by one. 4. And at last you will be able to create the business user (“Test”), and include all the created director’s, signature’s and shareholder’s IDs in the designated lists so that the sub-users will get linked with the SME **Test**. 5. If required you can create business SME Test’s identification and upload any supporting documents by using the same APIs mentioned in this section. ### SME onboarding step by step process Below you can find the step-by-step instructions on how to create a business user. ### Create SME’s sub-users To create a Director, Signature or Shareholder, send a **POST** request to **/users** endpoint and indicate relevant ‘user\_type’ (DIRECTOR, SIGNATURE or SHAREHOLDER). Below you can find sample requests and responses with relevant parameters for each user type. {% hint style="info" %} Note, you can create up to 10 sub-users of each type. {% endhint %} #### Create a sub-user type: **Director**
POST /users **`{`** **`"id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"title": "MR",`** **`"first_name": "John",`** **`"middle_name": "Anthony",`** **`"last_name": "Smith",`** **`"native_name": "Júañ Hérreró",`** **`"date_of_birth": "2012-05-04",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"gender": "male",`** **`"preferred_language": "en",`** **`"place_of_birth": "Las Vegas",`** **`"nationality": "USA",`** **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"country_residence": "USA",`** **`"user_type": "DIRECTOR",`** **`"designation": "CEO"`** **`}`**
Response **`{`** **`"id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"title": "MR",`** **`"first_name": "John",`** **`"middle_name": "Anthony",`** **`"last_name": "Smith",`** **`"native_name": "Júañ Hérreró",`** **`"date_of_birth": "2012-05-04",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"gender": "male",`** **`"preferred_language": "en",`** **`"place_of_birth": "Las Vegas",`** **`"nationality": "USA",`** **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"country_residence": "USA",`** **`"user_type": "DIRECTOR",`** **`"designation": "CEO"`** **`"status": "PENDINGKYB",`** **`"status_reason_code": "I0",`** **`"created": "2021-04-04T07:22:03.224Z",`** **`"modified": "2021-04-04T07:22:03.224Z"`** **`}`**
#### Create a sub-user type: **Signature**
POST /users **`{`** **`"id": "4ba3028b-0e38-4113-a90e-5a8cd3fb27a6",`** **`"title": "MR",`** **`"first_name": "Jack",`** **`"middle_name": "Michel",`** **`"last_name": "Swenny",`** **`"native_name": "Pedro Hérreró",`** **`"date_of_birth": "2012-05-04",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"gender": "male",`** **`"preferred_language": "en",`** **`"place_of_birth": "Las Vegas",`** **`"nationality": "USA",`** **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"country_residence": "USA",`** **`"user_type": "SIGNATURE",`** **`"designation": "CEO"`** **`}`**
Response **`{`** **`"id": "4ba3028b-0e38-4113-a90e-5a8cd3fb27a6",`** **`"title": "MR",`** **`"first_name": "Jack",`** **`"middle_name": "Michel",`** **`"last_name": "Sweeny",`** **`"native_name": "Pedro Hérreró",`** **`"date_of_birth": "2012-05-04",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"gender": "male",`** **`"preferred_language": "en",`** **`"place_of_birth": "Las Vegas",`** **`"nationality": "USA",`** **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"country_residence": "USA",`** **`"user_type": "SIGNATURE",`** **`"designation": "CEO",`** **`"status": "PENDINGKYB",`** **`"status_reason_code": "I0",`** **`"created": "2021-04-04T07:22:03.224Z",`** **`"modified": "2021-04-04T07:22:03.224Z"`** **`}`**
#### Create a sub-user type: **Shareholder**
POST /users **`{`** **`"id": "6daf85ea-f5f6-4e0b-b381-de5b7a9834e2",`** **`"title": "MR",`** **`"first_name": "Jacob",`** **`"middle_name": "Andrew",`** **`"last_name": "Fray",`** **`"native_name": "Max Hérreró",`** **`"date_of_birth": "2012-05-04",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"gender": "male",`** **`"preferred_language": "en",`** **`"place_of_birth": "Las Vegas",`** **`"nationality": "USA",`** **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"country_residence": "USA",`** **`"user_type": "SHAREHOLDER",`** **`"local_address": {`**  **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"shares_percentage": "100",`** **`"share_controller_name": "Nabil Radwan"`** **`}`**
Response **`{`** **`"id": "6daf85ea-f5f6-4e0b-b381-de5b7a9834e2",`** **`"title": "MR",`** **`"first_name": "Jacob",`** **`"middle_name": "Andrew",`** **`"last_name": "Fray",`** **`"native_name": "Max Hérreró",`** **`"date_of_birth": "2012-05-04",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"gender": "male",`** **`"preferred_language": "en",`** **`"place_of_birth": "Las Vegas",`** **`"nationality": "USA",`** **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"country_residence": "USA",`** **`"user_type": "SHAREHOLDER",`** **`"local_address": {`**   **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"shares_percentage": "100",`** **`"share_controller_name": "Nabil Radwan",`** **`"status": "PENDINGKYB",`** **`"status_reason_code": "I0",`** **`"created": "2021-04-04T07:22:03.224Z",`** **`"modified": "2021-04-04T07:22:03.224Z"`** **`}`**
### Create SME’s sub user’s identifications To create an identification, you should send a **POST** request to **/users/{user\_id}/identifications** endpoint, where you should indicate a **‘type’** parameter, relevant to this specific sub-user. Below you can find the list of available identification types: | **Name** | **Description** | | -------------------- | ------------------------------------------------------------------------------- | | PASSPORT | Passport | | VISA | Visa | | NATIONAL\_ID | National ID | | TRADE\_LICENSE | Trade license | | COMMERCIAL\_LICENSE | Commercial license | | INCORPORATION\_CERT | Company Certification of Incorporation | | INCUMBENCY\_CERT | Incumbency certificate | | MEMORANDUM\_ARTICLES | Memorandum and articles. Company Memorandum and Articles of Association/By-Laws | | BANK\_STATEMENT | Bank statement of 3 months. The size of the document should be up to 5 Mb. | | ADDITIONAL | Additional document (other company legal document) | {% hint style="info" %} The identification can be created for sub-users as well as for the SME business user itself if required. {% endhint %} Below you can find an example for **National ID** identification creation:
POST /users/{user_id}/identifications **`{`** **`"type": "NATIONAL_ID",`** **`"number": "132453123",`** **`"issuance_authority": "Ministry of defense",`** **`"place_of_issuance": "Lebanon",`** **`"expiration_date": "2012-05-04T19:42:32.987Z",`** **`"issuance_date": "2012-05-04T19:42:32.987Z",`** **`"identification_note": "Some note"`** **`}`**
Response **`{`** **`"id": "4e354f67-2ea5-43a9-92ec-2f967c3981f6",`** **`"type": "NATIONAL_ID",`** **`"number": "132453123",`** **`"issuance_authority": "Ministry of defense",`** **`"place_of_issuance": "UAE",`** **`"identification_note": "Some note",`** **`"expiration_date": "2012-05-04T19:42:32.987Z",`** **`"issuance_date": "2012-05-04T19:42:32.987Z",`** **`"document_status": PENDINGKYB,`** **`"document_status_reason": "I0",`** **`"created": "2021-07-18T07:52:21.755Z",`** **`"modified": "2021-08-18T07:53:21.755Z"`** **`}`**
Also here you can find an example for **VISA** identification creation:
POST /users/{user_id}/identifications **`{`** **`"type": "VISA",`** **`"number": "132451408",`** **`"issuance_authority": "Ministry of defense",`** **`"place_of_issuance": "Lebanon",`** **`"expiration_date": "2012-05-04T19:42:32.987Z",`** **`"issuance_date": "2012-05-04T19:42:32.987Z",`** **`"identification_note": "Some note"`** **`}`**
Response **`{`** **`"id": "4e394f67-2ea5-58a9-92ec-2f967c3981fw",`** **`"type": "VISA",`** **`"number": "132451408",`** **`"issuance_authority": "Ministry of defense",`** **`"place_of_issuance": "UAE",`** **`"identification_note": "Some note",`** **`"expiration_date": "2012-05-04T19:42:32.987Z",`** **`"issuance_date": "2012-05-04T19:42:32.987Z",`** **`"document_status": PENDINGKYB,`** **`"document_status_reason": "I0",`** **`"created": "2021-07-18T07:52:21.755Z",`** **`"modified": "2021-08-18T07:53:21.755Z"`** **`}`**
You can create any of the identification types mentioned above by sending a **POST** request to **/user/{user\_id}/identification** endpoint. Below you can find an example with **Trade license**:
POST /users/{user_id}/identifications **`{`** **`"type": "TRADE_LICENSE",`** **`"number": "132123123",`** **`"issuance_authority": "Ministry of defense",`** **`"place_of_issuance": "UAE",`** **`"identification_note": "Trade license of the SME Test",`** **`"expiration_date": "2012-05-04T19:42:32.987Z",`** **`"issuance_date": "2012-05-04T19:42:32.987Z"`** **`}`**
Response **`{`** **`"id": "9e354f40-2ea5-43a9-92ec-2f967c3981f9",`** **`"type": "TRADE_LICENSE",`** **`"number": "132123123",`** **`"issuance_authority": "Ministry of defense",`** **`"place_of_issuance": "UAE",`** **`"identification_note": "Trade license of the SME Test",`** **`"expiration_date": "2012-05-04T19:42:32.987Z",`** **`"issuance_date": "2012-05-04T19:42:32.987Z",`** **`"document_status": PENDINGKYB,`** **`"document_status_reason": "I0",`** **`"created": "2021-07-18T07:52:21.755Z",`** **`"modified": "2021-08-18T07:53:21.755Z"`** **`}`**
{% hint style="info" %} Note, that the user with 'user\_type' "DIRECTOR", "SIGNATURE" or "SHAREHOLDER" is automatically created with user 'status' as 'PENDINGKYB' and 'status\_reason\_code' as 'I0' for user identification purposes. {% endhint %} ### Upload SME’s sub user’s documents After identification is created, you can upload the relevant documents. For this you should send a **POST** request to **/users/{user\_id}/identifications/{identification\_id}/files** endpoint. Below you can find a sample request:
POST /users/{user_id}/identifications/{identification_id}/files **`{`** **`"id": "9e354f40-2ea5-43a9-92ec-2f967c3981f9.png",`** **`"file_name": "9e354f40-2ea5-43a9-92ec-2f967c3981f9.png",`** **`"identification_type": "PASSPORT",`** **`"identification_document_type": "PASSPORT_PAGE1",`** **`"content_type": "application/pdf",`** **`"size": 4562`** **`}`**
Response **`{`** **`"id": "9e354f40-2ea5-43a9-92ec-2f967c3981f9.png",`** **`"file_name": "9e354f40-2ea5-43a9-92ec-2f967c3981f9.png",`** **`"identification_type": "PASSPORT",`** **`"identification_document_type": "PASSPORT_PAGE1",`**  **`"document_version": 1,`** **`"content_type": "application/pdf",`** **`"size": 4562,`** **`"created": "2012-05-04T19:42:32.987Z"`** **`}`**
{% hint style="info" %} Note, that you can upload different types of documents such as NATIONAL\_ID, VISA, MEMORANDUM, BANK\_STATEMENT etc.. {% endhint %} ### Create business (SME) user Now you can create a business user along with the details and sub-users, created in step 1. For this you should send a **POST** request to **/users** endpoint and indicate ‘user\_type’ = BUSINESS. Below you can find a sample request and response.
POST /users **`{`** **`"id": "3ba3028b-0e38-4e0b-a90e-5a8cd3dj27a5",`** **`"title": "MR",`** **`"first_name": "Alex",`** **`"middle_name": "Daniel",`** **`"last_name": "Gates",`** **`"native_name": "Robert Shaw",`** **`"date_of_birth": "2012-05-04",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"gender": "MALE",`** **`"preferred_language": "EN",`** **`"place_of_birth": "Las Vegas",`**   **`"nationality": "USA",`** **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`**   **`"country_tax_residence": "USA",`** **`"company_name": "Example",`** **`"company_address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"company_country": "USA",`** **`"industry_type": "I01",`** **`"user_type": "BUSINESS",`** **`"business_legal_name": "Insurance corporation",`** **`"business_dba_name": "John Smith insurance corporation",`** **`"date_established": "2012-05-04T19:42:32.987Z",`** **`"phone_number": "+551185249635",`** **`"website": "example.com”,`** **`"incorporation_type": "LLC",`** **`"entity_registered_no": "2233445533",`** **`"old_entity_name": "",`** **`"old_entity_ops_start_date": "",`** **`"old_entity_ops_end_date": "",`** **`"regulated_entity": true,`** **`"regulator_name": "ABC",`** **`"business_activities": "IT Services",`** **`"other_operated_countries": "US",`** **`"tax_residence_country": "UAE",`** **`"tin": "1122334455",`** **`"external_auditor_name": "ABC",`** **`"director_list": [`** **`{`** **`"cf2de83b-ac68-441b-bc54-21de60014d57", "cf2de83b-ac68-441b-bc54-21de60014d47",`** **`"cf2de83b-ac68-441b-bc54-21de60014d53",`** **`}`** **`],`** **`"signature_list": [`** **`{`** **`"4ba3028b-0e38-4113-a90e-5a8cd3fb27a6", "4ba3028b-0e38-4166-a90e-5a8cd3fb27a8", "4ba3028b-0e38-4198-a90e-5a8cd3fb27a2",`** **`}`** **`],`** **`"shareholder_list": [`** **`{`** **`"6daf85ea-f5f6-4e0b-b381-de5b7a9834e2", "6daf85ea-f5f6-4e0b-b356-de5b7a9834e4", "6daf85ea-f5f6-4e0b-b581-de5b7a9834e7",`** **`}`** **`],`** **`"group_additional_info": {`** **`"group_entity": true,`** **`"independent_entity": false,`** **`"special_investment": false,`** **`"entity_details": "ABCD LLC"`** **`},`** **`"pep_check_info": {`** **`"pri_pep_check": true,`** **`"pri_pep_check_name": "ABC",`** **`"sec_pep_check":true,`** **`"sec_pep_check_name":XYZ`** **`},`** **`"no_of_employees":"25",`** **`"accept_cash_check": true,`** **`"annual_turnover":"120000",`** **`"source_of_funds":"Business",`** **`"source_fund_uae":true,`** **`"due_diligence_declaration": {`** **`"bankruptcy_declaration": false,`** **`"disciplinary_declaration": false,`** **`"fraud_aml_declaration": false,`** **`"disqualification_declaration": false,`** **`"conviction_accusition_declaration": false,`** **`"breach_of_law_declaration": false`** **`}`** **`}`**
Response **`{`** **`"id": "3ba3028b-0e38-4e0b-a90e-5a8cd3dj27a5",`** **`"title": "MR",`** **`"first_name": "Alex",`** **`"middle_name": "Daniel",`** **`"last_name": "Gates",`** **`"native_name": "Robert Shaw",`** **`"date_of_birth": "2012-05-04",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"gender": "MALE",`** **`"preferred_language": "EN",`** **`"place_of_birth": "Las Vegas",`**   **`"nationality": "USA",`**   **`"country_tax_residence": "USA",`** **`"company_name": "Example",`** **`"company_address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "USA"`** **`},`** **`"company_country": "USA",`** **`"industry_type": "I01",`** **`"user_type": "BUSINESS",`** **`"business_legal_name": "Insurance corporation",`** **`"business_dba_name": "John Smith insurance corporation",`** **`"date_established": "2012-05-04T19:42:32.987Z",`** **`"phone_number": "+551185249635",`** **`"website": "example.com”,`** **`"incorporation_type": "LLC",`** **`"entity_registered_no": "",`** **`"old_entity_name": "",`** **`"old_entity_ops_start_date": "",`** **`"old_entity_ops_end_date": "",`** **`"regulated_entity": "",`** **`"regulator_name": "",`** **`"business_activities": "",`** **`"other_operated_countries": "",`** **`"tax_residence_country": "",`** **`"tin": "",`** **`"external_auditor_name": "",`** **`"director_list": [`** **`{`** **`"cf2de83b-ac68-441b-bc54-21de60014d57", "cf2de83b-ac68-441b-bc54-21de60014d47",`** **`"cf2de83b-ac68-441b-bc54-21de60014d53",`** **`}`** **`],`** **`"signature_list": [`** **`{`** **`"4ba3028b-0e38-4113-a90e-5a8cd3fb27a6", "4ba3028b-0e38-4166-a90e-5a8cd3fb27a8", "4ba3028b-0e38-4198-a90e-5a8cd3fb27a2",`** **`}`** **`],`** **`"shareholder_list": [`** **`{`** **`"6daf85ea-f5f6-4e0b-b381-de5b7a9834e2", "6daf85ea-f5f6-4e0b-b356-de5b7a9834e4", "6daf85ea-f5f6-4e0b-b581-de5b7a9834e7",`** **`}`** **`],`** **`"group_additional_info": {`** **`"group_entity": true,`** **`"independent_entity": false,`** **`"special_investment": false,`** **`"entity_details": "ABDC LLC"`** **`},`** **`"pep_check_info": {`** **`"pri_pep_check": true,`** **`"pri_pep_check_name": "ABC",`** **`"sec_pep_check":false,`** **`"sec_pep_check_name":"XYZ"`** **`},`** **`"no_of_employees":"25",`** **`"accept_cash_check": true,`** **`"annual_turnover":"12000",`** **`"source_of_funds":"Business",`** **`"source_fund_uae": true,`** **`"due_diligence_declaration": {`** **`"bankruptcy_declaration": false,`** **`"disciplinary_declaration": false,`** **`"fraud_aml_declaration": false,`** **`"disqualification_declaration": false,`** **`"conviction_accusition_declaration": false,`** **`"breach_of_law_declaration": false`** **`},`** **`"status": "PENDINGKYB",`** **`"status_reason_code": "I0",`** **`"created": "2021-07-18T07:52:21.755Z",`** **`"modified": "2021-08-18T07:53:21.755Z"`** **`}`**
{% hint style="info" %} Please Note: 1. You can create up to 10 sub-users (Director, Signature and Shareholder) for each SME. 2. You can create sub-users first, and then create a SME business user. While creating a SME business user, you should provide all of the sub-user’s IDs in the designated fields for linking. **Or** 3. You can create a SME business user first along with the further details, and then create a list of required sub-users, create their identifications and upload the documents. Then you should update the SME business user while providing all of the created sub-user’s IDs for linking. 4. Now you can create identification for business SME user and upload any supporting documents such as TRADE\_LICENSE, COMMERCIAL\_LICENSE, INCORPORATION\_CERT, INCUMBENCY\_CERT, MEMORANDUM\_ARTICLES, BANK\_STATEMENT and/or ADDITIONAL. 5. You can retrieve relationships linked to a specific user by sending a **POST** request to **/users/{id}:getLinkedRelationships** endpoint. 6. Added new user type "SHAREHOLDER\_BUSINESS", which can be used in case you have business and shareholder as a single entity under business user. Also added 2 new related parameters - 'license\_type' and 'license\_expiry'. {% endhint %} ### KYB status transitions The SME’s sub-user, their identifications, and a SME itself will be created with a status as **PENDINGKYB** and it will only transition to **ACTIVE** when processed and approved by the NymCard’s compliance team after considerable amount of validation. If the documents are not verified due to any reason, the system will mark the **status** as **SUSPENDED** and **status\_reason\_code** as **S5** - ‘Admin rejected due to ID verification failed’. It means that the additional document is requested by the NymCard’s compliance team. You would be required to provide the requested documents by using the ‘[Upload single image of identification](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-documents/operation/uploadSingleFile)’ API as mentioned in section ‘[**Upload SME’s sub user’s document’**](#upload-smes-sub-users-documents)**.** # Necessary parameters per user type You can create a user with the following user types: * "INDIVIDUAL" * "BUSINESS" * "DIRECTOR" * "SIGNATURE" * "SHAREHOLDER" * "SHAREHOLDER\_BUSINESS" ### Individual user type To create an individual user, you should indicate at least **'first\_name'** parameter. Below you can find an example of user creation with 'user\_type'="INDIVIDUAL":
Sample **`curl --location --request POST '`**[**`https://api.dev.platform.nm-1.nymcard.com/v1/users`**](https://api.dev.platform.nm-1.nymcard.com/v1/users)**`' \`** **`--header 'Content-Type: application/json' \`** **`--header 'apikey: tenant1-key' \`** **`--data-raw '{`** **`"title": "MRS",`** **`"first_name": "Sara",`** **`"middle_name": "Anthony",`** **`"last_name": "pass",`** **`"native_name": "John Smith",`** **`"date_of_birth": "1989-11-07",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "UKR"`** **`},`** **`"gender": "MALE",`** **`"preferred_language": "EN",`** **`"place_of_birth": "USA",`** **`"nationality": "USA",`** **`"country_residence": "USA",`** **`"country_tax_residence": "USA",`** **`"employment_type": "SALARIED",`** **`"employment_title": "string",`** **`"monthly_salary": 0,`** **`"company_name": "string",`** **`"company_address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "UKR"`** **`},`** **`"company_country": "USA",`** **`"industry_type": "I01",`** **`"expected_monthly_balance": 0,`** **`// "relationship_with_parent": "SON",`** **`// "parent_user_id": "71204e77-73ce-4671-b997-baf610ff8532",`** **`"user_type": "INDIVIDUAL",`** **`"phone_number": "+551185249635"`**
**`}'`**
Response **`{`** **`"id": "95e7ffbe-0d8a-4c8d-ab84-4476c16a1494",`** **`"title": "MRS",`** **`"first_name": "Sara",`** **`"middle_name": "Anthony",`** **`"last_name": "pass",`** **`"native_name": "John Smith",`** **`"date_of_birth": "1989-11-07",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "UKR"`** **`},`** **`"gender": "MALE",`** **`"preferred_language": "EN",`** **`"place_of_birth": "USA",`** **`"nationality": "USA",`** **`"created": "2022-09-23T13:30:31.780Z",`** **`"modified": "2022-09-23T13:30:31.780Z",`** **`"country_residence": "USA",`** **`"country_tax_residence": "USA",`** **`"employment_type": "SALARIED",`** **`"employment_title": "string",`** **`"monthly_salary": 0,`** **`"company_name": "string",`** **`"company_address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "UKR"`** **`},`** **`"company_country": "USA",`** **`"industry_type": "I01",`** **`"expected_monthly_balance": 0,`** **`"user_type": "INDIVIDUAL",`** **`"phone_number": "+551185249635",`** **`"status": "PENDINGIDVERIFICATION",`** **`"status_reason_code": "I0",`** **`"director_list": [],`** **`"signature_list": [],`** **`"shareholder_list": [],`** **`"default_user": false`** **`}`**
### Business user type To create a business user, you should indicate at least **'business\_legal\_name'** and **"business\_dba\_name"** parameters. Below you can find an example of user creation with 'user\_type'="BUSINESS":
Sample **`curl --location --request POST '`**[**`https://api.dev.platform.nm-1.nymcard.com/v1/users`**](https://api.dev.platform.nm-1.nymcard.com/v1/users)**`' \`** **`--header 'Content-Type: application/json' \`** **`--header 'apikey: tenant1-key' \`** **`--data-raw '{`** **`// "title": "MR",`** **`"first_name": "John",`** **`"user_type": "BUSINESS",`** **`"middle_name": "Anthony",`** **`"last_name": "pass",`** **`"native_name": "John Smith",`** **`"date_of_birth": "2000-09-28",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "UKR"`** **`},`** **`"gender": "MALE",`** **`"preferred_language": "EN",`** **`"place_of_birth": "USA",`** **`"nationality": "USA",`** **`//"parent_user_id": "cf2de83b441b-bc54-21de60014d57",`** **`"country_residence": "USA",`** **`"country_tax_residence": "USA",`** **`"employment_type": "SALARIED",`** **`"employment_title": "string",`** **`"monthly_salary": 0,`** **`"company_name": "string",`** **`"company_address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "UKR"`** **`},`** **`"company_country": "USA",`** **`"industry_type": "I01",`** **`"expected_monthly_balance": 0,`** **`"user_type": "BUSINESS",`** **`"business_legal_name": "string",`** **`"business_dba_name": "string",`** **`"date_established": "2021-09-28",`** **`"phone_number": "+551185249635",`** **`"website": "string",`**
**`"incorporation_type": "LLC",`** **`"entity_registered_no": "22334455",`** **`"old_entity_name": "",`** **`"old_entity_ops_start_date": "2021-09-28T00:00:00.000Z",`** **`"old_entity_ops_end_date": "2021-09-28T00:00:00.000Z",`** **`"regulated_entity": true,`** **`"regulator_name": "XYZ",`** **`"business_activities": "Consultancy",`** **`"other_operated_countries": "UAE, US",`** **`"tax_residence_country": "UAE",`** **`"tin": "1122334455",`** **`"external_auditor_name": "",`** **`"group_additional_info": {`** **`"group_entity": true,`** **`"independent_entity": true,`** **`"special_investment": true,`** **`"entity_details": "name"`** **`},`** **`"pep_check_info": {`** **`"pri_pep_check": true,`** **`"pri_pep_check_name": "ABC",`** **`"sec_pep_check":true,`** **`"sec_pep_check_name":"XYZ"`** **`},`** **`// "no_of_employees":"25",`** **`"accept_cash_check": true,`** **`"annual_turnover":"120000",`** **`"source_of_funds":"IT services",`** **`"source_fund_uae":true,`** **`"due_diligence_declaration": {`** **`"bankruptcy_declaration": false,`** **`"disciplinary_declaration": false,`** **`"fraud_aml_declaration": false,`** **`"disqualification_declaration": false,`** **`"conviction_accusition_declaration": false,`** **`"breach_of_law_declaration": false`** **`}`** **`}'`**
Response **`{`** **`"id": "65eb57bd-6290-431d-bf23-1cb287d7d7a8",`** **`"first_name": "John",`** **`"middle_name": "Anthony",`** **`"last_name": "pass",`** **`"native_name": "John Smith",`** **`"date_of_birth": "2000-09-28",`** **`"email": "bob@example.com",`** **`"mobile": "+551185249635",`** **`"address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "UKR"`** **`},`** **`"gender": "MALE",`** **`"preferred_language": "EN",`** **`"place_of_birth": "USA",`** **`"nationality": "USA",`** **`"created": "2022-09-23T13:34:30.295Z",`** **`"modified": "2022-09-23T13:34:30.295Z",`** **`"country_residence": "USA",`** **`"country_tax_residence": "USA",`** **`"employment_type": "SALARIED",`** **`"employment_title": "string",`** **`"monthly_salary": 0,`** **`"company_name": "string",`** **`"company_address": {`** **`"address_line1": "Flat 1904",`** **`"address_line2": "Glass Tower",`** **`"city": "New York City",`** **`"state": "New York",`** **`"postal_code": "12345",`** **`"country": "UKR"`** **`},`** **`"company_country": "USA",`** **`"industry_type": "I01",`** **`"expected_monthly_balance": 0,`** **`"user_type": "BUSINESS",`** **`"business_legal_name": "string",`** **`"business_dba_name": "string",`** **`"date_established": "2021-09-28T00:00:00.000Z",`** **`"phone_number": "+551185249635",`** **`"website": "string",`** **`"status": "PENDINGKYB",`** **`"status_reason_code": "I0",`** **`"incorporation_type": "LLC",`** **`"entity_registered_no": "22334455",`** **`"old_entity_ops_start_date": "2021-09-28T00:00:00.000Z",`** **`"old_entity_ops_end_date": "2021-09-28T00:00:00.000Z",`** **`"regulated_entity": true,`** **`"regulator_name": "XYZ",`** **`"business_activities": "Consultancy",`** **`"other_operated_countries": "UAE, US",`** **`"tax_residence_country": "UAE",`** **`"tin": "1122334455",`** **`"director_list": [],`** **`"signature_list": [],`** **`"shareholder_list": [],`** **`"group_additional_info": {`** **`"group_entity": true,`** **`"independent_entity": true,`** **`"special_investment": true,`** **`"entity_details": "name"`** **`},`** **`"pep_check_info": {`** **`"pri_pep_check": true,`** **`"pri_pep_check_name": "ABC",`** **`"sec_pep_check": true,`** **`"sec_pep_check_name": "XYZ"`** **`},`** **`"accept_cash_check": true,`** **`"annual_turnover": 120000,`** **`"source_of_funds": "IT services",`** **`"source_fund_uae": true,`** **`"due_diligence_declaration": {`** **`"bankruptcy_declaration": false,`** **`"disciplinary_declaration": false,`** **`"fraud_aml_declaration": false,`** **`"disqualification_declaration": false,`** **`"conviction_accusition_declaration": false,`** **`"breach_of_law_declaration": false`** **`},`** **`"default_user": false`** **`}`**
### Parameters for each user type Description of the "[Create user](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Users/operation/createUser)" API in API catalog includes all parameters which are used in that API. For your convenience, below you can find a **set of API parameters** (both in pdf and excel formats), which are necessary for **each user type** creation: {% file src="/files/HOaJESk6iO72ZmbsI7Jw" %} PDF {% endfile %} {% file src="/files/G9h7AAeRMkXRo4Hf13NV" %} Excel {% endfile %} # User ID verification by SDK Fraud is always spearheading. Luckily, so is our technology. Using the best combination of human and machine learning fraud spotting, we protect your business against the 6 key types of document fraud: * Forged documents * Counterfeit documents * Blank stolen documents * Fantasy or camouflage documents * Impostor or ‘look-a-like’ documents * Compromised documents Conventionally, you have to rely on signals to trust a new user - on a device IP, a phone number, or credit database look-up. But these signals can also be exploited by imposters. This creates constant uncertainty, so you can’t focus on the user's experience, and instead start treating them with doubt. nCore platform integrated with the document verification service provider called Onfido which lets your users scan a photo ID from their mobile device, before checking if it's genuine. {% hint style="info" %} Please note that the Identity verification is applicable only for a user type INDIVIDUAL. In addition to that, user identity verification is only applicable for the customers who are using the SDK to upload documents. {% endhint %} ### High level identity verification steps The high level identification verification steps are given below: 1. Enable tenant level settings 2. Create webhook i.e. IDENTITY\_VERIFICATION 3. Create a user 4. Receive webhook having applicant ID and SDK token 5. Initialize SDK and Upload documents via Mobile SDK 6. Inform document uploaded successfully after a successful upload 7. Identification verification processing started by nCore platform 8. Identification verification processing finished successfully, the user is transitioned from PENDINGIDVERIFICATION to PENDINGKYC 9. nCore platform Inform by a webhook notification that the process is completed successfully ### Step by Step process Step by step process is given below to configure and perform a successful identification verification process. #### Tenant level settings Following are the settings that are required to be enabled at tenant level for Identity Verification. | Field Name | Field Type | Description | | -------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | require\_document\_verification |

boolean


| This check enables the identity verification process. | | checks | enum |

Following are the checks you can request to enable at tenant level as per your business need

| | privacy\_notices\_read\_consent\_given | boolean | This parameter indicates that the privacy notices and terms of service have been read and, where specific laws require, that consent has been given for Onfido. This parameter should be set to true after gaining the necessary consent, and if it's set to false the request will fail with a validation error. | #### Create a webhook Now create a webhook event as “IDENTITY\_VERIFICATION” for receiving a webhook event for applicant id and SDK token generation as shown below:
POST /webhooks **`{`**\ **`"endpoint": "https://example.com/",`**\ **`"events": [`**\ **`"IDENTITY_VERIFICATION"`**\ **`],`**\ **`"config": {`**\ **`"basic_auth_username": "username",`**\ **`"basic_auth_password": "password",`**\ **`"custom_headers": [`**\ **`{`**\ **`"header_name": "apikey",`**\ **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ **`}`**\ **`],`**\ **`"created": "2012-05-04T19:42:32.987Z",`**\ **`"modified": "2012-05-04T19:42:32.987Z"`**\ **`}`**\ **`}`**
#### Create a user After enabling webhook endpoint, you can create a user by sending a POST request to /users endpoint. Since the parameter require\_document\_verification is enabled as **true** at tenant level which means that the user will be created with a user status as PENDINGIDVERIFICATION.
POST /users **`{`**\ **`"first_name": "John",`**\ **`"middle_name": "Anthony",`**\ **`"last_name": "Smith",`**\ **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`**\ **`"user_type": "INDIVIDUAL",`**\ **`}`**
{% hint style="warning" %} The above sample is given just for reference, please refer to the API Catalog for a complete payload. Below you can find important restrictions: 1. 'first\_name' and 'last\_name' parameters are required in the user profile. 2. If address is provided in the user profile, then 'postal\_code' and 'country' become required. You can use a postal code of "00000" for countries that do not support postal codes. 3. The 'postal\_code' of the applicant's address. For UK postal codes, specify the value in the following format: SW4 6EH. 4. USA as a country is not supported ('address' > 'country'). 5. For addresses, the following characters are forbidden: !$%^\*=<>. 6. For names, the following characters are forbidden: ^!#$%\*=<>;{}". {% endhint %} #### Receive a notification Once the user is created successfully, you will receive a webhook notification along with the following details as given below:
Webhook notification sample **`{`**\ **`"event": "IDENTITY_VERIFICATION",`**\ **`"user_id": "055ef899-9650-4700-9497-e71826dd2825",`**\ **`"applicant_id": "generated applicant id",`** \ **`"sdk_token": "generated token",`** \ **`"note": "",`**\ **`"status": "PENDINGIDVERIFICATION",`**\ **`"old_status_reason_code": "",`**\ **`"status_reason_code": "I0",`**\ **`"status_description": "",`**\ **`"created": "2018-01-02T19:42:32.987Z",`**\ **`"modified": "2018-01-02T19:42:32.987Z"`**\ **`}`**
{% hint style="info" %} The system will send a webhook notification event "IDENTITY\_VERIFICATION" along with a status\_reason\_code as "B1" if the user is not verified. {% endhint %} {% hint style="warning" %} Please note that the SDK token expires in 90 mins. {% endhint %} To renew the SDK token, send a PUT request to /user/{id}:changeStatus endpoint with a value as “B2” in 'status\_reason\_code' field and ”PENDINGIDVERIFICATION” in 'status' field as shown below:
PUT /user/{id}:changeStatus **`{`**\ **`"status": "PENDINGIDVERIFICATION",`**\ **`"status_reason_code": "B2",`**\ **`}`**
Be aware that the 'status\_reason\_code' B2 has been added just for testing purposes, the system should not update the 'status\_reason\_code' from I0 to B2. #### Upload the documents for verification Now your mobile app user can start uploading the documents. {% hint style="warning" %} Prerequisite for this step: The integration between the mobile app user and your backend system. {% endhint %} #### Trigger user status change for a successful document upload Once the documents are uploaded successfully, you can send a PUT request to /user/{id}:changeStatus endpoint with a value as “**B0**” in status\_reason\_code field and ”**PENDINGIDVERIFICATION**” in status field as shown below:
PUT /user/{id}:changeStatus **`{`**\ **`"status": "PENDINGIDVERIFICATION",`**\ **`"status_reason_code": "B0",`**\ **`"note": "Users documents are uploaded successfully"`**\ **`}`**
#### IDV re-initiation flow Below you can find IDV re-initiation flow: * At first you send PUT request to /user/{id}:changeStatus endpoint to re-initiate IDV process by changing user status from PENDINGIDVERIFICATION B1, B5 or B6 to PENDINGIDVERIFICATION B2. * Documents are re-uploaded; then you send PUT request to /user/{id}:changeStatus endpoint to change user status from PENDINGIDVERIFICATION B2 to PENDINGIDVERIFICATION B0. * System will decline IDV re-initiation in case Onfido replies back with "SUSPECTED" or "REJECTED" status. In this case, user status will be updated to "TERMINATED". #### Document verification internal process nCore platform starts identity verification internally. #### Receive a successful identity verification notification Identification verification processing completed successfully, the user is transitioned from PENDINGIDVERIFICATION to PENDINGKYC and you will receive a user status change notification (if configured) as given below.
User status change notification **`{`**\ **`"event":"USER_STATUS_CHANGE",`**\ **`"User_status_change":{`**\ **`"id": "cf2de83b-ac68-441b-bc54-21de60014d57",`**\ **`"title": "MR",`**\ **`"first_name": "John",`**\ **`"middle_name": "Anthony",`**\ **`"last_name": "Smith",`**\ **`"native_name": "John Smith",`**\ **`"date_of_birth": "2021-10-25T12:47:04.361Z",`**\ **`"email": "bob@example.com",`**\ **`"mobile": "+551185249635",`**\ **`"address": {`**\ **`"address_line1": "Flat 1904",`**\ **`"address_line2": "Glass Tower",`**\ **`"city": "New York City",`**\ **`"state": "New York",`**\ **`"postal_code": "12345",`**\ **`"country": "USA"`**\ **`},`**\ **`"gender": "MALE",`**\ **`"preferred_language": "EN",`**\ **`"place_of_birth": "Las Vegas",`**\ **`"nationality": "USA",`**\ **`"parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`**\ **`"created": "2021-10-25T12:47:04.361Z",`**\ **`"modified": "2021-10-25T12:47:04.361Z",`**\ **`"country_residence": "USA",`**\ **`"country_tax_residence": "USA",`**\ **`"employment_type": "SALARIED",`**\ **`"employment_title": "string",`**\ **`"monthly_salary": 0,`**\ **`"company_name": "string",`**\ **`"company_address": {`**\ **`"address_line1": "Flat 1904",`** \ **`"address_line2": "Glass Tower",`**\ **`"city": "New York City",`**\ **`"state": "New York",`**\ **`"postal_code": "12345",`**\ **`"country": "USA"`**\ **`},`**\ **`"company_country": "USA",`**\ **`"industry_type": "I01",`**\ **`"expected_monthly_balance": 0,`**\ **`"relationship_with_parent": "SON",`**\ **`"user_type": "INDIVIDUAL",`**\ **`"business_legal_name": "string",`**\ **`"business_dba_name": "string",`**\ **`"date_established": "2021-10-25T12:47:04.362Z",`**\ **`"phone_number": "+551185249635",`**\ **`"website": "string",`**\ **`"status": "PENDINGKYC",`**\ **`"status_reason_code": "I0",`**\ **`"kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY"`**\ **`}`**\ **`}`**
Also you can check the status by sending a **GET** request to **/user/{id}** endpoint: > [**GET /users/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getUser)
Response **`{`**\ **`"id": "cf2de83b-ac68-441b-bc54-21de60014d57",`**\ **`"title": "MR",`**\ **`"first_name": "John",`**\ **`"middle_name": "Anthony",`**\ **`"last_name": "Smith",`**\ **`"user_type": "INDIVIDUAL",`**\ **`"status": "PENDINGKYC",`**\ **`"status_reason_code": "I0",`**\ **`"kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY"`**\ **`}`**
{% hint style="info" %} The above sample is given just for reference, please refer to the API Catalog for a complete payload. {% endhint %} ### IDV Re-verification upon document expiration **Background: INDIVIDUAL** users who are already verified but their documents have either expired or about to expire. To cater to that, we will introduce a mechanism for IDV re-verification. **New settings** (configured on NymCard side): {% code overflow="wrap" %} ``` "expired_idv_policy": { "days_prior_expiration": 30, (attached is a file to explain the expiration date calculation) "applicable_user_status": [ "ACTIVE"] (applicable to ACTIVE users for now) } ``` {% endcode %} **Cron Job** a. read tenant level settings related to expired\_idv\_policy b. pick INDIVIDUAL users and check for the expiry date of their documents c. update user status\_reason\_code to A6 if their documents have expired or about to expire d. Fintechs will receive webhook with status A6, then they need to start below mentioned process: * Change the (ACTIVE) user 'status\_reason\_code' to B2E (works exactly the same as B2) to generate a new IDV token and ask the end-user to upload his documents again * Update the (ACTIVE) user 'status\_reason\_code' to B0E (works exactly the same as B0) once the documents are uploaded to initiate the IDV process If the report is **CLEAR**, user status is updated to (ACTIVE), A7 (new status reason code). Otherwise; user takes on (ACTIVE), A8 'status\_reason\_code' for the **CONSIDER > CAUTION** scenario, T12E 'status\_reason\_code' for the **CONSIDER > TERMINATED** user status scenario & T13E 'status\_reason\_code' for the **CONSIDER > SUSPECTED** user status scenario (where A8, T12E (works same way as T12) & T13E (works same way as T13) are new status reason codes). Respectively, we added new values for user `status_reason_code`: * A6 : Document expired or about to expire * A7 - ID renewed * A8 : ID re-verification failed after document expiration * B2E: Generate SDK token, document expired (same as B2) * B0E: Documents re-uploaded after document expiration for identity verification (same as B0) * T12E: System terminated due to ID verification rejected after document expiration for identity verification (same as T12) * T13E: System terminated due to ID verification suspected after document expiration for identity verification (same as T13) {% hint style="info" %} To re-initiate IDV flow by generating a new SDK token: change `status_reason_code` from A8 to B2E. {% endhint %} Below you can find a document with IDV expiration days calculation samples. {% file src="/files/nGOPO6g0OjBTiAqyqF5F" %} Besides, we have added ability for system to verify issuing country of identity document so that IDV is not passed for users other than allowed country. For this we introduced several new status reason codes:
B9Document issuing country mismatch
B10Identity verification consider with caution status and document issuing country mismatch
B9EDocument issuing country mismatch upon IDV re-verification after document expiration
B10EIdentity verification consider with caution status and document issuing country mismatch upon IDV re-verification after document expiration
# User KYC process ### **About KYC verification** Know Your Customer (KYC) is the mandatory process of identifying and verifying the customer's identity before allowing them to have an account and perform transactions. KYC standards are designed to protect financial institutions against fraud, corruption etc. KYC process helps to establish customer identity and understand the nature of customers’ activities by performing KYC risk intelligence screening in order to qualify that the source of funds is legitimate. #### **KYC policies for individual user** nCore platform offers KYC process on two types of individual users given below:
S No.User TypePolicy namePrerequisite
1Parent userUAE_INDIVIDUAL_PRIMARYKYC processing must be enabled at tenant level
2Child userUAE_INDIVIDUAL_SECONDARY

KYC processing must be enabled at tenant level and

Parent user must be KYC verified

Please contact the NymCard representative at to enable KYC processing. #### **Restrictions on user status** Following are the KYC restrictions based on user status. When the user status is “**PENDINGKYC**”, “**SUSPENDED**” or “**TERMINATED**”, then operations like creating an account, creating a card and linking a card are not allowed. These operations are enabled for the user only when the user status is marked as “**ACTIVE**”. In addition to that, when the user status is “**PENDINGKYC**”, then the user can create a child user. Note, that if KYC settings=true at the tenant level, the following parameters can not be updated for user with **ACTIVE** status: ![](/files/sXMkn5gKnVbsqDr0Gt1R) #### **How to simulate user KYC process** nCore sandbox environment provides a feature to simulate the KYC processing of user(s) and update appropriate user statuses based on the KYC result. Once you create a request to perform a user KYC successfully by sending a **POST** request to **/users/{id}/kyc** endpoint, the platform starts a service which runs internally and performs the checks based on the policy you linked in the request. You can create more than one request. The internal service will pick all submitted KYC requests, process them and update the user and KYC statuses and give you a glance of the frictionless KYC processing which nCore platform provides in sandbox as well as in production environments. After a successful KYC processing you can create resources for the KYC verified users in a sandbox environment. #### **KYC Use cases** In the following ways you can simulate different KYC processing use cases. Before creating a user, please make sure that the KYC service picks only those KYC requests when * The ‘require\_kyc’ parameter is set as “true” at tenant level **and** * The user status is set as “PENDINGKYC” **and** * The KYC status is “SUBMITTED” *Positive use case:* To simulate a positive KYC processing case, please create a user with ‘last\_name’ as “pass” as given below.
POST /users **`{`** **`"first_name": "John",`**\ ` `**`"last_name": "pass"`** **`}`**
Now create a ‘perform KYC’ request as given below.
POST /users/{id}/kyc **`{`** **`"kyc_policy": "UAE_INDIVIDUAL_PRIMARY"`** **`}`**
{% hint style="success" %} Note: the KYC service will process the request and return a response as “OK”. {% endhint %} *Negative use case:* To simulate a negative KYC processing case, please create a user with a **last\_name** as “**fail**” as given below.
POST /users **`{`** **`"first_name": "John",`**\ ` `**`"last_name": "fail"`** **`}`**
Now create a ‘perform KYC’ request as given below.
POST /users/{id}/kyc **`{`** **`"kyc_policy": "UAE_INDIVIDUAL_PRIMARY"`** **`}`**
{% hint style="danger" %} Note: the KYC service will process the request and return a response as “FAILED”. {% endhint %} #### #### **KYC webhooks** Once the API user submits the KYC request a webhook ‘KYC\_RESULT’ is triggered and the notification is sent to the configured endpoint to notify the client. You can create a corresponding webhook as shown in the below example.
POST /webhooks **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"KYC_RESULT"`**\ ` `**`],`**\ ` `**`"config": {`**\ ` `**`"basic_auth_username": "username",`**\ ` `**`"basic_auth_password": "password",`**\ ` `**`"custom_headers": [`**\ ` `**`{`**\ ` `**`"header_name": "apikey",`**\ ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"created": "2021-05-27T18:48:00.074Z",`**\ ` `**`"modified": "2021-05-27T18:48:00.074Z"`**\ ` `**`}`**\ **`}`**
Also when the user's status is changing internally based on the KYC processing, the webhook status is kept notifying the client. You can create a corresponding webhook as shown in the below example.
POST /webhooks **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"USER_STATUS_CHANGE"`**\ ` `**`],`**\ ` `**`"config": {`**\ ` `**`"basic_auth_username": "username",`**\ ` `**`"basic_auth_password": "password",`**\ ` `**`"custom_headers": [`**\ ` `**`{`**\ ` `**`"header_name": "apikey",`**\ ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"created": "2021-05-27T18:48:00.074Z",`**\ ` `**`"modified": "2021-05-27T18:48:00.074Z"`**\ ` `**`}`**\ **`}`**
For further details, please refer to the [Webhooks](/get-started/webhooks) section. ### **KYC management** You can perform and manage KYC verification by using our APIs. Following are the APIs available at nCore platform for KYC management. * Perform KYC * Get KYC by ID * Search for KYC requests #### **Perform KYC of user** You can perform KYC on a user by sending a POST request to /users/{id}/kyc endpoint; where id is the user’s id to whom the KYC is requested. An example is given below.
POST /users/{id}/kyc **`{`**\ ` `**`"kyc_policy": "UAE_INDIVIDUAL_PRIMARY"`**\ **`}`**
#### **Get KYC by ID** You can retrieve a specific KYC by sending a GET request to /users/kyc/{id} endpoint, where id is the KYC request ID. > [**GET /users/kyc/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/User-KYC/paths/~1v1~1users~1kyc~1%7Bid%7D/get) #### **Search for KYC requests** You can search for KYC requests by sending a POST request to /users/kyc:search endpoint along with the filter as shown below.
POST /users/kyc:search **`{`**\ ` `**`"query": "Transfer",`**\ ` `**`"sort_by": "By name",`**\ ` `**`"order_by": "asc",`**\ ` `**`"matcher": [`**\ ` `**`"and"`**\ ` `**`],`**\ ` `**`"filters": [`**\ ` `**`{`**\ ` `**`"field": "ID",`**\ ` `**`"operator": "any_of",`**\ ` `**`"values": [`**\ ` `**`"21"`**\ ` `**`]`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"cursors": {`**\ ` `**`"after": "John Smith",`**\ ` `**`"has_more": true`**\ ` `**`},`**\ ` `**`"limit": 0`**\ **`}`**
# Issuance # Users ### What is a user A user is an entity which can be an individual that holds an account at nCore which is represented by the user object. The user object stores the user's demographic data like (name, date of birth, email, address, nationality, gender etc.). Your application calls the nCore API to create and manage the users and their identification. nCore supports linking multiple users in a parent-child relationship. You can use the **/users** endpoint to create these relationships between two users (where one user is the parent and the other is the child). The parent-child relationship can be extended to n-level of parent-child hierarchy. This relationship is very useful in maintaining real world relationships between multiple users. To create a parent-child relationship, the parent must be an existing user. When creating a child user, set the **parent\_user\_id** field to the unique identifier of the parent. \ The **parent\_user\_id** can also be set or reset later on by using the update user API. Below you can find user management decision flow: ![](/files/YeCIvx8CHKdf8ivxbfwu) ### Create a user Before creating user, what you will need: * A nCore API Key * Details about the individual you would like to onboard #### **Create an individual user** The following is sample code used to create a normal user.
POST /users **`{`** **`"first_name": "John",`**\ ` `**`"last_name": "Smith"`** **`}`**
#### **Create a child user** If you want to create a child user please include the parent user id in your **POST** request as given below.
POST /users **`{`** **`"first_name": "John",`**\ ` `**`"last_name": "Smith",`**\ ` `**`“parent_user_id”: “cf2de83b-ac68-44ab-bc54-21de60014d57”`** **`}`**
### Retrieve users nCore supports following retrieval methods. * To retrieve a list of all users, you can send a **GET** request to **/users** endpoint > [**GET /users** ](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/listUsers) * To retrieve a specific user, you can include the user **‘ID’** path parameter in your **GET** request > [**GET /users/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getUser) * To retrieve a specific user by name, email id or phone number as given below.
POST /users:search **`{`** **`"name": "John",`**\ ` `**`"mobile": "5503523",`**\ ` `**`"email": "johndoe@",`**\ ` `**`"limit": "10",`**\ ` `**`"after": "MTA="`** **`}`**
* You can retrieve child users for a specific parent user as given below. > [**GET /users/{id}:getLinkedRelationships**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Users/operation/getLinkedRelationships) ### Update a user You can update a specific user by sending a **PUT** request to **/users/{id}** endpoint as given below. > [ **PUT /users/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Users/operation/updateUser) # Cards A virtual card or a physical card can be issued to a registered user. The card will be created for a card product already defined in the system. The card will inherit all features and characteristics which are configured on the card product. The nCore offers a set of APIs for card product management, card issuance, and card lifecycle management. The nCore platform processes authorization transactions performed with the issued cards. {% hint style="info" %} Note: A card can only belong to a single card product. {% endhint %} #### **Card lifecycle** Card lifecycle is the transitioning of a card through different card statuses beginning from card's issuance to its termination.\ \ **Card statuses** Following table lists the possible card statuses. | **Status** | **Description** | | ---------- | ----------------------------------------------------------------------------------------------------------------- | | Inactive | A newly created card has its status set as inactive | | Active | The card can only be used for authorizations when its status is active | | Suspended | A card can be temporarily suspended and can be resumed to active status | | Terminated | A card can be terminated for various reasons, once terminated it cannot be transitioned back to any other status | **Card issuance and replacement** It is possible to set the initial status of a newly created card at card product level. Initial status can be configured separately at card product level for physical cards and virtual cards. This allows the physical card to have the initial status as ‘Inactive’, whereas the virtual card can have the initial status as ‘Active’ on issuance. An existing card can be replaced on termination. A replaced card has a different card number but has the same characteristics as the terminated card. For example, if a card expires then it can be replaced with the card having a new PAN and expiration date. Card replacement can be done more than once. The replaced card will have reference to the terminated card. For example, let's suppose you create a card **C1,** you can replace **C1** with **C2**, **C2** will have a reference to **C1** and so on. **Card expiration** nCore platform assigns an expiration date when a new card is created. This card remains valid until it reaches its expiration date.The nCore platform allows you to set the expiration date when creating a card. # Issuing Physical Cards This section includes information about individual and bulk card issuance, card PIN management, card replacement and fulfillment. Below you can find a physical card issuance decision flow: ![](/files/d66U0F6op5u3LWK7vM7X) # Individual card issuance Physical cards are the standard payment cards we carry with us in our wallets and bags. A physical card exists in a physical form. You can make cash withdrawal, online and in-app purchases with this card. By default, all our cards display the cardholder’s details like card number, an expiration date, and a CVV which is a three-digit number printed on the back of the card that is used in online purchases. Unlike virtual cards that can be used right after the issuance, the physical cards are delivered to the cardholder by mail or courier and require card activation by the cardholder before they can be used. nCore allows you to issue physical cards individually or in bulk. The nCore platform offers a range of optimization options for card design and personalization. nCore platform offers personalized as well as non-personalized cards. Non personalized cards are issued in bulk whereas personalized cards are issued individually. Issuing physical cards requires you to specify how nCore should manage the order for card shipment and personalization. \ Physical cards can be used after card activation. An additional security feature that the physical cards have and that is not there with their virtual counterparts are the card PINs. For further details, please refer to section [**Card PIN management**](/get-started/issuing-physical-cards/card-pin-management). A personalized physical card (i.e. a card with the user name on it) can be issued for a registered user. The card is created for a card product already defined in the system. The card inherits features and rules available on the card product. One card belongs to only one card product. You can issue a physical card and use it in the following steps. * Create a user * Create a card * Activate the card and set the card PIN * Fund the account * Use the card ### Create a user A user is an entity which can be an individual that holds an account at nCore which is represented by the user object. Please refer to the section [**Users**](/get-started/issuance/users) for more information. ### Create a card At nCore platform, payment cards are identified as an object of the cards resource, you can create a card by sending a **POST** request to **/cards** endpoint. The card object stores data about the card for example, name on card, card number, expiry date, CVV2, card product id etc. It also stores shipping information like shipping address, return address, delivery methods etc. Note: Create a user and a card product before creating a card. It is mandatory to provide the identifier of the user who owns the card, the type of card (physical in this case), and the identifier of the card product in **POST /cards** request as shown below.
POST /cards **`{`** **`"user_id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ ` `**`"card_type": "PHYSICAL",`**\ ` `**`"card_product_id": "b4eabfc-f839-4e51"`** **`}`**
#### Retrieve a card To retrieve a specific card, you can include the card ‘ID’ path parameter in your **GET** request and send it to **/card/{id}** endpoint. > [**GET /cards/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getCard) ### Activate a card and set the card PIN Physical card requires it to be activated before using it to perform any transaction. nCore platform provides the change card status API that can be used for card activation by changing the card status from inactive status to active. nCore platform also provides the set PIN API to set the card’s PIN. Only a PCI compliant client should use the set PIN API. nCore provides customizable PCI widgets for card activation and set PIN that enables non-PCI compliant customers to perform these card activities securely without handling the sensitive card data (card number, expiry, CVV, PIN). **For PCI compliant customers:** * **To activate the card**, send **PUT /cards/{id}:statuschange** request to change the card status as given below.
PUT /cards/{id}:statuschange **`{`** **`"status": "ACTIVE",`**\ ` `**`"status_reason_code": "a0",`** **`}`**
* **After activating the card**, send **PUT /cards/{id}:changepin** request to set card PIN as given below.
PUT /cards/{id}:changepin **`{`** **`"enc_pin": “ncrypt:1:4p1aPxnRvuoJOoymTSA4XH1rRaaj0HvAEISFCyQouPc:2TM-I0I”`** **`}`**
**For non-PCI compliant customers:** \ To activate the card and set the card PIN, please integrate nCore’s PCI widgets in your cardholder facing applications to enable your cardholders to securely activate their card and set the card PIN please check the [**PCI Widget**](/get-started/security/pci-widget) section for further details. {% hint style="info" %} Note, that if a user attempts to provision a card with an invalid CVV2/expiry more than the allowed retries limit (of 5), the card will be blocked for 24 hours. {% endhint %} ### Fund the account Whenever a new card is issued a General Ledger (GL) account will be automatically created and linked to the card. The card account is a term which is usually used to refer to this account. The account holds the funds of the card. To access account and retrieve details, please follow these steps. * Send a **GET** request to **/cards/{id}/accounts** endpoint to fetch the accounts linked to the card. Send this request with the Card ID parameter field. * Once you have the card accounts, you can then send a **GET** request to **/accounts/{id}** endpoint with the account ID to retrieve the account details like account currency, balance etc. > [**GET /cards/{id}/accounts**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardAccounts) > [**GET /accounts/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getAccount) To fund the card account, please refer to the [**Funding**](/get-started/funding-and-transfers/internal-funding-source) section. ### Use the card The personalized card can be delivered to the cardholder selected shipment address or it can be delivered to a centralized location (e.g. a branch or a retail outlet) from where the cardholder can collect the card and start using it after card activation. # Bulk card issuance You can place a request for issuing a bulk of non-personalized physical cards. For this you need to provide the card product, the number of cards to be created in the bulk request and the shipping address to deliver the bulk cards. \ The bulk can be delivered to a centralized location (e.g. a branch or a retail outlet). Amount can optionally be provided when creating the bulk card request which will serve as the preloaded amount for the non-personalized cards. \ A walk-in customer can be enrolled as a user and a non-personalized card taken from the bulk can be assigned to the newly registered user. ### Create bulk card request You can order non-personalized physical cards in bulk by sending **POST** request to **/bulkissuances** endpoint as given below.
POST /bulkissuances **`{`**\ ` `**`"card_product_id": "f4947edd-0dc1-4d60-af5a-f0dcb01d141c",`**\ ` `**`"number_of_cards": 50,`**\ ` `**`"amount": 100,`**\ ` `**`"currency": "USD",`**\ ` `**`"name_on_card": "Gift Card",`**\ ` `**`"dry_run": false`** **`}`**
{% hint style="info" %} Please note that the create bulk card request API supports maximum 5000 cards creation per call. It is advisable to create ≤ 5000 cards in one call. {% endhint %} ### Retrieve bulk card requests nCore offers two bulk card request retrieval options. * **Retrieve existing bulk card requests** You can retrieve all existing bulk card requests by sending a **GET** request to **/bulkissuances** endpoint shown below. > [**GET /bulkissuances**](https://nymcard.com/docs/api#tag/Card-Bulk-Issuances/operation/listBulkIssuances) * **Retrieve a specific bulk card request** You can retrieve a specific bulk card request by sending a **GET** request to **/bulkissuances/{id}** endpoint, where id is the bulk id. > [**GET /bulkissuances/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Bulk-Issuances/operation/getBulkIssuance) ### Update a bulk issuance request You can update an existing bulk issuance request by sending a **PUT** request to **/bulkissuances/{id}** endpoint as shown below. In the below sample let's suppose you want to update the status of an existing request from “draft” to “submitted”.
PUT /bulkissuances/{id} **`{`** **`"currency": "USD",`**\ ` `**`"status": "SUBMITTED"`** **`}`**
### Link a bulk card to a user A non-personalized card created using bulk issuance needs to be linked to a user before it can be used to perform transactions. nCore supports secure card linking and activation to link a bulk card with a user. You can link a bulk card to an existing user or a newly created user. Please refer to section **Users** for further info on how to create and manage users. To link a bulk card to a user, send a **POST** request to **/cards:link** endpoint as shown below. The API endpoint requires an activation\_token which can be created by performing a SHA-512 hash on the card information.
POST /cards:link **`{`** **`“activation_token”: “4E8AACE317CBF21390FA7F9DB3F772E724DB1A50609F5592F3007E3AD54A463F9BD0B45A8EC1BC204C32655E8AE`**\ **`1B3964B67C2DAADFA0DA95B49C1CE83F86946”,`**\ ` `**`“user_id”: “8009ace0-c16e-4d03-8a89-36010cf30b87”`** **`}`**
{% hint style="info" %} You can re-link bulk-issued cards and pre-linked accounts from a business user to an individual user by using this [API](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Users/operation/relinkCardAccount). It allows individual users to gain ownership of their cards and perform transactions independently. {% endhint %} **Steps to calculate activation token** 1\. To calculate an activation token for a particular card, you need card information as given below. * Card PAN (Primary Account Number) * Card Expiry Date (YYMM) * CVV2 Example: * Card PAN: 4122432442321234 * Card Expiry Date: 2112 * CVV2: 453 Concatenate the card information in the following sequence: String format: \\\ String result: 41224324423212342112453 2\. Apply SHA-512 hash algorithm to the above string. SHA-512 is a hashing algorithm that performs a hashing function on the data given to it. Hashing algorithms are used in many things such as internet security, digital certificates, and etc. Result in hash format: 4E8AACE317CBF21390FA7F9DB3F772E724DB1A50609F5592F3007E3AD54A463F9BD0B45A8EC1BC204C32655E8AE\ 1B3964B67C2DAADFA0DA95B49C1CE83F86946 {% hint style="warning" %} Please ensure that the SHA-512 hash result passed to the API in activation\_token has the hexadecimal letters (A-F) in uppercase. {% endhint %} # Card fulfillment Card fulfillment mechanism helps you to track your newly created physical cards request. Fulfillment mechanism is managed for two possible cases: * Individual card fulfillment * Bulk cards fulfillment #### Individual card fulfillment This card fulfillment is appropriate for a single cardholder. Cardholders receive their personalized cards by mail at the addresses provided in the create card request. #### Bulk cards fulfillment This card fulfillment enables you to create N number of non-personalized cards in bulk form. \ The bulk of cards is delivered to the shipping address provided in the create bulk card issuance request. \ Bulk cards fulfillment is a good option when you want to have more control over individual card details e.g., assigning specific user tokens. #### Card fulfillment status When a card is fulfilled, the fulfillment\_status field of the card object and the bulk issuance object is updated. For physical cards, fulfillment providers (perso vendors) offer different shipping options. If the fulfillment provider supports live tracking and status updates then the fulfillment\_status will be updated and will reflect the live status of card fulfillment journey. | **Fullfullment status** | **Description** | | ----------------------- | ---------------------------------------------------------------------------------- | | Created | On card creation, the fulfillment status is set as created | | Ordered | When embossing request for the card is generated, the status is updated as ordered | # Card PIN management ### Introduction Physical cards have an additional security feature i.e. PINs (Personal Identification Number). It is a number used to verify the identity of the cardholder and make transactions more secure. The PIN is required to validate the cardholder when the physical card is used on the terminals (like POS or ATM). Initially a random PIN is set for a newly activated card. The initial random PIN can be securely retrieved and presented to the cardholder through a cardholder facing app. The nCore platform also provides the feature to change the card PIN if the cardholder wishes to set his own preferred PIN. A PIN is treated as a password and it should be kept secret to prevent unauthorized access to cardholder's accounts and related information. #### Types of PINs There are two types of card PINs and both have different validation processes as given below. * An online PIN is entered by the cardholder, then it is transmitted along with the card details to the nCore platform via the merchant acquirer system for authentication. \ The online PIN is not stored on the card. The nCore platform receives the authentication request in real time from the card network, the platform validates the PIN, then confirms to the merchant terminal where the card is inserted. * An offline PIN is entered by the cardholder, then transferred in encrypted form to the card’s integrated chip where the PIN is stored. \ The chip uses its internal procedures to validate and confirm the PIN to the merchant terminal where the card is inserted without transmitting it in real time to the issuer. {% hint style="info" %} Please note that the Card PIN management features (such as get card PIN and change card PIN) are available for PCI DSS compliant customers. nCore platform provides a set of PCI widgets for non-PCI DSS compliant customers. For further information please refer to the [**PCI Widget**](/get-started/security/pci-widget) section. {% endhint %} **Card PIN Management APIs** There are some pre-requisites, which you have to know before dealing with card PIN management. It is preferred to have knowledge of such cryptographic algorithms as 3DES, AES and RSA . Also you should have an understanding of such concepts as encryption/decryption, Base64 encoding, symmetric/asymmetric keys, PIN block formats. nCore platform provides the following card PIN management features though APIs: * Set card PIN * Get card PIN ### **Change card PIN** A cardholder can change his/her card PIN as required. Send a **PUT** request to **/cards/{id}:changePin** endpoint as given below to change the card PIN.
PUT /cards/{id}:changePin **`{`**\ ` `**`"enc_pin": "ncrypt:2:bP6dZTzopk6TTYeP4lETrw:`**\ **`kjQRz3M9wzOFPU3cphAomtHoMv3aC2-CkMtAgiLvYfpy1cEwTm3ag7_caXHFThWN_SBxHpj9aviki9rr7okJKN-Bqd`**\ **`O46d7Uu4Bx9dNo0_Tn9ZcKV7X-dAGLgNViYeAaGbA2jlcESYZZLecqPBq`**\ **`BADQ12DdGV4VfRtEb3pDZRO3VRP1hXL4VgN_H1vRwIwT5vTyBLuzQA`**\ **`3Lh3xqrlVrrRFHah42oH3YkgaY6M8mc3r3e3pBItNMiwW10wjfO50z7dy`**\ **`2O0yAGyy-QSWqu4LQYMLKMAPx4wsuEcAQg3Xpmnv3GmP_goAvu88`**\ **`ASH9u4iKWGh0OtrldQZlmUqiYcq9mWMQ:`**\ **`Ok9OebFuRwQ"`**\ **`}`**
{% hint style="info" %} Please note: * Remove **"enters"** from the sample message given above when testing on sandbox. * An encrypted PIN is required to get a successful response. {% endhint %} ### **Card PIN enciphering method** Below you can see the encryption flow: ![](/files/s9q60Im1Hw6pg1CMkwux) Please refer to the following steps to encrypt the digital envelope: 1\. Generate a 16-byte random **\** and encode it into **Base64 URL encoding (RFC 4648)** to get **\** 2\. Create a PIN Block **\** in ISO 9564-1 format 1 as given below format: ISO 9564-1 format 1 = \\\\ Below you can find an example of code snippet: ``` // function createPINBlock(plaintext){ var pinLength = plaintext.length; var pinBlock = '1' + pinLength + plaintext + forge.util.bytesToHex(forge.random.getBytesSync(8)); pinBlock = pinBlock.substring(0, 16); console.log(pinBlock); } ``` 3\. Generate a random 3DES key **<3DESkey>** of 16 bytes. Below you can find an example of code snippet: ``` // function generateDESKey(){ var key = forge.random.getBytesSync(16); var secretKey = forge.util.createBuffer(key, 'raw'); console.log(secretKey.toHex().toUpperCase()); } ``` 4.1. Encrypt the **\** with **<3DESkey>**, you will get **\** 4.2. Transform the **\** into Hex bytes to get the data in Hex **\** 4.3. Now encode the **\** into Base64 URL encoding (RFC 4648), you will get **\** Below you can find an example of code snippet: ``` // function encrypt3DES(key, pinBlock) { var secretKey = forge.util.createBuffer(forge.util.hexToBytes(key), 'raw'); secretKey.putBytes(forge.util.hexToBytes(secretKey.toHex().substring(0, 16), 'raw')); var cipher = forge.cipher.createCipher('3DES-ECB', secretKey); var data = forge.util.createBuffer(forge.util.hexToBytes(pinBlock)); cipher.start({iv: ''}); cipher.update(data); cipher.finish(); var encryptedPIN = forge.util.bytesToHex(cipher.output); encryptedPIN = encryptedPIN.substring(0, 16); console.log(encryptedPIN); } ``` 5\. Encrypt the **<3DESkey>** with NymCard's shared key **\** in OAEPWithSHA512 to get **\** 6\. Encode**\** into **Base64 URL encoding** **(RFC 4648)** to get **\** Below you can find an example of code snippet: ``` // function encryptRSA(desKey, pubKey) { var publicKey = forge.pki.publicKeyFromPem(pubKey); var encryptedData = forge.util.encryptRSA2(forge.util.hexToBytes(desKey), publicKey); var encoded = forge.util.base64urlencode(forge.util.encode64(encryptedData)); console.log(encoded); } ``` 7\. Create a digital envelope with the separator **“:”** in the format **\:2:\:\:\** and send the created digital envelope in Change Card PIN request. Below you can find an example of code snippet: ``` // function createEnvelope(encodedEncryptedSecretKey, pinBlock) { var encodedIV = forge.util.base64urlencode( forge.util.encode64(forge.random.getBytesSync(8)) ); var encBuffer = forge.util.createBuffer(); encBuffer.putBytes(forge.util.hexToBytes(pinBlock.substring(0, 16), 'raw')); var encodedEncryptedData = forge.util.base64urlencode( forge.util.encode64( encBuffer.bytes()) ); var envelope = `ncrypt:2:${encodedIV}:${encodedEncryptedSecretKey}:${encodedEncryptedData}`; console.log(envelope); } ``` **Encryption example** Below you can find an encryption example steps: 1\. Create a PIN Block \ in ISO 9564-1 format 1 as given below format *Where, for example:*\ **Version:** 1\ **PIN Length:** 4\ **PIN:** 1234\ **Random HEX digits**: 3CB5055865 > **\** = 1412343CB5055865 2\. Generate a random 3DES key of 16 bytes > **<3DESkey>** = 1FB3F48A6D51832CE91C1C734554086D 3.1 Now encrypt the **\** with **<3DESkey>**, you will get **\** > **\** = 3A4F4E79B16E4704 3.2. Transform the **\** into Hex bytes to get the data in Hex **\** 3.3. Now convert the **\** into Base64 URL encoding (RFC 4648), you will get **\** > **\** = Ok9OebFuRwQ 4\. Encrypt the **<3DESkey>** with NymCard's shared key **\** in **OAEPWithSHA512 and encode it in Base64 URL encoding (RFC 4648),** you will get **\** > **\ =** kjQRz3M9wzOFPU3cphAomtHoMv3aC2-CkMtAgiLvYfpy1cEwTm3ag7\_caXHFThWN\_SBxHpj9aviki9rr7okJKN-Bqd\ > O46d7Uu4Bx9dNo0\_Tn9ZcKV7X-dAGLgNViYeAaGbA2jlcESYZZLecqPBq\ > BADQ12DdGV4VfRtEb3pDZRO3VRP1hXL4VgN\_H1vRwIwT5vTyBLuzQA\ > 3Lh3xqrlVrrRFHah42oH3YkgaY6M8mc3r3e3pBItNMiwW10wjfO50z7dy\ > 2O0yAGyy-QSWqu4LQYMLKMAPx4wsuEcAQg3Xpmnv3GmP\_goAvu88\ > ASH9u4iKWGh0OtrldQZlmUqiYcq9mWMQ 5\. Generate a 16-byte random **\** and convert it into **Base64 URL encoding (RFC 4648)** > **\** = c31378867535cc5d1159613388253dab > > **\ =** wxN4hnU1zF0RWWEziCU9qw 6\. Create a digital envelope with the separator **“:”** in the format **\:2:\:\:\** and send the created digital envelope in Change Card PIN request. Sample message is given in below table: | **Component** | **Position** | **Sample message** | | ------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \ | 1 | ncrypt | | \ | 2 | 2 | | <64\_IVcomponent> | 3 | bP6dZTzopk6TTYeP4lETrw | | <64\_encryptedsecretKey> | 4 |

kjQRz3M9wzOFPU3cphAomtHoMv3aC2-CkMtAgiLvYfpy1cEwTm3ag7\_caXHFThWN\_SBxHpj9aviki9rr7okJKN-Bqd
O46d7Uu4Bx9dNo0\_Tn9ZcKV7X-dAGLgNViYeAaGbA2jlcESYZZLecqPBq
BADQ12DdGV4VfRtEb3pDZRO3VRP1hXL4VgN\_H1vRwIwT5vTyBLuzQA
3Lh3xqrlVrrRFHah42oH3YkgaY6M8mc3r3e3pBItNMiwW10wjfO50z7dy
2O0yAGyy-QSWqu4LQYMLKMAPx4wsuEcAQg3Xpmnv3GmP\_goAvu88
ASH9u4iKWGh0OtrldQZlmUqiYcq9mWMQ

| | <64\_encryptedData> | 5 | Ok9OebFuRwQ | {% hint style="info" %} Test keys which can be used in the sandbox environment are given in the [**Test Keys**](#test-keys) section. {% endhint %} **For non-PCI compliant customers:** To change the card PIN, please integrate nCore’s PCI widget in your cardholder facing applications to enable your cardholders to securely change their card PIN. Please check the [**PCI Widget**](/get-started/security/pci-widget) section for further details. ### **Get card PIN** **For PCI compliant customers:** Send **GET** request to **/cards/{id}:getPin** endpoint to get an encrypted card PIN, which can be decrypted by your application to show the PIN in clear form to the cardholder. > [**GET /cards/{id}:getPin**](https://nymcard.com/docs/api#tag/Cards/operation/getCardPin) Where {id} is the card ID and it is a mandatory field. ### **Card PIN deciphering method** Let's send a Get PIN request and receive the encrypted envelope message as given below.
Get PIN request **`{`**\ ` `**`"enc_pin": "ncrypt:2:xKzHT-2NJ8yCZIv7Ra9oFQ:`**\ **`VETEcevv-ZyndOeLF7CqO-4aNJ6Z5Tha0wcMFoJEDAJAoLsst1ccMSeeMdbJUwq1GfKjCpm5mM`**\ **`wkEn51ZAFqLW43EcNkapSiPPVRJtU5V1z9u4ZGEXi4swPVzY2j0NfaM4a4aGM_WdpKSx6r7m86`**\ **`vhjI5901GXRd2vpyGAztfL9krOMA7KgLGaVlqj1i-xIaxvGbIDhFVepIWcxTxiSHqwZxLMN1HMojtf2pJacwoq5nOBP3DX3DgdapIdJN8AWCSIpZ8M6n`**\ **`wf4-2Wr8GGTJrUChU1eJiALKZ-lliP8RvIERG9zP3Z41kQDoWP9JlEFr547xREvXIf6IS4a_ixuwrg:`**\ **`1Ya9e6e0Los"`**\ **`}`**
{% hint style="info" %} Remove **"enters"** from the sample message given above when testing on sandbox. {% endhint %} Now we will apply the steps to decrypt the Card PIN as shown below. ![](/files/L6CaobI1mbj0eUC9mNn0) Steps to decrypt a digital envelope: 1\. Parse the digital envelope with separator “:”. 2\. Now decode the components \, \ and <64\_encryptedData> with BASE64 (RFC 4648), after that you will get **\, \, \** Below you can find an example of code snippet: ``` // function parseEnvelope(envelope) { var envelopeComponents = envelope.split(":"); var encIVh forge.util.bytesToHex(forge.util.decode64(forge.util.base64urldecode(envelopeComponents[2]))); var encKey = forge.util.bytesToHex(forge.util.decode64(forge.util.base64urldecode(envelopeComponents[3]))); var encPIN = forge.util.bytesToHex(forge.util.decode64(forge.util.base64urldecode(envelopeComponents[4]))); console.log(encIVh); console.log(encKey); console.log(encPIN); } ``` 3\. Decrypt the **\** with the receiver's private key in OAEPWithSHA512 to get the you will get the **3DES key <3DESkey>** Below you can find an example of code snippet: ``` // function decryptRSA(encKey, privateKey) { var encryptedSecretKey = forge.util.decode64(forge.util.base64urldecode( encKey )); var privateKey = forge.pki.privateKeyFromPem(privateKey); var decryptedSecretKey = forge.util.decryptRSA2(encryptedSecretKey, privateKey); console.log(forge.util.bytesToHex(decryptedSecretKey).toUpperCase()); } ``` 4\. Now decrypt <**encryptedData**> with <**3DESkey**> so that you will get the clear PIN block **\** in ISO 9564-1 format 1 Below you can find an example of code snippet: ``` // function decrypt3DES(desKey, encPin) { var decryptedSecretKey = forge.util.hexToBytes(desKey); var buffer = forge.util.createBuffer(decryptedSecretKey); if(buffer.length() !== 24) { buffer.putBytes(forge.util.hexToBytes(buffer.toHex().substring(0, 16), 'raw')); } var decipher = forge.cipher.createDecipher('3DES-ECB', buffer.bytes()); var encryptedData = forge.util.hexToBytes(encPin); var dataBuffer = forge.util.createBuffer(encryptedData); if(dataBuffer.length() !== 16) { dataBuffer.putBytes(forge.util.hexToBytes(dataBuffer.toHex().substring(0, 16), 'raw')); } decipher.start({iv: ''}); decipher.update(dataBuffer); var result = decipher.finish(); var pinBlock = decipher.output.toHex(); var pinLength = pinBlock.substring(1, 2); var pin = pinBlock.substring(2, parseInt(pinLength) + 2); console.log(pin); } ``` 5\. Now parse the clear PIN block as per the following ISO 9564-1 format 1, you will get the clear PIN **\** ISO 9564-1 format 1 = \\**\**\ {% hint style="info" %} Test keys which can be used in the sandbox environment are given in the [**Test Keys**](#test-keys) section. {% endhint %} **For non-PCI compliant customers:** To retrieve the card PIN and show it to the cardholder, please integrate nCore’s PCI widget in your cardholder facing applications to enable your cardholders to securely retrieve and see their card PIN. Please check the [**PCI Widget**](/get-started/security/pci-widget) section for further details.\ **Decryption example** Below you can find a decryption example steps: 1\. Parse the digital envelope with separator “:” as given below. | **Component** | **Position** | **Parsed Message** | | ------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \ | 1 | ncrypt | | \ | 2 | 2 | | <64\_IVcomponent> | 3 | xKzHT-2NJ8yCZIv7Ra9oFQ | | <64\_encryptedsecretKey> | 4 |

VETEcevv-ZyndOeLF7CqO-4aNJ6Z5Tha0wcMFoJEDAJAoLsst1ccMSeeMdbJUwq1GfKjCp
m5mMwkEn51ZAFqLW43EcNkapSiPPVRJtU5V1z9u4ZGEXi4swPVzY2j0NfaM4a4aGM\_W
dpKSx6r7m86vhjI5901GXRd2vpyGAztfL9krOMA7KgLGaVlqj1i-xIaxvGbIDhFVepIWcxTxiSHqwZxLMN1HMojtf2pJacwoq5nOBP3DX3DgdapIdJN8AWCSIpZ
8M6nwf4-2Wr8GGTJrUChU1eJiALKZ-lliP8RvIERG9zP3Z41kQDoWP9JlEFr547xREvXIf6IS4a\_ixuwrg

| | <64\_encryptedData> | 5 | 1Ya9e6e0Los | 2\. Now decode the components \, \ and <64\_encryptedData> with BASE64 (RFC 4648), after that you will get **\, \, \** as given below. > **\** = c4acc74fed8d27cc82648bfb45af6815 > > **\** = VETEcevv+ZyndOeLF7CqO+4aNJ6Z5Tha0wcMFoJEDAJAoLsst1ccMSeeMdbJUwq1\ > GfKjCpm5mMwkEn51ZAFqLW43EcNkapSiPPVRJtU5V1z9u4ZGEXi4swPVzY2j0NfaM4a4aGM/WdpKSx6r7m\ > 86vhjI5901GXRd2vpyGAztfL9krOMA7KgLGaVlqj1i+xIaxvGbIDhFVepIWcxTxiSHqwZxLMN1HMojtf2pJacwoq\ > 5nOBP3DX3DgdapIdJN8AWCSIpZ8M6nwf4+2Wr8GGTJrUChU1eJiALKZ+lliP8RvIERG9zP3Z41kQDoWP9JlE\ > Fr547xREvXIf6IS4a/ixuwrg== > > **\** = D586BD7BA7B42E8B 3\. Decrypt the **\** with the receiver's private key in OAEPWithSHA512 to get the you will get the **3DES key <3DESkey>** > **<3DESkey>** = 9D233E02CD9D26E3519768B50B0BEC31 4\. Now decrypt <**encryptedData**> with <**3DESkey**> so that you will get the clear PIN block **\** in ISO 9564-1 format 1 > **\** = 141234284C1B97D0 5\. Now parse the clear PIN block as per the following ISO 9564-1 format 1, you will get the clear PIN **\** ISO 9564-1 format 1 = \\**\**\ > **\** = <1><4>**<1234>**<284C1B97D0> > > **\** = <1234> {% hint style="info" %} Test keys which can be used in the sandbox environment are given in the [**Test Keys**](#test-keys) section. {% endhint %} ### **Test Keys** You can use the following test keys to perform Get and Change PIN operations. {% hint style="info" %} Remove **"enters"** from the Test keys given below when testing. {% endhint %} | **Test Keys Name** | **Test Keys** | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NymCard’s Public Key |

-----BEGIN RSA PUBLIC KEY-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnoKm9GUmDj2to8ldXHk1fX87NK8S99KAZ600ok+cnr6k0raeNI7BtQP9lhv/5ZeiZnCC6VNihDY9SfIGglDUi4pAGNYOmo0VmlbzTUejKJgktePdhjw5M3YStxidFN0oNVaaw6RQpcfeUGIoF6DiKC9p8hP85R/+C5dKy5Eflw5jrPDAkFZ01INSThZFEzK3f/KXpzGm7Y/9cfkqVlCoq+2wcBiX6B6SQplD7DUKA9SyI/YXKz/aKA1iBMumPyn+VfR9lDTLbYlw2JXsES7BWluAXpXC7yJ2fTfqCzGGmh/4f36EXGrkQnASA9DzNbYwyA3ZXsUIJzRL+38B8QVx1wIDAQAB

-----END RSA PUBLIC KEY-----

| | Client’s Public Key |

-----BEGIN RSA PUBLIC KEY-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvlWX39E2k2CYRKGZFwlZLHE7p139zkaQkCy4Yx1T70I
GFtHIKBmPnjb9uzDmxTW1AihjO4iExYZh1OJz7/PYbgjRufEJ28uzJaCAJGKJZaXtgrKqgLAgxJr0IHQ+KFtilqbrqecFO0
aBdptxY3jvBblg2cfb/AS5U3RmUwF6RzmJuTSeSK7sxnezheeubFusnxrop3iiopqJv9iGkVa97P3jAiF/tVN1HqmsAHaiXo
bnOV2xXsNfHUJ0J8xW61Vpy7SvtEx0SLcVb/kMaUstQNdIIvEeSxEmdmUHj3JakGWhFC79pQXP/tDaeH71mVZJFHq
O+Mfbm5+EtHU7OzfzKwIDAQAB

-----END RSA PUBLIC KEY-----

| | Client’s Private Key |

-----BEGIN RSA PRIVATE KEY-----

MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC+VZff0TaTYJhEoZkXCVkscTunXf3ORpCQLLhjHVP
vQgYW0cgoGY+eNv27MObFNbUCKGM7iITFhmHU4nPv89huCNG58Qnby7MloIAkYollpe2CsqqAsCDEmvQgdD4oW2
KWpuup5wU7RoF2m3FjeO8FuWDZx9v8BLlTdGZTAXpHOYm5NJ5IruzGd7OF565sW6yfGuineKKimom/2IaRVr3s/eMC
IX+1U3UeqawAdqJehuc5XbFew18dQnQnzFbrVWnLtK+0THRItxVv+QxpSy1A10gi8R5LESZ2ZQePclqQZaEULv2lBc/+0
Np4fvWZVkkUeo74x9ubn4S0dTs7N/MrAgMBAAECggEATyDqiQRDejXYWAAO00LxrcZNlKFA2TcA9s+AwMP6lyeNvIL
uga1Oxen6xo3oAuj3HbSIvMFe4XeiyIx0wrdPrT9BYdpRzOz8x5HYdEf68yVufr2koOeYV+RLxgpNpR2I+TTgGLyQsjn3rMW
m+EHYrTqKhz/NtxKHsahcufmNSnprMlFnhR81HkwMTJVFduD8awNQgywOoEKky9LtsdRi59uH+PZfxZM1AubuChIezO
QwiSu+IiL+ypgTv7gSyYeChsZJPFN7oyTjU0gx2IKpUOiPMxPsOVY6SxXDbQFoakyA/tuH3a3xWi4TsbNk3tIgyZbIkPPvHfj
eTA6IZCxeUQKBgQDuPTA6vt78ilJG0TidMaVPIxJ4/mskVVfPcSZplXKGNbJDDUD5vaTU3zMLV3CXdcvu8d9gQDdOaFu
WIbVZY0NbwiZPVy7E6eKTpgAzsEbVXw/P4GSFSMuUErOOKFNeGOgj+6b81j/XNk3YmPkKhN+bEc4ADpEU7tKU9/bX
EYMutQKBgQDMhiPnc5MlFP3008nJ6cp1zRDD79EsesMo0TnQHlrTAjuY2T/6fuErlnNxY7ynE+xcJQbYcJmfyndyoX/OVJ
QOPcoiU5AgjBgwweCYOQpW6Kh7LRQXv1TQvzVjM9lssZ+Lwmda5xxFympCgANiqyn+iSbfTvh7E6EOIfYb+ifmXwKBg
DFL9gPh5RBKqvW+a0GTuUojzrm8o3z0L+Rb3H/yja0ZxVY8ktpalJX7zXsmT8T3eghqgjdPcmJGE9WACh+B+7kr9nNqbe
IPJ3Q34EjRzAZw0jvIieROiNmN+RuMWpvY+YgglZAx4SnuMbOFC9tSXVagG4lFel3jgS2UFb6w//0VAoGAcOVazFgv0ThV
Nt/xc1NqPryDlKS8giEBuXZEw2z+FZwV6bmCZ3PCN51E/EJh0Jhe0D5gGPmO03WfmdcsBWkKkRHqkiguVsj+UWuz3lM
eMfsbhWLMxI8I8nGZtrjYO/eQakVVaAhKwvuIzEx9kemJtMdgfcPJxaaAMJzujWL4w2ECgYBc09fYu8CamUpVDTgCUGizV
4fBzeBiygmxUAyg1wcV3E5HHSrCmZRL0jRi0RqlURprgb2R3wyvD9nDobDY6AZYEqTw8DKP2U55Fxo1aoua1TT/uQe0z
RnDugAu/BNAboe0FWMNd004NiM73TC/x8yUP+wo2B3o0+G7OCiUqvqGMw==

-----END RSA PRIVATE KEY-----

| ### Card PIN Controls The card PIN settings such as PIN length, PIN type, and PIN retries are defined on the card product. A card inherits all of the PIN setting from the card product. When the cardholder performs a transaction with an incorrect PIN (bad PIN), a counter shall be maintained and updated at the card level to keep track of successive bad PIN attempts. Before reaching the threshold if the cardholder is able to perform a successful PIN verification, then the counter shall be reset. If the bad PIN retries threshold is achieved, the card status shall be automatically changed to suspended status and the status reason code shall indicate that the card is suspended because PIN retries are exhausted. When the card is suspended, all POS and ATM authorizations are blocked. The card status can be changed from suspended to active. The cardholder KYC must be performed before resetting the PIN, the PIN counter and the card status. Once KYC is verified then you can perform the following steps to update card PIN and card status. * Call change PIN API to reset the card PIN\ Send **PUT** request to **/cards/{id}:changePin** endpoint as given below.
PUT /cards/{id}:changePin **`{`**\ ` `**`"enc_pin": "ncrypt:2:bP6dZTzopk6TTYeP4lETrw:`**\ **`kjQRz3M9wzOFPU3cphAomtHoMv3aC2-CkMtAgiLvYfpy1cEwTm3ag7_caXHFThWN_SBxHpj9aviki9rr7okJKN-Bqd`**\ **`O46d7Uu4Bx9dNo0_Tn9ZcKV7X-dAGLgNViYeAaGbA2jlcESYZZLecqPBq`**\ **`BADQ12DdGV4VfRtEb3pDZRO3VRP1hXL4VgN_H1vRwIwT5vTyBLuzQA`**\ **`3Lh3xqrlVrrRFHah42oH3YkgaY6M8mc3r3e3pBItNMiwW10wjfO50z7dy`**\ **`2O0yAGyy-QSWqu4LQYMLKMAPx4wsuEcAQg3Xpmnv3GmP_goAvu88`**\ **`ASH9u4iKWGh0OtrldQZlmUqiYcq9mWMQ:`**\ **`Ok9OebFuRwQ"`**\ **`}`**
* Once you change the card PIN you can reset the card status from Suspended to Active using the change card status API\ Send **PUT** request to **/cards/{id}:statuschange** endpoint to change card status from suspended to active as given below.
PUT /cards/{id}:statuschange **`{`** **`“status”: “ACTIVE”,`**\ ` `**`“status_reason_code”: “a1”`** **`}`**
# Card replacement The platform provides card replacement feature to replace the terminated card. A terminated card (personalized or non personalized) can be replaced with a non-personalized bulk card or with a personalized card when requested by the API user. The API user can raise a card replacement request for a terminated card due to any reason, e.g. stolen, lost, damaged, expired, etc. The replaced card will take the place of the original terminated card and will be linked to the existing account of the original card instead of creating a new account. On this page: * [Replace a card with a personalized card](#replace-a-card-with-a-personalized-card) * [Replace a card with a non-personalized bulk card](#replace-a-card-with-a-non-personalized-bulk-card) * [Card renewal](#card-renewal) ### **Replace a card with a personalized card** A terminated (non-personalized or personalized) card can be replaced with a personalized card when requested by the API user. After the successful card replacement the replaced card takes the place of the original terminated card and is linked to the existing account of the card being replaced. Please note: 1\. A new PAN (Primary Account Number), PIN (Primary Identification Number), CVV2 (Card Verification Value 2) & expiry date is generated and instead of creating a new account **this new card is linked to the original card’s account.** 2\. For a successful card replacement, following details required. * original card product ID in **"card\_product\_id"** * original user ID in **"user\_id"** * original card ID in **"reference\_card\_id"** You can replace a card with a personalized card by sending a **POST** request to **/cards** endpoint as shown below.
POST /cards **`{`**\ ` `**`"id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ ` `**`"user_id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ ` `**`"card_type": "PHYSICAL",`**\ ` `**`"card_product_id": "",`**\ ` `**`"reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ ` `**`"bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ ` `**`"name_on_card": "John Smith",`**\ ` `**`"shipping_details": {`**\ ` `**`"method": "COURIER",`**\ ` `**`"return_address": {`**\ ` `**`"first_name": "John",`**\ ` `**`"middle_name": "Anthony",`**\ ` `**`"last_name": "Smith",`**\ ` `**`"mobile": "+551185249635",`**\ ` `**`"address_line1": "Flat 1904",`**\ ` `**`"address_line2": "Glass Tower",`**\ ` `**`"city": "New York City",`**\ ` `**`"state": "New York",`**\ ` `**`"country": "USA",`**\ ` `**`"postal_code": "12345"`**\ ` `**`},`**\ ` `**`"shipping_address": {`**\ ` `**`"first_name": "John",`**\ ` `**`"middle_name": "Anthony",`**\ ` `**`"last_name": "Smith",`**\ ` `**`"mobile": "+551185249635",`**\ ` `**`"address_line1": "Flat 1904",`**\ ` `**`"address_line2": "Glass Tower",`**\ ` `**`"city": "New York City",`**\ ` `**`"state": "New York",`**\ ` `**`"country": "USA",`**\ ` `**`"postal_code": "12345"`**\ ` `**`}`**\ ` `**`},`**\ ` `**`"dry_run": "false",`**\ ` `**`"card_validity_term": 36`**\ **`}`**
### **Replace a card with a non-personalized bulk card** nCore supports feature to replace the terminated card (from a personalized or non-personalized card to a non-personalized bulk card) when requested by the API user. The API user can raise a card replacement request for a terminated card due to any reason e.g. stolen, lost, damaged, expired etc.. The replaced card takes the place of the original terminated card and is linked to the existing account of the original card instead of creating a new account. Please note: To replace a terminated card (personalized or non-personalized) with a non-personalized card you require: * Please make sure that the **original card's** card product ID = **bulk issuance's** card product ID. * Get a card created in bulk issuance you want to link/replace by sending a **GET** request to **/cards** endpoint. * provide terminated card id in “**reference\_card\_id**” field when replacing a card. The platform treats it as a card replacement request and links the non-personalized card provided in the request with the account of the original card present in field **"reference\_card\_id"**. You can send a **POST** request to **/cards/{id}:replace** endpoint; where id is the non-personalized card id you want to replace the terminated card with.
POST /cards/{id}:replace **`{`**\ ` `**`"reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7459",`**\ ` `**`"activate_card": true`**\ **`}`**
### **Card renewal** Introduced the following parameters in the response of [Card products](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products) APIs under 'card\_settings' parameter: **"allow\_card\_renewal", "renew\_before\_days", "new\_pan\_on\_renewal", "auto\_renewal\_process"**. They are used to renew an existing card so that if a card is about to be expired, a new card can be generated and provided to the cardholder for uninterrupted card services. Impacted APIs: * Create card product * Update card product * Get card product * Get list of card product This enhancement has impact on both existing and new card products. Example: ``` "card_settings": { ... "allow_card_renewal": true, // default = false "renew_before_days": 60, // default = 60 "new_pan_on_renewal": false, // default = false "auto_renewal_process": true // default = false } ``` # Proxy number usage You can use a proxy number instead of card ID in many cases. A proxy number can be printed on the card envelope as a nonsensitive unique identifier of the card and can be used to activate the plastic card once received from the cardholder instead of PAN, CVV and expiration date. There are two reasons why not to use the card ID for card activation: * it is too long (32 characters) * it has a very specific format that may not fit with customer requirements. The power of the Proxy number is the flexibility that NymCard offers to the customer to define the length and the format. For example, one client asked for 9 digits proxy number that does not start with 0. We are open to any other format as well.
# Issuing Virtual Cards A virtual card is a type of payment card which usually refers to a digital substitute of a physical card. It is a card which is fully functional and it is an ideal solution for online payments as it is extremely helpful in keeping your account secure online. A virtual card exists in a virtual form. You can make online and in-app purchases with this card. A virtual card has card details (e.g. 16 digit card number, an expiry and a CVV2) which users can retrieve and use for online payments. The virtual card will be created for a card product already defined in the system. A card can only belong to a single card product and will inherit all of its features and characteristics applied to the card product. Virtual cards can be used instantly after creation. You can issue a virtual card and use it in the following steps. * Create a user * Create a card * Fund the account * Use the card Below you can find a virtual card issuance decision flow: ![](/files/fvlLZW2oxiWipZEvaOZE) ### Create a user A user is an entity which can be an individual that holds an account at nCore which is represented by the user object. Please refer to the section [**Users**](/get-started/issuance/users) for more information. ### Create a card At nCore platform, payment cards are identified as an object of the cards resource, you can create a card by sending a POST request to **/cards** endpoint. The card object stores data about the card for example, **name on card, card number, expiry date, CVV2, card product** etc. *Note: Create a user and a card product before creating a card. It is mandatory to provide the the identifier of the user who owns the card,* *the type of card (virtual/physical), and the identifier of the card product in **POST*** **/cards** *request as shown below.*
POST /cards **`{`**\ ` `**`"user_id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ ` `**`"card_type": "VIRTUAL",`**\ ` `**`"card_product_id": "b4eabfc-f839-4e51"`**\ **`}`**
Please note that virtual card’s PAN, expiry date, and a CVV2 are provided to the cardholders in 2 ways: * **For non PCI DSS compliant customers:** Virtual cards details are displayed to the cardholder by using PCI widgets. For further information, please refer to the [**PCI widget**](/get-started/security/pci-widget) section. * **For PCI DSS compliant customers:** Virtual card details can be retrieved by sending a **GET** request to **/cards/{id}/show\_info** endpoint. For further information on PCI DSS please refer to the [**Security**](/get-started/security) section. #### Retrieve a card To retrieve a specific card, you can include the card ‘ID’ path parameter in your **GET** request and send it to **/card/{id}** endpoint. > [**GET /cards/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getCard) ### Fund the account Whenever a new card is issued a General Ledger (GL) account will be automatically created and linked to the card. The card account is a term which is usually used to refer to this account. The account holds the funds of the card. To access account and retrieve details, please follow these steps: * Send a GET request to **/cards/{id}/accounts** endpoint to fetch the accounts linked to the card. Send this request with the Card ID parameter field. > [**GET /cards/{id}/accounts**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardAccounts) * Once you have the card accounts, you can then send a **GET** request to **/accounts/{id}** endpoint with the account ID to retrieve the account details like account currency, balance etc. > [**GET /accounts/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getAccount) To fund the card account, please refer to the [**Funding**](/get-started/funding-and-transfers/internal-funding-source) section. ### Use the card After the card account is funded the card is ready to be used for online and in-app purchases. {% hint style="info" %} For digital wallets (ApplyPay, SamsungPay & GooglePay), a user is limited to a maximum of 10 tokens per card from the respective wallet providers (Terminated tokens are excluded). Also take into account that a card is temporarily blocked for 24 hours for provisioning if the user makes five consecutive invalid CVV2 or expiry attempts. {% endhint %} # Migration of virtual to physical card ## Introduction A new feature has been introduced in the system to allow users to migrate a virtual card to a physical card while retaining the same card details. ## The flow Below you can find the flow details**:** 1. The user calls the Update Card API with the newly introduced parameter `change_to_physical` = true. 2. The system updates the card status reason code to `AT` – Active Transition, and the fulfillment status becomes `CREATED` . 3. Once the embossing of the physical card is generated, the status moves to `ORDERED` . After completing these steps, user needs to manually update the card status to `A0` – Active Initial, which update the card type from VIRTUAL to PHYSICAL. **Restrictions During Transition:** 1. While in the transition period, the status reason can only be changed to `ST` – Suspended Transition, indicating that the card is temporarily blocked during migration. 2. If the user wishes to permanently block the card, it is allowed at any time during the transition. 3. While the card is in the transition period, authorization settings will be restricted, preventing specific transactions until the migration to physical is fully completed. ## API changes The following API changes added: **1.** [**Update Card**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/updateCard) **API (PUT /v1/cards/{id})** * New Parameter: "`change_to_physical`" (Boolean) * Allows the user to initiate the virtual-to-physical card migration. **2.** [**Update Card Authorization Settings**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/upsertCardAuthSettings) **API (PUT /v1/cards/{id}/authsettings)** * Restriction: Users cannot change the card’s authorization settings during the transition period. **3.** [**Change Card Status**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/changeCardStatus) **API (PUT /v1/cards/{id}:statuschange)** * New status codes introduced: * AT – Active in Transition (Card is in migration phase). * ST – Suspended in Transition (Card is temporarily blocked during migration). **4.** [**Card Products**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products) **APIs Updates:** * New parameter: "`virtual_to_physical_expiry_duration`" * Allows configuration of the maximum duration allowed before the virtual card expires during migration. For more information refer to the [API catalog](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs). \ \
# Funding and transfers # Funding Funding enables you to load and manage funds of an individual user account. The nCore platform provides General Ledger (GL) accounts that hold the balances of the users. nCore APIs are available to manage the funds held in these accounts. **Types of funding:** NymCard supports two types of funding given below: * [**Internal funding** **source**](/get-started/funding-and-transfers/internal-funding-source) - when you want to load funds from an nCore platform based account to another nCore platform based account. * [**External funding source**](/get-started/funding-and-transfers/external-funding-source) - when you want to enable a cardholder to load funds from debit, prepaid or credit card to nCore platform based account. # Internal funding source Funding enables you to load and manage funds of an individual user account. The nCore platform provides General Ledger (GL) accounts that hold the balances of the users. nCore APIs are available to manage the funds held in these accounts. ### Load funds The user account linked to the card needs to be funded before the card can be used for the transactions. You can load funds to the user account by sending a **POST** request to the **/accounts/{id}:loadFunds** endpoint. This API call will load funds from program funding account to the user account.
POST /accounts/{id}:loadFunds **`{`**\ ` `**`"currency": "USD",`**\ ` `**`"amount": 100,`**\ ` `**`“dry_run”: false`** \ **`}`**
### Unload funds In order to transfer back your user account funds to your program funding account, you can send a **POST** request to the **/accounts/{id}:unloadfunds** endpoint.
POST /accounts/{id}:unloadFunds **`{`**\ ` `**`"currency": "USD",`**\ ` `**`"amount": 100,`**\ ` `**`"dry_run”: false`**\ **`}`**
### Check balance After loading funds into the user account, you can check your balance by sending a **GET** request to the **/accounts/{id}** endpoint. > [**GET /accounts/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getAccount) # External funding source nCore platform gives you a possibility to load money into a NymCard card account from different external funding sources: * [from card](/get-started/funding-and-transfers/external-funding-source/from-card) (using MPGS integration) * [from bank account](/get-started/funding-and-transfers/external-funding-source/from-bank-account) (using a widget) {% hint style="info" %} Please be aware that transfers, load/unload, DAPI, and LEAN direct API flow will be declined if either the sender's or recipient's user status is not ACTIVE. {% endhint %} # From card nCore platform provides you a feature to load money into a NymCard card account from an external funding source which can make you able to top-up your card account using any card. For example, a user can use his debit card issued by a bank to top up his prepaid card account in nCore platform. To load card account from outside of the nCore platform, NymCard integrates with Mastercard Payment Gateway Services (MPGS), which offers different payment methods (currently ‘hosted checkout’ payment method is supported). NymCard's frontend/backend client initiates request to nCore platform for loading into the card account. **Prerequisite:** * Identify the BUSINESS user having default\_user value as true in the tenant. * Identify the account with default\_account as true linked to the business user. * Business account (default\_account) has to be loaded with funds (in AED) covering the transferred amount. ### Configurations applicable at tenant level Following are the configuration requirements that need to be done at tenant level by NymCard.
FieldDescriptionSample value
‘payment_gateway’The name of the payment gateway.'MPGS'
‘merchant_id’ID of the merchant. This ID is assigned by the payment gateway.'500536'
‘user_name’The name of the user in the merchant profile, which is configured on the gateway portal.'merchant.500536'
‘user_password’The password of the user in the merchant profile, which is configured on the gateway portal.'user-password'
‘mpgs_api_url’API URL of the payment gateway where nCore API communicates.'https://test-gateway.mastercard.com'
‘authentication_limit’Applicable in HOSTED_SESSION payment method.'25'
‘merchant_currency’The merchant currency in format of 3-character ISO alpha code. Default value is ‘AED’. It is the only supported currency for now.'AED'
‘merchant_mcc’4-characters MCC code of the merchant.'1234'
{% hint style="info" %} Please ask your NymCard account manager to make sure that you have the corresponding setting `"default_currency": "AED"` configured for your tenant. {% endhint %} ### External funding flow You can take the following steps to perform the external funding flow: 1\. Create order using nCore API (you can find this API request and response samples in "[**Orders management**](#orders-management)" section of this document): ![](https://lh5.googleusercontent.com/Ivi1NPXDc1Xs9GXgl25HH6zwsoBmiMqZGb2_Xywr2WhTNB8-4VwuvpaWTJBImoFFNN4hVp4kCkkoodQWZKMkDb5jpTkoIn0Agzre2Lw4IVrTD77GJIq7OpZqWqGZt9hhzOz98hSl6Ry5O8QpWw) \ 2\. Take ‘session\_id’ value from API response received from the nCore platform and place it together with the following payment gateway code snippets in your widget: > **``** > **`Checkout.configure({`** > > **`session: {`** > > **`id: SESSION0002617523020H25893709N7`** > > **`}`** > > **`});`** Please refer to the [**Payment gateway integration guide**](https://test-gateway.mastercard.com/api/documentation/integrationGuidelines/hostedCheckout/integrationModelHostedCheckout.html) for more details. 3\. Initialize your code. 4\. Select hosted page: \- To display the checkout interaction in a lightbox on existing page, use: *Checkout.showLightbox();* \- To display the checkout interaction on a new page, use: *Checkout.showPaymentPage();* In case of lightbox, you will get the pop-up window where you should fill in card info: ![](https://lh4.googleusercontent.com/60-h8p5UNUsx6t5EfqvF6EOGY-Vf8tOFJLEPg42B4T_KFcuc4AbSBRngpOSnfRC7abyKyitnjldNTkH-aFWXxzJ5wBpNVAmfPM-GlaHHikkyLZSphoFuz4looxEMoqIKoWHwDmEX0qwUIbam9w) \ ![](https://lh5.googleusercontent.com/e1HPFcvTItUWpUyJ_34HQI_DE0AP9hgbkFIjQiWgwaEXMH5OJ2fF5eBrZuhsZdGhIz84I35pKZrvpvYoDjuS-h8dCdhIVQazTeKRgB4GCgNXMNSiu_37zhZqcbSOHK1PGhA_dozidraMxGSQtA) In case of hosted payment page, you will be redirected to a separate page where you should fill in card info: ![](https://lh4.googleusercontent.com/G_LYVoBPkVg6zEWOl1U8KQDmR37G6N0pV6PTbrZKSPIgmzqAg_AJzdeGsSg6dYJGs-ReciUy339Q0FmNqoJYZjUOjqbTfURjpNYnepOwuiiMrd2r17miG0raHitbrdyxwRDRRhuEBQmJto0hcA) \ 5\. After the payment is successful at step 4, NymCard will callback on the 'redirect\_URL', which is provided by the client in 'Create order' API, together with 'order\_id' and the payment status. Below you can see an example: ![](https://lh4.googleusercontent.com/jobC5JRFKKsR_Ol_jqZxZfngqh0XVxFhoCxAB21sNg-LyufIGtT-vtlA2CazeBaKdXosijIKQC2T6MTmuDXvRBTGeilOVcWFsBRh0Mi9hxYcyEeyCT0EFLgl5Z1N1W4Z03UX--rqqPdfXysTrw) ### Order statuses {% hint style="info" %} **The links below are just examples. The actual URL will be based on 'redirect\_URL', which is provided by the client in the 'Create order' API.** {% endhint %} There are several order statuses, which you can face: 1. The operation was **successful**. Then you will get the following URL after payment fulfillment: \ *localhost:9000/redirect?order\_id=d78f5600-08b5-4b6f-8c73-0025b5e4fb6c\&status=SUCCESS* 2. The operation was **canceled**. Then you will get the following URL after payment fulfillment: \ *localhost:9000/redirect?order\_id=d78f5600-08b5-4b6f-8c73-0025b5e4fb6c\&status=CANCEL* 3. **Timeout** occurred during operation processing. 4. An **error** occurred during operation processing. ### Interaction between Client-NymCard-Payment gateway \ Below you can find the communication process between client, NymCard and payment gateway: 1. Client's frontend captures the amount and currency from the user and communicates it to its backend. Note that multi-currency loading is not supported for now. 2. Client’s backend calls the “[Create order”](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Orders/operation/createOrder) API. 3. NymCard creates a hosted checkout session with MPGS and returns the unique order and session IDs in the 'Create order' API response. 4. Client's frontend calls ‘checkout.showlightbox’ or ‘checkout.showpaymentpage’. 5. Payment gateway processes the payment. 6. nCore platform callbacks the redirect URL, provided by the client, along with order 'status' and 'order\_id'. 7. Client's backend/frontend displays the results to the user. ### Orders management You can create and manage your orders by using our APIs. Following are the APIs available at nCore platform for orders management. * Create order * Get specific order #### **Create order** You can create an order by sending a **POST** request to **/orders** endpoint as given below.
POST /orders **`{`**\ **`"dry_run": false,`**\ **`"account_id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ **`"amount": 123.45,`**\ **`"currency": "AED",`**\ **`"note": "Funds load",`**\ **`"payment_method": "HOSTED_CHECKOUT",`**\ **`"redirect_url": "https://localhost/redirect-url",`**\ **`"save_card": false,`**\ **`"token_id": "9473840270683376"`**\ **`}`**
Response **`{`**\ **`"order_id": "e82c3059-33af-4ed0-969a-7c23801dd770",`**\ **`"session_id": "SESSION0002034447366K45355737H1",`**\ **`"transaction_id": "111c3059-33af-4ed0-969a-7c23801dd555",`**\ **`"merchant_id": "500532",`**\ **`"merchant_currency": "AED",`**\ **`"request": {`**\ **`"dry_run": false,`**\ **`"account_id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ **`"amount": 123.45,`**\ **`"currency": "AED",`**\ **`"note": "Funds load",`**\ **`"payment_method": "HOSTED_CHECKOUT",`**\ **`"redirect_url": "https://localhost/redirect-url",`**\ **`"save_card": false,`**\ **`"token_id": "9473840270683376"`**\ **`},`**\ **`"result": {`**\ **`"fee_amount": 10.05,`**\ **`"status": "SUCCESS",`**\ **`"status_reason": "ORDER_CREATED"`**\ **`},`**\ **`"created": "2012-05-04T19:42:32.987Z",`**\ **`"modified": "2012-05-04T19:42:32.987Z"`**\ **`}`**
#### **Get specific order** You can retrieve a specific order by sending a GET request to /orders/{id} endpoint, where id is the order ID. > [**GET /orders/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Orders/operation/getOrder) ### Order response result field breakdown You can use the following table to map the ‘result’ field received in response which can help to understand the reason if the order failed due to some reason. Note, that below you can find the most popular responses. The full list of 'status\_reason' values you can find in '[**Create order**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Orders/operation/createOrder)**'** API (go to Response ,'status\_reason' enums).
NymCard ‘status’ field valuesNymCard ‘status_reason’ field valueNymCard ‘status_description’ field value
SUCCESSORDER_CREATED
ERRORFAILED“The operation was declined or rejected by the payment gateway.”
ERROR

INVALID_REQUEST


“The request was rejected by the payment gateway because it did not conform to the API protocol.“
ERRORREQUEST_REJECTED“The request was rejected by the payment gateway due to security reasons such as firewall rules, expired certificate, etc.”
ERRORSERVER_BUSY“The payment gateway server did not have enough resources to process the request at the moment.”
ERRORSERVER_FAILED“There was an internal system failure at the payment gateway side.”
### **Sample cards** Below you can find sample card info, which you can use for testing purposes:
Test CardsCard Number3-D Secure Enrolled
Mastercard5123450000000008Y
2223000000000007Y
5111111111111118N
2223000000000023N
Visa4508750015741019Y
4012000033330026N
American Express345678901234564Y
371449635398431N
Diners Club30123400000000Y
36259600000012N
JCB3528000000000007Y
3528111100000001N
Discover6011003179988686Y
6011963280099774N
Maestro5000000000000000005Y
5666555544443333N

UATP

(UATP cards do not support CSC/CVV and 3DS)

135492354874528N
135420001569134N
| **Expiry Date** | **Transaction Response Gateway Code** | | --------------- | ------------------------------------- | | **01 / 39** | APPROVED | | **05 / 22** | DECLINED | | **04 / 27** | EXPIRED\_CARD | | **08 / 28** | TIMED\_OUT | | **01 / 37** | ACQUIRER\_SYSTEM\_ERROR | | **02 / 37** | UNSPECIFIED\_FAILURE | | **05 / 37** | UNKNOWN | | **CSC/CVV** | **CSC/CVV Response Gateway Code** | | ------------------------------ | --------------------------------- | | **100** | MATCH | | **101** | NOT\_PROCESSED | | **102** | NO\_MATCH | | **For American Express cards** | | | **1000** | MATCH | | **1010** | NOT\_PROCESSED | | **1020** | NO\_MATCH | | **Billing Address Street** | **AVS Response Gateway Code** | | -------------------------- | --------------------------------- | | **10001 Alpha St** | ADDRESS\_MATCH | | **10002 Gamma St** | NOT\_VERIFIED | | **10003 November St** | NO\_MATCH | | **10004 Romeo St** | SERVICE\_NOT\_AVAILABLE\_RETRY | | **10005 Sierra St** | SERVICE\_NOT\_SUPPORTED | | **10006 Uniform St** | NOT\_AVAILABLE | | **10007 Whiskey St** | ZIP\_MATCH | | **10008 X-ray St** | ADDRESS\_ZIP\_MATCH | | **10009 Kilo St** | NAME\_MATCH | | **10010 Oscar St** | NAME\_ADDRESS\_MATCH | | **10011 Lima St** | NAME\_ZIP\_MATCH | | **10012 Zero St** |

NOT\_REQUESTED


| # From bank account nCore platform provides you a feature to transfer funds from your bank account to your NymCard card account using the widget. **Prerequisite:** * As a client, you need to provide NymCard with a list of countries - which banks you want to see in the widget (step 4 in the instruction below) - so we can configure it on a tenant level. * Identify the BUSINESS user having default\_user value as true in the tenant. * Identify the account with default\_account as true linked to the business user. * Business account (default\_account) has to be loaded with funds (in AED) covering the transferred amount. Below you can find: * [the standard flow](#the-standard-flow) * [the new smart flow](#the-new-smart-flow) There is also another variant - DAPI direct API flow, which you can find [here](https://docs.nymcard.com/get-started/funding-and-transfers/external-funding-source/dapi-direct-api-flow). ## The standard flow **High level steps** 1. Generate a token 2. Append generated token with the URL 3. Select or add bank 4. Transfer funds **Step by Step process** To transfer funds from your bank account to your NymCard card account, take the following steps: 1\. **Generate token** Generate a token using the “[Create temporary user token](https://nymcard.com/docs/api#tag/Orders/operation/createDapiToken)” API. In this API you need to pass your NymCard account ID, and you will receive the token itself and timestamp, which indicates when this token will expire. Expiration time is 30 minutes. Here you can find request sample:
POST /orders/token **`{`** **`"account_id": "e6b500c7-b37b-46cf-baae-e1b4f43e8749"`** **`}`**
Here you can find response sample:
Response sample **`{`** **`"token": "42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant",`** **`"expire_at": "2012-05-04T19:42:32.987Z"`** **`}`**
2\. **Append generated token with the URL** Go to the following widget URL (**) and add this token at the end of URL after slash. Example: > **`https://openbanking.sand.platform.nymcard.com/dapi_bank_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant`** 3\. **Select or add bank** You will get a web page where you can add your bank. For this use the 'Link new bank button:
3.1. Choose bank’s country of origin You will get the list of countries with sublists of possible banks. Choose your bank and click on it.
3.2. Enter bank account credentials You will get a pop-up window, where you should enter your bank account credentials (which you should already have after account creation in this particular bank):
3.3. Two-Factor Authentication Proceed with two-factor authentication steps (if it is initialized by your bank). It can be OTP-verification, PIN, secret question, captcha - depending on which two-factor authentication your bank is using. {% hint style="info" %} Note that if your bank credentials are changed, you need to conduct add-bank-procedure ( previous steps of this instruction) again to be able to make transfers. {% endhint %} 3.4. Cool down period After this your bank will be added to the list. Note that some banks may require a cool down period for some verifications. So in this case you will get a warning, and when this cool down period will end, the 'Initiate Transfer' button will appear.
3.5. Remove bank from the list If you want to remove your bank from the list, just click the 'De-Link' button:
4\. **Transfer funds** To transfer funds to your NymCard card account, click on the 'Initiate Transfer' button:
4.1. Choose a specific account You will get the list of accounts, which you have in your particular bank:
{% hint style="info" %} Note, that only AED currency is supported at the moment. So both your bank account and NymCard card account should be in AED currency. 'Transfer Funds' button will be inactive for bank accounts with another currency. {% endhint %} 4.2. Initiate transfer Click the 'Transfer Funds' button near the account from which you want to transfer funds:
4.3. Fill in transfer details You will get the following page with all the transfer details, where you have to fill in the amount which should be transferred. Note that amount value can not be bigger than the balance. Also optionally you can add some note:
4.4. Finish the transfer Click the 'Transfer' button. Proceed with two-factor authentication steps. You will get the following info about the successful fund transfer:
## **The new smart flow** We would like to introduce some significant enhancements to this process below. In standard flow at first you have to select a country, then select appropriate bank, and then credentials window will appear:


Below you can find **2 new flows,** which allow you to: \- skip the country and bank selection step and go straight to the credentials in case of adding/linking a new bank. \- go straight to fund transfer step


### **“Add new bank” scenario** Using this flow you can skip the country and bank selection step. Take the following steps: **1.Generate token** Generate a token using the “Create temporary user token” API. In this API you need to pass your NymCard account ID, and you will receive the token itself and timestamp, which indicates when this token will expire. Expiration time is 30 minutes. Here you can find request sample:
POST /orders/token **`{`** **`"account_id": "e6b500c7-b37b-46cf-baae-e1b4f43e8749"`** **`}`**
Here you can find response sample:
Response sample **`{`** **`"token": "42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant",`** **`"expire_at": "2012-05-04T19:42:32.987Z"`** **`}`**
**2.Add token the URL** Go to the following widget URL (**) and add this token at the end of the URL after slash. Example: [*https://openbanking.sand.platform.nymcard.com/dapi\_bank\_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant*](https://openbanking.sand.platform.nymcard.com/dapi_bank_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant) **3.Add linking bank parameters in the URL** Now you have to add specific parameters at the end of the URL after slash. Necessary parameters: * "action" ( value :"LINK\_BANK") * "bank\_id" (please note that its not open ended value, there are specific IDs for each bank provided by open banking payment gateway and the value should be according to it) * "allow\_ui\_flow" (values "YES" or "NO". If "NO" is selected, then it is recommended for you to close the widget on your front-end side after receiving the callback from NymCard; if "YES" is selected, then you are recommended not to close the widget after receiving the callback from NymCard). However it's up-to you whether to close the widget or not depending upon the UI flow on client FE side. You should form the json message like this: > **`{"action":"LINK_BANK","bank_id":"DAPIBANK_AE_HSBC","allow_ui_flow":"YES"}`** Then it should be encoded in base64 format and added after slash in the URL. Example after encoding: [*https://openbanking.sand.platform.nymcard.com/dapi\_bank\_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant*](https://openbanking.sand.platform.nymcard.com/dapi_bank_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant)[*/eyJhY3Rpb24iOiJMSU5LX0JBTksiLCJiYW5rX2lkIjoiREFQSUJBTktfQUVfSFNCQyIsImFjY291bnRfbnVtYmVyIjoxNjY4NTEwNzYwMzk4NjIzMjA3MTc5LCJhbGxvd191aV9mbG93IjoiWUVTIn0*=](https://openbanking.dev.platform.nm-1.nymcard.com/dapi_bank_list/de49b937-89c2-4f5a-808f-fe3474961cda%7Ctenant1/eyJhY3Rpb24iOiJMSU5LX0JBTksiLCJiYW5rX2lkIjoiREFQSUJBTktfQUVfSFNCQyIsImFjY291bnRfbnVtYmVyIjoxNjY4NTEwNzYwMzk4NjIzMjA3MTc5LCJhbGxvd191aV9mbG93IjoiWUVTIn0=) **Note** If bank\_id is not received in request then NymCard system will display the bank selection screen:
**4. Embed front-end code** You need to embed the following code on your front end side to capture a systematic response ( success, fail etc.) returned by NymCard system: ``` // “window.addEventListener('message', function(event) { if(event['data']){ console.log("callback Result",event['data']); } });” ``` **5.Success response** In case of success linking of bank, these are the parameters which will be returned by NymCard system in json form: * bank\_id * bank\_name * swift\_code * branch\_address * cool\_down\_period\_unit * cool\_down\_period\_value * action = “LINK\_BANK” (value received in encoded data in action field) * status = “SUCCESS” * allow\_ui\_flow = “YES” OR “NO” depending upon what is received in the request (If value not received or field is missing then value as “YES” will be returned). **6.Failure response** In case of failure the following mandatory and optional parameters will be returned by NymCard System in json form. Mandatory parameters: * action = “LINK\_BANK” * status = “FAILED” * status\_description * allow\_ui\_flow = “YES” OR “NO” depending upon what is received in the request (If value not received or field is missing then value as “YES” will be returned). Optional parameters: * status\_reason * bank\_id = this value received from encoded data in field “bank\_id” ### **“Transfer funds” scenario** Using this flow you can go straight to the fund transfer step. To transfer funds from your bank account to your NymCard card account, take the following steps: **1.Generate token** Generate a token using the “Create temporary user token” API. In this API you need to pass your NymCard account ID, and you will receive the token itself and timestamp, which indicates when this token will expire. Expiration time is 30 minutes. Here you can find request sample:
POST /orders/token **`{`** **`"account_id": "e6b500c7-b37b-46cf-baae-e1b4f43e8749"`** **`}`**
Here you can find response sample:
Response sample **`{`** **`"token": "42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant",`** **`"expire_at": "2012-05-04T19:42:32.987Z"`** **`}`**
**2.Add token the URL** Go to the following widget URL (**) and add this token at the end of the URL after slash. Example: [*https://openbanking.sand.platform.nymcard.com/dapi\_bank\_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant*](https://openbanking.sand.platform.nymcard.com/dapi_bank_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant) **3.Add transfer fund parameters the URL** Now you have to add specific parameters at the end of the URL after slash. Necessary parameters: * "action" ( value :"TRANSFER\_FUNDS") * "bank\_id" (please note that its not open ended value, there are specific IDs for each bank provided by open banking payment gateway and the value should be according to it) * "account\_number" (It can be either account number or IBAN) * "amount" * "allow\_ui\_flow" (values "YES" or "NO". If "NO" is selected, then it is recommended for you to close the widget on your front-end side after receiving the callback from NymCard; if "YES" is selected, then you are recommended not to close the widget after receiving the callback from NymCard). However it's up-to you whether to close the widget or not depending upon the UI flow on client FE side. You should form the json message like this: > **`{"action":"TRANSFER_FUNDS","bank_id":"DAPIBANK_AE_HSBC","amount":"10","account_number":"1668510760398623207179","allow_ui_flow":"YES"}`** Then it should be encoded in base64 format and added after slash in the URL. Example after encoding: [*https://openbanking.sand.platform.nymcard.com/dapi\_bank\_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant*](https://openbanking.sand.platform.nymcard.com/dapi_bank_list/42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant)[*/*](https://openbanking.dev.platform.nm-1.nymcard.com/dapi_bank_list/de49b937-89c2-4f5a-808f-fe3474961cda%7Ctenant1/eyJhY3Rpb24iOiJMSU5LX0JBTksiLCJiYW5rX2lkIjoiREFQSUJBTktfQUVfSFNCQyIsImFjY291bnRfbnVtYmVyIjoxNjY4NTEwNzYwMzk4NjIzMjA3MTc5LCJhbGxvd191aV9mbG93IjoiWUVTIn0=)[*eyJhY3Rpb24iOiJUUkFOU0ZFUl9GVU5EUyIsImJhbmtfaWQiOiJEQVBJQkFOS19BRV9IU0JDIiwiYW1vdW50IjoiMTAiLCJhY2NvdW50X251bWJlciI6MTY2ODUxMDc2MDM5ODYyMzIwNzE3OSwiYWxsb3dfdWlfZmxvdyI6IllFUyJ9*](https://openbanking.dev.platform.nm-1.nymcard.com/dapi_bank_list/de49b937-89c2-4f5a-808f-fe3474961cda%7Ctenant1/eyJhY3Rpb24iOiJUUkFOU0ZFUl9GVU5EUyIsImJhbmtfaWQiOiJEQVBJQkFOS19BRV9IU0JDIiwiYW1vdW50IjoiMTAiLCJhY2NvdW50X251bWJlciI6MTY2ODUxMDc2MDM5ODYyMzIwNzE3OSwiYWxsb3dfdWlfZmxvdyI6IllFUyJ9) **Note** As transfer funds flow consists of several widget screens so NymCard will bypass the screens depending upon the availability of information in the request received. For example: In case action = TRANSFER\_FUNDS, ‘bank\_id’ and ‘account\_number’ and ‘amount’ fields are available in request along with valid values, then direct transfer screen will appear in read only mode; ![](https://lh3.googleusercontent.com/tyIEMGE5LCsOEMKoW7nhhLLtSt2a484_Uxr_PrRUB3nllydVwX-v3atBaP9E_amz4huSKSJZVv8lFaxs08qNupz_ze-rGAyvNQBR0VcEAvG13LGyrLUxdlkaiyRE0mi4FcLccVxmLgaJF049RX4VwSlZ5C3zEZpErXiqWmDTnvFpLUD7ZKeYOCSrDcpLaw)
In case action = TRANSFER\_FUNDS, ‘bank\_id’ and ‘account\_number’ are available in request along with valid values, then direct transfer screen will appear, however ‘amount’ field will be enabled to capture the amount: ![](https://lh3.googleusercontent.com/if2QG3EeecorAseXZXsSZ7vLpHUvuYg3g0_NqnGZEEmr-HRagdT8YIWWtu5VmIhzeBvGf7GADTQZjJ6yDH2aIsLGOkCdfGDl0p8QNjFU1P8lmOSNYTkRQpMRUJ_wJbj6iSb-1zXnzihsACZ8NDai9V-4pOr19xUsefVMBt0r5jtC38so8kNC3FlOJpSlkw)
In case action = TRANSFER\_FUNDS, and only ‘bank\_id’ available in request along with valid value, then select bank account screen will appear:
**4. Embed front-end code** You need to embed the following code on your front end side to capture a systematic response ( success, fail etc.) returned by NymCard system: ``` // “window.addEventListener('message', function(event) { if(event['data']){ console.log("callback Result",event['data']); } });” ``` **5.Success response** In case of success linking of bank, these are the parameters which will be returned: * bank\_id * bank\_name * account\_number * iban * account\_name * currency * type * amount * note * transaction\_id (it is transactionID returned by NymCard) * reference\_number (it is field “reference” returned by external open banking system) * action = “TRANSFER\_FUNDS” * status = “SUCCESS” . **Note** - please refer only to this specific ‘status’ field in the 'result' structure, which you can see on the sample screenshot below:
* allow\_ui\_flow = “YES” OR “NO” (value received in encoded data field “allow\_ui\_flow“. If value not received or field is missing then value as “YES”).
**6.Failure response** In case of failure the following mandatory and optional parameters will be returned. Mandatory parameters: * action = “TRANSFER\_FUNDS” * status = “FAILED” * status\_description * allow\_ui\_flow Optional parameters: * status\_reason * bank\_id - this value received from encoded data in the field “bank\_id”. * account\_number - this value received from encoded data in the field “account\_number”. * iban - (will be returned by NymCard if information is available) * amount - this value received from encoded data in field “amount”. # Lean API flow LEAN is a payment gateway service provider in the UAE that supports bank transfers from one bank account to another bank account. NymCard is now offering a new feature for loading funds into the card account of the cardholder using direct integration between the fintech and LEAN. This new capability will allow you to build your own user experience for the loading funds feature with other capabilities offered by LEAN to the clients. Below you can find a HOLD flow. Take the following steps: 1. Generate token Generate a token using the “[Generate external token](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/createAccountToken)” API. In this API you need to pass your NymCard account ID and pass "LEAN" channel. You will receive the token itself and timestamp, which indicates when this token will expire. Expiration time is 60 minutes. Here you can find request sample:
POST /accounts/{id}:token **`{`** **`"channel": "LEAN"`** **`}`**
Here you can find response sample:
Response sample **`{`** **`"token": "mn7-RjV04loSfUyueaekjkDrKhrdP1JzQqQa3cchimH8JaLjaVtBNHqKZYezbfphEXBjd8ehwPZKr4C1PPy46w==",`** **`"expiry": 3600`** **`}`**
2. Load Account Funds with Token API: \[HOLD] Upon performing “HOLD”, the amount will be set to hold for the prefunded (pool) account and no funds will be credited to the cardholder account yet. Perform the following API: LEAN HOLD request: ``` curl --location 'https://api.qa.platform.nm-1.nymcard.com/internal/v1/accounts:loadFunds' \ --header 'X-Nymos-Idempotency-Key: sed0083' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json;charset=UTF-8' \ --header 'apikey: tenant2-5aade201-368d-4bde-b194-21c296e7e75c' \ --data '{ "channel": "LEAN", "type": "HOLD", "token": "mn7-RjV04loSfUyueaekjkDrKhrdP1JzQqQa3cchimH8JaLjaVtBNHqKZYezbfphEXBjd8ehwPZKr4C1PPy46w==", "amount": 15, "dry_run": false }' ``` You will get the following response: ``` { "reference_number": "AHSA4050110433X" } ``` 3. Also you will receive the following webhook: ``` { "event": "TRANSACTION", "card_transaction": { "id": "2fd14380-a687-45cf-810a-c7644a752b81", "transaction_timestamp": "2024-02-19T11:04:33.422Z", "message_type": "API", "transaction_type": "WALLET_TRANSFER", "transaction_description": "Wallet Transfer", "user_id": "asiddiqui_27_11_23_04", "account_id1": "Bussines_account_QA_29DEC23_003", "card_product1": "MUHAY TESTING CP 29DEC23_0003", "account_id2": "cbeeea69-658f-4b9c-87ce-b342dfec5e0c", "card_product2": "bulk issuance product", "rrn": "4050110433rL", "reference_number": "AHSA4050110433X", "transaction_amount": 15, "transaction_currency": "AED", "fee_amount": 0, "fee_details": [], "status_code": "0000", "transfer_id": "2fd14380-a687-45cf-810a-c7644a752b81", "reversal_count": 0, "clearing_count": 0, "sender_user_id": "Business_Muhay_QA_User_03", "source_channel": "LEAN", "type": "HOLD", "incremental_transaction": false, "is_cancelled": "NO", "is_cash_advance": false } } ``` 4. Once you receive a successful response from NymCard for payment intent, you need to pass the details to LEAN along with token. You also have to add external reference number for reconciliation purposes. {% hint style="info" %} For POST/RELEASE scenarios, please coordinate with LEAN. {% endhint %} # DAPI direct API flow Below you can find 2 flows: * [HOLD - POST flow](#hold-post-flow) * [HOLD - RELEASE flow](#hold-release-flow) ### HOLD - POST flow Take the following steps:\ **1.Generate token** Generate a token using the “[Generate external token](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/createAccountToken)” API. In this API you need to pass your NymCard account ID and pass "DAPI" channel. You will receive the token itself and timestamp, which indicates when this token will expire. Expiration time is 60 minutes. Here you can find request sample:
POST /accounts/{id}:token **`{`** **`"channel": "DAPI"`** **`}`**
Here you can find response sample:
Response sample **`{`** **`"token": "42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant",`** **`"expiry": 3600`** **`}`**
**2.Load Account Funds with Token API: Request \[HOLD]** Upon performing “HOLD”, the amount will be set to hold for the prefunded (pool) account and no funds will be credited to the cardholder account yet. Perform the following API: ``` curl --location 'api.dev.platform.nm-1.nymcard.com/internal/v1/accounts:loadFunds' \ --header 'X-Nymos-Idempotency-Key: ida957795' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json;charset=UTF-8' \ --header 'apikey: tenant1-key' \ --data '{ "channel": "DAPI", "type": "HOLD", "token": "ZOJal3wB5A5FzyQAwOmrdntn-gt6Od1-GQaPVbX0Id9E1UTCUbMTUUOIAhnQbDhEhwGppg88FgJgmBepZCNGnA==", "amount": 19, "dry_run": false }' ``` You will get the following response: ``` { "reference_number": "SUNY3165110617H" } ``` Also you will receive the following **webhook**: ``` { "event": "TRANSACTION", "card_transaction": { "id": "5ec9f345-fd8d-403b-9952-0632e01ffb4c", "transaction_timestamp": "2023-06-14T11:06:17.769Z", "message_type": "API", "transaction_type": "WALLET_TRANSFER", "transaction_description": "Wallet Transfer", "user_id": "MuhayUdDinTestForSashi_14JUNE23_00", "account_id1": "77779999999999999271", "card_product1": "Description of the cardproducthk105", "account_id2": "MUHAYTestingAcct14JUNE_00", "card_product2": "MUHAY TESTING CP 12MAY23_01", "rrn": "3165110618GU", "reference_number": "SUNY3165110617H", "transaction_amount": 19, "transaction_currency": "AED", "fee_amount": 0, "fee_details": [], "status_code": "0000", "transfer_id": "5ec9f345-fd8d-403b-9952-0632e01ffb4c", "reversal_count": 0, "clearing_count": 0, "sender_user_id": "hkbusiness36", "source_channel": "DAPI", "type": "HOLD" } } ``` **3.Load Account Funds with Token API: Request \[POST]** Upon performing “POST”, the amount will be debited from the prefunded (pool) account and credited to the cardholder account. Perform the following API: ``` curl --location 'api.dev.platform.nm-1.nymcard.com/internal/v1/accounts:loadFunds' \ --header 'X-Nymos-Idempotency-Key: ida957798' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json;charset=UTF-8' \ --header 'apikey: tenant1-key' \ --data '{ "channel": "DAPI", "type": "POST", "token": "ZOJal3wB5A5FzyQAwOmrdntn-gt6Od1-GQaPVbX0Id9E1UTCUbMTUUOIAhnQbDhEhwGppg88FgJgmBepZCNGnA==", "amount": 19, "dry_run": false, "external_reference_number": "MUHAY04" }' ``` You will get the following response: ``` { "reference_number": "SUNY3165110617H" } ``` **Webhooks** Upon performing “POST”, two webhooks will be received. One is for original transaction and another one is for completion. Webhook 1 ``` { "event": "TRANSACTION", "card_transaction": { "id": "5ec9f345-fd8d-403b-9952-0632e01ffb4c", "transaction_timestamp": "2023-06-14T11:06:17.769Z", "message_type": "API", "transaction_type": "WALLET_TRANSFER", "transaction_description": "Wallet Transfer", "user_id": "MuhayUdDinTestForSashi_14JUNE23_00", "account_id1": "77779999999999999271", "card_product1": "Description of the cardproducthk105", "account_id2": "MUHAYTestingAcct14JUNE_00", "card_product2": "MUHAY TESTING CP 12MAY23_01", "rrn": "3165110618GU", "reference_number": "SUNY3165110617H", "transaction_amount": 19, "transaction_currency": "AED", "fee_amount": 0, "fee_details": [], "status_code": "0000", "transfer_id": "5ec9f345-fd8d-403b-9952-0632e01ffb4c", "reversal_count": 0, "clearing_count": 1, "sender_user_id": "hkbusiness36", "source_channel": "DAPI", "type": "HOLD" } } ``` Webhook 2 ``` { "event": "TRANSACTION", "card_transaction": { "id": "ef21bf40-6127-4430-a8c5-bdece20b776a", "transaction_timestamp": "2023-06-14T11:11:32.938Z", "parent_transaction_id": "5ec9f345-fd8d-403b-9952-0632e01ffb4c", "message_type": "API", "transaction_type": "WALLET_TRANSFER", "transaction_description": "Wallet Transfer", "user_id": "MuhayUdDinTestForSashi_14JUNE23_00", "account_id1": "77779999999999999271", "card_product1": "Description of the cardproducthk105", "account_id2": "MUHAYTestingAcct14JUNE_00", "card_product2": "MUHAY TESTING CP 12MAY23_01", "rrn": "3165111133GE", "reference_number": "SUNY3165110617H", "transaction_amount": 19, "transaction_currency": "AED", "fee_amount": 0, "fee_details": [], "status_code": "0000", "transfer_id": "ef21bf40-6127-4430-a8c5-bdece20b776a", "settlement_status": "MATCHED", "reversal_count": 0, "clearing_count": 0, "sender_user_id": "hkbusiness36", "source_channel": "DAPI", "external_reference_number": "MUHAY04", "type": "POST" } } ``` ### HOLD - RELEASE flow Take the following steps:\ \ **1.Generate token** Generate a token using the “[Generate external token](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/createAccountToken)” API. In this API you need to pass your NymCard account ID and pass "DAPI" channel. You will receive the token itself and timestamp, which indicates when this token will expire. Expiration time is 60 minutes. Here you can find request sample:
POST /accounts/{id}:token **`{`** **`"channel": "DAPI"`** **`}`**
Here you can find response sample:
Response sample **`{`** **`"token": "42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant",`** **`"expiry": 3600`** **`}`**
**2.Load Account Funds with Token API: Request \[HOLD]** Upon performing “HOLD”, the amount will be set to hold for the prefunded (pool) account and no funds will be credited to the cardholder account yet. Perform the following API: ``` curl --location 'api.dev.platform.nm-1.nymcard.com/internal/v1/accounts:loadFunds' \ --header 'X-Nymos-Idempotency-Key: ida957795' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json;charset=UTF-8' \ --header 'apikey: tenant1-key' \ --data '{ "channel": "DAPI", "type": "HOLD", "token": "ZOJal3wB5A5FzyQAwOmrdntn-gt6Od1-GQaPVbX0Id9E1UTCUbMTUUOIAhnQbDhEhwGppg88FgJgmBepZCNGnA==", "amount": 19, "dry_run": false }' ``` You will get the following response: ``` { "reference_number": "SUNY3165112536b" } ``` Also you will receive the following **webhook**: ``` { "event": "TRANSACTION", "card_transaction": { "id": "882863d4-aff6-48e2-aa4c-12d1e9591327", "transaction_timestamp": "2023-06-14T11:25:36.913Z", "message_type": "API", "transaction_type": "WALLET_TRANSFER", "transaction_description": "Wallet Transfer", "user_id": "MuhayUdDinTestForSashi_14JUNE23_00", "account_id1": "77779999999999999271", "card_product1": "Description of the cardproducthk105", "account_id2": "MUHAYTestingAcct14JUNE_00", "card_product2": "MUHAY TESTING CP 12MAY23_01", "rrn": "3165112537Lm", "reference_number": "SUNY3165112536b", "transaction_amount": 23, "transaction_currency": "AED", "fee_amount": 0, "fee_details": [], "status_code": "0000", "transfer_id": "882863d4-aff6-48e2-aa4c-12d1e9591327", "reversal_count": 0, "clearing_count": 0, "sender_user_id": "hkbusiness36", "source_channel": "DAPI", "type": "HOLD" } } ``` **3.Load Account Funds with Token API: Request \[RELEASE]** Upon performing “RELEASE”, amount will be released back into the prefunded (pool) account. {% hint style="info" %} Note, that we can not perform “RELEASE“ on a transaction which is already completed. {% endhint %} Perform the following API: ``` curl --location 'api.dev.platform.nm-1.nymcard.com/internal/v1/accounts:loadFunds' \ --header 'X-Nymos-Idempotency-Key: ida957802' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json;charset=UTF-8' \ --header 'apikey: tenant1-key' \ --data '{ "channel": "DAPI", "type": "RELEASE", "token": "_qvvrgNwDuu077cXSXcOXn8ggowqRrsucG4-jhaE_zQRFQ5HH3m3tiro1kU73Gvsuf-0Dts5VkTLUYUysHegvg==", "amount": 23, "dry_run": false, "error_description" : "Test Error Description 02 Muhay" }' ``` You will get the following response: ``` { "reference_number": "SUNY3165112536b" } ``` **Webhooks** On performing “RELEASE”, two webhooks will be received. One is for original transaction and another one is for reversal transaction. Webhook 1 ``` { "event": "TRANSACTION", "card_transaction": { "id": "882863d4-aff6-48e2-aa4c-12d1e9591327", "transaction_timestamp": "2023-06-14T11:25:36.913Z", "message_type": "API", "transaction_type": "WALLET_TRANSFER", "transaction_description": "Wallet Transfer", "user_id": "MuhayUdDinTestForSashi_14JUNE23_00", "account_id1": "77779999999999999271", "card_product1": "Description of the cardproducthk105", "account_id2": "MUHAYTestingAcct14JUNE_00", "card_product2": "MUHAY TESTING CP 12MAY23_01", "rrn": "3165112537Lm", "reference_number": "SUNY3165112536b", "transaction_amount": 23, "transaction_currency": "AED", "fee_amount": 0, "fee_details": [], "status_code": "0000", "transfer_id": "882863d4-aff6-48e2-aa4c-12d1e9591327", "reversal_count": 1, "clearing_count": 0, "sender_user_id": "hkbusiness36", "source_channel": "DAPI", "type": "HOLD" } } ``` Webhook 2 ``` { "event": "TRANSACTION", "card_transaction": { "id": "493be65a-17b3-4e52-a91e-c84d432ccc53", "transaction_timestamp": "2023-06-14T11:27:06.718Z", "parent_transaction_id": "882863d4-aff6-48e2-aa4c-12d1e9591327", "message_type": "API", "transaction_type": "WALLET_TRANSFER", "transaction_description": "Wallet Transfer", "user_id": "MuhayUdDinTestForSashi_14JUNE23_00", "account_id1": "77779999999999999271", "card_product1": "Description of the cardproducthk105", "account_id2": "MUHAYTestingAcct14JUNE_00", "card_product2": "MUHAY TESTING CP 12MAY23_01", "rrn": "3165112706Od", "reference_number": "SUNY3165112536b", "transaction_amount": 23, "transaction_currency": "AED", "fee_amount": 0, "fee_details": [], "status_code": "0000", "transfer_id": "493be65a-17b3-4e52-a91e-c84d432ccc53", "reversal_count": 0, "clearing_count": 0, "sender_user_id": "hkbusiness36", "source_channel": "DAPI", "type": "RELEASE" } } ``` # Transfers ### Introduction nCore platform support fund transfer from one account to another account. Using this fund transfer method you can move funds between your own account as well as to any other user’s account which is also known as a peer to peer (P2P) transfer. The fund transfer method has a real time effect which means that the funds will be debited from the sender account and immediately credited to the recipient account. #### **Account transfers pre-requisite** Following are the prerequisites for funds sender and funds receiver accounts. For further information regarding card products, please refer to section [**Product management**](/get-started/product-management). ### Transfer funds You can transfer funds from one account to another account by sending a POST request to /transfers endpoint as given below.
POST /transfers **`{`**\ ` `**`"sender_account_id": "bc121529-e6e9-45f1-b820-8c46ce7f005a",`**\ ` `**`"recipient_account_id": "39dbff34-5505-4181-9e81-727b71e72186",`**\ ` `**`"amount": 100,`**\ ` `**`"currency": "USD",`**\ ` `**`"notes": "Account transfer for 100 USD",`**\ ` `**`"dry_run": false`**\ **`}`**
### Retrieve transfers The nCore platform offers the following retrieval options for transfers. **Retrieve all transfers** You can retrieve all existing transfers by sending a **GET** request to **/transfers** endpoint shown below. > [**GET /transfers**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fund-Transfers/operation/getTransfers) **Retrieve a list of transfers by filters** You can retrieve transfers by using the applicable filters given below. | **Filter parameter** | **Description** | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | sender\_account\_id | Sender account Identifier. You can use sender account id to get all the account transfers performed by a user. | | recipient\_account\_id | Recipient account Identifier. You can use the receiver's account id to get all the account transfers received by a user. | | transfer\_date\_time\_start | Date and time of a transfer, starting with which you want to filter a list of transfers. | | transfer\_date\_time\_end | Date and time of a transfer, ending with which you want to filter a list of transfers. | {% hint style="info" %} You can use the above filter parameters in combination as well to get a precise list of transfers. {% endhint %}
GET /transfers **`{`**\ ` `**`"transaction_id": "123456789012",`**\ ` `**`"sender_account_id": "bc121529-e6e9-45f1-b820-8c46ce7f005a",`**\ ` `**`"recipient_account_id": "39dbff34-5505-4181-9e81-727b71e72186",`**\ ` `**`"transfer_date_time_start": “10012021",`**\ ` `**`“transfer_date_time_end”: “11012021”`**\ **`}`**
**Retrieve a specific transfer** You can retrieve a specific transfer by sending a **GET** request to **/transfers/{id}** endpoint, where id is the transfer ID. > [**GET /transfers/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fund-Transfers/operation/getTransfer) ### Transfer between user's OWN account/wallet We've implemented new enums for the 'transfer\_type' parameter, enabling the system to differentiate whether a transfer occurs between the user's OWN account/wallet or not. When transferring between the user's own accounts, the transfer\_type will indicate 'OWN' (e.g. CHA2CHAOWN). Here are the various account types and their meanings: * CHA: Cardholder Account * CHCA: Cardholder Child Account * AMA: Agent Master Account * AMCA: Agent Master Child Account * CHMCA: Cardholder Master Child Account * CHMA: Cardholder Master Account Furthermore, we've added a new 'transfer\_type' field to the TRANSACTIONS [webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook).
# Western Union APIs We've added several [APIs](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Western-Union) to API catalog, which are used for integration with Wester Union. {% hint style="info" %} Note, that these APIs are for Sandbox & Staging testing. {% endhint %} Below you can find detailed information regarding the following APIs: * ["Get delivery option template"](#get-delivery-option-template-api) * ["Get cascade list values"](#get-cascade-list-values-api) ### "Get delivery option template" API The "**description**" field in the response of this [API](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Western-Union/operation/getDeliveryOptionTemplate) can be divided in several following fields:
For example, the **AccountName** field is returned with the following description: {% code overflow="wrap" %} ``` receiver.bank_account.account_holder;Account Name; 35; 1563; Account Name required; 0; UPRSTRING; NL; 35; ``` {% endcode %} The number of semicolon (;) will identify you the number of the fields. The raw structure can be considered as follows for the above description: {% code overflow="wrap" %} ``` Field1;Field2; Field3; Field4; Field5; Field6; Field7; Field8; Field9;< /DESCRIPTION> ``` {% endcode %} The description of the delimiter can be defined as follows: {% code overflow="wrap" %} ``` Xpath;label text; data length; field ID; is required(y/n); N/A; field type; new line; count of records for combo ``` {% endcode %} The rest of the details will remain same like AIS. {% hint style="info" %} Important Note: The presence of “NL” value in Field 7 denotes that the next record in the record-set is a new APN field. If this field is blank, partner needs to process and display the next records in the record-set till the next “NL” will be read as 1 APN field. {% endhint %} ### "Get cascade list values" API The **"firstLevelValue" & "secondLevelValue"** fields in this [API](https://nymcard.com/docs/api#tag/Western-Union/operation/getCascadeList) can be divided in several fields. It depends on the region. Below you can find an example (for Bangladesh):
# Checkout widget ### Introduction Checkout is a payment gateway designed for processing debit and credit card payments online, offering access to local payment methods through global payment platforms. NymCard has integrated with Checkout, enabling users to transfer funds from their debit or credit cards to their NymCard wallet. This document describes the **Checkout widget**, which allows non-PCI-compliant customers to securely collect and submit card details. It supports the following functionalities: * Users can manually input the card number and other required details. * The widget can read card details from an image for seamless data entry.
### Checkout widget usage In order to open the Checkout widget, take the following steps: 1. Perform “[Create LUT](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Orders/operation/createLut)” API. LUT is a limited usage token, which expires after 10 minutes after being created. Each LUT will work for 10 requests. For creating LUT you need to fill the following parameters: * 'source\_id' - put "default\_pci\_source" here * ‘operation’ - put "CHECKOUT\_TOKEN" here Below there is an example of request: ``` curl -X POST "https://{env_url}/v1/orders/users/{id}:createLut" \ -H "Content-Type: application/json" \ --header "ApiKey: tenant1-key" \ -d '{ "source_id": "default_pci_source", "operation": "CHECKOUT_TOKEN" }' ``` Response sample: ``` {"token":"SMJXdC/sCRogr0K7fuMz0/6QFLBDLglA2rCeZAPgS9Rb04L/BW3mYXkY2L4nab8b"} ``` 2\. Encode token together with ‘**cardId**’/‘**accountId**’ and '**userId'**, values using Base64 encryption format. Below you can find an example of data which should be encoded: ``` { "token":"4hNuBSoaezq+KygTkjjihvLtzQMcNZc/pvQbTDd/bXJDDqi0wHli32aPqUd6mcnf", "userId":"Sunny_25APRIL_DevEnv_0000", "cardId":"muhaycheckoutAEDCardAccount07MAY25"} ``` 3\. Take the following URL and add base64 encrypted token to it. Below you can see an example: 
https://{widget_url}/cards/eyAidG9rZW4iOiJJTjlmVlpuQmlxV1dvcHgvbmlIWGo5Qi9mRnk4ckJyamYvTC9WYkR5MkJQMnArcWNkTnpUMGZlRHp5R2grZHZCIiwidXNlcklkIjoiU3VubnlfMjVBUFJJTF9EZXZFbnZfMDAwMCIsImNhcmRJZCI6Im11aGF5Y2hlY2tvdXRBRURDYXJkQWNjb3VudDA3TUFZMjUifQ==
4\. The mobile app will need to create an iframe to display the widget inside a native view. Below you can find an example code (please adapt it to your own standards/code): **For iOS (Swift/Objective-C):** ``` let webView = WKWebView(frame: CGRect(x: 0, y: 0, width: self.view.frame.size.width, height: self.view.frame.size.height)) let url = URL(string: "https://your-widget-url.com")! let request = URLRequest(url: url) webView.load(request) self.view.addSubview(webView) ``` **For Android (Java/Kotlin):** ``` WebView webView = new WebView(this); webView.loadUrl("https://your-widget-url.com"); setContentView(webView); ``` 5\. The checkout widget will be loaded. Below you can find two flows for performing checkout payments: * Using existing saved card details * Using the card details of a newly-created card ### Loading Funds from already added card Take the following steps: 1. Select the Receiver Card and call the checkout widget. 2. Widget will display the list of already added cards. Select the necessary card and click **Confirm**: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXfVKwZ329Y9QwtlrBUVELVysCcWP6Pz_bF4DLlFOT-JNczLAkkUZJ1L79TzsHX6rmqo8hkHetype4wwZIFcuJuNKzMPl1T2PtuE0q8fojWch0bPVNeFeyGnuVWBKHWt6JuvabUu8ro93Z4yCqsmbPI?key=t2KmKFW9-6IODDsl2uPhAA) 3. Enter money amount which you want to transfer, select the way how the fee will be deducted (**Deduct from amount** or **Charge from the card**) and click **Pay Now**: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdRtd6ifLR0PDvSo5xOKpI7zHvGjsMAtbqooqp6tATUAqdDEoivmZOt1tXFEat-iGrASJYNybd77ohgY2e7ESsiOiA25_BmYeoDf0g5IGPyB5VJYy2TnDcHOnZeKJiRimtnthYoTVRO1FV0balJtg?key=t2KmKFW9-6IODDsl2uPhAA) 4. If 3DS setting is set as true, then you will get screen where you can enter the OTP code: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXe1BaNL4u1mafRAMgoFfibkNq-WVUCj1KwGR5aPJt2qe-FVPWEEXyJnDT7rn0dReXw0hxEO3Rn8ivIMImnqDK4mvP_dyAPVjSg5808e8NXnzMwNNeeMP_WlSGRPtcW9BJFYkNRH074V-QOa9zLP96E?key=t2KmKFW9-6IODDsl2uPhAA)
5. After that you will receive a message about a successful operation. ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdSlYqmOCqlmSLQkj_RKkjqTbLNXDVZeY-0TvFPLmdGI7-ikQ-xTEZsspUNiI0r-PE7SH9GHSUkWbMBcCxzp8A-1rg-mmFPfR3JpSoDts8qm9u_AhujthbKZjDiZK7B-jZIiLwFtgsMwAw6trkw9A?key=t2KmKFW9-6IODDsl2uPhAA) ### Loading Funds using new card Take the following steps: 1. Select the Receiver Card and call the checkout widget. 2. Widget will display the list of already added cards together with **Add a new card** button. Click on it: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcW0VNsAirWJdQjnvIuWcSaEnbsnCBDU3IBHrEmcm2zFLx-SYcvlN3zI1FaINZ65YN1ePvh9DY8IezLCAyDT8dNKS2rLzdqCOGDRYcNr0-sCPCqMdrOhWLl-zAg2DBsWzxF_4-U95swAP47XTUF5c0?key=t2KmKFW9-6IODDsl2uPhAA) 3. Enter such card details, as Card number, expiry, CVV, cardholder name. Activate **Save card details** toggle button to save details for further payments. Click **Confirm** button: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcFZ-AxLenbw0KypklJuQd3K9NuNxevVO529bklWq3UsoghGxyQoYuA-MxXNvjB0fHOV5gEu81kFWEGISuemoxfLE5r4pSsReTty2F6bl3mbcdxQwaE573iePdbwhZFSno51Pvg3tWv4YAzKhyEFQ?key=t2KmKFW9-6IODDsl2uPhAA)
4. Enter money amount which you want to transfer, select the way how the fee will be deducted (**Deduct from amount** or **Charge from the card**) and click **Pay now**: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXfEt3V9eCm32xqkeHm8Jc9hfGMchqsrgYQ_Ibd-evV5Xu4JSiD64gUIsAM8tnLvtyVehx9He6O235FFIixTGuSCmO5y0NLGlwEWRtFx8Cmwe6J3mAVHFH6PfKMSLevPAy3LhV_2GU9yXq_j-6-cWFs?key=t2KmKFW9-6IODDsl2uPhAA) 5. If 3DS setting is set as true, then you will get screen where you can enter the OTP code: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXe1BaNL4u1mafRAMgoFfibkNq-WVUCj1KwGR5aPJt2qe-FVPWEEXyJnDT7rn0dReXw0hxEO3Rn8ivIMImnqDK4mvP_dyAPVjSg5808e8NXnzMwNNeeMP_WlSGRPtcW9BJFYkNRH074V-QOa9zLP96E?key=t2KmKFW9-6IODDsl2uPhAA) 6. After that you will receive a message about a successful operation. ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXe46hLpZhUjoUffsM5o23a-UqcUdedI5tMIW0j2mWr-OWXb73sYaYZYKZKEf6VKFFB3VbGUpEhgyGNp39nvyHIjQFLkOK-Ai6ASlqNbR5abPUlfcRZ9GjD6VbbizHEc1kbpxP3TfWBI9XXKxtQyV00?key=t2KmKFW9-6IODDsl2uPhAA) ### Deleting already added card If you want to delete already added card, take the following steps: 1. Select the Receiver Card and call the checkout widget. 2. Widget will display the list of already added cards. Click on the **Bin** icon next to the card which you want to delete: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXelPDv7L4f2ADyiRFoz1t4PJYS-qYZM8EyMZWdv6zpxuP75OVuPKTF3eJ39HlzZ1EUPbh7CfZR6q7jInVk0BGE2X5VuepcE88OvL1t2QKF5yT2J8OHGzPOPGxuKidNHfXLXV75N7SBQ7v3X1oN0pdY?key=t2KmKFW9-6IODDsl2uPhAA)
3. Confirm the deletion by clicking the **Remove** button: ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdkn37vy4XV7fBPCJjjEd6oMNAch35luDtQE2PBdfg4WnDPPXMdJ2I9ozWJHId0PJ7kpVD5ZLRkYNYKfNJ1_zr9QzKUeY9rk8d_xloHN7cT9TagKt-W7PV79Dy22ryo449Y_e6X0kidX4V30SB0Ew?key=t2KmKFW9-6IODDsl2uPhAA) After that you will receive a message about a successful deletion. # Load Processing We understand the importance of timely fund transfers and want to clarify how incoming payments are processed in our bank accounts, including potential delays due to regulatory checks. Below is a detailed breakdown of the process: * [How Funds Are Received in Our Bank Accounts](#how-funds-are-received-in-our-bank-accounts) * [Possible Delays in Fund Receipts](#possible-delays-in-fund-receipts) * [How NymCard Handles Delays](#how-nymcard-handles-delays) * [Best Practices for Smooth Transactions](#best-practices-for-smooth-transactions) ### How Funds Are Received in Our Bank Accounts #### A. Transfer Mechanisms in the UAE In the UAE, fund transfers are processed through the UAE Funds Transfer System (UAEFTS), operated by the Central Bank of the UAE (CBUAE). The system includes: * Immediate Payment Instruction (IPI): Used for instant, real-time transfers (urgent or instant transfers). * Intra-Lender Facility for Investments (Intra LFI): Used for interbank management, typically for larger or bulk transactions within the same bank. #### B. Clearing & Settlement Process Initiation by Sender: * The remitting bank sends a payment instruction via UAEFTS. * For instant payments (IPI), funds are credited in real-time (subject to beneficiary bank checks). * For bulk or high-value transactions, clearing may take 1-2 business days (depending on cut-off times). Beneficiary Bank Processing: * Our bank (NymCard’s partner bank) receives the payment request. * The funds are credited to our account after verification. Final Settlement: * CBUAE ensures final settlement between banks at predefined cycles (usually same-day or next business day). #### C. VIBAN (Virtual IBAN) SME Load Process NymCard utilizes an automated vIBAN SME load process, improving fund transfer management for SME clients. This system ensures efficient processing and adherence to regulatory requirements, minimizing manual intervention while maximizing security and transparency. 1\. Automated Fund Processing: The system streamlines the entire fund transfer journey from initial receipt to final loading, reducing processing time with high accuracy and security. 2\. Secure Source-IBAN Management: An advanced API-based Source-IBAN administration system enables full IBAN lifecycle management, including adding and removing SME/IBAN associations. Every IBAN or account update requires supporting documentation and review by our compliance team. 3\. Real-time Notifications: Webhooks allow clients to track funds and maintain complete visibility over incoming transfers. 4\. Batch Timings for VIBAN Loads: * Statement Processing: Mashreq's account statements are downloaded and processed automatically via API every hour. * Fund Loading: Approximately half an hour after the statement extraction, the system proceeds with the fund load once validation is complete. This process involves a three-tier validation: * Source-IBAN Validation: Matches the sender's IBAN with registered records. * Name Validation: If IBAN validation fails, the system checks the sender's name against the identified SME's list of names, using configurable fuzzy logic. * Manual Validation: If both automated checks fail, the transfer is placed in a queue for manual processing by the Operations team. For validated transfers, the SME account is credited, and a notification is triggered. ### Possible Delays in Fund Receipts While most transfers are processed smoothly, delays may occur due to: *Request for Information (RFI) by Beneficiary Bank* * If a transaction appears suspicious (e.g., unusual amount, mismatched details), the beneficiary bank may raise an RFI (Request for Information). * Impact: * The incoming payment is placed on hold until the remitting bank provides clarification. * NymCard is notified of the RFI, and we work with the beneficiary bank to resolve it. * Delays typically range from 24 to 72 hours, depending on response time. \ *Cut-off Times & Clearing Cycles* * Same-Day Credits: Transfers initiated before the UAEFTS cut-off time (usually 2:00 PM GST) are processed the same day. * Next-Day Credits: Transactions after cut-off or on weekends/holidays are processed the next business day. \ *Bank Holidays & System Downtime* * Delays may occur during UAE public holidays or due to UAEFTS/CBUAE system maintenance. ### How NymCard Handles Delays * We proactively monitor incoming transactions and respond to RFIs promptly. * If a delay occurs, we will: * Notify you (if the delay is on our end). * Escalate with the beneficiary bank (if the delay is due to an RFI or compliance check). * Provide updates until resolution. * For unreported delays: * Weekday transfers: If a delay exceeds 24 hours from initiation time (during business days) without updates, raise a Jira ticket. * Weekend/holiday transfers: Wait until Monday’s first batch processing (or next business day after holidays) before escalating via Jira. ### Best Practices for Smooth Transactions To minimize delays: ✅ Ensure sender details (account name, IBAN, reference) match exactly. ✅ Avoid initiating large transfers near cut-off times or holidays. ✅ Avoid making cash or cheque deposits to the accounts as this channel of funding is not accepted. **Glossary** * Beneficiary Bank: The bank that receives funds on behalf of the beneficiary (in this case, NymCard's partner bank). * Remitting Bank: The bank that sends the funds on behalf of the sender. * Central Bank of the UAE (CBUAE): The monetary authority of the United Arab Emirates, responsible for regulating the financial system. * Clearing: The process of exchanging financial transaction information between financial institutions. * Settlement: The final process where funds are actually transferred between banks to complete a transaction. * IBAN (International Bank Account Number): A standardized international bank account number used for identifying bank accounts across borders. * Request for Information (RFI): A formal request for clarification or additional details regarding a transaction. # Product Management In this section you will find information about card product management, balance limits and velocity limits creation, fee management and authorization controls. Below you can find a product management decision flow: ![](/files/1L7irSlqfa8A1dH7jGwd) # Card product The nCore platform uses the concept of card product that acts as a template to define characteristics of the cards associated to the card product. **Card product settings** The card product offers different settings, these settings allow you to customize the card product as per your business needs. * **Currency settings:** These settings allow you to define the currencies you want to support, the currency in which to settle, the order to use in sweeping the fund, and various controls at currency level. * **Card settings:** These settings help to define attributes like BIN (Bank Identification Number), PAN length, PAN range, card initial status on its creation, and other controls at card level. * **Account settings:** These settings allow you to link cards with the card product’s account and to configure number of cards per account. * **PIN settings:** nCore platform provides you the ability to customize your card PIN settings for attributes like PIN type, PIN length, and number of allowed retries. * **Authorization settings:** It provides you to control you card usage on ATMs, in-store POS terminals, E-Commerce with/without 3DS, fallback transactions, and other transaction use cases. {% hint style="info" %} All these features are defined with the card product, it is mandatory to include a card product when creating a card. {% endhint %} ### Create a card product The card product is created in ‘Inactive’ status. When a card is issued the status of a card product becomes ‘Active’ automatically. You can create a card product as per your business need by sending a **POST** request to **/cardproducts** endpoint as given below.
POST /cardproducts **`{`**\ ` `**`"description": "Some description of the card product",`**\ ` `**`"currency_settings": [`**\ ` `**`{`**\ ` `**`"supported_currency": "USD",`**\ ` `**`"settlement_currency": "USD",`**\ ` `**`"priority": 1`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"card_settings": {`**\ ` `**`"bin": "412345",`**\ ` `**`"pan_range": [`**\ ` `**`{`** **`"start_range": 0,`**\ ` `**`"end_range": 9999999`**\ ` `**`}`**\ ` `**`]`**\ ` `**`}`** **`}`**
### **Retrieve card products** nCore offers two card product retrieval options. ***Retrieve existing card products*** You can retrieve all existing card products by sending a **GET** request to **/cardproducts** endpoint shown below. > [**GET /cardproducts**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/listCardProducts) ***Retrieve a specific card product*** You can retrieve a specific card product by sending a **GET** request to **/cardproducts/{id}** endpoint, where id is the card product id. > [**GET /cardproducts/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/listCardProducts) ### Update a card product You can update a card product by sending a **PUT** request to **/cardproducts/{id}** endpoint as given below. > [**PUT /cardproducts/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/updateCardProduct) {% hint style="warning" %} Once a card product is in ‘Active’ status, certain attributes are not allowed to be modified. {% endhint %} Below you can find the parameters **which cannot be updated** for an ACTIVE/SUSPENDED card product:
Card settingsPIN settingsCurrency settingsAuth settingsAccount settings
BIN'pin_retries' if tenant level setting 'allow_card_product_update_pin_retries' is set to 'false'for base currency,priority=1AllAll
PAN length
PAN ranges (however, new ranges can be added)
soft_expiry_period
create_account_with_card
initial_status_of_physical_card: "INACTIVE", if 'create_account_with_card':false
initial_status_of_virtual_card: "INACTIVE", if 'create_account_with_card':false
### Card renewal We introduced the following parameters in the response of [Card products](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products) APIs under 'card\_settings' parameter: **"allow\_card\_renewal", "renew\_before\_days", "new\_pan\_on\_renewal", "auto\_renewal\_process"**. They are used to renew an existing card so that if a card is about to be expired, a new card can be generated and provided to the cardholder for uninterrupted card services. Impacted APIs: * Create card product * Update card product * Get card product * Get list of card product This enhancement has impact on both existing and new card products. Example: ``` "card_settings": { ... "allow_card_renewal": true, // default = false "renew_before_days": 60, // default = 60 "new_pan_on_renewal": false, // default = false "auto_renewal_process": true // default = false } ``` # Balance limits The balance limit feature in nCore platform enables you to define the maximum and/or minimum limit on the funds an individual account can hold. Balance limit that you define shall be tied with the card product. Balance limit shall become applicable to the accounts associated with the card product. ### Create balance limit You can create a new balance limit as per your requirement by sending a **POST** request to **/balancelimits** endpoint as shown below.
POST /balancelimits **`{`**\ ` `**`"description": "The balance limit – For account",`**\ ` `**`"type": "PER_ACCOUNT",`**\ ` `**`"min_amount": 1500,`**\ ` `**`"max_amount": 1500,`**\ ` `**`"currency": "USD"`**\ **`}`**
### Retrieve balance limits nCore offers two balance limits retrieval options. ***Retrieve all balance limits*** You can retrieve all existing balance limits by sending a **GET** request to **/balancelimits** endpoint shown below. > [**GET /balancelimits** ](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/listBalanceLimits) ***Retrieve a specific balance limit*** You can retrieve a specific balance limit by sending a **GET** request to **/balancelimits/{id}** endpoint, where id is the balance limit id. > [**GET /balancelimits/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getBalanceLimit) ### Update a balance limit You can update a balance limit by sending a **PUT** request to **/balancelimits/{id}** endpoint as shown below. > [**PUT /balancelimits/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/updateBalanceLimit) ### Link balance limit with a card product You can associate a balance limit to your card product by sending a **POST** requests to **/cardproducts/{id}/balancelimits:link** endpoint as shown below. > [**POST /cardproducts/{id}/balancelimits:link**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/linkBalanceLimits) ### Unlink a balance limit from a card product You can unlink a balance limit from a card product by sending a **POST** request to /**cardproducts/{id}/balancelimits:unlink** endpoint as shown below. > [**POST /cardproducts/{id}/balancelimits:unlink** ](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/unlinkBalanceLimits) ### Retrieve linked balance limits You can retrieve all balance limits which are linked with your card product. Send a **GET** request to /**cardproducts/{id}/balancelimits** endpoint as shown below. > [**GET /cardproducts/{id}/balancelimits**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getBalanceLimits) ### Link balance limit to account You can link balance limit to the specific account. Send a **POST** request to **/accounts/{id}/balancelimits:link** endpoint as shown below. > [**POST /accounts/{id}/balancelimits:link**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/linkBalanceLimit) ### **Unl**ink balance limit to account You can unlink balance limit from the specific account. Send a **POST** request to **/accounts/{id}/balancelimits:unlink** endpoint as shown below. > [**POST /accounts/{id}/balancelimits:unlink**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/unlinkBalanceLimit) ### **Get balance limits linked to account** You can get list of balance limits linked to specific account. Send a **GET** request to **/accounts/{id}/balancelimits** endpoint as shown below. > [**GET /accounts/{id}/balancelimits**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getBalanceLimitsByAccountId) # Velocity limits On this page: * [Velocity limits](#velocity-limits) * [Advanced velocity limits](#advanced-velocity-limits) ## Velocity limits Velocity limits can be used to control transaction spending**\***. It defines the aggregated amount and the total number of transactions**\*\*** which can be performed by a cardholder within a specified time**\*\*\***. Like balance limits, velocity limits are also linked with the card product. Cards associated with the card product shall follow the velocity limits tied to that card product. **\*** *What are transaction spending controls? For example, allow 50 USD per authorization or 15,000 USD spending per month.* **\*\*** *What is total number of transactions? For example, allow upto 5 authorizations per day. Also known as transaction frequency.* **\*\*\*** *What is specified time? For example, specified time can be daily, monthly, yearly, or lifetime.* Velocity limits can be applied to the card product at the time of creation of the card product or the velocity limits can be modified later as well. ### Create a velocity limit You can create a new velocity limit by sending a **POST** request to **/velocitylimits** endpoint as given below.
POST /velocitylimits **`{`**\ ` `**`"description": "The velocity limit - withdrawals",`**\ ` `**`"type": “PER_TRANSACTION”,`**\ ` `**`"min_amount": 1500,`**\ ` `**`"max_amount": 1500,`**\ ` `**`"currency": "USD",`**\ ` `**`"frequency": 3,`**\ ` `**`"period": "DAILY",`**\ ` `**`"transaction_scope": [`**\ ` `**`"WITHDRAWALS"`**\ ` `**`]`** **`}`**
### Retrieve velocity limits The nCore platform offers following retrieval options for velocity limits. ***Retrieve all velocity limits*** You can retrieve all existing balance limits by sending a **GET** request to **/velocitylimits** endpoint shown below. > [**GET /velocitylimits**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/listVelocityLimits) ***Retrieve a specific velocity limit*** You can retrieve a specific velocity limit by sending a **GET** request to **/velocitylimits/{id}** endpoint, where id is the balance limit id. > [**GET /velocitylimits/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getVelocityLimit) ### Update velocity limit You can update the existing velocity limit as required. Send a **PUT** request to **/velocitylimits/{id}** endpoint to update a velocity limit. Include the limit ID as a path parameter to indicate the velocity limit which is required to be updated. > [**PUT /velocitylimits/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/updateVelocityLimit) ### Link velocity limit with a card product You can link a velocity limit to your card product by sending a **POST** request to **/cardproducts/{id}/velocitylimits:link** as given below. > [**POST /cardproducts/{id}/velocitylimits:link**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/paths/~1v1~1cardproducts~1{id}~1velocitylimits:link/post) ### Unlink velocity limit from a card product You can unlink a velocity limit from your card product by sending a **POST** request to **/cardproducts/{id}/velocitylimits:unlink** as given below. > [**POST /cardproducts/{id}/velocitylimits:unlink**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/unlinkVelocityLimits) ### Retrieve linked velocity limits You can retrieve all velocity limits which are linked with your card product. Send a **GET** request to /**cardproducts/{id}/velocitylimits** endpoint as shown below. > [**GET /cardproducts/{id}/velocitylimits**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getVelocityLimits) ## **Advanced velocity limits** We added ability to configure advanced velocity limits, which allow you to add additional configurations such as merchants (i.e. categories or identifications) in velocity limit profile, so that you can configure velocity limit profile that is applicable for specified configuration. For this we have developed several new external [**APIs**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Advanced-velocity-limits): * Create advanced velocity limit – POST v1/advancedlimits * Update advanced velocity limit – PUT v1/advancedlimits/{id} * Get all advanced velocity limits – GET v1/advancedlimits * Get advanced velocity limit – GET v1/advancedlimits/{id} Advanced velocity limits are used to apply the special limit on transactional data such as limits on merchant category code, on a specific merchant or on the country from where the transaction has been initiated. Below you can find **possible condition types**: * "MCC" * "MERCHANT\_ID" * "KYC\_LEVEL" * "CHANNEL\_SCOPE" * "API\_CHANNEL" * "TRANSFER\_TYPE" * "PURCHASE\_TYPE" (has such enums as PURCHASE and ECOMMERCE) * "CARD\_TYPE" (has such enums as VIRTUAL and PHYSICAL) * "TRANSACTION\_ORIGIN" (has such enums as DOMESTIC, FOREIGN and ANY) Below you can find an **example** of 'Create advanced velocity limit' (POST /advancedlimits) request and response:
Request **`{`** **`"id" : "77a02486-10e2-4d55-9788-d0d49ed03d23",`** **`"name": "",`** **`"type": "PER_TRANSACTION",`** **`"description": "",`** **`"currency": "AED",`** **`"transaction_scope": [`** **`"WITHDRAWALS",`** **`"PURCHASES"`** **`],`** **`"active": true,`** **`"amount": 25000,`** **`"frequency": 7,`** **`"period": "NUM_OF_DAYS",`** **`"num_of_days": 7,`** **`"effective_from": "2023-12-01T00:00:00.000Z",`** **`"effective_to": "2023-12-31T11:59:59.999Z",`** **`"conditions": [`** **`{`** **`"type": "MCC",`** **`"values": ["4511", "4582", "4722"]`** **`},`** **`{`** **`"type": "ACQUIRER_COUNTRY",`** **`"values": ["UAE"]`** **`},`** **`{`** **`"type": "MERCHANT_ID",`** **`"values": ["45576893", "47583920"]`** **`},`** **`{`** **`"type": "KYC_LEVEL",`** **`"values": ["2"]`** **`},`** **`{`** **`"type": "CHANNEL_SCOPE",`** **`"values": ["VISA", "MERCURY"]`** **`}`** **`]`** **`}`**
Response **`{`** **`"id" : "77a02486-10e2-4d55-9788-d0d49ed03d23",`** **`"name": "",`** **`"type": "PER_TRANSACTION",`** **`"description": "",`** **`"currency": "AED",`** **`"transaction_scope": [`** **`"WITHDRAWALS",`** **`"PURCHASES"`** **`],`** **`"active": true,`** **`"min_amount": 0,`** **`"max_amount": 25000,`** **`"frequency": 7,`** **`"period": "NUM_OF_DAYS",`** **`"num_of_days": 7,`** **`"effective_from": "2023-12-01T00:00:00.000Z",`** **`"effective_to": "2023-12-31T11:59:59.999Z",`** **`"program_level": false,`** **`"created" : "2021-06-10T07:12:09.048Z",`** **`"modified" : "2021-06-10T07:12:09.048Z",`** **`"conditions": [`** **`{`** **`"type": "MCC",`** **`"values": ["4511", "4582", "4722"]`** **`},`** **`{`** **`"type": "ACQUIRER_COUNTRY",`** **`"values": ["UAE"]`** **`},`** **`{`** **`"type": "MERCHANT_ID",`** **`"values": ["45576893", "47583920"]`** **`},`** **`{`** **`"type": "KYC_LEVEL",`** **`"values": ["2"]`** **`},`** **`{`** **`"type": "CHANNEL_SCOPE",`** **`"values": ["VISA", "MERCURY"]`** **`}`** **`]`** **`}`**
Also we added ability for system to allow **link/unlink** advanced velocity limit(s) to the **card products or cards** so that the advanced limit can be linked when it needs to be applied and can be unlinked once it’s not required to be applied on any card or card product. For this we have developed several new APIs: * Link advanced velocity limit to card product ([POST](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/linkAdvancedVelocityLimits)) * Unlink advanced velocity limit from card product ([POST](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/unlinkAdvancedVelocityLimits)) * Link advanced velocity limit to card ([POST](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/linkCardAdvancedVelocityLimits)) * Unlink advanced velocity limit from card ([POST](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/unlinkCardAdvancedVelocityLimits)) * Get advanced velocity limits linked to card product ([GET](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/getAdvancedVelocityLimits)) * Get advanced velocity limits linked to card ([GET](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getAdvancedCardVelocityLimits)) # Fees On this page: * [Introduction](#introduction) * [Fee APIs](#fee-apis) * [Fee configuration for individual channel](#fee-configuration-for-individual-channel) * [Advanced fees](#advanced-fees) ### Introduction The fee generally refers to a stream of revenue generating from your customers. Which means that when the cardholder performs a transaction an associated fee with the card product will be charged. At nCore platform you can link different fees on the card product based on transaction types (e.g. purchase, withdrawal, and etc.). The transaction will be authorized only if there are sufficient funds available in the account which means it is real time fee evaluation. Real time fee evaluation requires that the account has sufficient funds available to cover both the transaction amount and the fee to authorize the transaction. What does it mean to have **sufficient funds**? There are typically three types of amounts involved in an authorization, which are: * ***Transaction amount (TA)** is the amount requested in the authorization* * ***Acquirer fee (AF)** is the fee that is charged by the acquirer (optional)* * ***Issuer fee (IF)** issuer fee is the fee that you configure and link to the card product (optional)* *In order to authorize the transaction the account should have sufficient funds to cover the three amounts, otherwise the authorization will be declined. That is **funds in account ≥*** ***TA + AF + IF***. Following are the fee types offered in nCore. | **S No.** | **Fee Type** | **Fee Description** | | --------- | -------------- | ------------------------------------------------------------------------------------- | | 1 | Flat fee | A fixed amount that the cardholder pays regardless of the transaction amount | | 2 | Percentage fee | A percentage applied on the transaction amount that the cardholder pays | | 3 | Range fee | Transaction amount based fee slabs where each slab has a flat fee or a percentage fee | ### Fee APIs #### Create a fee You can create a fee as required by sending a **POST** request to **/fees** endpoint as given below.
POST /fees **`{`**\ ` `**`"description": "Withdrawal Fee",`**\ ` `**`"type": "FLAT",`**\ ` `**`"currency": “USD”,`**\ ` `**`"amount": 2.5,`**\ ` `**`"transaction_type": "WITHDRAWALS",`**\ ` `**`"transaction_origin": "DOMESTIC"`**\ **`}`**
#### Retrieve a fee nCore offers two retrieval options for fees. **Retrieve all fees** You can retrieve all existing fees by sending a **GET** request to **/fees** endpoint as shown below. > [**GET /fees**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fees/paths/~1v1~1fees/get) **Retrieve a specific fee** You can retrieve a specific fee by sending a **GET** request to **/fees/{fee\_id}** endpoint as shown below. > [**GET /fees/{fee\_id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fees/paths/~1v1~1fees~1{fee_id}/get) #### Update a fee You can update a specific fee as required. Send a **PUT** request to **/fees/{fee\_id}** endpoint.
PUT /fees/{fee_id} **`{`**\ ` `**`"description": "Withdrawal Fee",`**\ ` `**`"active": true,`**\ ` `**`"type": "RANGE",`**\ ` `**`"currency": "USD",`**\ ` `**`"range": [`**\ ` `**`{`**\ ` `**`"greater_than": 0,`**\ ` `**`"less_than_equal_to": 1000,`**\ ` `**`"percentage": 3`**\ ` `**`},`** **`{`**\ ` `**`"greater_than": 1000,`**\ ` `**`"less_than_equal_to": 2000,`**\ ` `**`"percentage": 2`**\ ` `**`}`** **`]`**\ **`}`**
#### Link a fee with a card product You can link a fee with a card product by sending a **POST** request to **/cardproducts/{id}/fees:link** endpoint as given below. > [**POST /cardproducts/{id}fees:link**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/paths/~1v1~1cardproducts~1{id}~1fees:link/post) #### Unlink a fee from a card product You can unlink a fee from a card product as per your requirement by sending a **POST** request to **/cardproducts/{id}/fees:unlink** endpoint. Noted that fee will not charge for a specific card product after unlinking it. > [**POST /cardproducts/{id}/fees:unlink**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/unlinkFees) #### Retrieve linked fees You can retrieve all fees which are linked with your card product. Send a **GET** request to /**cardproducts/{id}/fees** endpoint as shown below. > [**GET /cardproducts/{id}/fees**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#operation/getFees) ### Fee configuration for individual channel We introduce new ‘source\_channel’ parameter , which is added to the [Fees](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fees) APIs. Possible values are ‘MPGS’, ‘DAPI’ or ‘ANY’ (default). It gives an opportunity to choose an appropriate channel, so that fee for every channel can be applied accordingly. This parameter is currently applicable for ‘transaction\_type’ = ‘TRANSFERS’ only. Also we implemented ability to post fee on recipient account instead of sender account, so you can charge the transfer funds fee to recipient instead of sender. If there is a fee plan (with ‘source\_channel’ = ‘DAPI’, ‘MPGS’ or ‘ANY’) linked to the recipient card product and ‘source\_channel’ in the transfer request received is either ‘MPGS’ or ‘DAPI’, then fee is being deducted from the recipient account. Below you can find a table which describes different scenarios:
### Advanced fees We have added ability for system to allow fees configuration along with the dynamic conditions so that fees can be applied based on the configured conditions. Below you can find **possible condition types**: * "MCC" * "MERCHANT\_ID" * "ACQUIRER\_COUNTRY" * "KYC\_LEVEL" * "TRANSFER\_TYPE" * "IS\_FORIEGN\_CURRENCY\_FEE" * "SCHEME\_SCOPE" (has such enums as VISA, MASTERCARD, MERCURY, UNIONPAY) * "PURCHASE\_TYPE" (has such enums as PURCHASE and ECOMMERCE) * "API\_CHANNEL" (has such enums as API, MPGS, DAPI, LEAN) * "TRANSACTION\_ORIGIN" (has such enums as DOMESTIC, FOREIGN and ANY) Following new endpoints are implemented to maintain advanced fees: * [Create advanced fees](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Advanced-Fees/paths/~1v1~1advancedfees/post) – `POST v1/advancedfees` * [Update advanced fees](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Advanced-Fees/paths/~1v1~1advancedfees~1%7Bfee_id%7D/put) – `PUT v1/advancedfees/{id}` * [Get all advanced fees](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Advanced-Fees/paths/~1v1~1advancedfees/get) – `GET v1/advancedfees` * [Get specific advanced fee](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Advanced-Fees/paths/~1v1~1advancedfees~1%7Bfee_id%7D/get) – `GET v1/advancedfees/{id}` * [Link advanced fee to card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/linkAdvancedFees) - `POST v1/cardproducts/{id}/advancedfees:link` * [Unlink advanced fee from card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/unlinkAdvancedFees) - `POST v1/cardproducts/{id}/advancedfees:link` * [Get list of advanced fees related to the card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/getCardProductAdvancedFees) - `GET v1/cardproducts/{id}/advancedfees` Besides, we have added new parameter “`is_forex_fee`" in advanced fees. This parameter works in combination with transaction type same as `PURCHASE_FOREIGN_CURRENCY` in fees. # Charges ### Card i**ssuance charges** We added an ability to post card issuance charges so that it can be applied to respective cardholder's account. This will be executed one time only for every new card that is issued. It can be applied when: 1\) Personalized physical card is issued for the first time 2\) Personalized virtual card is issued for the first time 3\) Bulk card is linked to the user {% hint style="info" %} If card is replaced then issuance charges shall not be considered. {% endhint %} A cron job will be executed daily to retrieve charges in "PENDING" status and apply the charge amount to either the cardholder's or master's account, as per the configuration. ### Card replacement **charges** We have added support of card replacement charges, so that it can be parked, when physical or virtual cards are replaced to cardholder. New supported enums for 'charge\_type' are: * PHYSICAL\_CARD\_REPLACEMENT * VIRTUAL\_CARD\_REPLACEMENT. {% hint style="info" %} Card replacement charges work when 'application\_type' = INSTANT. {% endhint %} ### Card activation **charges** We have added the support of card activation charges. This new charge is applied to cardholder when a card is activated for the first time. This will be charged one-time only for every new card that is activated . For example, if two different cards are created for a user, then he will be charged for every card. New supported enum for 'charge\_type' is: * CARD\_ACTIVATION\_CHARGES {% hint style="info" %} * The card activation charges function properly with application\_type = INSTANT. * When a card is activated (i.e. status becomes ACTIVE/A0), the charge is debited from the cardholder’s account and the webhook event CHARGE\_APPLIED is triggered. * Charges will continue to be deducted even if the account status is INACTIVE or SUSPENDED. {% endhint %} ### **Charges APIs** The below APIs are exposed in API Catalog: * [Create charge](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Charges/operation/createCharges) * [Update charge](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Charges/operation/updateCharges) * [Get a specific charge](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Charges/operation/getCharges) * [Get list of charges](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Charges/operation/listCharges) * [Link charges to card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/linkCharges) (you can link multiple charges at once) * [Unlink charges from card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/unlinkCharges) (you can unlink multiple charges at once) * [Get list of charges related to card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/getCharges) {% hint style="info" %} Note, that supported enums for 'charge\_type' are "PHYSICAL\_CARD\_ISSUANCE", "VIRTUAL\_CARD\_ISSUANCE", "PHYSICAL\_CARD\_REPLACEMENT", "VIRTUAL\_CARD\_REPLACEMENT" and "DELIVERY". {% endhint %} ### Webhooks New [webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#charges-webhook) event/enum "CHARGE\_APPLIED" is addded. Below you can find webhook sample: ``` { "event": "CHARGE_APPLIED", "charge_applied": { "id": "0fcf8c07-ae35-4243-890d-0a39b2618578", "description": "charges dev 28", "currency": "AED", "amount": 2, "card_id": "f3bd66fd-80d5-4c7c-90e2-ac062c923ff0", "account_id": "f3bd66fd-80d5-4c7c-90e2-ac062c923ff0", "charge_id": "CHARGEAHSAN19", "charge_type": "PHYSICAL_CARD_ISSUANCE" } } ``` # Multi-currency On this page: * [Introduction](#introduction) * [Enhancements to existing APIs](#enhancements-to-existing-apis) 1. [Card Product APIs](#card-product-apis) 2. [Accounts APIs](#accounts-apis) 3. [Fees APIs](#fees-apis) 4. [Balance Limits APIs](#balance-limits-apis) 5. [Velocity Limits APIs](#velocity-limits-apis) * [Newly created APIs](#newly-created-apis) 1. [‘Get all FX rate providers’ API](#get-all-fx-rate-providers-api) 2. [‘Get specific FX rate provider details by ID’ API](#get-specific-fx-rate-provider-details-by-id-api) 3. [‘Get all custom rate groups’ API](#get-all-custom-rate-groups-api) 4. [‘Get specific FX rate group details by ID’ API](#get-specific-fx-rate-group-details-by-id-api) 5. [‘Update Account’ API](#update-account-api) 6. [‘Request FX rate quote’ API](#request-fx-rate-quote-api) 7. [‘Book FX rate quote’ API](#book-fx-rate-quote-api) 8. [‘Get all FX rate quotes’ API](#get-all-fx-rate-quotes-api) 9. [‘Get a FX rate quote details’ API](#get-a-fx-rate-quote-details-api) * [Authorization](#authorization)
## Introduction NymCard is introducing a multi-currency feature: cards and accounts are created with multiple currency wallets under an account. Users just need to swipe the card and payments are seamlessly made on respective currency wallets. Below you can find APIs, which are developed/enhanced to define the multi-currency related settings.\ \ **Important:** These APIs will be exposed on API catalog once the multi-currency changes are all implemented. **Prerequisite:** The below have to be configured through the NymCard operations team to support multi-currency changes: 1. Configure FX rate provider\* 2. Define custom rate group 3. Link custom rate group with FX rate provider \*Fexco is a “Fexco Merchant Services Limited Company” that offers treasury as a service for FX rates. NymCard will integrate with Fexco to get different currency rates and then sell/buy on need basis. Fexco will also manage all Foreign Exchange aspects as well as daily settlement with VISA on behalf of NymCard. **Note:** Multi currency products are applicable only for VISA scheme cards. ## Enhancements to existing APIs ### Card Product APIs Impacted APIs: * [Create card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/Create%20card%20product) * [Update card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/updateCardProduct) * [Get card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/getCardProduct) * [Get list of all card products](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/listCardProducts)
New parameters introduced in card products: * **is\_multi\_currency\_product (boolean true/false)** \* A new field to identify whether a card product is **Single** Currency or **Multi**-Currency. Default value is **false**. **Note:** Card product with multiple currencies in currency\_settings is not allowed if is\_multi\_currency\_product = false. * **wallet\_settings** To restrict the wallets, “**wallet\_settings**” new object is introduced with the following fields. If **is\_multi\_currency\_product = true** then becomes mandatory. \ a) **initial\_num\_of\_wallets\_offered**: This field is to specify how many initial wallets are offered whenever a new card is issued. Users don’t have to opt-in for wallets as these will be readily available to utilize. b) **maximum\_active\_wallets\_allowed**: This field is to specify how many active wallets a user may have at a time.\ \ c) **maximum\_wallets\_allowed\_in\_sweep**: This field is to specify the maximum number of wallets to use in SWEEPING * **fxrates\_settings** This field is to link the custom rate group with card product against different transaction types. It has two child fields to specify **transaction\_type** and custom **rate\_group\_id**. 1. It is applicable if **is\_multi\_currency\_product = true**. 2. If not provided then the system auto links the default custom rate group with the card product. 3. Multiple groups against the same **transaction\_type** are not allowed. 4. Transaction types are “**TRANSFERS**” and “**SWEEP**” * Purpose of keeping separate TRANSFERS and SWEEP is to apply different currency rates. However it's on the future road map, for now rates are the same. So the same custom group should be for TRANSFERS and SWEEP. * if a cardholder converts one currency into another currency, in such cases TRANSFERS are applicable.
* During authorization like PURCHASE or WITHDRAWAL, if funds are insufficient, then the system automatically pulls the funds from the currency wallets in order to make sufficient funds in the wallet on which the transaction is being posted. In such cases SWEEP is applicable. Below you can find ‘Create card product’ sample request payload: ``` { … "is_multi_currency_product": true, "wallet_settings": { "initial_num_of_wallets_offered": 3, "maximum_active_wallets_allowed": 3, "maximum_wallets_allowed_in_sweep": 1 }, "fxrates_settings": [ { "transaction_type": "TRANSFERS", "rate_group_id": "R1" }, { "transaction_type": "SWEEP", "rate_group_id": "R2" } ] ``` ### Accounts APIs Following changes are made in the ‘[Create account](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/createAccount)’ API: * **currencies** A new optional array field is introduced to specify wallet currencies in ‘Create account’ request. Currencies must match with card product supported currencies. If not provided then the system creates the account of currency as per card product priority 1(base currency) currency only. * **wallet\_details** A new object is introduced in response payload of Accounts APIs. It has the following child fields: **Currency** Represents the currency of the wallet. **Priority** Represents the priority of the wallet. Priority is used for sweeping purposes when due to insufficient funds, the system needs to automatically pull the funds from other wallets. So based on priority number, the system will pick the highest priority first. **Status** Represents the wallet status is ACTIVE or INACTIVE. Below you can find ‘Create account’ sample request payload: **POST {{baseUrl}}/v1/accounts** ``` {   "user_id": "user001393",   "card_product_id": "CP0032",   "type": "PREPAID",   "id": "prepaidmulti25",   "currencies": [       "USD", "AED", "CAD", "EUR"   ] } ``` Below you can find ‘Create account’ sample response payload: ``` {     "id": "prepaidmulti25",     "user_id": "user001393",     "card_product_id": "CP0032",     "type": "PREPAID",     "balances": {         "AED": 0.00,         "EUR": 0.00,         "USD": 0.00,         "CAD": 0.00     },     "ledger_balances": {         "AED": 0.00,         "EUR": 0.00,         "USD": 0.00,         "CAD": 0.00     },     "status": "ACTIVE",     "created": "2023-05-24T10:01:10.515Z",     "modified": "2023-05-24T10:01:10.515Z",     "default_account": false,     "currencies": [         "AED",         "EUR",         "USD",         "CAD"     ],     "wallet_details": [         {             "currency": "USD",             "priority": 1,             "status": "ACTIVE"         },         {             "currency": "AED",             "priority": 2,             "status": "ACTIVE"         },         {             "currency": "CAD",             "priority": 3,             "status": "ACTIVE"         },         {             "currency": "EUR",             "priority": 4,             "status": "ACTIVE"         }     ] ``` ### Fees APIs Impacted APIs: * [Create fee](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fees/paths/~1v1~1fees/post) * [Update fee](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fees/paths/~1v1~1fees~1%7Bfee_id%7D/put) * [Get specific fee](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fees/paths/~1v1~1fees~1%7Bfee_id%7D/get) * [Get list of fees](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fees/paths/~1v1~1fees/get) * [Link fees to the card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/paths/~1v1~1cardproducts~1%7Bid%7D~1fees:link/post) * [Unlink fees from the card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/unlinkFees) * [Get list of fees related to the card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/getFees) **Linking different currencies of fee with card product** Previously, the system did not allow linking a fee plan with the card product if the currency of the fee does not match the priority 1 currency. Here comes the new implementation to unblock the restriction of currency mismatch.\ \ **New fee types introduced:** 1- PURCHASE\_FOREIGN\_CURRENCY 2- WITHDRAWAL\_FOREIGN\_CURRENCY Above two fees are introduced. These fees are charged when a foreign currency transaction is received other than the supported wallets. For example, there exists 3 wallets AED, USD, EUR under an account. A transaction like PURCHASE is received in OMR currency then the system will additionally charge this fee on top of typical PURCHASE fee if transaction currency matches with the currency of fee PURCHASE\_FOREIGN\_CURRENCY. Note The above fee can also be defined with currency \*\*\*. This definition will work as a default foreign currency fee if the dedicated currency fee is not defined. For Example There exists 3 wallets AED, USD, EUR under an account and fees PURCHASE\_FOREIGN\_CURRENCY in currency CAD and PURCHASE\_FOREIGN\_CURRENCY in currency \*\*\* is linked with the card product. A transaction like PURCHASE is received in OMR currency then the system will charge fee PURCHASE\_FOREIGN\_CURRENCY(with \*\*\*) on top of typical PURCHASE. The currency of fee (PURCHASE\_FOREIGN\_CURRENCY and WITHDRAWAL\_FOREIGN\_CURRENCY ) should not match with the supported currencies on the card product while linking the fee with the card product. Below you can find ‘Create fee’ sample request payload: ``` { "description": "PURCHASE FOREIGN CURRENCY FEE", "type": "FLAT", "currency": "AED", "transaction_type": "PURCHASE_FOREIGN_CURRENCY", "transaction_origin": "ANY" } ``` Below you can find ‘Create fee’ sample response payload: ``` { "id": "b2c0a34d-da31-42c7-ace4-5058b295fab6", "description": "PURCHASE FOREIGN CURRENCY FEE", "active": true, "type": "FLAT", "currency": "AED", "amount": 3.00, "range": [], "transaction_type": "PURCHASE_FOREIGN_CURRENCY", "transaction_origin": "ANY", "created": "2023-05-24T10:19:56.139Z", "modified": "2023-05-24T10:19:56.139Z" } ``` ### Balance Limits APIs System now allows linking balance limits in different currencies at card product or account. There is a multi-currency card product with 2 currencies of AED (priority 1) and USD (priority 2). The two balance limits can now be linked either to the card product or account level. 1- Balance limit of currency = AED exists and another balance limit of currency = USD exists and both can be linked with card product. If a transaction is posted on the USD wallet, the system will check the linked Balance limit of USD currency. If the balance limit of the account remains within the related limit linked, then the transaction is successfully authorized. Otherwise, it is declined. Similarly if a transaction is posted on AED wallet, the system will check the linked balance limit of AED currency. If the balance limit of the account remains within the related limit linked, then the transaction transaction is successfully authorized. Otherwise, it is declined. \ **Balance limit linking to card product:** Impacted APIs: * Get list of balance limits related to the card product * Link balance limits to the card product * Unlink balance limits from the card product **Balance limit linking to account:** Impacted APIs: * Link balance limit to account * Unlink balance limit from account * Get balance limits linked to account * Get account details * Get list of accounts * Change account status Below you can find sample response for ‘Get account details’ API: ``` { "id": "d089a80f-e641-4045-8a80-54841e4a7458", "user_id": "gg5a80f-e641-4045-8a80-54841e4a55555", "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234", "type": "PREPAID", "balances": { "USD": 125.58, "EUR": 400.2 }, "ledger_balances": { "USD": 125.58, "EUR": 400.2 }, "status": "ACTIVE", "currencies": [ "USD" ], "wallet_details": [ { "currency": "USD", "priority": 0, "status": "ACTIVE" } ], "created": "2012-05-04T19:42:32.987Z", "modified": "2012-05-04T19:42:32.987Z" } ``` **Note:** A cumulative balance limit in a base currency is also maintained at tenant level. Whenever credit or debit is applied on account, an accumulative balance is calculated by the system and it is checked whether it violates the tenant level balance limit setting or not. For configuration of accumulative balance limit at tenant level, please contact the NymCard operations team. ### Velocity Limits APIs The system now allows linking of velocity limits in different currencies. Example:\ \ There is a multi-currency card product with 2 currencies of AED (priority 1) and USD (priority 2).\ \ Velocity limit of currency = AED exists. Velocity limit of currency = USD exists. Now both velocity limits can be linked either at card product or card level. If a transaction is posted on a USD wallet, the system will check the linked velocity limit of USD currency.\ \ If the transaction amount falls within the defined velocity limit, the transaction is successfully authorized. Otherwise, it is declined. Similarly if a transaction is posted on AED wallet, the system will check the linked velocity limit of AED currency. If the transaction amount falls within the defined velocity limit, the transaction is successfully authorized. Otherwise, it is declined. **Velocity limit linking to card product** Impacted APIs: * Link velocity limits to the card product * Unlink velocity limits from the card product * Get list of velocity limits related to the card product \ **Velocity limit linking at card** Impacted APIs: * Set velocity limits for card * Remove velocity limits for card * Get velocity limits linked to card ## Newly created APIs ### ‘[Get all FX rate providers](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/getFxRateProviders)’ API A new API is developed to get the list of all FX rate providers: **GET v1/fxrates/providers** Below you find an example of response: ``` { "data": [ { "provider_id": "FEXCOID", "provider_name": "FEXCO", "type": "EXTERNAL", "status": "ACTIVE", "rate_expiry_buffer_time": 5, "fxrate_mode": [ { "transaction_type": "TRANSFERS", "mode": "ONLINE" }, { "transaction_type": "SWEEP", "mode": "ONLINE" } ], "fxrate_provider_groups": [ { "provider_group_id": "4", "status": "ACTIVE" } ], "created": "2023-05-24T10:48:28.283Z", "modified": "2023-05-24T10:48:28.283Z" }, …. ``` ### ‘[Get specific FX rate provider details by ID](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/findFxRateProviderById)’ API A new API is developed to get details of specific FX rate provider: **GET v1/fxrates/providers/{id}** Below you find an example of response: ``` { "provider_id": "FEXCOID", "provider_name": "FEXCO", "type": "EXTERNAL", "status": "ACTIVE", "rate_expiry_buffer_time": 5, "fxrate_mode": [ { "transaction_type": "TRANSFERS", "mode": "ONLINE" }, { "transaction_type": "SWEEP", "mode": "ONLINE" } ], "fxrate_provider_groups": [ { "provider_group_id": "4", "status": "ACTIVE" } ], "created": "2023-05-24T10:48:28.283Z", "modified": "2023-05-24T10:48:28.283Z" } ``` ### ‘[Get all custom rate groups](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/getFxRateGroups)’ API A new API is developed to get the list of custom rate groups: **GET {{baseUrl}}/v1/fxrates/groups**\ \ Response: ``` { "data": [ { "id": "customrategroup14", "providerId": "FEXCOID", "providerGroupId": "group4", "status": "ACTIVE", "isDefault": false, "created": "2023-05-24T11:00:32.230Z" } ``` ### ‘[Get specific FX rate group details by ID](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/getFxRateGroupById)’ API A new API is developed to get details of specific FX rate group: **GET v1/fxrates/groups/{id}** Below you find an example of response: ``` { "id": "R1", "provider_id": "1", "provider_group_id": "P1", "status": "ACTIVE", "is_default": "true", "created": "2018-01-02T19:42:32.987Z", "modified": "2012-05-04T19:42:32.987Z" } ``` ### ‘[Update Account](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/updateAccount)’ API A new API is developed to have capability to manage the wallets; i.e. to add/remove wallets (applicable for products whereby "is\_multi\_currency\_product" = true). **PUT v1/accounts/{id}** Request: ``` { "wallet_details": [ { "currency": "USD", "priority": 3, "status": "INACTIVE" }, { "currency": "SAR", "priority": 2, "status": "ACTIVE" }] } ``` **Definition:**\ \ 1- “currency”: Mandatory field - For a multi-currency product this field shows which currency wallets are used in maintaining the funds.\ \ 2- “priority”: Mandatory field - For a multi-currency product this field gives the priority in which the currency wallets are used in funds sweeping.\ \ 3- “status”: Mandatory field - enums: "ACTIVE" / "INACTIVE For a multi-currency product, if this field is set to 'INACTIVE' then the wallets of particular currency cannot be used in any transactions. The system does not allow to change priority 1 currency status. **Few points to mention:** \- Changing priority 1 currency status to INACTIVE is not allowed \- Changing the priority of priority 1 currency is not allowed \- Adding a new currency (as long as the total number of wallets does not exceed what is defined in "initial\_num\_of\_wallets\_offered": 4) \- Adding new wallets is allowed even if the user has reached the total number of ACTIVE wallets defined in "maximum\_active\_wallets\_allowed" but the newly added wallet will be in INACTIVE status. \- Changing the status of any of the supported currencies to INACTIVE is allowed \- Changing the status of any of the supported currencies is to ACTIVE is allowed as long as the total number of ACTIVE wallets do not exceed what is defined as "maximum\_active\_wallets\_allowed" at product level \- Changing the priority of any of the supported currencies is allowed ### ‘[Request FX rate quote](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/getFxRatesQuote)’ API \ A new API is developed for users to convert the amount of a currency into another currency wallet. It's a two step process, initially to determine the exchange rate against different currency pairs, this API is used. This API will return the exchange rate so that users can review it and if rate is acceptable, then a second API ‘Book a quote’ will be used. **POST {{baseUrl}}/v1/fxrates:quote**\ \ Request: ``` { "from_currency": "USD", "to_currency": "AED", "amount": 9, "account_id": "prepaidmulti23" } ``` Response: ``` { "id": "eb2c02dd-3d02-463d-86f5-8923fe6f5371", "ts": "2023-05-24T11:30:58.556Z", "from_currency": "USD", "amount": 10, "to_currency": "AED", "to_amount": 36.70, "exchange_rate": 3.67, "status": "OFFERED", "expiry": "2023-06-04T11:46:12.937Z", "fxrate_provider_id": "FEXCOID", "fxrate_provider_name": "FEXCO-ID" } ``` ### ‘[Book FX rate quote](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/bookFxRate)’ API \ A new API is developed to book FX rate quote. This API is a second step for converting the amount of a currency into other currency. Upon receiving this API request, the system will shift the balance from the currency wallet into the other currency wallet. So debit is applied on from currency wallet and credit is applied on to currency wallet. **PUT {{baseUrl}}/v1/fxrates/%quote\_id%:book** \ Response: ``` { "id": "c4f35a93-671f-466a-9829-4e30f20233cb", "ts": "2023-05-22T07:05:58.820Z", "from_currency": "AED", "amount": 8.00, "to_currency": "USD", "to_amount": 2.17, "exchange_rate": 0.27146, "status": "BOOKED", "transaction_id": "1ff20bd8-974f-440a-8825-e30763885499", "fxrate_provider_id": "53", "fxrate_provider_name": "FEXCO", "fee_amount": 0.00, "fee_details": [], "account_id": "MUHAYTESTING18MAY23_00", "booking_ts": "2023-05-22T07:06:53.703Z", "created": "2023-05-22T07:05:58.848Z", "modified": "2023-05-22T07:06:53.706Z" } ``` ### ‘[Get all FX rate quotes](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/getFxRatesQuotes)’ API This API is used to fetch the details of all existing quotes. **GET v1/fxrates/quotes** Below you find an example of response: ``` { "after": "MjAxOC0wMS0wMlQxOTo0MjozMi45ODda", "has_more": true, "data": [ { "id": "bc121529-e6e9-45f1-b820-8c46ce7f005a", "account_id": "bc121529-e6e9-45f1-b820-8c46ce7f0058", "ts": "2020-06-08T14:57:30.123456", "booking_ts": "2020-06-08T14:57:30.123456", "from_currency": "AED", "amount": 500, "to_currency": "USD", "to_amount": "136.15", "exchange_rate": "0.272294" "status": "BOOKED", "transaction_id": "12dr4", "fxrate_provider_id": "1", "fxrate_provider_name": "NymCard", "fee_amount": "1.5", "fee_detail": [ { "fee_id": "173427", "description": "transaction fee", "amount": "1.5", "currency": "AED" } ], "created": "2023-02-06T10:54:02.956Z", "modified":"2023-02-06T10:54:02.956Z" }] } ``` ### ‘[Get a FX rate quote details](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/getFxRatesQuoteById)’ API This API is used to fetch the details of an existing quote. **GET v1/fxrates/quotes/{id}** Below you find an example of response: ``` { "id": "bc121529-e6e9-45f1-b820-8c46ce7f005a", "account_id": "bc121529-e6e9-45f1-b820-8c46ce7f0058", "ts": "2020-06-08T14:57:30.123456", "booking_ts": "2020-06-08T14:57:30.123456", "from_currency": "AED", "amount": 500, "to_currency": "USD", "to_amount": "136.15", "exchange_rate": "0.272294" "status": "BOOKED", "transaction_id": "12dr4", "fxrate_provider_id": "1", "fxrate_provider_name": "NymCard", "fee_amount": "1.5", "fee_detail": [ { "fee_id": "173427", "description": "transaction fee", "amount": "1.5", "currency": "AED" } ], "created": "2023-02-06T10:54:02.956Z", "modified": "2023-02-06T10:54:02.956Z" } ``` ## Authorization **Scheme based transactions - Authorization with Sweeping** When an account wallet has insufficient funds then the system needs to pull the funds from another currency wallet of the same account so that sufficient funds are available in order to authorize the transaction. Example: A multi-currency card product exists with "maximum\_wallets\_allowed\_in\_sweep": 1 An account exists under the multi-currency card product: \[AED, P1, ACTIVE, 40] \[USD, P2, ACTIVE, 30] \[EUR, P3, ACTIVE, 20]
1- A transaction is received of amount = 50 AED 2- There are insufficient funds in AED. The system needs 10 more AEDs to process the transaction 3- The system checks card product field wallet\_settings.maximum\_wallets\_allowed\_in\_sweep and its value is 1, so the system will use other wallets (as per configuration) to pull the funds and convert into AED and credit it into AED wallet. Here exchange rate USD to AED will be used of type SWEEP. 4- So debit of 2.27 on USD wallet and credit of 10 AED on AED wallet are applied (as per exchange rate) during authorization and transaction is approved.\ \ 5- If there are insufficient funds in the USD wallet and given that maximum\_wallets\_allowed\_in\_sweep defined in the card product is 1, then the system will not pull funds from the second wallet and will decline the transaction. **Reflecting Sweep Details to users in Webhook and Transaction APIs**\ \ “Sweep\_details” is reflected in the “TRANSACTION” webhook.\ \ Also, it is reflected in the response of the below APIs:\ \- Get transaction details API\ \- Search for transactions API ``` "sweep_details": [ { "debit_from_currency": "EUR", "debit_from_amount": 2.55, "credit_to_currency": "AED", "credit_to_amount": 10.00, "exchange_rate": 3.91552 } ] ``` **Clearing and Reversal** In case of CLEARING, the system will NOT do SWEEPING to pull the funds from the other wallets. If there is insufficient funds then the account goes into overdraft (business as usual).\ \ There is also NO SWEEPING in reversals (whether partial or full reversal). # Authorization controls These controls can allow or restrict authorizations based on the allowed or restricted countries list or merchants list. You can limit spending at a single country or at a group of countries, and you can limit spending by a single user, users with a particular card product, or all users. And the same applies to merchants. There are two types of authorization controls nCore platform offers. * Allowed countries authorization controls * Allowed MCCs authorization controls ### **Allowed countries authorization controls** The allowed countries authorization controls functionality checks while processing authorizations whether the authorization is coming from a certain country which is allowed (whitelisted) or restricted (blacklisted). If the authorization is coming from a whitelisted country, then this control check is passed and move for the further processing else if the authorization is coming from a blacklisted country then the authorization is rejected and do not move forward for further processing. It is a non-financial check specific to a country list to allow (whitelist) certain countries or restrict (blacklist) certain countries as per your business needs. The allowed countries' whitelisting or blacklisting should be configured and managed at card product level as well as at an individual card level. #### **Allowed lists management** You can create and manage allowed lists by using our APIs. Following are the APIs available at nCore platform for allowed lists management. * Create a list of allowed countries * Retrieve all allowed countries lists * Get allowed countries list by ID * Update a specific list of allowed countries **Create a list of allowed countries** You can create a list of allowed countries by sending a **POST** request to **/allowedcountries** endpoint. An example is given below.
POST /allowedcountries **`{`**\ **`"id": "d089a80f-e641-4045-8a80-54841e4a7458",`**\ **`"name": "Country list 01",`**\ **`"allow": true,`**\ **`"active": true,`**\ **`"country_codes": [`**\ **`"string"`**\ **`]`**\ **`}`**
{% hint style="info" %} The parameter “allow” is used to blacklist or whitelist the allowed countries list. If “allow” is ***false*** then the countries list will be considered as a blacklist. {% endhint %} \ **Retrieve all lists of allowed countries** You can retrieve all existing lists of allowed countries by sending a **GET** request to **/allowedcountries** endpoint as given below. > [**GET /allowedcountries**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/listAllowedCountries) \ **Get a list of allowed countries by ID** You can retrieve a specific list of allowed countries by its ID by sending a **GET** request to **/allowedcountries/{id}** endpoint as given below. > [**GET /allowedcountries/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/getAllowedCountries) \ **Update a specific list of allowed countries** You can update a list of allowed countries by sending a **PUT** request to **/allowedcountries/{id}** endpoint as given below. > [**PUT /allowedcountries/{id}**](https://nymcard.com/docs/api#tag/Allowed-Lists/operation/updateAllowedCountries) ### **Allowed MCCs authorization controls** The allowed MCCs authorization controls functionality checks whether the authorization is initiated at a certain merchant which is allowed (whitelisted) or restricted (blacklisted). If the authorization is coming from a whitelisted merchant, then this control check is passed and move for the further processing else if the authorization is coming from a blacklisted merchant then the authorization is rejected and do not move forward for further processing. It is a non-financial check specific to a MCCs list (MCCs - merchant category codes) to allow (whitelist) certain merchants or restrict (blacklist) certain merchants as per your business needs. The list can be either a whitelist or a blacklist and logically cannot be both at the same time. The MCC whitelisting or the blacklisting should be configured on both card product level as well as at an individual card level. {% hint style="warning" %} It is allowed up to 1000 MCC codes per list. {% endhint %} In the file below you can find the list of supported MCCs: {% file src="/files/FusElVpTqemcTgiwg1pB" %} #### **Allowed lists management** You can manage allowed lists by using our APIs. Following are the APIs available at nCore platform for allowed lists management. * Create list of allowed MCCs * Retrieve all lists of allowed MCCs * Get a specific list of allowed MCCs by ID * Update a specific list of allowed MCCs **Create list of allowed MCCs** You can create a list of allowed MCCs by sending a **POST** request to **/allowedmccs** endpoint as given below. > [**POST /allowedmccs**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/createAllowedMccs) **Retrieve all lists of allowed MCCs** You can retrieve all existing lists of allowed MCCs by sending a **GET** request to **/allowedmccs** endpoint as given below. > [**GET /allowedmccs**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/listAllowedMccs) **Get a specific list of allowed MCCs** You can retrieve a list of allowed MCCs by its ID by sending a **GET** request to **/allowedmccs/{id}** endpoint as given below. > [**GET /allowedmccs/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/getAllowedMccs) \ **Update a specific list of allowed MCCs** You can update a list of allowed MCCs by sending a **PUT** request to **/allowedmccs/{id}** endpoint as given below. > [**PUT /allowedmccs/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/updateAllowedMccs) {% hint style="warning" %} We have implemented several enhancements for MCC list management. For details refer to this [document](https://docs.nymcard.com/get-started/product-management/authorization-controls/enhancements-for-mcc-list-management). {% endhint %} ### Merchant lists We have introduced a merchant list functionality, which gives the ability to allow transactions from specific merchants. This list can be linked to a card product or an individual card and include Merchant IDs with an allow flag set to true or false. If a merchant list is linked to both the card and the card product, the card configuration will take priority. In scope of this functionality the following APIs are developed: * [Create allowed merchants list](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/createAllowedMerchants) * [Get list of allowed merchants](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/listAllowedMerchants) * [Update allowed merchants list](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/updateAllowedMerchants) * [Get specific allowed merchants list](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/getAllowedMerchants) * [Get allowed merchants linked to card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/getCardProductAllowedMerchants) * [Link allowed merchants to a card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/linkAllowedMerchantsToCardProduct) * [Unlink allowed merchants from card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/unlinkAllowedMerchantsFromCardProduct) * [Link allowed merchants to card](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/linkAllowedMerchantsToCard) * [Unlink allowed merchants from card](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/unlinkAllowedMerchantsFromCard) * [Get allowed merchants linked to card](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardAllowedMerchants) # Enhancements for MCC list management We’ve implemented enhancements for MCC list management. Now you can have allowed and blocked MCCs in one list so that transactions can be authorized based on configured settings. ['Update allowed MCCs list by ID](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/updateAllowedMccs)' API has the following updates: * "name" and "allow" parameters are removed * "mccs" parameter is changed to array list MCC list can be updated even for ACTIVE card products using '[Update allowed MCCs list by ID](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/updateAllowedMccs)' API. 'Update MCC list API': To add new mcc code(s), all existing mcc codes should be passed in the update payload in addition to the new one(s). To remove mcc code(s), all mcc codes should be passed in the update payload except for the one(s) to be removed. Now the system creates and links default MCC list while creating card product with the ALL mcc codes = true (DEFAULT). **The impact on the existing card products/cards** is the following: * Existing card product with no MCC list > MCC list will be created and linked to it (default of ALL = true) * Existing card product with one or more MCC lists (having some of the mcc codes = false) > migrated into 1 default MCC list with default ALL = true while the other MCC codes will still be read as "false". Moreover, changes will be applied to the cards associated with the existing card products. The below indicates that all MCC codes are supported: ``` "mccs": [ { "mcc_id":"ALL", "allow":true } ] ``` The below indicates that all MCC codes are supported except for MCC code = "9852": ``` "mccs": [ { "mcc_id":"ALL", "allow":true }, { "mcc_id":"9852", "allow":false } ] ``` The "allowed\_mccs\_id" parameter is removed from '[Create card product'](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/Create%20card%20product) and '[Update card product](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/updateCardProduct)' APIs requests. Also "allowed\_mccs\_id " parameter continues to be reflected in the response of the following APIs: 1\. Get card product 2\. Get list of card products 3\. Create card product 4\. Update card product 5\. Create card 6\. Update card 7\. Get card details 8\. Get list of cards 9\. Get card authorization settings data 10\. Update card authorization settings data 11\. Change card status {% hint style="info" %} You can still create a new MCC list and add it at the card level via '[Update card auth settings](https://nymcard.com/docs/api#tag/Cards/operation/upsertCardAuthSettings)' API. {% endhint %} Besides, you can find the list of supported MCCs in this[ GSG doc](https://docs.nymcard.com/get-started/product-management/authorization-controls#allowed-mccs-authorization-controls). # Transactions # Payment ecosystem A transaction is an electronic message that carries data, which is used for payment processing. Transactions generally originate when cardholders perform any payment transactions, either online, in-app purchases, ATM withdrawals or over the counter at a point of sale (POS) terminal. #### Payments in a nutshell In the payment automated system, transaction-processing is enabled as per the following processes. * **Authorization** – It is the process to determine the customer’s card validity which includes financial checks as well as non-financial checks. Users can perform the transactions based on the business criteria setup for a particular card, the card account must contain an ample amount of funds to authorize the transaction. Once all the checks and required criteria are met, then the card account will get a temporary hold on those funds. The hold will remain until the clearing is processed. * **Clearing** – It is the process of finalizing the transaction amount and successfully posting the transaction on the card account. The clearing is initiated by the merchant. If clearing is not received and processed within a specified time then the funds held on the card account will be released. * **Settlement** – It is a process which is used to transfer the funds from the cardholder's bank to the merchant’s bank or vice versa. Transactions can be authorized, cleared, and settled either as dual-message transactions (known as a Dual Message System) or as single-message transactions (known as a Single Message System). The processing method may vary depending upon the payment method issuer, the type of card, or the region in which the transaction takes place. * A **single-message** transaction can be recognized when the merchant submits a single electronic message containing all data required for the authorization, clearing, and settlement of the transaction. * A **dual-message** transaction can be recognized when the merchant submits an electronic message containing the information required for an authorization decision at the time of purchase and later point in time, the merchant submits a second message which contains an additional data required for clearing and settlement. Most transactions processed by merchants are dual-message transactions. Single-message transactions usually occur when a cardholder uses their PIN at a point of sale or at an ATM. Few other common transaction types besides authorization and clearing include: * **PIN based transactions** – These transactions recognized when a cardholder performs a payment transaction by using its PIN. These transactions typically contain all information required for authorization and clearing in a single electronic message. * **Reversals** – These type of transaction recognized when a merchant cancels a transaction after the authorization has succeeded but before the clearing has taken place. Reversals can be initiated for partial amount or full amount. * **Refunds** – These transactions occur when a cardholder requests a merchant to return the funds for a transaction after the clearing has completed for it. * **Chargebacks** – These are recognized as a dispute transactions and usually initiated by the issuer processor on behalf of their cardholders. # Transaction lifecycle nCore platform creates and keeps electronic messages received from the payment card network as an object called transaction. Transaction state changes during their lifecycle depends on whether they are in a temporary state or final state. Temporary and final transactions states are closely related to single-message and dual-message transactions. In dual-message transaction system there are two or more transaction messages requires to complete, for example: * The merchant submits an electronic message containing the information required for an authorization decision at the time or purchase. * Later point in time, the merchant submits another electronic message containing additional data which is required for clearing and settlement. In this scenario, the first message is a **temporary** transaction, which means it can be reversed. The last message is a **final** transaction. Temporary transaction messages, such as authorizations flows in real time from the merchant to the issuer processor and these are handled synchronously. However, the **final** transaction messages are handled asynchronously because these requests can be submitted later. Some transactions, for example a PIN based transactions contain all the information required for authorization and clearing in a single electronic message. These transactions are typically considered as **final** transactions that are handled synchronously. # Transaction types Following are the transaction types and definition | **Transaction type** | **Field transaction\_type** | **Definition** | | --------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Purchase | PURCHASE | It indicates that the transaction is any kind of card purchase, which can be identified in more detail via the pos\_environment field | | Cash withdrawal | CASH\_WITHDRAWAL | It indicates that the transaction is a cash withdrawal and it is performed by the cardholder at the ATM | | Refund | REFUND | A refund is a credit note on the card which can happen in case the customer bought something and gave it back, for example | | Balance Inquiry | BALANCE\_INQUIRY | It indicates that the transaction is checking the account balance on the ATM | | Account Verification | ACCOUNT\_VERIFICATION | This transaction type is use to verify the account when adding the card on a payment gateway portal, the payment gateway will generate a transaction just to verify that the account is valid (transaction amount = 0) | | Wallet Debit | WALLET\_DEBIT | It indicates that the transaction is unloading of funds | | Wallet Credit | WALLET\_CREDIT | It indicates that the transaction is the loading of funds | | Wallet Transfer | WALLET\_TRANSFER | It indicates that the transaction is account to account transfer | | Original Credit Transaction | OCT | It is a financial transaction that delivers funds directly to a recipient's eligible account | | Account Funding Transaction | AFT | It is a type of transaction where a payment service provider, such as a bank or a financial institution, directly debits a payment from a cardholder's account |
# Transaction endpoints scenarios You can use Transactions APIs for performing operations on individual transactions. In particular, Transactions APIs enables you to: * Retrieve a list of transactions initiated from a specific card by a specific cardholder at a specific merchants etc.. * Get a specific transaction record using transaction ID * Filter or retrieve a sorted list of transactions related to a specific user, performed at a specific time, specific transaction type or amount etc. ### **Search for transactions** nCore platform stores all transactions, which were fulfilled earlier. You can search the transactions based on the filter parameters enabled at nCore platform. **Transaction search use cases** 1. If you are preparing some financial statistics specific to merchants, you can call the /transactions:search endpoint to filter all transactions related to a specific merchant identified by the merchant\_name parameter. 2. If you are developing some customer relationship management system, you may have requests to get the list of transactions, conducted by a specific card. In this case, you can call the /transactions:search endpoint and use the card id query parameter to get transactions for the specific card. 3. If you are developing a mobile application, users may have a possibility to review their transaction history. In this case, you can call the /transactions:search endpoint and use the user\_id query parameter to get transactions conducted by a specific user. Send a **POST** request to **/transactions:search** endpoint as shown below to retrieve maximum ten transactions initiated with a specific card which are sorted by a transaction amount in ascending order.
POST /transactions:search **`{`**\ ` `**`"sort_by": "transaction_amount",`**\ ` `**`"order_by": "asc",`**\ ` `**`"limit": 10,`**\ ` `**`"filters": [`**\ ` `**`{`**\ ` `**`"field": "card_id",`**\ ` `**`"operator": "any_of",`**\ ` `**`"values": [`**\ ` `**`"z7a3a3f0-63b2-4619-a8d5-a3542188f5a6"`**\ ` `**`]`**\ ` `**`}`**\ ` `**`]`**\ **`}`**
### **Retrieve a specific transaction** \ This API call will display to you the full details of any transaction by sending a **GET** request to **/transactions/{id}** endpoint, where id is the transaction ID. > [**GET /transactions/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Transactions/operation/getTransactionById) #### Transaction status codes Below you can find a file with the list of transaction status codes, which can occur: {% file src="/files/UZaNWFjc7Hv64DATXsAX" %} #### Webhooks You can receive information about transactions as they occur by configuring webhooks. Webhooks give a possibility to receive real-time notifications about API events, such as card status change, transactions etc.. Learn more about webhooks in the [**Webhooks**](/get-started/webhooks) section. # Multi-clearing process We are excited to announce an enhancement to our multi-clearing process, designed to improve security and prevent negative balances in cardholder accounts. **Current Risk:** Currently, when processing completion-amount-lesser and multi-clearing transactions, we return the remaining authorized amount to the cardholder immediately. This carries the risk that if further multi-clearing transactions for the same authorization are received, the cardholder's account could go into a negative balance. **Enhancement:** With this new update, if the first clearing amount is less than the originally authorized amount, the remaining amount will no longer be immediately returned to the cardholder's wallet. Instead, the waiting time will be 30 days to allow any additional clearing transactions to be received and processed. If no additional clearings are received within this period, the remaining amount will then be returned to the cardholder with same Auth-aging process. **Example:** 1. A cardholder authorizes a transaction for $100. 2. The first clearing transaction is for $20. 3. Instead of immediately returning the remaining $80 to the cardholder, the waiting time will be 30 days. 4. If another clearing transactions for the remaining $80 is received within this period, it will be processed accordingly. 5. If no further clearing transactions are received, the $80 will be returned to the cardholder's account with Auth-aging process. # Source IBAN Validation We have added several new APIs to manage and store IBAN linking requests for SME users and accounts. These APIs ensure that IBANs are securely associated with accounts and can be used for validation purposes. Below you can find the list of relevant APIs: * [Link source IBAN with SME user/account](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/paths/~1v1~1accounts~1iban~1bulk~1link/post) - users can use this API to link source IBAN with SME (nCore) user\_id / account\_id and IBAN will be parked for admin approval. * [Update source IBAN linking with SME user/account](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/updateLinkedIban) - this API is used to update source IBAN linking with SME (nCore) user\_id / account\_id for validation. * [Delete source IBAN linking with SME user/account](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/deleteLinkedIban) - this API is used to delete source IBAN linking with SME (nCore) user\_id / account\_id for validation. * [Get linked source IBAN with SME user/account](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getLinkedAccountPerIbanOrAccountNumber) - this API is used to retrieve linked source IBAN with SME (nCore) user\_id / account\_id for validation. * [Get source IBAN of SME user/account](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getLinkedIbans) - this API is used to retrieve source IBAN of SME (nCore) user\_id / account\_id for validation. * [Upload document for later IBAN link](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/uploadDocumentForIbanLink) - this API is used to upload documents for later IBAN links. # VISA Click to Pay We have added several new APIs for Visa Click to Pay. It is a tokenized, EMV® Secure Remote Commerce-based solution designed to streamline and secure online checkout for cardholders, merchants, and issuers. Below you can find the list of relevant APIs: * [Retrieve CTP Enrollment Details](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Visa-Click-to-Pay/operation/listClickToPayEnrollments) - users can use this API to retrieve CTP enrollment details. * [Delete Visa Click to Pay Enrollment Data](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Visa-Click-to-Pay/operation/deleteVisaClickToPayEnrollmentData) - this API integrates with Visa’s Delete Data API to enable customers to delete their information into the Visa Click to Pay service. **Note:** * **User deleted** → All associated cards for that user are deleted (cascade delete) * **Card (instrument) deleted** → Only that specific card is deleted, user remains unaffected * [Retrieve Visa Click to Pay Enrollment by user ID](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Visa-Click-to-Pay/operation/getVisaClickToPayEnrollment) - this API is used to retrieve VISA Click to Pay Enrollment by User ID. # Webhooks # Introduction to webhooks Webhooks provide a powerful way to keep you aware of what's happening in your card program. Webhooks notifications are triggered by the nCore platform to notify about the different activities happening outside of your system, such as a card status change, a card transaction at a point-of-sale (POS) terminal, etc. For example, when a card is activated, a webhook notification is sent with details of the card status update from “card not active” to “a card is active” status to the preconfigured endpoint. To receive and process these notifications, you are required to configure a webhook endpoint in your environment. Webhooks are HTTPS requests sent from the nCore platform to your system as HTTPS POST requests. These requests contain JSON formatted information about the event and it is sent to a pre-configured receiving endpoint hosted on your system. **Essential uses** Following are the primary uses of webhooks notifications. * Financial record tracking:\ It can be used as a financial activity tracker, for example, load funds, transfers from one account to another account, etc. * Non-financial record tracking: \ It can be used as a non-financial activity tracker, for example, KYC verification and card lifecycle. # nCore webhook events Following are the available webhooks you can create to receive event notifications. | **Event name** | **Event type** | **Send webhook notification when** | | ------------------------ | --------------------------------- | ------------------------------------------- | | Status change | CARD\_STATUS\_CHANGE | A card status is updated | | Transaction | TRANSACTION | A transaction is performed by a card | | KYC | KYC\_RESULT | Changes in user’s KYC request are done | | User creation | USER\_CREATED | User is created | | User status | USER\_STATUS\_CHANGE | User status is changed | | User document | USER\_DOCUMENT\_ALERT | The document expiration date is approaching | | IDV | IDENTITY\_VERIFICATION | Identity verification needed | | PIN change | PIN\_CHANGE | PIN is changed | | Auth expiry | EXPIRED\_AUTH | Auth/pre-auth is expired | | Charges | CHARGE\_APPLIED | Charges are applied | | Account status | ACCOUNT\_STATUS\_CHANGE | Account status is changed | | Card provisioning | CARD\_PROVISIONING | Card is tokenized | | Token notification | TOKEN\_NOTIFICATION | Digital wallet token status is updated | | Card or account creation | SUCCESSFULLY\_CREATED | Card or account is successfully created | | Card delivery | CARD\_DELIVERY\_PARTNER\_ASSIGNED | Card delivery partner is assigned | | Card delivery | CARD\_DELIVERY\_STATUS\_CHANGED | Card delivery status is changed | **Handling** Following are the methods in which nCore platform handles webhooks notifications. * The nCore platform maintains a retry counter and resends the failed notifications by triggering the expired webhooks. * It includes a Basic Auth (encoded in base64) header in the webhook notification message. * The nCore platform pings a configured webhook to validate the credential and connectivity. * To support token uniqueness, each transaction is recognized by a unique transaction token, and each webhook is identified by a unique event token. # Steps to configure a webhook Following are the steps to configure a webhook. **1. Webhook event selection:** Select the webhook event for which you want to receive the notification as given below. > **`"events": [`**\ > ` `**`"CARD_STATUS_CHANGE"`**\ > ` `**`]`** **2. Decide the endpoint:** Decide the endpoint where you want to receive the webhook notification. Note that the endpoint should be hosted in your destination system. > **"endpoint": "**[**https://example.com**](https://nymcard.com/)**"** **3. Security configuration:** Determine the security characteristics as given below, choose the security credentials (username and password). > **`"config": {`**\ > ` `**`"basic_auth_username": "username",`**\ > ` `**`"basic_auth_password": "password",`**\ > ` `**`"custom_headers": [`**\ > ` `**`{`**\ > ` `**`"header_name": "apikey",`**\ > ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ > ` `**`}`** > > **`]`** **4. Create a webhook:** You can create a webhook now by sending a **POST** request to **/webhooks** endpoint as given below.
POST /webhooks **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"CARD_STATUS_CHANGE"`**\ ` `**`],`**\ ` `**`"config": {`**\ ` `**`"basic_auth_username": "username",`**\ ` `**`"basic_auth_password": "password",`**\ ` `**`"custom_headers": [`**\ ` `**`{`**\ ` `**`"header_name": "apikey",`**\ ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"created": "2021-05-27T18:48:00.074Z",`**\ ` `**`"modified": "2021-05-27T18:48:00.074Z"`**\ ` `**`}`**\ **`}`**
{% hint style="info" %} It is possible to link more than one event with a single endpoint. {% endhint %} # Webhooks samples nCore platform supported webhook events and sample notifications are given below. On this page you can find samples of the following webhooks: * [Card status change](#card-status-change-webhook) * [Transaction](#transaction-webhook) * [KYC result](#kyc-result-webhook) * [User creation](#user-creation-webhook) * [User status change](#user-status-change-webhook) * [User document alert](#user-document-alert-webhook) * [Identity verification](#identity-verification-webhook) * [PIN change](#pin-change-webhook) * [Authorizations and clearing](#authorization-and-clearing-webhooks) * [Auth/pre-auth expiry](#auth-pre-auth-expiry) * [Charges](#charges-webhook) * [Account status change](#account-status-change-webhook) * [Card provisioning](#card-provisioning-webhook) * [Token notification](#token-notification-webhook) * [Successfully created card/account](#successfully-created-card-account-webhook) * [Card delivery partner assignment](#card-delivery-partner-assignment-webhook) * [Card delivery status change](#card-delivery-status-change-webhook) ### Card status change webhook You can create webhook as shown in below example.
POST /webhooks **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"CARD_STATUS_CHANGE"`**\ ` `**`],`**\ ` `**`"config": {`**\ ` `**`"basic_auth_username": "username",`**\ ` `**`"basic_auth_password": "password",`**\ ` `**`"custom_headers": [`**\ ` `**`{`**\ ` `**`"header_name": "apikey",`**\ ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"created": "2021-05-27T18:48:00.074Z",`**\ ` `**`"modified": "2021-05-27T18:48:00.074Z"`**\ ` `**`}`**\ **`}`**
#### Webhook notification sample You will start to receive the notification for a card status change event (CARD\_STATUS\_CHANGE) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "CARD_STATUS_CHANGE",`** **`"card_status_change": {`** **`"card_id": "eef930c7-6e44-4846-948a-dfd7855484b6",`** **`"old_status": "ACTIVE",`** **`"new_status": "SUSPENDED",`** **`"status_reason_code": "S0",`** **`"note": {`** **`"category": "aaa",`** **`"description": "First time activation",`** **`"extras": {}`** **`}`** **`}`** **`}`**
### Transaction webhook You can create webhook as shown in below example.
POST /webhooks **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"TRANSACTION"`**\ ` `**`],`**\ ` `**`"config": {`**\ ` `**`"basic_auth_username": "username",`**\ ` `**`"basic_auth_password": "password",`**\ ` `**`"custom_headers": [`**\ ` `**`{`**\ ` `**`"header_name": "apikey",`**\ ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"created": "2021-05-27T18:48:00.074Z",`**\ ` `**`"modified": "2021-05-27T18:48:00.074Z"`**\ ` `**`}`**\ **`}`**
#### Webhook notification sample You will start to receive the notification for a transaction event (TRANSACTION) after creating a webhook endpoint as shown below. When the **event = TRANSACTION,** **message\_type = AUTHORIZATION;** then the webhook notification can be received for **CASH\_WITHDRAWAL, PURCHASE, BALANCE\_INQUIRY,** **REFUND,** and **REVERSAL** as per the configured transaction type shown below:
PURCHASE **`{`** **`"event": "TRANSACTION",`** **`"card_transaction": {`** **`"id": "9829a089-1804-40b6-9920-d31bacc07f17",`** **`"transaction_timestamp": "2022-09-23T12:13:01.295Z",`** **`"network": "VISA",`** **`"message_type": "AUTHORIZATION",`** **`"transaction_type": "PURCHASE",`** **`"transfer_type": "CHA2CHAOWN",`** **`"transaction_description": "Purchase",`** **`"transmission_date_time": "2022-09-23T12:13:01.000Z",`** **`"date_time_acquirer": "2022-07-18T19:16:25.000Z",`** **`"card_id": "8ac1eba8-9ccd-4cf7-acb1-8666007a9634",`** **`"card_first6_digits": "450133",`** **`"card_last4_digits": "4110",`** **`"card_expiry_date": "052024",`** **`"user_id": "2f8548e5-f505-491a-aeee-830948fa3046",`** **`"acquirer_id": "000000",`** **`"merchant_id": "MERCHID01",`** **`"mcc": "7386",`** **`"merchant_name": "ACQUIRER NAME",`** **`"merchant_city": "Abu Dhabi",`** **`"merchant_country": "ARE",`** **`"terminal_id": "111",`** **`"stan": "000022",`** **`"rrn": "226612000022",`** **`"auth_id_response": "962851",`** **`"transaction_amount": 100,`** **`"transaction_currency": "AED",`** **`"billing_amount": 100,`** **`"billing_currency": "AED",`** **`"billing_amount_account": 10,`** **`"billing_currency_account": "USD",`** **`"conversion_rate_billing_account": 1,`** **`"original_amount_billing": "null",`** **`"fee_amount": 1.5,`**\ **`"fee_details": [`**\ **`{`**\ **`"fee_id": "Fee1",`**\ **`"description": "PURCHASE FEE",`**\ **`"amount": 0.5,`**\ **`"currency": "AED",`**\ **`"is_advanced": false`**\ **`},`** **`"status_code": "0000",`** **`"status_description": "Transaction approved",`** **`"card_entry": "Unknown",`** **`"pos_environment": "Unknown",`** **`"fallback": false,`** **`"pin_present": false,`** **`"moto": false,`** **`"recurring": false,`** **`"installment_transaction": false,`** **`"reversal_count": 0,`** **`"`**[**`clear`**](#user-content-fn-1)[^1]**`ing_count": 0,`** **`"auth_expired_at":"2023-01-04T08:45:09.135Z",`** **`"auth_expired_by":"AUTO",`** **`"source_channel": "OPEN_BANKING",`** **`stip_reason_code: "9020",`** **`"sweep_details":`** **`[`** **`{`** **`"debit_from_currency": "USD",`** **`"debit_from_amount": 10.00,`** **`"credit_to_currency": "AED",`** **`"credit_to_amount": 36.70,`** **`"exchange_rate": "3.6153",`** **`"markup_percentage": 1.5,`** **`"markup_amount": 0.15,`** **`"markup_details": {`** **`"category": "INTERNAL",`** **`"percentage": 1,`** **`"amount": 0.1,`** **`"currency": "USD"`** **`},`** **`}]`** **`"notes": "Performing operation for 10 USD",`** **`"type": "HOLD",`** **`"incrementalTransaction": true,`** **`"isPreAuth": "Y",`** **`"isCancelled": "YES",`** **`"token_details": {`** **`"wallet_identifier": "APPLEPAY",`** **`"token_number": "458965212585236",`** **`"token_type": "01",`** **`"acquirerCountry": "USA",`** **`"device_details": {`** **`"device_type": "MOBILE_PHONE",`** **`} }`** **`}`** **`}`**
BALANCE_INQUIRY **`{`** **`"event": "TRANSACTION",`** **`"card_transaction": {`** **`"id": "bb5b17d3-31f7-43ff-9fe7-bcf4dd78f5f0",`** **`"transaction_timestamp": "2023-01-23T07:44:13.022Z",`** **`"network": "VISA",`** **`"message_type": "AUTHORIZATION",`** **`"transaction_type": "BALANCE_INQUIRY",`** **`"transfer_type": "CHA2CHAOWN",`** **`"transaction_description": "Balance Inquiry",`** **`"transmission_date_time": "2023-01-23T07:44:12.000Z",`** **`"date_time_acquirer": "2023-11-02T12:00:00.000Z",`** **`"card_id": "2a22806a-ff7d-4943-b75a-82baa255471d",`** **`"card_first6_digits": "450133",`** **`"card_last4_digits": "3167",`** **`"card_expiry_date": "092024",`** **`"user_id": "ahsansiddiqui34",`** **`"acquirer_id": "000000",`** **`"merchant_id": "MERCHID01",`** **`"mcc": "5011",`** **`"merchant_name": "ACQUIRER NAME",`** **`"merchant_city": "New York",`** **`"merchant_country": "ARE",`** **`"terminal_id": "TERMID01",`** **`"stan": "000044",`** **`"rrn": "302307000044",`** **`"auth_id_response": "379457",`** **`"transaction_amount": 0,`** **`"transaction_currency": "AED",`** **`"billing_amount": 0,`** **`"billing_currency": "AED",`** **`"fee_details": [],`** **`"status_code": "0000",`** **`"status_description": "Transaction approved",`** **`"card_entry": "Unknown",`** **`"pos_environment": "Unknown",`** **`"fallback": false,`** **`"pin_present": false,`** **`"moto": false,`** **`"recurring": false,`** **`"installment_transaction": false,`** **`"reversal_count": 0,`** **`"acquirerCountry": "USA",`** **`"clearing_count": 0`** **`}`** **`}`**
When the **event = TRANSACTION,** **message\_type = API;** then the webhook notification can be received for **WALLET\_CREDIT, WALLET\_DEBIT,** and **WALLET\_TRANSFER** as per the configured transaction type shown below:
WALLET_CREDIT ``` { "event": "TRANSACTION", "card_transaction": { "id": "wqwrhsDfEGGJn", "transaction_timestamp": "2022-09-23T11:15:01.043Z", "message_type": "API", "transaction_type": "WALLET_CREDIT", "transfer_type": "CHA2CHAOWN", "transaction_description": "Wallet Credit", "user_id": "0d7f87bf-0390-40a2-988a-c5cb0187066a", "account_id1": "1443a27f-46e7-44a3-b92b-f4391f634ed2", "card_product1": "DescrirptgefjjgfcfaFRjFrdproluf", "rrn": "2266111501sc", "transaction_amount": 3000, "transaction_currency": "AED", "fee_amount": 0, "feeDetail":[ { "fee_id":"173427", "description":"transaction fee", "amount":"6.0", "currency":"AED" }], "original_amount_billing": "null", "status_code": "0000", "load_id": "wqwrhsDfEGGJn", "reversal_count": 0, "clearing_count": 0, "notes": "Performing operation for 3000 AED", { "account_details":[ { "id":"1256352443", "balances":[ { "currency": "USD", "available_balance": 1500.75, "ledger_balance": 2000.00 }, { "currency": "AED", "available_balance": 1510.75, "ledger_balance": 2000.00 } ] }, } } ```
WALLET_DEBIT ``` { "event": "TRANSACTION", "card_transaction": { "id": "testeTsRRdgfyR", "transaction_timestamp": "2022-09-23T11:15:54.909Z", "message_type": "API", "transaction_type": "WALLET_DEBIT", "transfer_type": "CHA2CHAOWN", "transaction_description": "Wallet Debit", "user_id": "0d7f87bf-0390-40a2-988a-c5cb0187066a", "account_id1": "1443a27f-46e7-44a3-b92b-f4391f634ed2", "card_product1": "DescrirptgefjjgfcfaFRjFrdproluf", "rrn": "2266111554WY", "transaction_amount": 50, "transaction_currency": "AED", "fee_amount": 0, "original_amount_billing": "null", "status_code": "0000", "unload_id": "testeTsRRdgfyR", "reversal_count": 0, "clearing_count": 0, "notes": "Performing operation for 50 AED", { "account_details":[ { "id":"1256352443", "balances":[ { "currency": "USD", "available_balance": 1500.75, "ledger_balance": 2000.00 }, { "currency": "AED", "available_balance": 1510.75, "ledger_balance": 2000.00 } ] }, } } ```
WALLET_TRANSFER **`{`** **`"event": "TRANSACTION",`** **`"card_transaction": {`** **`"id": "b90e1563-7438-42b7-a997-9b871ad64ffb",`** **`"transaction_timestamp": "2022-09-23T14:26:42.881Z",`** **`"message_type": "API",`** **`"transaction_type": "WALLET_TRANSFER",`** **`"transfer_type": "CHA2CHAOWN",`** **`"transaction_description": "Wallet Transfer",`** **`"user_id": "hkuser282",`** **`"sender_user_id": "hkuser282",`** **`"account_id1": "77779999999999999210",`** **`"card_product1": "Description of the cardproducthk77",`** **`"account_id2": "77779999999999999211",`** **`"card_product2": "Description of the cardproducthk77",`** **`"rrn": "2266142642hO",`** **`"transaction_amount": 10,`** **`"transaction_currency": "AED",`** **`"fee_amount": 0,`** **`"original_amount_billing": "null",`** **`"status_code": "0000",`** **`"transfer_id": "b90e1563-7438-42b7-a997-9b871ad64ffb",`** **`"reversal_count": 0,`** **`"clearing_count": 0,`** **`"notes": "Performing operation for 10 AED",`** **`"receiver_user_id": "0dcbdc26-41cb-48b1-bdb8-b9e3db9ff40c"`** **`}`** **`}`**
Below you can find a document with transaction event types and messages scenarios: {% file src="/files/3PIvnITPBuvePcOEOuIa" %} ### KYC result webhook You can create webhook as shown in below example.
POST /webhooks **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"KYC_RESULT"`**\ ` `**`],`**\ ` `**`"config": {`**\ ` `**`"basic_auth_username": "username",`**\ ` `**`"basic_auth_password": "password",`**\ ` `**`"custom_headers": [`**\ ` `**`{`**\ ` `**`"header_name": "apikey",`**\ ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"created": "2021-05-27T18:48:00.074Z",`**\ ` `**`"modified": "2021-05-27T18:48:00.074Z"`**\ ` `**`}`**\ **`}`**
#### Webhook notification sample You will start to receive the notification for a KYC result event (KYC\_RESULT) after creating a webhook endpoint as shown below.
KYC_RESULT / KYC STATUS: SUBMITTED **`{`** **`"event": "KYC_RESULT",`** **`"kyc_policy": "UAE_INDIVIDUAL_PRIMARY",`** **`"kyc_id": "b70c8e15-fde2-420b-ba4b-e0a248231310",`** **`"user_id": "0d7f87bf-0390-40a2-988a-c5cb0187066a",`** **`"note": "Some note",`** **`"status": "SUBMITTED",`** **`"status_code": "S0",`** **`"created": "2022-09-22T06:08:07.987Z",`** **`"modified": "2022-09-22T06:08:07.987Z"`** **`}`**
KYC_RESULT / KYC STATUS: INCONCLUSIVE **`{`** **`"event": "KYC_RESULT",`** **`"kyc_policy": "UAE_INDIVIDUAL_PRIMARY",`** **`"kyc_id": "b70c8e15-fde2-420b-ba4b-e0a248231310",`** **`"user_id": "0d7f87bf-0390-40a2-988a-c5cb0187066a",`** **`"note": "Some note",`** **`"old_status": "SUBMITTED",`** **`"status": "INCONCLUSIVE",`** **`"status_code": "C0",`** **`"created": "2022-09-22T06:08:07.987Z",`** **`"modified": "2022-09-22T06:08:15.202Z"`** **`}`**
KYC_RESULT / KYC STATUS: PASS **`{`** **`"event": "KYC_RESULT",`** **`"kyc_policy": "UAE_INDIVIDUAL_PRIMARY",`** **`"kyc_id": "a0b896ef-ba81-43fc-ab23-b3d53359fe30",`** **`"user_id": "0d7f87bf-0390-40a2-988a-c5cb0187066a",`** **`"note": "Some note",`** **`"old_status": "SUBMITTED",`** **`"status": "PASS",`** **`"status_code": "P0",`** **`"created": "2022-09-22T06:09:32.215Z",`** **`"modified": "2022-09-22T06:09:37.802Z"`** **`}`**
### User creation webhook You can create webhook as shown in below example.
POST /webhooks **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"USER_CREATED"`**\ ` `**`],`**\ ` `**`"config": {`**\ ` `**`"basic_auth_username": "username",`**\ ` `**`"basic_auth_password": "password",`**\ ` `**`"custom_headers": [`**\ ` `**`{`**\ ` `**`"header_name": "apikey",`**\ ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"created": "2021-05-27T18:48:00.074Z",`**\ ` `**`"modified": "2021-05-27T18:48:00.074Z"`**\ ` `**`}`**\ **`}`**
#### Webhook notification sample You will start to receive the notification for a user creation event (USER\_CREATED) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "USER_CREATED",`** **`"user_id": "ea27ae20-82a6-4940-a361-bc52c3147d7f",`** **`"new_status": "PENDINGKYB",`** **`"new_status_reason_code": "I0",`** **`"user_type": "BUSINESS",`** **`"created": "2022-09-23T12:35:51.798Z"`** **`}`**
### User status change webhook You can create webhook as shown in below example.
POST /webhooks **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"USER_STATUS_CHANGE"`**\ ` `**`],`**\ ` `**`"config": {`**\ ` `**`"basic_auth_username": "username",`**\ ` `**`"basic_auth_password": "password",`**\ ` `**`"custom_headers": [`**\ ` `**`{`**\ ` `**`"header_name": "apikey",`**\ ` `**`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`**\ ` `**`}`**\ ` `**`],`**\ ` `**`"created": "2021-05-27T18:48:00.074Z",`**\ ` `**`"modified": "2021-05-27T18:48:00.074Z"`**\ ` `**`}`**\ **`}`**
#### Webhook notification sample You will start to receive the notification for a user status change event (USER\_STATUS\_CHANGE) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "USER_STATUS_CHANGE",`** **`"user_id": "0d7f87bf-0390-40a2-988a-c5cb0187066a",`** **`"old_status": "PENDINGKYC",`** **`"old_status_reason_code": "I0",`** **`"new_status": "ACTIVE",`** **`"new_status_reason_code": "A0",`** **`"user_type": "INDIVIDUAL",`** **`"created": "2022-09-22T06:09:37.839Z"`** **`}`**
### User document alert webhook You can create a webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/"`** **`"events": [`** **`"USER_DOCUMENT_ALERT"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2021-08-24T07:01:42.185Z",`** **`"modified": "2021-08-24T07:01:42.185Z"`** **`}`** **`}`**
#### Webhook notification sample You will start to receive the notification for a USER\_DOCUMENT\_ALERT event after creating a webhook endpoint. There are 2 types of notification samples for this webhook event: * triggered when document is near expiry
Sample **`{`** **`"event": "USER_DOCUMENT_ALERT",`** **`"alert_type": "DOCUMENT_NEAR_EXPIRY",`** **`"user_id": "9377a07a-a191-45b8-9af2-7635fea37274",`** **`"identification_id": "81e1f962-df62-4bdf-badd-51827074ad4d",`** **`"type": "NATIONAL_ID",`** **`"number": "804",`** **`"issuance_authority": "Ministry of Interior",`** **`"place_of_issuance": "Taiwan",`** **`"expiration_date": "2022-09-28",`** **`"issuance_date": "2022-09-16"`** **`}`**
* triggered when document is expired
Sample **`{`** **`"event": "USER_DOCUMENT_ALERT",`** **`"alert_type": "DOCUMENT_EXPIRED",`** **`"user_id": "116afe44-131b-4502-8369-7206f301f4ab",`** **`"identification_id": "23747e45-86f5-4973-87d6-7aa62e5f9071",`** **`"type": "NATIONAL_ID",`** **`"number": "705",`** **`"issuance_authority": "Ministry of Interior",`** **`"place_of_issuance": "Cocos (Keeling) Islands",`** **`"expiration_date": "2022-09-06",`** **`"issuance_date": "2022-08-26",`** **`"grace_period_end_date": "2022-11-05"`** **`}`**
### Identity verification webhook You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/"`** **`"events": [`** **`"IDENTITY_VERIFICATION"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2021-08-24T07:01:42.185Z",`** **`"modified": "2021-08-24T07:01:42.185Z"`** **`}`** **`}`**
#### Webhook notification sample You will start to receive the notification for an IDENTITY\_VERIFICATION event after creating a webhook endpoint. 1. Webhook received upon user creation:
Sample **`{`** **`"event": "IDENTITY_VERIFICATION",`** **`"user_id": "1ae3f657-5ce0-4fc6-8e56-c6d9e9866bac",`** **`"applicant_id": "a187fc40-1189-4d99-a878-9728f70bf81f",`** **`"sdk_token": "eyJhbGciOiJFUzUxMiJ9.eyJleHAiOjE2NjM5Mzg3NjMsInBheWxvYWQiOnsiYXBwIjoiYTE4N2ZjNDAtMTE4OS00ZDk5LWE4NzgtOTcyOGY3MGJmODFmIiwiY2xpZW50X3V1aWQiOiJiNjM1OTA3OC01N2Q4LTQyMGMtYjdkZC02NWMxODljMThmYmEiLCJpc19zYW5kYm94IjpmYWxzZSwic2FyZGluZV9zZXNzaW9uIjoiYjFlMDJiOTAtYmU3Mi00NWE3LTkwY2EtM2VjODBjNjViYzIxIn0sInV1aWQiOiJXdncyOTNleWFmMyIsInVybHMiOnsiZGV0ZWN0X2RvY3VtZW50X3VybCI6Imh0dHBzOi8vc2RrLm9uZmlkby5jb20iLCJzeW5jX3VybCI6Imh0dHBzOi8vc3luYy5vbmZpZG8uY29tIiwiaG9zdGVkX3Nka191cmwiOiJodHRwczovL2lkLm9uZmlkby5jb20iLCJhdXRoX3VybCI6Imh0dHBzOi8vYXBpLm9uZmlkby5jb20iLCJvbmZpZG9fYXBpX3VybCI6Imh0dHBzOi8vYXBpLm9uZmlkby5jb20iLCJ0ZWxlcGhvbnlfdXJsIjoiaHR0cHM6Ly9hcGkub25maWRvLmNvbSJ9fQ.MIGIAkIB15_-N53zYfYQZ1DigFvRl2eOxU5QpltIH-8391oiKnWQfhqSIYDWfJyMgjYT9s7I0CATsZxnljgRTEeb8NS5sKQCQgCsXWfHBnromgtaqCGGtimoXsc1n_nXNAkZqE-rS5FqVnn8OwjyO1CGphNI69uIzn_Jk04BAqyfiF4qjIIivP-ndA",`** **`"status": "PENDINGIDVERIFICATION",`** **`"status_reason_code": "I0"`** **`}`**
2\. Webhook received upon updating user status from PENDINIDVERIFICATION I0 to PENDINGIDVERIFICATION B0:
Sample **`{`** **`"event": "IDENTITY_VERIFICATION",`** **`"user_id": "user478",`** **`"applicant_id": "8ecac870-bf18-4583-8d8d-fa6bacca3cd5",`** **`"status": "PENDINGIDVERIFICATION",`** **`"old_status_reason_code": "I0",`** **`"status_reason_code": "B0"`** **`}`**
### PIN change webhook You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"PIN_CHANGE"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
#### Webhook notification sample You will start to receive the notification for a PIN change event (PIN\_CHANGE) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "PIN_CHANGE",`** **`"user_id": "hkuser282",`** **`"card_id": "77779999999999999212",`** **`"card_status": "ACTIVE",`** **`"card_status_reason": "A0",`** **`"created": "2022-09-27T12:39:51.293Z"`** **`}`**
### Authorization and clearing webhooks In the document below (docx or pdf format) you can find samples of such webhooks, as: * Cash withdrawal * Pre Auth and Incremental Authorization * Partial Reversals * Full reversals * Refund * Original Credit Transaction * Partial Capture Clearing * Over Capture Clearing * Multi-capture Clearing * Forced Capture Clearing * Partial Refund Clearing * Reverse Clearing {% file src="/files/4EuNEotdQIbzbL2DPDFy" %} DOCX format {% endfile %} {% file src="/files/lBLFoqWOGN3e91Fb9y07" %} PDF format {% endfile %} ### Auth/pre-auth expiry You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"EXPIRED_AUTH"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
You will start to receive the notification for an auth/pre-auth expiry event (EXPIRED\_AUTH) after creating a webhook endpoint as shown below.
Sample { "event": "EXPIRED\_AUTH", "card\_transaction": { "id": "3b9ac07c-4e5c-4b69-be55-1dee49320d2b", "transaction\_timestamp": "2023-01-04T08:27:43.390Z", "network": "VISA", "message\_type": "AUTHORIZATION", "transaction\_type": "PURCHASE", "transaction\_description": "Purchase", "transmission\_date\_time": "2023-01-04T08:27:42.000Z", "date\_time\_acquirer": "2023-01-04T13:27:40.000Z", "card\_id": "59e056c2-0645-48fb-890f-ef08ba1a7ff9", "card\_first6\_digits": "456789", "card\_last4\_digits": "0007", "card\_expiry\_date": "102024", "user\_id": "users1285", "acquirer\_id": "12345678901", "merchant\_id": "CARD ACCEPTOR", "mcc": "5999", "merchant\_name": "ACQUIRER NAME", "merchant\_city": "CITY NAME", "merchant\_country": "USA", "terminal\_id": "TERMID01", "stan": "001394", "rrn": "300408001394", "auth\_id\_response": "339305", "network\_transaction\_id": "313004045401395", "transaction\_amount": 10, "transaction\_currency": "USD", "billing\_amount": 10, "billing\_currency": "USD", "billing\_amount\_account": 10, "billing\_currency\_account": "USD", "conversion\_rate\_billing\_account": 1, "acquirer\_fee\_amount": 0.1, "fee\_amount": 0.5, "status\_code": "0000", "status\_description": "Transaction approved", "card\_entry": "Physical entry", "pos\_environment": "Attended POS", "fallback": false, "pin\_present": false, "moto": false, "recurring": false, "installment\_transaction": false, "reversal\_count": 1, "clearing\_count": 0, "auth\_expired\_at": "2023-01-04T08:45:09.135Z", "auth\_expired\_by": "AUTO" } }
### Charges webhook You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"CHARGE_APPLIED"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
You will start to receive the notification for charges event (CHARGE\_APPLIED) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "CHARGE_APPLIED",`** **`"charge_applied":`** **`{`** **`"id" : "ide20259037739",`** **`"card_id" : "3198413a-0083-4dbc-92cf-77f47f1ee23b",`** **`"account_id" : "43b1a6d8-6cf2-4abe-ac01-52d5c50753e8",`** **`"charge_id" : "irty20259345354",`** **`charge_type : "PHYSICAL_CARD_ISSUANCE"`** **`"amount" : 5.00,`** **`"currency" : "USD",`** **`"description" : "ISSUANCE CHARGES - Yearly 2023"`** **`}`** **`}`**
### Account status change webhook You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"ACCOUNT_STATUS_CHANGE"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
You will start to receive the notification for account status event (ACCOUNT\_STATUS\_CHANGE) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "ACCOUNT_STATUS_CHANGE",`** **`"old_status": "ACTIVE",`** **`"new_status": "TERMINATED",`** **`"account_id": "0a8735ca-2c2d-4a5f-bfd3-79b20c60ea14",`** **`"note": "Changing the account status from to ."`** **`}`**
### Card provisioning webhook {% hint style="info" %} Please note that CARD\_PROVISIONING event is only applicable for VISA at the moment. {% endhint %} You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"CARD_PROVISIONING"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
You will start to receive the notification for card provisioning event (CARD\_PROVISIONING) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "CARD_PROVISIONING",`** **`"user_id": "055ef899-9650-4700-9497-e71826dd2825",`** **`"card_id": "055ef899-9650-4700-9497-e71826dd2822",`** **`"network": "VISA",`** **`"wallet_identifier": "APPLEPAY",`** **`"token_number": "458965212585236",`** **`"token_type": "SECURE_ELEMENT",`** **`"device_name": "Apple MaxPro 14",`** **`"device_type": "MOBILE_PHONE",`** **`"status": "APPROVED",`** **`"created": "2018-01-02T19:42:32.987Z",`** **`"pan_source": "MOBILE_BANKING_APP",`** **`"consumer_entry_mode": "KEY_ENTERED",`** **`"timestamp": "2025-09-18T12:32:26.059Z",`** **`"device_ip_address_v4": "49.207.217.141",`** **`"client_wallet_account_id": "933F30AC6A9A9631",`** **`"token_expiration_date": "09/2028",`** **`"number_of_active_tokens_for_pan": 0`** **`}`**
### Token notification webhook You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"TOKEN_NOTIFICATION"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
You will start to receive the notification for token notification event (TOKEN\_NOTIFICATION) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "TOKEN_NOTIFICATION",`** **`"alert_type": "TOKEN_STATUS_UPDATE",`** **`"user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",`** **`"card_id": "145236599",`** **`"token_info":`** **`{`** **`"id" : "124563289",`** **`"token_reference_id" : "56985236",`** **`"old_token_status" : "INACTIVE",`** **`"new_token_status" : "INACTIVE",`** **`"token_requestor_id" : "523658963246",`** **`"wallet_provider": "APPLEPAY"`** **`},`** **`"device_info":`** **`{`** **`"device_id" : "124563289",`** **`"device_type" : "MOBILE",`** **`"device_name" : "apple",`** **`"device_number" : "523658963246"`** **`}`** **`"pan_source": "MOBILE_BANKING_APP",`** **`"consumer_entry_mode": "KEY_ENTERED",`** **`"timestamp": "2025-09-18T12:32:26.059Z",`** **`"device_ip_address_v4": "49.207.217.141",`** **`"client_wallet_account_id": "933F30AC6A9A9631",`** **`"token_expiration_date": "09/2028",`** **`"number_of_active_tokens_for_pan": 0`** **`}`**
### Successfully created card/account webhook You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"SUCCESSFULLY_CREATED"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
You will start to receive the notification for this event (SUCCESSFULLY\_CREATED) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "SUCCESSFULLY_CREATED",`** **`"event_type": "card_created",`** **`"user_id": "Buiness_user_for_MSRQ_bank",`** **`"card_details": {`** **`"card_id": "d7c5451f-d381-409e-a9dc-05ea557c3dfd",`** **`"first_four_digits": "473212",`** **`"last_four_digits": "5966",`** **`"name_on_card": "Ahsan Siddiqui",`** **`"card_product_id": "CP_04",`** **`"card_type": "PHYSICAL",`** **`"status": "INACTIVE",`** **`"status_reason": "I2"`** **`}`** **`}`**
### Card delivery partner assignment webhook You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"CARD_DELIVERY_PARTNER_ASSIGNED"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
You will start to receive the notification for this event (CARD\_DELIVERY\_PARTNER\_ASSIGNED) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "CARD_DELIVERY_PARTNER_ASSIGNED",`** **`"user_id": "User_QA_210525_02",`** **`"card_id": "264c6885-1b73-4f50-88df-b00aa215894e",`** **`"waybill_number": "44262738752",`** **`"status_description": "Delivery partner assigned",`** **`"modified_date": "2025-06-18T06:19:52.652Z"`** **`}`**
### Card delivery status change webhook You can create webhook as shown in below example.
POST /webhooks **`{`** **`"endpoint": "https://example.com/",`** **`"events": [`** **`"CARD_DELIVERY_STATUS_CHANGED"`** **`],`** **`"config": {`** **`"basic_auth_username": "username",`** **`"basic_auth_password": "password",`** **`"custom_headers": [`** **`{`** **`"header_name": "apikey",`** **`"header_value": "306e38e4-54be-469f-beca-4297129289d6"`** **`}`** **`],`** **`"created": "2022-08-24T07:01:42.185Z",`** **`"modified": "2022-08-24T07:01:42.185Z"`** **`}`** **`}`**
You will start to receive the notification for this event (CARD\_DELIVERY\_STATUS\_CHANGED) after creating a webhook endpoint as shown below.
Sample **`{`** **`"event": "CARD_DELIVERY_STATUS_CHANGED",`** **`"user_id": "User_QA_210525_02",`** **`"card_id": "65b4bcb8-b112-470b-95dc-6bc1b686af4e",`** **`"waybill_number": "44262738741",`** **`"status_description": "Picked Up From Shipper",`** **`"modified_date": "2025-03-07T15:43:00.000+03:00"`** **`}`**
Below you can find several examples, which can be returned by '**`status_description'`** parameter in the sample above: • Record Created – The shipment record has been created in the system.\ • Picked Up From Shipper – The package has been collected from the sender.\ • Received at Origin Operation Facility – The package has reached the first processing center.\ • Out for Delivery – The package is out for final delivery to the recipient.\ • Delivered – The package has been successfully delivered. {% hint style="info" %} Please note that if there is an event update, the job retrieves the status and forwards it to clients at two-hour intervals. {% endhint %} [^1]: # Webhook changes for simulation We have added the ability to simulate (pre-defined successful) user’s status and to proceed for completing the user verification process ( for KYC and IDV) on the test environments (DEV, Staging, Sandbox, UAT). Below you can find respective webhook changes - the new fields in USER\_STATUS\_CHANGE & KYC\_RESULT webhooks. Changes in USER\_STATUS\_CHANGE webhook - new "note" field: ``` // { "event": "USER_STATUS_CHANGE", "user_id": "muhaysaaduser18JAN23", "old_status": "PENDINGKYC", "old_status_reason_code": "I0", "new_status": "ACTIVE", "new_status_reason_code": "A0", "user_type": "INDIVIDUAL", "note": "service.kyc.simulation", "created": "2023-01-18T11:55:23.976Z" } ``` Changes in KYC\_RESULT webhook - new "status\_description" field: ``` // { "event": "KYC_RESULT", "kyc_policy": "UAE_INDIVIDUAL_PRIMARY", "kyc_id": "performkyca18JAN2301", "user_id": "muhaysaaduser18JAN23", "note": "Some note", "old_status": "SUBMITTED", "status": "PASS", "status_code": "P0", "status_description": "service.kyc.simulation", "created": "2023-01-18T11:55:23.840Z", "modified": "2023-01-18T11:55:23.946Z" } ``` # Webhooks management You can create and manage your webhooks events by using our APIs. Following are the APIs available at nCore platform for webhooks event management. * Update a webhook * Get a list of webhooks * Get a specific webhook * Delete a webhook * Ping an existing webhook * Trigger an expired webhooks * Search webhooks ### **Update a webhook** You can update the existing webhook as required. Send a **PUT** request to **/webhooks/{id}** endpoint to update a webhook. Include the webhook ID as a path parameter to indicate the webhook which is required to be updated.
PUT /webhooks/{id} **`{`**\ ` `**`"endpoint": "`**[**`https://example.com/`**](https://example.com/)**`",`**\ ` `**`"events": [`**\ ` `**`"CARD_STATUS_CHANGE"`**\ ` `**`]`**\ **`}`**
### **Retrieve webhooks** The nCore platform offers the following retrieval options for webhooks. ***Retrieve all webhooks*** You can retrieve all existing webhooks by sending a **GET** request to **/webhooks** endpoint as shown below. > [**GET /webhooks**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Webhooks/operation/listWebhookNotifications) ***Retrieve a specific webhook*** You can retrieve a specific webhook by sending a **GET** request to **/webhooks/{id}** endpoint, where id is the webhook ID. > [**GET /webhooks/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Webhooks/operation/getWebhook) ### **Delete a webhook** You can delete a specific webhook by sending a **DELETE** request to **/webhooks/{id}** endpoint, where id is the webhook ID. > [**DELETE /webhooks/{id}**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Webhooks/operation/deleteWebhook) ### **Ping a webhook** You can ping an existing webhook endpoint for testing purposes (for example, to validate credentials and connectivity). You can send a **POST** request to **/webhooks/{id}:ping** endpoint, where id is the webhook ID. > [**POST /webhooks/{id}:ping** ](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Webhooks/operation/pingWebhook) ### **Trigger expired webhooks** A webhook notification is counted as successfully transmitted when a positive response is received from your system. If a positive response is not received, then the platform retries to transmit the webhook notification. The number of retry attempts and the interval between retries (in seconds) are configured. If all the retries are exhausted for an individual notification event then that event is marked as expired. It is possible to mark the expired events for retransmission on your request by sending a **POST** request to **/webhooks/sendexpired** endpoint.
POST /webhooks:sendexpired **`{`** **`"notification_id": “b012776c-ab74-4ece-8403-0bbb9130508c”`** **`}`**
### **Search webhooks** You can search webhooks by sending a **POST** request to **/webhooks:search** endpoint as shown below. > [**POST /webhooks:search**](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Webhooks/operation/searchWebhooks) # Security # PCI widget ### PCI DSS compliance details nCore is certified for Payment Card Industry Data Security Standards (PCI DSS) as a Level 1 Service Provider. PCI compliance is a shared responsibility between both NymCard and your business. When processing, storing and forwarding payments transactions, it is essential that you do so in a PCI compliant procedure. The complexity of this depends upon your integration methods. However, the easiest way to remain PCI compliant is never to access or read your customers' card data. To make this simple for you, we have some significant integration advices below. * Use Transport Layer Security TLS for all payment pages, i.e. HTTPS * Always stay compliant. Review and validate your PCI compliance once a year * If you are non-PCI compliant, use our PCI widget that enables you to show sensitive card data without ever handling it. **PCI widget** Companies that store, process, or transmit **sensitive card data\*** must comply with the Payment Card Industry Data Security Standard (PCI DSS). Achieving PCI DSS certification is both tedious and costly. If you want to handle sensitive card data, you will be required to comply with PCI DSS security requirements and obtain relevant PCI DSS certification. This can be a challenging task specially for small businesses. To help you in reducing the scope and burden of PCI compliance, the nCore performs all the handling of sensitive data so that the sensitive data is never stored, processed and broadcasted through your systems or applications. nCore offers widgets which you can embed in your frontend applications (mobile and web applications) that will handle the sensitive data and get the required functionality executed without exposing sensitive data to your systems. **\*What is sensitive card data?** Sensitive card data includes: * Primary account number (PAN) * Card verification value (CVV2) * Primary Identification Number (PIN) ### **PCI widget usage** Using the PCI widget, you can perform the following actions: * Show clear card details * Get PIN * Change PIN Below you can find an instruction on how to do it: 1.Perform **“**[**Create LUT**](https://nymcard.com/docs/api#tag/Cards/operation/createLut)**”** API. LUT is a limited usage token, which has a timeout of 5 minutes before getting used. Each LUT is for one time use. For creating LUT you need fill the following parameters: * ‘id’ - ID of the card or proxy number, which info you want to encrypt * ‘source\_id’ - put "default\_pci\_source" here * ‘operation’ - put "SHOW\_CLEAR\_CARD\_DETAILS" or "GET\_PIN" " or "CHANGE\_PIN", depending on the action you want to fulfill Below there is an example of request for showing a card details:
POST /cards/{id}:createLut **`{`** **`"source_id": "default_pci_source",`** **`"operation": "SHOW_CLEAR_CARD_DETAILS"`** **`}`**
Response sample **`{`** **`"token": "fMQaLj+HpuCnm9hssEd9qlfFHiitpnxfq+yTHZppiSStXcqwkD/PxFKTJgvSPi/Y"`** **`}`**
2\. Encode LUT token together with ‘card\_id’ value or proxy number and ‘source\_id’="default\_pci\_source" using Base64 encryption format. {% hint style="warning" %} Note, that ‘source\_id’="default\_pci\_source" only for sandbox and staging environments. For production environment, please ask for the 'source\_id' from the customer success team. {% endhint %} Below you can find an example of data which should be encoded: > **`{"card_id":"85c8360d-e53d-429c-8124-b1c43de1c9da","lut":"fMQaLj+HpuCnm9hssEd9qlfFHiitpnxfq+yTHZppiSStXcqwkD/PxFKTJgvSPi/Y","source_id":"default_pci_source"}`** {% hint style="info" %} Note, that **for testing purposes** you can also encode 'api\_key' together with above mentioned parameters. {% endhint %} 3\. Take the following URL and add base64 encrypted token to it. Below you can see an example: > **`https://showcardwidget.sand.platform.nymcard.com/reveal-card-details/eyJjYXJkX2lkIjoiODVjODM2MGQtZTUzZC00MjljLTgxMjQtYjFjNDNkZTFjOWRhIiwibHV0IjoiNW0yYjFMeFhSM2EwRUN5bmZvZ2ttYUFwTlRjV0JjclcxKzBWT1dkaDZ0ZEI4eFdJWWlabHFGSXM5Z09rVHBlcCIsInNvdXJjZV9pZCI6ImRlZmF1bHRfcGNpX3NvdXJjZSJ9`** {% hint style="info" %} Note, that part of this URL depends on the operation, which you have chosen: * reveal-card-details * get-card-pin * change-card-pin {% endhint %} \ 4\. Put this URL in a web browser or inside the mobile application. In case of mobile application, you should also embed the following code: > **``** Where ‘urlSafe’ is the same as in step 3: > **`"https://showcardwidget.sand.platform.nymcard.com/reveal-card-details/eyJjYXJkX2lkIjoiODVjODM2MGQtZTUzZC00MjljLTgxMjQtYjFjNDNkZTFjOWRhIiwibHV0IjoiNW0yYjFMeFhSM2EwRUN5bmZvZ2ttYUFwTlRjV0JjclcxKzBWT1dkaDZ0ZEI4eFdJWWlabHFGSXM5Z09rVHBlcCIsInNvdXJjZV9pZCI6ImRlZmF1bHRfcGNpX3NvdXJjZSJ9"`** 5\. PCI widget will be loaded and you will see info, depending on the operation you have chosen: * clear card details ![](https://lh3.googleusercontent.com/qrvjiRj6rBq2w8KHnwzDNpHQoGzNdjdsPwpKEMhQpds_lalPI7XBG1mrgJssBlbnK944ytf0pYN4kI6_55cpIuW-hnsYI6-2-C7yxr1hswKIQH2nw1xbSINTkptrpqHT2cNlrkyg) * PIN itself ![](https://lh6.googleusercontent.com/Ve0L_CJ0ZtYjZZCNXgzqa011eWjI9QDiC_ULPNf6-WyC_Iu7vRM8t5hTgkxd6ghaFI0JkhNnLfWN6p2PyOmust5chd2BmzUd8VieEU2EwPRBO5OvuSZGSNQVNPNuomPoc1h04zfv) * “Change PIN” window ![](https://lh5.googleusercontent.com/Gh3F63edALodH7R5nfLytZiM6RocJ7_Ew0L1SRkXjQaSpf2j8WhMCM_Y4ObYuKXBTx1rFdKM785eaFDhZtQH-mVh1-syeM-obd8HxAR6n4H_VUt5yruAR4Er9FDx0YDylwUdcjXH) {% hint style="info" %} Note that Get PIN/change PIN functionality is applicable only for physical cards. Also PIN length should be aligned with 'pin\_length' parameter, which is set on card product level. {% endhint %} For any additional information, please contact NymCard representatives at . # 3D Secure **3D Secure** is a protocol that introduces an additional layer of security to improve internet payments experience for e-commerce. The 3D stands for the three different entities which are involved in providing this added security. * The acquirer entity (For Example: The merchant shop) * The interchange entity (For example: The payment card network) * The issuer entity (For example: The nCore platform) nCore supports both 3D Secure 1 and 3D Secure 2 protocols. Details are given below. **3D Secure version 1:** 3D Secure version 1 requires authenticating the cardholder before processing the e-commerce transaction. It is to authorize online transactions by requesting customers to complete a verification with the issuer every time. For example, when the merchant initiates 3D Secure authentication, the cardholder must then enter a one-time passcode (OTP) received via SMS or email to continue with their online purchase. {% hint style="info" %} Note, that the strings \ and \ should be uppercase in SMS template body. {% endhint %} **3D Secure version 2:** 3D Secure version 2 is a new and improved secure authentication protocol, which makes several enhancements to the original 3D Secure protocol version 1. Even though 3D Secure 1 provided good security, 3D Secure 2 gives an enhanced cardholder experience and it is updated for payments made using smartphones and wallets (for example Apply Pay, Google Pay or Samsung Pay etc), also leveraging advanced authentication like biometrics. 3D Secure version 2 provides seamless shopping experience, increased approval rate, and maximum security for merchants and their customers. Main advantages are: * **Frictionless flow** does not require any interaction from the cardholder * **Challenged based flow** has a high risk, **additional authentication**\* is required which brings higher authorization rates with lower fraudulent transactions **What does “additional authentication\*” mean?** It means that the issuer has the capability and access to significantly more transaction data points like merchant address, URL, device information, billing address & etc to take decision and route cardholder either to a frictionless flow or the challenged based flow. **3DS 1 vs 3DS 2:** | **S No** | **3D Secure 1** | **3D Secure 2** | | -------- | --------------------- | ------------------------------------------------------------ | | 01 | Static password - OTP | Frictionless flow with no cardholder action required | | 02 | High abandonment | Better risk analysis which reduce false declines | | 03 | Outdated Technology | Compliant with latest technology and regulatory requirements | | 04 | Low adaptation | High compatibility | {% hint style="info" %} For more about using 3D Secure with the nCore platform, please contact Nym*C*ard’s representative. {% endhint %} # OTP SMS templates Below you can find several examples of notifications, which you can use in SMS in '[Create template](https://nymcard.com/docs/api#tag/Notification-Templates/operation/createTemplate)' API: {% code title="Example 1" overflow="wrap" %} ``` // is your OTP for online purchase of at thru card ``` {% endcode %} {% code title="Example 2" overflow="wrap" %} ``` // Your OTP to complete your transaction of at for card is ``` {% endcode %} {% code title="Example 3" overflow="wrap" %} ``` // For transaction of at on card card , the OTP is ``` {% endcode %} # Release announcements ### Changes in Upcoming Release * Added new versions of '[Get Account Limits Info](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getCardLimitsV2)' and '[Get Card Limits Info](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardsLimitsV3)' APIs in order to improve system stability and standardize limit handling. * Velocity Limits API – The existing Velocity Limits API is now marked as deprecated (Old Service). We strongly recommend migrating to the Advanced Velocity Limits API, which will be the supported path going forward '[Get Account Limits Info](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getCardLimitsV2)' . * ALL\_TIME to be removed from Velocity Limit only. Clients can use it in Advance Velocity Limit. * Get Card Limits Info API – The existing Get Card Limits Info API is now marked as deprecated (Old Service). Migrated to Get Card Limits Info (v2), which will be the supported version moving forward. '[Get Card Limits Info](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardsLimitsV3)'. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (29/07/2026) * Changes in Visa Direct APIs for corridors and Get List of Fields. * Enhancement in Foreign Exchange Rates(GetIndicativeRate) API Response. * Validate Payout API Enhancement as Account Verification Service (AVS) Mode. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/07/2026) * Changes in Advance Limit for Withdrawal Transactions to support Merchant\_id condition type. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (01/07/2026) * Support Additional Transaction Types in Advance Velocity Limit. For more information, refer to this [API Catalog](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Velocity-Limits). * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (17/06/2026) * Support additional transaction types in Advanced Fees. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (02/06/2026) * Introducing new account status reason code for accounts that have been flagged as delinquent. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (13/05/2026) * Introduced several new APIs for Visa Click to Pay. It is a tokenized, EMV® Secure Remote Commerce-based solution designed to streamline and secure online checkout for cardholders, merchants, and issuers. For more information, refer to this [API Catalog](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Visa-Click-to-Pay/operation/listClickToPayEnrollments) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (29/04/2026) * Changes in linking multiple merchant lists to card and card product - V2 [`Merchant allowed APIs`](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/getAllowedMerchant) [`Merchant Link/Unlink APIs`](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/cards/operation/linkAllowedMerchantsToCardV2) [`Card Product Link APIs`](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/card-products/operation/unlinkAllowedMerchantsFromCardProductV2) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/04/2026) * Changes in recipient details on VISA Payout [`APIs`](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Remittance-VISA-Direct/operation/validateVisaDirectPayout) with respect to country of birth and date of birth. * Address and country in Payout Recipient Details are now not mandatory. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients ### Release Notes (01/04/2026) * Added new versions of '[Get Account Limits Info](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getCardLimitsV2)' and '[Get Card Limits Info](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardsLimitsV3)' APIs in order to improve system stability and standardize limit handling. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (18/03/2026) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (04/03/2026) * Added a new "invoice\_translation\_id" parameter in the response of '[Upload payment invoice](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Invoice-management/operation/uploadPaymentInvoice)' and '[Get payment invoice details](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Invoice-management/operation/getPaymentInvoiceDetails)' APIs. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (18/02/2026) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (10/02/2026) * Added several new [APIs](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Notification-Templates/operation/createMarketingCampaign) for triggering marketing push notifications. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (22/01/2026) * Added a new status reason code to '[Users](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Users)' APIs - A1R (Active – Passport Rejected). * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (24/12/2025) * Added several new enum values to the `dispute_status` parameter in the ‘[Dispute credit card transaction](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Credit/operation/disputeTransaction)’ API, enabling automatic dispute processing based on dispute status and product-level chargeback settings. * Added the `stip_reason_code` filter to the '[Search for transactions](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Transactions/operation/searchNymcardTransactions)’ API. * Added several new enhancements to [FX rates](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates) APIs to support calculation of the markup amount as part of a quotation. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (10/12/2025) * Added a new `revert_rule_structure` parameter to the [Delinquency](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/createDelinquency) APIs, allowing you to define multiple revert rules for a delinquency action. This lets you configure different revert conditions based on both the number of delinquency days and the percentage of the statement balance paid. The parameter supports two enum values: `BASIC` and `ADVANCED`. If `revert_rule_structure` is not provided, it defaults to `BASIC` to ensure legacy implementations remain functional. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (26/11/2025) * Added support for initiating payments in the checkout widget using an account ID in addition to a card ID, enabling payments to be made directly to an account. For more information refer to [Checkout widget](/get-started/funding-and-transfers/checkout-widget). * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (12/11/2025) * Added a new ‘acquirerCountry’ parameter to Transaction [webhook sample](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook), which provides acquirer country details. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (29/10/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/10/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (01/10/2025) * Added several new fields to the CARD\_PROVISIONING and TOKEN\_NOTIFICATION [webhook events](https://docs.nymcard.com/get-started/webhooks/webhooks-samples), enabling users to view the required details for each event. * Introduced a merchant list functionality, which gives the ability to allow transactions from specific merchants. For more information refer to this [page](https://docs.nymcard.com/get-started/product-management/authorization-controls#merchant-lists). * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (19/09/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (03/09/2025) * Added several new [APIs](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/createCardDesign), which help to upload and manage the card design using the provided design ID so that the same design can be linked to multiple card products. * Updated descriptions of 'allow\_outgoing\_sweeps' and 'allow\_incoming\_sweeps' parameters in [currency settings](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Card-Products/operation/Create%20card%20product) of Card products according to an enhanced business logic. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/08/2025) * Added a new ‘is\_advanced’ parameter to Transaction [webhook sample](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook), which provides advanced fee details. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (06/08/2025) * Introduced several new APIs to manage and store IBAN linking requests for SME users and accounts. These APIs ensure that IBANs are securely associated with accounts and can be used for validation purposes. For more information, refer to this [GSG page](/get-started/transactions/source-iban-validation). * Added a new `"SETTLE"` enum to the `execution_type` parameter in the '[Transfer funds between accounts (version 2)](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fund-Transfers/operation/transferV2)' API. This enables users to transfer funds between NYMCARD wallets of the same currency, with the additional capability to execute the transaction using the SETTLE mechanism. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (23/07/2025) * Added 'source\_channel' filter in '[Search for transaction](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Transactions/operation/searchNymcardTransactions)' API. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (09/07/2025) * Added version 2 of the '[Transfer funds between accounts](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Fund-Transfers/operation/transferV2)' API, enabling users to transfer funds from their NYMCARD wallet to another NYMCARD wallet in the same currency. Comparing with version 1 API, we have added 2 new parameters - 'original\_transaction\_id' and 'execution\_type' ( with HOLD, POST and RELEASE enums). * Introduced 2 new APIs: '[Get card tracking details](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardsTracking)' and '[Get card delivery status](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardDeliveryStatus)', which allow to retrieve card tracking information and delivery status. * Added 2 new [webhook events](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Webhooks/operation/createWebhookNotification), 'CARD\_DELIVERY\_PARTNER\_ASSIGNED' and 'CARD\_DELIVERY\_STATUS\_CHANGED', which notify you whenever a card delivery status is changed or a delivery partner is assigned to a shipment. Webhook samples can be found [here](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#card-delivery-partner-assignment-webhook). * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (25/06/2025) * Added a new [API](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Users/operation/relinkCardAccount) that enables the re-linking of bulk-issued cards and pre-linked accounts from a business user to an individual user, allowing individual users to gain ownership of their cards and perform transactions independently. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (11/06/2025) * Introduced the Checkout widget, allowing non-PCI-compliant customers to securely collect and submit card details. For more information, refer to [this](https://docs.nymcard.com/get-started/funding-and-transfers/checkout-widget) page. * Added a new 'soft\_expiry\_date' parameter to the '[Set Card Soft Expiry](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/updateSoftExpiry)' API, enabling explicit assignment or update of the card's soft expiry to a specific date value. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (28/05/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (09/05/2025) * Added a new ‘transfer\_type' enum within the 'filters' parameter in '[Search for transactions](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Transactions/operation/searchNymcardTransactions)’ API. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (30/04/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (14/04/2025) * Added new parameters, 'dry\_run' and 'transaction\_type,' to the '[Request FX rate quote](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/FX-rates/operation/getFxRatesQuote)' API. These parameters allow you to control whether a quotation is stored in the system and define the type of transaction being processed. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (26/03/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (12/03/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (21/02/2025) * Added new status reason codes to ['Users](https://nymcard.com/docs/api#tag/Users)' APIs - S10 (Suspended by Host via automatic external creation) and A10 (Active, not verified by Host). * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (12/02/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (29/01/2025) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/01/2025) * Implemented a new '[Get all MDES tokens](https://nymcard.com/docs/api#tag/MDES-Tokens/operation/listMdesTokens)' API, which allows you to retrieve the data of tokenized cards. * Added a new 'design\_code' parameter to the [Cards](https://nymcard.com/docs/api#tag/Cards) APIs. This parameter enables a card to be printed with the design selected by the user when requesting the card. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (21/12/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (18/12/2024) {% hint style="info" %} **New Features** {% endhint %} * Added a new “[Find applicable advanced fees](https://nymcard.com/docs/api#tag/Advanced-Fees/operation/findApplicableAdvancedFees)” API, which allows you to return advance fees against several specific parameters. * Added a new '[Remittance - Mastercard](https://nymcard.com/docs/api#tag/Remittance-Mastercard)' section to API catalog, which includes bunch of new APIs. It gives a possibility to integrate with Mastercard Cross-Border Services to conduct remittances. The Cross-Border Service APIs enable financial institutions and partners to build flexible solutions that support many different funds transfer and payment types via a single connection to Mastercard. {% hint style="success" %} **Improvements** {% endhint %} * Added 'balances' parameters to the webhook TRANSACTION event, allowing you to easily identify the balances information. A sample webhook can be found [here](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook). * Added a new 'auth\_id\_response' parameter to the nFront "[Simulate authorization transaction](https://nymcard.com/docs/api#tag/Transactions/operation/simulateTransaction)" API, which is used for Unionpay 'cancellation' transaction type. {% hint style="danger" %} **Bug fixes** {% endhint %} * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (04/12/2024) * Added new '[Get account limits info](https://nymcard.com/docs/api#tag/Accounts/operation/getCardLimits)' API, which allows you to retrieve the details of all available limits associated with an account. * Added new status reason code S9 (Suspended by Host) to ['Users](https://nymcard.com/docs/api#tag/Users)' APIs. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/11/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (06/11/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (23/10/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/10/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (30/09/2024) * Changed the length of the 'first\_name' and 'last\_name' parameters from 40 to 60 characters in the Users APIs to accommodate users with longer names during registration. ### Release Notes (24/09/2024) * Added new 'native\_last\_name' parameter to Users APIs, so that user's last name can be stored in native language. * Added a new webhook event, 'SUCCESSFULLY\_CREATED', which notifies you whenever an account or card is successfully created. A sample webhook can be found [here](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#successfully-created-card-account-webhook). * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (10/09/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (27/08/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (20/08/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (05/08/2024) {% hint style="info" %} **New Features** {% endhint %} * Introduced a new "[Set Card Soft Expiry](https://nymcard.com/docs/api#tag/Cards/operation/updateSoftExpiry)" API, allowing the card’s soft expiry to be updated with configurations available at the card product level. We've also added the parameters `soft_expiry_update_allowed` and `soft_expiry_setting` for card product APIs. * Added 2 new token lifecycle management APIs - for [VISA](https://nymcard.com/docs/api#tag/VTS-Tokens/operation/statusChangeToken) and [Mastercard](https://nymcard.com/docs/api#tag/MDES-Tokens/operation/changeStatusMdesToken). {% hint style="success" %} **Improvements** {% endhint %} * Added the ability to request an FX rate quote for `provider_type = EXTERNAL`. For this we've introduced several new parameters (`amount_type`, `derived_rate` and `final_rate`) in the "[Request FX rate quote](https://nymcard.com/docs/api#tag/FX-rates/operation/getFxRatesQuote)" API request. * Added the `receiver_user_id` field to several transaction and transfer APIs, as well as to the webhook TRANSACTION event, allowing you to easily identify the beneficiary of transfers. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (11/06/2024) {% hint style="info" %} **New Features** {% endhint %} * Introduced support of card activation charges. For this we added a new 'charge\_type' - "CARD\_ACTIVATION\_CHARGES" in 'Create charge' API. For more information about charges refer to this [document](https://docs.nymcard.com/get-started/product-management/charges). * Added '[Search Webhooks](https://nymcard.com/docs/api#tag/Webhooks/operation/searchWebhooks)' API, which is used to search webhooks by different criteria. {% hint style="success" %} **Improvements** {% endhint %} * Added enhancement for advanced velocity limits - now you can create an advanced velocity limit with two extra conditions: "TRANSACTION\_ORIGIN" (DOMESTIC, FOREIGN, ANY) and "CARD\_TYPE" (VIRTUAL, PHYSICAL). Relevant [enums](https://nymcard.com/docs/api#tag/Advanced-velocity-limits/operation/createAdvancedVelocityLimit) are added to the 'type' parameter in 'CONDITIONS' array. * Added a new "recipient\_account\_id" parameter in '[Request FX rate quote](https://nymcard.com/docs/api#tag/FX-rates/operation/getFxRatesQuote)' API. This parameter is used for fund transfer between accounts of different wallet currencies. * Implemented an enhancement to our multi-clearing process, designed to improve security and prevent negative balances in cardholder accounts. For more information refer to this [document](https://docs.nymcard.com/get-started/transactions/multi-clearing-process). {% hint style="danger" %} **Bug fixes** {% endhint %} * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (30/04/2024) * Implemented advanced fees functionality. It allows fees configuration along with the dynamic conditions so that fees can be applied based on the configured conditions. For this we developed several new APIs. For more information refer to this [document](https://docs.nymcard.com/get-started/product-management/fees#advanced-fees). * Implemented new enums for the "transfer\_type" parameter, enabling the system to differentiate whether a transfer occurs between the user's OWN account/wallet or not. For more information refer to this [document](https://docs.nymcard.com/get-started/funding-and-transfers/transfers#transfer-between-users-own-account-wallet). Also added a new "transfer\_type" field in TRANSACTIONS [webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook). * Added a new "consumed\_limit" and "consumed\_frequency" fields for velocity limits and advanced velocity limits in the response of '[Get card limits info](https://nymcard.com/docs/api#tag/Cards/operation/getCardLimitInfo)' API. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/04/2024) * Introduced a new "allow\_overdraft" field in [Charges](https://nymcard.com/docs/api#tag/Charges) APIs, the default value is 'false'. * Added a new "allow\_initial\_load" field in "auth\_settings" and "currency\_settings" of a [card product](https://nymcard.com/docs/api#tag/Card-Products) with default value of 'false'. * Introduced a new "allowed\_load\_type" parameter under "wallet\_details" in [Accounts](https://nymcard.com/docs/api#tag/Accounts) APIs. * Added a new parameter "group" with a default value of "SINGLE" in [Advanced velocity limits](https://nymcard.com/docs/api#tag/Advanced-velocity-limits) APIs. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (26/03/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (12/03/2024) * We've made improvements to our **Courier Reports** by including information on delays. This addition is designed to provide clients with insights into the reasons for delayed card deliveries, giving them the ability to address issues independently and bypass the need to raise tickets for resolution.Column Name: "Reason of Delay". * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (28/02/2024) * Two new APIs have been developed: "Get advanced velocity limits related to card product" and "Get advanced velocity limits linked to card." These APIs allow you to retrieve a list of advanced velocity limits for a specific card product or card. * A new webhook event, "ACCOUNT\_STATUS\_CHANGE," has been added. This event allows you to be notified whenever the account status changes, enabling you to take appropriate action. A sample webhook can be found [here](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#account-status-change-webhook). * The "Change user status," "Change card status," and "Change account status" APIs now include a new optional parameter called "modified\_by." This parameter helps identify the user who executed the operation. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (31/01/2024) * New status reason codes (A3, S3 to S6, T7 to T18) introduced in the Cards resource (to be utilized by NymCard). Refer to the [API Catalog](https://nymcard.com/docs/api#tag/Cards) for more details. * A new API "[Get card limits info](https://nymcard.com/docs/api#tag/Cards/operation/getCardLimitInfo)" developed to fetch the limits associated with the card. * Implemented several internal enhancements, which have no major impact on client's current implementation. ### Release Notes (17/01/2024) * Enhanced functionality: clients can now create SMS templates based on wallet providers. Please be aware that the "wallet\_provider" field is specifically applicable for the ITSP\_OTP category type. The available enums for "wallet\_provider" include APPLEPAY, SAMSUNGPAY, and GOOGLEPAY. Additionally, clients have the option to add a custom email OTP template using a new "email" parameter. For detailed information refer to the "[Notification templates](https://nymcard.com/docs/api#tag/Notification-Templates)" section in our API catalog. * Now clients can define new placeholders - CARD\_NAME, FINTECH\_NAME to use in SMS text in [Notification templates](https://nymcard.com/docs/api#tag/Notification-Templates) APIs. It is applicable for ITSP\_OTP category only. CARD\_NAME placeholder will read from the description field of the card product to which the card belongs. * "quote\_id" field (if available) is now returned in the response of '[Get transaction details'](https://nymcard.com/docs/api#tag/Transactions/operation/getTransactionById) and '[Search for transactions](https://nymcard.com/docs/api#tag/Transactions/operation/searchNymcardTransactions)' APIs. * "transaction\_id" field is now returned in the response of '[Get list of FX rate quotes](https://nymcard.com/docs/api#tag/FX-rates/operation/getFxRatesQuotes)' and '[Get specific FX rate quote](https://nymcard.com/docs/api#tag/FX-rates/operation/getFxRatesQuoteById)' APIs (applicable when status of the quote is BOOKED). * Introduced new "card\_type" field (with enums PHYSICAL, VIRTUAL) for [Card Bulk Issuances](https://nymcard.com/docs/api#tag/Card-Bulk-Issuances) APIs, so now you can create both physical and virtual bulk cards. * Added a new global setting related to abandoned tokens for VISA tokenization service, ensuring that webhooks are generated when a user does not complete the provisioning process within the allowed timeframe (24 hours). * Added two new enums (TRANSFER\_TYPE & PURCHASE\_TYPE) in 'conditions' array 'type' parameter in [Advanced Velocity limits](https://nymcard.com/docs/api#tag/Advanced-velocity-limits) APIs, so now there is an option to configure separate velocity limit for TRANSFER\_TYPE and PURCHASE\_TYPE. ### Release Notes (19/12/2023) * Introduced support of custom fields in [Users](https://nymcard.com/docs/api#tag/Users) APIs to add some additional fields as per business needs. Custom field object will be returned in the response of [Users ](https://nymcard.com/docs/api#tag/Users)APIs. * Added a new "reference\_number" field to the response of ['Get transaction details'](https://nymcard.com/docs/api#tag/Transactions/operation/getTransactionById) and ['Search for transactions'](https://nymcard.com/docs/api#tag/Transactions/operation/searchNymcardTransactions) APIs. This field is intended for reporting needs. * Added a new '[Validate card PIN](https://nymcard.com/docs/api#tag/Cards/operation/validatePin)' API to enable the validation of user PINs through an API. This modification has no impact on clients' integrations. * Implemented several internal enhancements, which have no major impact on client's current implementation. ### Release Notes (05/12/2023) * For digital wallets (ApplyPay, SamsungPay & GooglePay), a user is limited to a maximum of 10 tokens per card from the respective wallet providers (Terminated tokens are excluded). * Please be aware that transfers, load/unload, DAPI, and LEAN direct API flow will be declined if either the sender's or recipient's user status is not ACTIVE. * Take into account that a card is temporarily blocked for 24 hours for provisioning if the user makes five consecutive invalid CVV2 or expiry attempts. * Implemented several internal enhancements, which have no major impact on client's current implementation. ### Release Notes (22/11/2023) * From now on, notifications for 'near expiry'/'expired' documents will be triggered only for Onfido documents. USER\_DOCUMENT\_ALERT webhook is used for this. For documents added via the upload APIs, it will be handled in upcoming releases. * Implemented several internal enhancements, which have no major impact on client's current implementation. ### Release Notes (07/11/2023) * Added changes to [TRANSACTION webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook); below you can find new fields related to card tokens: ``` "token_details": { "wallet_identifier": "APPLEPAY", "token_number": "458965212585236", "token_type": "01", "device_details": { "device_type": "MOBILE_PHONE" } } ``` * Implemented several internal enhancements, which have no major impact on client's current implementation. ### Release Notes (25/10/2023) * Added several new optional parameters to the 'Users' APIs, so that you can store and get this information against each user: * new field "education\_level" * new field "nearest\_place" under existing object "address" * new field "nearest\_place" under existing object "company\_address" * new field "created\_by" (unique ID of the agent who will be onboarding the INDIVIDUAL user) * Added a new field 'is\_cancelled' in TRANSACTION webhook to indicate whether the auth transaction is cancelled and funds are credited back to cardholder (needed for a new payment scheme to be supported). * Added ability to configure advanced velocity limits, which allow you to add additional configurations such as merchants (i.e. categories or identifications) in velocity limit profile, so that you can configure velocity limit profile that is applicable for specified configuration. You can find related APIs [here](https://nymcard.com/docs/api#tag/Advanced-velocity-limits). * Implemented several internal enhancements, which have no major impact on client's current implementation. ### Release Notes (11/10/2023) * Added 2 new parameters 'charge\_type' and 'ids' to '[Get list of charges](https://nymcard.com/docs/api#tag/Charges/operation/listCharges)' API, so now you can fetch charges list by charge type or charge IDs. * Added new enums ‘ADDITIONAL\_PAGE\_1' & 'ADDITIONAL\_PAGE\_2' for 'file\_identification\_document\_type’ parameter in User Identification APIs, so it can be stored and returned for uploading identification files. Note, that 'file\_identification\_document\_type' remains optional for 'file\_identification\_type' : ADDITIONAL. * Implemented several internal enhancements, which have no major impact on client's current implementation. ### Release Notes (26/09/2023) * DAPI direct API flow enhancement: Upon calling DAPI flow with HOLD transaction type, a proper error message is returned in case of insufficient funds in the pool account (error: Prefunded account has insufficient funds). * Implemented several internal enhancements, which have no major impact on client's current implementation. ### Release Notes (12/09/2023) * Implemented several internal enhancements, which have no impact on client's current implementation. ### Release Notes (29/08/2023) * Implemented several internal enhancements, which have no impact on client's current implementation. ### Release Notes (17/08/2023) **Enhancements:** * Onboarding / User Verification: Know which IDV/KYC provider is being assigned and to which category or check.\ \ For that purpose, a [new API](https://nymcard.com/docs/api#tag/Tenant-Settings/operation/getUserVerificationSettings) has been developed to retrieve some information related to user verification settings. See the below example: ``` { "user_verification_settings": { "KYC": [ { "category": "all", "provider": "worldcheck" } ], "IDV": [ { "category": "NATIONAL_ID", "provider": "onfido" } ] } } ``` * Cards & Accounts: Introduced new "is\_account\_linked" parameter in [Cards](https://nymcard.com/docs/api#tag/Cards) APIs to indicate whether the card is linked to an account or not.
* Onboarding / User Verification: Users' documents of issuing country other than that of the issuer country is being verified and accepted. That explains the purpose of the new validation being implemented.\ \ To cater to that changes, new user status reason codes *\[“status\_reason\_code”: B9, B9E, B10, B10E]* are introduced. A new validation has been implemented to verify if the issuing country of the identity document matches with the issuer country (system level). If not, user will remain in **PENDINGIDVERIFICATION** status and will take on status\_reason\_code of B9 in case Onfido report is **CLEAR**; Otherwise, it is a B10. For more info refer to this [document](https://docs.nymcard.com/get-started/program-management/user-id-verification-by-sdk#idv-re-verification-upon-document-expiration).
* Business User Onboarding: Introduced new 'optional' fields in [Users](https://nymcard.com/docs/api#tag/Users) APIs for "user\_type" = BUSINESS to capture related information for compliance reasons: ``` "estimated_activity_through_nymcard" "expected_number_of_cards" "expected_use_of_ncs_services" ``` * Transactions / Webhooks: Added two new fields in TRANSACTION webhook for Incremental Authorization: ``` "incrementalTransaction" "isPreAuth" ``` * Scheme Transactions: Transaction processing (authorization) is influenced by the below two settings being set to "false" at the system level. Meaning, regardless of the assigned value (true or false) at product or card level, the corresponding transaction will not be approved. ``` "allow_chip_fallback": false, "allow_account_verification_without_CVV": false ``` * Users: Change in the length of "shareholder\_list" field in [Users](https://nymcard.com/docs/api#tag/Users) APIs - now accepts up to 50 shareholder ids to be linked.
* Users: Change in the length of "share\_controller\_name" field in [Users](https://nymcard.com/docs/api#tag/Users) APIs - accepts up to 100 characters now.
* Account Termination: Added account termination rule: If an auth is partially reversed and its clearing is not received yet, then that particular auth is considered to be a pending auth and therefore, the account cannot be terminated.\ \ **Bug-fix:**
* Card status correction: The correct "status\_reason\_code" I3 is now reflected in [Cards](https://nymcard.com/docs/api#tag/Cards) APIs for a card created without an account but with an embossing already generated.
### Release Notes (19/07/2023) * Added a new field 'title' to [User Documents](https://nymcard.com/docs/api#tag/User-documents) APIs. It is used during identification creation and the system can store 'title' and return it with identification document information. * Introduced several new status reason codes regarding a mechanism for IDV re-verification for INDIVIDUAL users who are already verified but their documents have either expired or about to expire. For more info refer to [this document](https://docs.nymcard.com/get-started/release-announcements/changes-in-the-upcoming-release-on-13-07-2023). * Added multi-currency functionality. You can find details in this [document](https://docs.nymcard.com/get-started/product-management/multi-currency). Also you can find related APIs [here](https://nymcard.com/docs/api#tag/FX-rates). ### Release Notes (20/06/2023) * Introduced a new ‘type' parameter (with enums HOLD, POST & RELEASE), which gives ability to identify for which status the TRANSACTION webhook is triggered. It is added to the response of '[Get transaction details](https://nymcard.com/docs/api#tag/Transactions/operation/getTransactionById)' and '[Search for transactions](https://nymcard.com/docs/api#tag/Transactions/operation/searchNymcardTransactions)' APIs. Also, it will be added to Transaction [webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples). * Implemented several other internal enhancements, which have no impact on client's current implementation. ### Release Notes (06/06/2023) * Implemented several internal enhancements, which have no impact on client's current implementation. ### Release Notes (26/05/2023) * "note" field is now returned in TRANSACTION webhook for "transaction\_type": "WALLET\_CREDIT" & "WALLET\_DEBIT". You can find webhook samples [here](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook). ### Release Notes (23/05/2023) * Implemented several significant enhancements regarding Fees. For more information please refer to this [document](https://docs.nymcard.com/get-started/release-announcements/changes-in-the-upcoming-release). * Added six new APIs to manage charges, namely card issuance charges, which can be applied when physical or virtual cards are issued to cardholders for the first time. For more information regarding Charges refer to this [document](https://docs.nymcard.com/get-started/release-announcements/changes-in-the-upcoming-release). * Developed four new APIs to manage external bank account details so that these details can be used to execute the external transfers: * [Link user external bank details](https://nymcard.com/docs/api#tag/Users/operation/linkExternalBankDetailsToUser) * [Get user specific external bank details](https://nymcard.com/docs/api#tag/Users/operation/getExternalBankAccountDetails) * [Update user external bank details](https://nymcard.com/docs/api#tag/Users/operation/updateExternalBankAccountDetails) * [Unlink user external bank details](https://nymcard.com/docs/api#tag/Users/operation/unlinkExternalBankAccountDetails)
* Added a new "messageReasonCode" field to TRANSACTION [webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples) (message\_type = AUTHORIZATION, transaction\_type = REVERSAL\_ADVICE). This field explains why the acquirer is rejecting authorization. * Added an extra validation check on date of birth (DOB): DOB retrieved from Onfido should match the DOB in the user profile. For this we added a new enum to '[status\_reason\_code](https://nymcard.com/docs/api#tag/Users/operation/changeStatus)' parameter - “B7” (Date of birth consider). Note, that B7 validation is skipped in case date of birth (DOB) is not present in the user profile. * Increased the size of the 'business\_activities' field to 1000 characters in '[Users](https://nymcard.com/docs/api#tag/Users)' APIs. * "sender\_user\_id" parameter is now returned in the response of '[Get list of transfers](https://nymcard.com/docs/api#tag/Fund-Transfers/operation/getTransfers)' & '[Get specific transfer](https://nymcard.com/docs/api#tag/Fund-Transfers/operation/getTransfer)' APIs.
### Release Notes (18/04/2023) * Added "sender\_user\_id" parameter to the response of '[Search for transactions](https://nymcard.com/docs/api#tag/Transactions/operation/searchNymcardTransactions)' API when searching for WALLET\_TRANSFER transactions. Also, "sender\_user\_id" is added as a transaction search filter. * Implemented enhancement for MPGS - whenever a session or transacting is created via MPGS, a proper fintech name will now appear instead of“NymCard Payment LLC” as a merchant name.
### Release Notes (04/04/2023) * Added new enum for ‘status\_reason\_code’ parameter in '[Perform KYC of user](https://nymcard.com/docs/api#tag/User-KYC/operation/performKyc)' API. New enum is C1 (INCONCLUSIVE). In case you receive this reason code, it means that the user account is on hold. * Fixed an issue with "allowed\_mccs\_id" parameter, which is now returned in the response of '[Update card product](https://nymcard.com/docs/api#tag/Card-Products/operation/updateCardProduct)' API. {% hint style="info" %} Also be aware, that some enhancements will be added to API catalog later, when full features will be implemented. But these changes have impact on current implementation, so please get acquainted with all details in this [document](https://docs.nymcard.com/get-started/release-announcements/changes-in-the-upcoming-release). {% endhint %} ### Release Notes (21/03/2023) Features and improvements: * Implemented several vital enhancements for MCC list management. We strongly recommend to get acquainted with all details in this [document](https://docs.nymcard.com/get-started/product-management/authorization-controls/upcoming-enhancements-for-mcc-list-management). * Added 'auth\_settings' parameter to responses of the following APIs: '[Get list of cards](https://nymcard.com/docs/api#tag/Cards/operation/listCards)', '[Get card details](https://nymcard.com/docs/api#tag/Cards/operation/getCard)' and '[Change card status](https://nymcard.com/docs/api#tag/Cards/operation/changeCardStatus)'. * Added new '[Create account token](https://nymcard.com/docs/api#tag/Accounts/operation/createAccountToken)' API, which is used to create an account token for external transactions that are initiated from third parties. * Implemented enhancement for DAPI smart flow - now system supports 'note' field in URL parameters for transfer funds through DAPI widget so that you can pass 'note' as a customized information. * Added possibility to change 'allowed\_mccs\_id' parameter on a card level using '[Update card authorization settings data'](https://nymcard.com/docs/api#tag/Cards/operation/upsertCardAuthSettings) API. ### Release Notes (09/03/2023) Features and improvements: * Implemented enhancement regarding webhooks - "sender\_user\_id" parameter is now received in TRANSACTION (for WALLET\_TRANSFERS) [webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook). Also, "sender\_user\_id" is returned in the response of "[Get transaction details](https://nymcard.com/docs/api#tag/Transactions/operation/getTransactionById)' API when passing the ID of a WALLET\_TRANSFER transaction. * Fixed an issue when cardholder "enc\_name" was displayed on the PCI widget instead of "name\_on\_card". * Fixed an issue when issuer fees were charged for the refunds transactions.
### Release Notes (16/02/2023) Features and improvements: * Added a new parameter - “type” to the '[Create card product](https://nymcard.com/docs/api#tag/Card-Products/operation/Create%20card%20product)' API. This field indicates the type of card product (value should be 'PREPAID'). Also it is added to the responses of ['Get card product](https://nymcard.com/docs/api#tag/Card-Products/operation/getCardProduct)' and '[Get list of all card products](https://nymcard.com/docs/api#tag/Card-Products/operation/listCardProducts)' APIs. ### Release Notes (02/02/2023) Features and improvements: * Added ability to simulate (pre-defined successful) user’s status and to proceed for completing the user verification process ( for KYC and IDV) on the test environments (DEV, Staging, Sandbox, UAT). Also you can find the respective webhook changes in this [document](https://docs.nymcard.com/get-started/webhooks/webhook-changes-for-simulation). * Added "source\_channel" & "notes'' parameters to responses of ‘[Transfers](https://nymcard.com/docs/api#tag/Fund-Transfers)’ and ‘[Transactions](https://nymcard.com/docs/api#tag/Transactions)’ APIs in order to get some additional transaction’s information. Also these two parameters are added to the sample of "TRANSACTION" [webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook). * Added ability to search and get the balance inquiry transaction details as well in addition to the other transactions. Also you can find a "BALANCE\_INQUIRY" webhook sample [here](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#transaction-webhook). * Fixed an issue with fees - fee in declined transactions is now returned in 'Get transaction details' and 'Search transactions' API responses and in 'TRANSACTION' webhook.
### Release Notes (19/01/2023) Features and improvements: * Added a new webhook event - 'EXPIRED\_AUTH',so now you can [configure the webhook](https://nymcard.com/docs/api#tag/Webhooks/operation/createWebhookNotification) for expired authorizations to be aware whenever an authorization is expired by the system. Webhook sample you can find in this [GSG doc](https://docs.nymcard.com/get-started/webhooks/webhooks-samples). Also four new related parameters “auth\_expired\_by“, “auth\_expired\_at”, “is\_reversed“ and “is\_settled“ are added to [Transactions](https://nymcard.com/docs/api#tag/Transactions) APIs. * Added ability to cancel bulk card issuance request: for this new enum "CANCELLED" is added to the 'status' parameter in '[Card Bulk Issuances](https://nymcard.com/docs/api#tag/Card-Bulk-Issuances)' APIs. Note, that this functionality can be used only when bulk issuance card request is in status "DRAFT". If the bulk issuance request is "SUBMITTED", then it can not be modified any more. * A new "status\_reason\_code" - "O1" (reason: Other) is now supported for user status change. It is used by our internal APIs to clarify user status change to SUSPENDED or TERMINATED in case the reason is other than the ones we already support in our API Catalog. * Added a new "fee\_details" parameter in '[Fund transfers](https://nymcard.com/docs/api#tag/Fund-Transfers)' and ‘[Transactions’](https://nymcard.com/docs/api#tag/Transactions) APIs responses, so that you can have more detailed information of all associated charged fees. Also this new "fee\_details" parameter is added to TRANSACTION [webhook sample](https://docs.nymcard.com/get-started/webhooks/webhooks-samples). * Added a [document](https://docs.nymcard.com/get-started/security/otp-sms-templates) to the Getting started guide, where you can find examples of notifications, which you can use in SMS in '[Create template](https://nymcard.com/docs/api#tag/Notification-Templates/operation/createTemplate)' API. * Fixed an issue when wallet transfer was declined with max amount limit reached. * Fixed an issue when ‘status\_reason\_code’ parameter was missing in TRANSACTION webhook for WALLET\_TRANSFER ‘transaction\_type’ for declined MPGS transaction. * Fixed an issue when user with CLEAR report from Onfido was changed to B1 status. * Fixed an issue when user report was not retrieved in user IDV report APIs. ### Release Notes (04/01/2023) Features and improvements: * Added new ‘[Get user verification by reportID](https://nymcard.com/docs/api#tag/User-IDV/operation/getIdentityVerification)’ API, which gives an opportunity to see the customer’s identification report by ‘report\_id’, so that you can get the detailed report information with possible respective failure reason details. * Added new '[Get encrypted card details'](https://nymcard.com/docs/api#tag/VTS-Tokens/operation/encryptCardDetails) API, which helps to generate encrypted card details so that you can use encrypted card details in VISA SDK inApp provisioning flow for tokenizing the card. * Increased file upload size from 20Mb to 128Mb for '[Upload single image of identification](https://nymcard.com/docs/api#tag/User-documents/operation/uploadSingleFile)' and '[Upload user identification](https://nymcard.com/docs/api#tag/User-documents/operation/UploadIdentification)' APIs. * Added new KYC status reason code 'T0' to ['User KYC](https://nymcard.com/docs/api#tag/User-KYC)' APIs, which informs when KYC process failed due to timeout or other technical issue on WC side. Upon receiving the T0 status for the KYC, you need to trigger perform KYC again. * Added new tags \ and \ which you can use in SMS in '[Create template](https://nymcard.com/docs/api#tag/Notification-Templates/operation/createTemplate)' API (along with existing tags \ and \). * Fixed an issue with MPGS credit card transaction, when amount deducted from credit card was not the same amount credited to NymCard account. * Fixed an issue when 'user\_type' was missing in the 'User status change' webhook received upon changing user status from "PENDINGIDVERIFICATION "B4" to "PENDINGKYC" "I0" or "ACTIVE" "I0". * Fixed an issue with changing user status from ACTIVE to PENDINGKYC. * Fixed an issue with constraint violation when performing KYC. * Fixed an issue when users were not moving to World check during performing KYC. ### Release Notes (15/12/2022) Features and improvements: * Changed length of the 'name\_on\_card' parameter from 32 to 20 characters in [Cards](https://nymcard.com/docs/api#tag/Cards) APIs so that same length can be matched with embossing export format. ### Release Notes (05/12/2022) Features and improvements: * Added new ['Get balance limits linked to account'](https://nymcard.com/docs/api#tag/Accounts/operation/getBalanceLimitsByAccountId) API, which helps to retrieve the list of balance limit ID(s) linked to the account. * Added new ['Get user's IDV report details'](https://nymcard.com/docs/api#tag/USER-IDV/operation/getIdentityVerificationsDetail) API, which helps to get the detail information of customer’s identification report. * Implemented enhancements for DAPI widget - now you can skip country and bank selection step and go straight to the credentials in case of adding/linking a new bank or to fund transfer step. For more details refer to the [GSG documentation](https://docs.nymcard.com/get-started/funding-and-transfers/external-funding-source/from-bank-account). * Added new 'billing\_amount\_account', 'billing\_currency\_account' and 'conversion\_rate\_billing\_account' parameters to '[Get transaction details](https://nymcard.com/docs/api#tag/Transactions/operation/getTransactionById)' and '[Search for transactions](https://nymcard.com/docs/api#tag/Transactions/operation/searchNymcardTransactions)' APIs, so you can fetch billing currency and amount applied on the account and understand clearly in which currency the billing amount is charged. * Added ‘source\_channel’ parameter to the [Fees](https://nymcard.com/docs/api#tag/Fees) APIs. Possible values are MPGS, DAPI or ANY (default). It gives an opportunity to choose an appropriate channel, so that fee for every channel can be applied accordingly. This parameter is currently applicable for ‘transaction\_type’ = TRANSFERS only. Also added ability to post fee on recipient account instead of sender account, so you can charge the transfer funds fee to recipient instead of sender. For more details refer to the [GSG documentation](https://docs.nymcard.com/get-started/product-management/fees#fee-configuration-for-individual-channel). * Fixed an issue when card ID was missing in the 'TRANSACTION' webhook for declined transactions. * Fixed an issue when ‘CARD\_STATUS\_CHANGE’ webhook was not received upon changing the card status to ‘SUSPENDED’ due to max. number of pin retries attempts. * Fixed an issue with appropriate response code mapping regarding system errors. More info about transaction status codes you can find [here](https://docs.nymcard.com/get-started/api-core-principles#transaction-status-codes)[.](https://docs.nymcard.com/get-started/api-core-principles#transaction-status-codes) ### Release Notes (17/11/2022) Features and improvements: * Added ability to set balance limit on individual account by using a new API - '[Link balance limit to account](https://nymcard.com/docs/api#tag/Accounts/operation/linkBalanceLimit)'. Also you can unlink balance limit from account using another new API - '[Unlink balance limit from account](https://nymcard.com/docs/api#tag/Accounts/operation/unlinkBalanceLimit)'. * Increased file upload size from 5Mb to 20Mb for '[Upload single image of identification](https://nymcard.com/docs/api#tag/User-documents/operation/uploadSingleFile)' and '[Upload user identification](https://nymcard.com/docs/api#tag/User-documents/operation/UploadIdentification)' APIs. * Implemented enhancement regarding '[Get card authorization settings data](https://nymcard.com/docs/api#tag/Cards/operation/getCardAuthSettings)’ API: card auth settings inherited from the card product will be returned only for the newly created cards. For existing cards, after updating the auth settings at the card level and calling 'Get card authorization settings data' API, the auth settings will be returned in response. * Added ability for system to generate export after processing the clearing file so it can be shared for reconciliation. Please contact the customer success team for details. * Implemented enhancement regarding webhooks: from now onwards 'original\_amount\_billing' parameter will be forwarded only in Reversal\_advice webhooks, as it is only required for partial reversal cases. * Restricted user status change from ACTIVE to PENDINGIDVERIFICATION (B0 or B2) using 'Change user status' public/internal API.
### Release Notes (03/11/2022) Main features and improvements: * Developed and implemented core enhancements to the Card Product management process. Once a Card is created, its "Auth Settings" - inherited from its Card Product - cannot be changed. For any questions or concerns, please reach out to our Support or Customer Success teams. * Added an explanation that "company\_name" parameter is required if "employment\_type" = 'SALARIED", "EMPLOYED" or "BUSINESS\_OWNER". It is applicable for [Users](https://nymcard.com/docs/api#tag/Users) APIs. * Updated the 'pin' parameter in the “[Simulate transaction"](https://nymcard.com/docs/api#tag/Transactions/operation/simulateTransaction) API - it is a string now. So, as an example, the format now is the following - "pin": "0190". * Added ability for PCI widgets to support ‘proxy\_number’ along with ‘card\_id’. You can read more about proxy number usage [here](https://docs.nymcard.com/get-started/issuing-physical-cards/proxy-number-usage). * Added support of proxy number when [linking card to account](https://nymcard.com/docs/api#tag/Accounts/operation/linkCardsToAccount). You can read more about proxy number usage [here](https://docs.nymcard.com/get-started/issuing-physical-cards/proxy-number-usage). * Fixed an issue when 'card\_id' was not returned in '[Simulate transaction](https://nymcard.com/docs/api#tag/Transactions/operation/simulateTransaction)' API response. * Fixed an issue with missing fields in clearing webhooks. Now the following fields can be sent in clearing webhooks: “userid”, ”feeamount”, "ecommercesecuritylevel”, "cardentry", "posenvironment", "fallback", "pinpresent", "moto", "recurring", "installmenttransaction". * Fixed an issue when 'status\_code' was not received in the negative/declined cases of webhooks with "event": "TRANSACTION", "message\_type": "API" and "transaction\_type": "WALLET\_TRANSFER".
### Release Notes (13/10/2022) Main features and improvements: * Added ability to link IDV verification policies for parent and child users at tenant level. In terms of this feature new [IDV policies APIs](https://nymcard.com/docs/api#tag/User-KYC) are added to API catalog. * Implemented new name verification mechanism to match name fields of API and uploaded documents so that identity verification process can be smoothly completed. Also in terms of this improvement new user status reason codes were added to [API catalog](https://nymcard.com/docs/api#tag/Users). * Updated ability to terminate accounts, so now it is possible to [update account status](https://nymcard.com/docs/api#tag/Accounts/operation/changeAccountStatus) to TERMINATED if account has no balance or account has no pending authorizations. Bug fixes: * Minor bug fixes and performance improvements. ### Release Notes (20/09/2022) Main features and improvements: * Added such new [API](https://nymcard.com/docs/api#tag/Cards) parameters as 'soft\_expiry\_period' and 'card\_soft\_expiry', which give ability to define soft expiry of the card (the concept of soft expiry usually applies to bulk cards/gift cards). Bug fixes: * Fixed a lot of internal issues. ### Release Notes (01/09/2022) Main features and improvements: * Added support of proxy number in '[Cards](https://nymcard.com/docs/api#tag/Cards)' APIs, so that you can perform card operations by providing proxy number instead of card ID. * Introduced new [user type](https://nymcard.com/docs/api#tag/Users/operation/createUser) "SHAREHOLDER\_BUSINESS", which can be used in case you have business and shareholder as a single entity under business user. Also added 2 new related parameters - 'license\_type' and 'license\_expiry'. * Added new parameters to ‘[Search for users](https://nymcard.com/docs/api#tag/Users/operation/search)’ API, so now there is capability to search users based on creation and modified date.
Bug fixes: * Fixed a lot of internal issues. ### Release Notes (22/08/2022) Main features and improvements: * Added new 'allow\_contactless' parameter to [card product](https://nymcard.com/docs/api#tag/Card-Products) APIs, which indicates if contactless transactions are allowed or not. * Added a new ‘USER\_CREATED’ webhook event to the ‘[Create webhook](https://nymcard.com/docs/api#tag/Webhooks/operation/createWebhookNotification)’ API. * Implemented enhancements to [Fees](https://nymcard.com/docs/api#tag/Fees) APIs - instead of “CURRENCY\_MARKUP“ transaction type , two new transaction types are introduced - “PURCHASE\_MULTI\_CURRENCY“ and “WITHDRAWAL\_MULTI\_CURRENCY“. Bug fixes: * Fixed a lot of internal issues. ### Release Notes (08/08/2022) Main features and improvements: * Added a new 'status' parameter to "[Search for users](https://nymcard.com/docs/api#tag/Users/operation/search)" API, which helps to filter users based on their user statuses. * Added 'PIN\_CHANGE' [webhook](https://nymcard.com/docs/api#tag/Webhooks/operation/createWebhookNotification), so when the PIN change operation is completed a webhook will be generated. * Added "date\_of\_birth\_city" parameter to '[Users](https://nymcard.com/docs/api#tag/Users)' APIs. * Added the "pin" parameter to the '['Simulate authorization transaction'](https://nymcard.com/docs/api#tag/Transactions/operation/simulateTransaction)' API, so you can simulate PIN based transactions and test scenarios like bad PIN. Bug fixes: * Fixed a lot of internal issues. ### Release Notes (25/07/2022) Main features and improvements: * Added ability to sort\_by & order\_by for users in ['Search for users](https://nymcard.com/docs/api#operation/search)' API. Bug fixes: * Fixed a lot of internal issues. ### Release Notes (25/05/2022) Main features and improvements: * Implemented an [API](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/getLinkedRelationships) to get linked relationships of a user. * Improved ‘User Status Change’ [webhook](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/createWebhookNotification) by adding new parameters 'old\_status' and 'old\_status\_reason\_code'. * Added ability to set Mastercard as a value for ‘channel\_scope’ parameter in ‘[Velocity limits](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Velocity-Limits)’ APIs. Bug fixes: * Fixed an issue when user KYC call could be performed without uploading an identification or with uploading the wrong identification type. * Fixed an error which occurred upon changing card status. * Fixed an issue when 'ledger\_balances' parameter was empty during account creation. ### Release Notes (03/05/2022) Main features and improvements: * Implemented return of both available balance and ledger balances in [‘Accounts’](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Accounts) APIs responses. * Implemented changes to support the new industry standard – eight-digit issuing BIN. * Improved "IDENTITY\_VERIFICATION" [webhook](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/createWebhookNotification), so now the system will send this webhook notification event along with a ‘status\_reason\_code’ as "B1" if the user is not verified. Bug fixes: * Fixed an error, which occurred when [updating a user](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/updateUser) with 'user\_type'=BUSINESS. * Fixed the issue with duplicated BIN & PAN range during card product creation/update within the tenant. * Fixed the issue which occurred when performing KYC for users with 'status' = PENDINGIDVERIFICATION. * Fixed the issue with webhooks response time. ### Release Notes (19/04/2022) Main features and improvements: * Updated [webhook](https://docs.nymcard.com/get-started/webhooks/ncore-webhook-events) event name from “CARD\_TRANSACTION“ to “TRANSACTION", as it includes both card transactions and API transactions. Note, that if you are using an old webhook event ‘CARD\_TRANSACTION’, now it will have an 'events' type - ‘TRANSACTION’. Bug fixes: * Fixed an issue when used card PIN did not conform with PIN length defined at card product level. * Fixed an issue when duplicate webhook notifications were received for load transactions. * Fixed error issues in '[Create/Update user identification](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/User-documents)' APIs. * Fixed an issue with an informative error message upon trying to link a bulk card to an inactive user. * Fixed “matcher” format in the sample request for ‘[Search for transactions](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/searchNymcardTransactions)’ API . * Fixed an issue when user KYC status for secondary users could not be changed. * Fixed an issue when invalid values were accepted for 'director\_list', 'signature\_list' and 'shareholder\_ list' parameters in '[Users](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Users)' APIs. * Fixed an issue with the 'regulator\_name' parameter in '[Users](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Users)' APIs.
### Release Notes (04/04/2022) Main features and improvements: * Added new '[Link cards to account](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/linkCardsToAccount)' API, which is used to link multiple cards to one particular account. So when performing transactions from any of the cards, only the one linked account is debited or credited. * Added ability to create a card without an account. It is configured on the card product level, where you have to set the '[link\_account\_to\_card](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/Create%20card%20product)' parameter as 'false'. * Added new parameters to '[Users](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Users)' APIs, which are applicable for BUSINESS user\_type. It helps to register a business user in the system and issue an account to him. * Implemented the following enhancements to the open banking widget, which helps to transfer funds from your bank account to your NymCard card account: * added a button to delink a bank * implemented handling of returned error codes * added ability to re-link the bank again in case the user has changed its banking credentials. * Implemented Postman collection setup. So now you can run the NymCard API collection in Postman. For more info refer to the [relevant section](https://docs.nymcard.com/get-started/quick-tutorial#run-the-api-collection-in-postman) of this guide. Bug fixes: * Fixed the following issues with the widget, which helps to transfer funds from your bank account to your NymCard card account: * added error message showing upon transferring funds to a suspended/terminated account * fixed authentication error message * fixed the issue when cool-down period icon overlapped with the text * fixed the cool-down page draft * updated main page draft * fixed 'Top Up completed' page * improved user experience when it comes to navigating back to the main page. * Fixed the issue with uploading files for some[ identification types](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/searchIdentification). * Fixed the issue with an error, which occurred when running '[Update card product](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/updateCardProduct)' API. * Fixed issues related to PCI Widget, regarding set/change PIN functionality in particular. * Fixed an issue when KYC status could not be updated for users with 'SECONDARY KYC' policy. * Fixed an issue with special symbols when adding addresses in 'Create card' API. Now you can also use the following symbols: comma, semicolon, colon, apostrophe. * Fixed an issue with declined transaction status in '[Simulate transaction](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/simulateTransaction)' API while linking a velocity limit to the card product. * Fixed an issue related to receiving webhook notifications with “event”: “IDENTITY\_VERIFICATION” when tenant settings checks=‘FACIAL\_SIMILARITY\_VIDEO’. ### Release Notes (16/03/2022) Main features and improvements: * NymCard offers a possibility to transfer funds from your bank account to your NymCard card account using the widget. For more information refer to the ‘Funding and transfers’ section of our Getting Started guide. * Added ability to view and change card PIN using PCI widget, so cardholders can change or view the PIN which is required to perform cash withdrawals at the ATM or POS purchases with a physical card. For more information refer to the ‘Security’ section of our Getting Started guide. * Now you can maintain [identification file type](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/uploadSingleFile) when the user uploads any document, so that the document and its version can be identified easily. * Added 'document\_status' and 'document\_status\_reason' parameters to response in "[User documents](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/User-documents)" APIs to capture the details of the identification lifecycle for each identification. * Now the “company\_name” parameter in “[Users](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Users)” APIs is required ONLY IF the user is employed (i.e. employment\_type is "SALARIED", "SELF\_EMPLOYED" or "BUSINESS\_OWNER"). * Added such new user types as Director, Signature and Shareholder to “[Users](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Users)” APIs. This is part of SME Onboarding (KYB). * Added ‘desing\_code’ parameter to “[Card Products](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Card-Products)” APIs and ‘extra\_embossing\_line’ parameters to “[Cards](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#tag/Cards)” APIs. It gives a possibility to define in which card design a card will be printed and enables to add the company name on a corporate card. This is required by the Perso center so they can find the exact card design that they need to Print on the plastic card. * Added “create\_account\_with\_card” parameter to “[Create card product](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/Create%20card%20product)” API. Also a new category “account\_settings” is added to the “[Update card product](https://portal.sand.platform.nymcard.com/default/documentation/02_api_specs#operation/updateCardProduct)” API. These new parameters allow customers to create a card separately without auto-creating a card account and then linking this card to a preexisting account or to a newly created account. It provides the flexibility to link multiple cards to the same account. * Mandatory fields on the NymCard dashboard are now marked accordingly. * Conducted a reset on the NEO Admin Panel Dashboard. Bug fixes: * fixed an issue with change of commission fees on Asia Cell and Toters. * Fixed BIN rerouting for several clients. * Fixed an issue when an error occurred while linking a bulk card to a user. * Fixed Onfido integration issues. # IQ release notes ### Changes in Upcoming Release * Velocity Limits API – The existing Velocity Limits API is now marked as deprecated (Old Service). We strongly recommend migrating to the Advanced Velocity Limits API, which will be the supported path going forward '[Get Account Limits Info](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Accounts/operation/getCardLimitsV2)' . * ALL\_TIME to be removed from Velocity Limit only. Clients can use it in Advance Velocity Limit. * Get Card Limits Info API – The existing Get Card Limits Info API is now marked as deprecated (Old Service). Migrated to Get Card Limits Info (v2), which will be the supported version moving forward. '[Get Card Limits Info](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Cards/operation/getCardsLimitsV3)'. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (29/07/2026) * Changes in Visa Direct APIs for corridors and Get List of Fields. * \[INC Onboarding] Capture additional personal information attributes * Enhancement in Foreign Exchange Rates(GetIndicativeRate) API Response. * Validate Payout API Enhancement as Account Verification Service (AVS) Mode. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/07/2026) * Fix for FX Rate For USD Card to IQD Wallet. * Fix for expired national ID idv report issue. * Missing Country of Transactions in New PMD Dashboard. * Authorization advice transactions in PMD appear as approved payment transactions in App. * Added enhancement to Visa Direct to support additional corridor. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (01/07/2026) * Changes related to security fixes has been deployed as a hotfix. * Fix to show USD wallet migration transaction on portal. * Fix to show USD wallet migration transaction on mobile apps. * Fix for notification turn off changes. * NS-311-Incorrect flow with IDV Syrian account. * Changes to filter AUTHORIZATION\_ADVICE of status code 0885. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (22/06/2026) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients ### Release Notes (02/06/2026) * Fix for wallets exceeded top up limit. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (13/05/2026) * Introduced several new APIs for Visa Click to Pay. It is a tokenized, EMV® Secure Remote Commerce-based solution designed to streamline and secure online checkout for cardholders, merchants, and issuers. For more information, refer to this [API Catalog](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Visa-Click-to-Pay/operation/listClickToPayEnrollments) * Fix for the Bill Payment transaction display on PMD. * Enable Maker/Checker (4-Eyes) for Unload Funds. This enables no single user can debit customer accounts without a second authorized approval. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (29/04/2026) * Changes in linking multiple merchant lists to card and card product - V2 [`Merchant allowed APIs`](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/Allowed-Lists/operation/getAllowedMerchant) [`Merchant Link/Unlink APIs`](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/cards/operation/linkAllowedMerchantsToCardV2) [`Card Product Link APIs`](https://portal.stg.platform.ae-1.nymcard.com/default/documentation/02_api_specs#tag/card-products/operation/unlinkAllowedMerchantsFromCardProductV2) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (15/04/2026) * Added backend support for mobile app banner. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (01/04/2026) * Added new 'card\_product\_id' parameter in the response of the Card Listing API, so that you can identify the product associated with each card and apply relevant product-specific logic or UI behaviour. * Updated existing MASTER wallets to set IQD as priority 1 and USD as priority 2 in order to normalize wallet priorities for existing users who have both IQD and USD MASTER wallets. * Enhanced card search capabilities in the mobile application to allow users to search their own cards securely, enable searching recipient cards using specific identifiers, restrict visibility to only eligible (Active) cards etc.. * Added backend support for mobile app banner. * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (18/03/2026) * Added enhancement to nFront to fall back to 'transaction\_currency' and 'transaction\_amount' when 'billing\_currency' and 'cardholder\_billing\_amount' are missing,\ so that the app always shows the correct currency and amount even for reversal advice messages where billing fields are not present. * Added enhancement to Virtual Card PAN Generation. * Implemented backend support for Areeba Payment Gateway (ARPG), including new source channel handling, Transfers API updates, CMS-level integration, and forex logic. * Enhanced the PIN retry counter (now it is set to 5 attempts). * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. # Embedded Lending Release Notes ### Release Notes (26/12/2024) * Enhanced SMS configuration and the ‘remind\_events\_emitter’ worker. * Fixed an issue where an Insecure Direct Object Reference (IDOR) allowed adding employees to any merchant profile. * Fixed an issue involving unauthenticated access to checkout data through a public API endpoint. * Fixed an issue with potential cross-merchant data leakage via an API endpoint. ### Release Notes (11/12/2024) * Several internal enhancements have been implemented, which do not significantly impact the current implementation for clients. ### Release Notes (27/11/2024) * Fixed an issue where the sales value in the merchant dashboard did not account for refunds. * Enabled Lender Portal login for staff users with shared email addresses or usernames. ### Release Notes (30/10/2024) * Fixed an issue when nationality was not displayed on the API dashboard for some users. ### Release Notes (16/10/2024) * Implemented a system to send periodic SMS reminders to customers about upcoming payments in addition to existing push notification reminders. * Fixed an issue when the merchant email verification process was asking for a 6-digit input code instead of the expected 4-digit input. ### Release Notes (02/10/2024) * Updated the text color for 'Limited Time Offer' and pricing details on the offer banner. * Added an explanatory message for users already registered as merchants, informing them to register using a different email or phone number. ### Release Notes (18/09/2024) * Added description enhancement saying about 4 bi-weekly payments in both Checkout and Consumer Mob App. * Added ability to find out where the order was placed. For this the source column has been added, and the search functionality is working correctly. Now you can search using options like Instore, Payment Link, and Online. * Introduced UI enhancements: changed home screen in consumer mobile app with orders and added card section and new UI for shop directory. * Implemented MasterCard validation within the VGS Collect field into the Consumer Mobile App for the NymCard platform. * Removed Lean API use in consumer web platform. * Added an ID verification (IDV) step immediately after users sign up on the consumer web platform. Additionally, users are able to re-upload their IDV documents from the account settings page if needed. * Fixed an issue preventing a user from deleting an account on Consumer Mobile App. ### Release Notes (28/08/2024) * Added ability to send an OTP via SMS to user, which is verified by the merchant on the dashboard. Once verified, merchant can approve/decline the payment request. * Added ability to print receipts for orders from the dashboard. * Added a comment section so that you can be aware of the reason why merchant refunds an order. ### Release Notes (14/08/2024) * Added KYC status filter to 'IDV Attempts' admin section. * 'IDV Attempts' admin section and 'Merchant approval' are now available on API portal. * Bi-Weekly payment plan is now available on production. # Changes in the release on 13/07/2023 {% hint style="warning" %} This enhancement has impact on upcoming implementation, so please make sure to get acquainted with it thoroughly. **Deployment Dates:** Staging: July 13 Production: July 19 {% endhint %} ### IDV Re-verification upon document expiration **Background: INDIVIDUAL** users who are already verified but their documents have either expired or about to expire. To cater to that, we will introduce a mechanism for IDV re-verification. **New settings** (configured on NymCard side): {% code overflow="wrap" %} ``` "expired_idv_policy": { "days_prior_expiration": 30, (attached is a file to explain the expiration date calculation) "applicable_user_status": [ "ACTIVE"] (applicable to ACTIVE users for now) } ``` {% endcode %} **Cron Job** a. read tenant level settings related to expired\_idv\_policy b. pick INDIVIDUAL users and check for the expiry date of their documents c. update user status\_reason\_code to A6 if their documents have expired or about to expire d. Fintechs will receive webhook with status A6, then they need to start below mentioned process: * Change the (ACTIVE) user 'status\_reason\_code' to B2E (works exactly the same as B2) to generate a new IDV token and ask the end-user to upload his documents again * Update the (ACTIVE) user 'status\_reason\_code' to B0E (works exactly the same as B0) once the documents are uploaded to initiate the IDV process If the report is **CLEAR**, user status is updated to (ACTIVE), A7 (new status reason code). Otherwise; user takes on (ACTIVE), A8 'status\_reason\_code' for the **CONSIDER > CAUTION** scenario, T12E 'status\_reason\_code' for the **CONSIDER > TERMINATED** user status scenario & T13E 'status\_reason\_code' for the **CONSIDER > SUSPECTED** user status scenario (where A8, T12E (works same way as T12) & T13E (works same way as T13) are new status reason codes). Respectively, we added new values for user `status_reason_code`: * A6 : Document expired or about to expire * A7 - ID renewed * A8 : ID re-verification failed after document expiration * B2E: Generate SDK token, document expired (same as B2) * B0E: Documents re-uploaded after document expiration for identity verification (same as B0) * T12E: System terminated due to ID verification rejected after document expiration for identity verification (same as T12) * T13E: System terminated due to ID verification suspected after document expiration for identity verification (same as T13) {% hint style="info" %} To re-initiate IDV flow by generating a new SDK token: change `status_reason_code` from A8 to B2E. {% endhint %} Below you can find a document with IDV expiration days calculation samples. {% file src="/files/tQlAiJNcnuQ0djbzRZQ2" %} # Changes in the release on 23/05/2023 Below you can find manuals regarding two main functionality enhancements in the upcoming release: * [Fee enhancements](#fee-enhancements) * [Charges](#charges) ## Fee enhancements {% hint style="warning" %} These enhancements have impact on current implementation, so please make sure to get acquainted with it thoroughly. We encourage you to focus on the 'Use cases' section and to prepare/create the data ASAP to validate them later after migration run on Staging on Wednesday afternoon (17/05/2023). {% endhint %} **Changes:** 1. "CURRENCY\_MARKUP" is renamed to "PURCHASE\_FOREIGN\_CURRENCY" 2. "PURCHASE\_FOREIGN\_CURRENCY" is applicable to "PURCHASES" in foreign currencies 3. Introduced a new enum "WITHDRAWAL\_FOREIGN\_CURRENCY" for transaction type in Fees APIs and it is applicable to "WITHDRAWALS" in foreign currencies 4. Allowed definition of fee with currency value as \*\*\* (\*\*\* stands for any currency other than the one(s) supported by the card product) 5. Added description in "transaction\_origin" field that this field is applicable for transaction types WITHDRAWALS, PURCHASES, PURCHASE\_FOREIGN\_CURRENCY & WITHDRAWAL\_FOREIGN\_CURRENCY 6. Added description in "currency" field that \*\*\* is applicable for transaction type "PURCHASE\_FOREIGN\_CURRENCY" & WITHDRAWAL\_FOREIGN\_CURRENCY {% code title="Example:" overflow="wrap" %} ``` Single currency card product with base currency of AED. Fee plan of "transaction_type": "PURCHASE_FOREING_CURRENCY" is linked to the card product, where: "currency": "***" ,  "type": "FLAT",  "amount": 5, "transaction_origin": "ANY". PURCHASE transaction of amount USD 50 is received. Transaction amount (USD 50) is converted into AED and deducted from the AED account. Similarly, fee amount (USD 5) is converted into AED and deducted from the AED account. ``` {% endcode %} What to expect after **migration** run: 1. "CURRENCY\_MARKUP" enum will be changed to "PURCHASE\_FOREIGN\_CURRENCY". It will take on the default currency of \*\*\*. 2. A new fee plan (unique ID) of type "WITHDRAWAL\_FOREIGN\_CURRENCY" is created and linked to the same product to which "PURCHASE\_FOREIGN\_CURRENCY" is initially linked to. It will take on the default currency of \*\*\*. 3. The new fee plan "WITHDRAWAL\_FOREIGN\_CURRENCY" will inherit the same details as that of the existing fee plan "PURCHASE\_FOREIGN\_CURRENCY" except that the fee plan corresponding to "WITHDRAWALS" will have an extra string "\_WITHDRAWAL" in the description field. **Use cases**: * A card product with fee plan of type PURCHASE linked to it After the migration: no impact (fee will be applied on PURCHASE transactions done in base currency - business as usual) * A card product with multiple fee plans linked to it among which are PURCHASE and CURRENCY\_MARKUP After the migration: \- CURRENCY\_MARKUP is updated to PURCHASE\_FOREIGN\_CURRENCY \- a new fee plan of type "WITHDRAWAL\_FOREIGN\_CURRENCY is created and linked to the same card product \- perform PURCHASE transactions in base currency and confirm the correct fee is being applied \[speaking of "PURCHASE" fee plan] \- perform PURCHASE transactions in foreign currencies and confirm the correct fee is being applied \[speaking of PURHCASE\_FOREIGN\_CURRENCY] \- perform WITHDRAWAL transactions in foreign currencies and confirm the correct fee is being applied \[speaking of WITHDRAWAL\_FOREIGN\_CURRENCY] * "CURRENCY\_MARKUP" is linked to more than one product After the migration: everything will continue to work normally except that different fee plans of type "WITHDRAWAL\_FOREIGN\_CURRENCY" will be created and linked to the different card products ## Charges {% hint style="info" %} This is new functionality, so it does not have impact on current implementation. {% endhint %} We added an ability to post card issuance charges so that it can be applied to respective cardholder's account. This will be applied one time only for every new card that is issued. In Scope: 1\) Personalized physical card is issued first time 2\) Personalized virtual card is issued first time 3\) Bulk card is linked to the user Out of Scope: If card is replaced then issuance charges shall not be considered. API Catalog: The below APIs are exposed in API Catalog: * [Create charge](https://nymcard.com/docs/api#tag/Charges/operation/createCharges) * [Update charge](https://nymcard.com/docs/api#tag/Charges/operation/updateCharges) * [Get a specific charge](https://nymcard.com/docs/api#tag/Charges/operation/getCharges) * [Get list of charges](https://nymcard.com/docs/api#tag/Charges/operation/listCharges) * [Link charges to card product](https://nymcard.com/docs/api#tag/Card-Products/operation/linkCharges) (you can link multiple charges at once) * [Unlink charges from card product](https://nymcard.com/docs/api#tag/Card-Products/operation/unlinkCharges) (you can unlink multiple charges at once) * [Get list of charges related to card product](https://nymcard.com/docs/api#tag/Card-Products/operation/getCharges) Note, that supported enums for 'charge\_type' are "PHYSICAL\_CARD\_ISSUANCE" & "VIRTUAL\_CARD\_ISSUANCE". Webhooks New [webhook](https://docs.nymcard.com/get-started/webhooks/webhooks-samples#charges-webhook) event/enum "CHARGE\_APPLIED" is addded. Below you can find webhook sample: ``` { "event": "CHARGE_APPLIED", "charge_applied": { "id": "0fcf8c07-ae35-4243-890d-0a39b2618578", "description": "charges dev 28", "currency": "AED", "amount": 2, "card_id": "f3bd66fd-80d5-4c7c-90e2-ac062c923ff0", "account_id": "f3bd66fd-80d5-4c7c-90e2-ac062c923ff0", "charge_id": "CHARGEAHSAN19", "charge_type": "PHYSICAL_CARD_ISSUANCE" } } ``` Cron Job: A cron will run on a daily basis to pick up those charges in "PENDING" status and apply the charge amount to cardholders' accounts. # Changes in the release on 04/04/2023 Be aware, that the following enhancements **will be added to API catalog later**, when full features will be implemented. But these changes have impact on current implementation, so please get acquainted with it: * [Card renewal](#card-renewal) * [Multi-currency related enhancements](#multi-currency-related-enhancements) ### Card renewal Introduced the following parameters in the response of [Card products](https://nymcard.com/docs/api#tag/Card-Products) APIs under 'card\_settings' parameter: **"allow\_card\_renewal", "renew\_before\_days", "new\_pan\_on\_renewal", "auto\_renewal\_process"**. They are used to renew an existing card so that if a card is about to be expired, a new card can be generated and provided to the cardholder for uninterrupted card services. Impacted APIs: * Create card product * Update card product * Get card product * Get list of card product This enhancement has impact on both existing and new card products. Example: ``` "card_settings": { ... "allow_card_renewal": true, // default = false "renew_before_days": 60, // default = 60 "new_pan_on_renewal": false, // default = false "auto_renewal_process": true // default = false } ``` ### Multi-currency related enhancements Multi-currency feature is not fully implemented yet, but still there are some enhancements, which impact current implementation. 1. Introduced a new parameter **"is\_multi\_currency\_product"** in [Card products](https://nymcard.com/docs/api#tag/Card-Products) APIs to indicate whether the card product is a single currency or a multi-currency card product. It is already reflected in the response of card product related APIs for single currency card products with default value of "is\_multi\_currency\_product": false. 2. Added new parameters ( **"currencies", "wallet\_details" - "currency", "priority", "status"**) to [Accounts ](https://nymcard.com/docs/api#tag/Accounts)APIs. It gives possibility to create initial wallets upon account creation, so that users can utilize multi-currency wallets. This enhancement has impact only on new accounts. Impacted APIs: * Create account - "currencies" & "wallet\_details" are returned in the response * Get account details - "balance\_limits" if linked to the account, "currencies" & "wallet\_details" are returned in the response * Get list of accounts - "balance\_limits" if linked to the account, "currencies" & "wallet\_details" are returned in the response * Change account status - "balance\_limits" if linked to the account, "currencies" & "wallet\_details" are returned in the response 3. Added new parameters ( **"balance\_limits" - "currency", "balance\_limit\_id"**) to [Accounts](https://nymcard.com/docs/api#tag/Accounts) APIs. It gives possibility to link balance limits of non-priority 1 currencies so that balance limits in each currency can be applied during transactions. This enhancement has impact on both existing and new accounts. Impacted APIs: * Get account details * Get list of accounts * Change account status Example: ``` {  "balance_limits": [         {             "balance_limit_id": "BLimit003",             "currency": "AED"         }     ],     "currencies": [         "AED"     ],     "wallet_details": [         {             "currency": "AED",             "priority": 1,             "status": "ACTIVE"         }     ] } ```