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:

There is also another variant - DAPI direct API flow, which you can find here.

The standard flow

High level steps

Generate a token
Append generated token with the URL
Select or add bank
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” 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 (https://openbanking.sand.platform.nymcard.com/dapi_bank_list) 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.

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.

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:

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.

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

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 (https://openbanking.sand.platform.nymcard.com/dapi_bank_list) 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

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

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 (https://openbanking.sand.platform.nymcard.com/dapi_bank_list) 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

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

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:

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

PreviousFrom card NextLean API flow

Last updated 5 months ago