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.

Field

Description

Sample 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'

Please ask your NymCard account manager to make sure that you have the corresponding setting "default_currency": "AED" configured for your tenant.

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" section of this document):

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:

<script src="https://test-gateway.mastercard.com/checkout/version/61/checkout.js" data-error="errorCallback" data-cancel="cancelCallback"></script>

Checkout.configure({
session: {
id: SESSION0002617523020H25893709N7
}
});

Please refer to the Payment gateway integration guide 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:

In case of hosted payment page, you will be redirected to a separate page where you should fill in card info:

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:

Order statuses

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.

There are several order statuses, which you can face:

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
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
Timeout occurred during operation processing.
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:

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.
Client’s backend calls the “Create order” API.
NymCard creates a hosted checkout session with MPGS and returns the unique order and session IDs in the 'Create order' API response.
Client's frontend calls ‘checkout.showlightbox’ or ‘checkout.showpaymentpage’.
Payment gateway processes the payment.
nCore platform callbacks the redirect URL, provided by the client, along with order 'status' and 'order_id'.
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}

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' API (go to Response ,'status_reason' enums).

NymCard ‘status’ field values

NymCard ‘status_reason’ field value

NymCard ‘status_description’ field value

SUCCESS

ORDER_CREATED

ERROR

FAILED

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

ERROR

REQUEST_REJECTED

“The request was rejected by the payment gateway due to security reasons such as firewall rules, expired certificate, etc.”

ERROR

SERVER_BUSY

“The payment gateway server did not have enough resources to process the request at the moment.”

ERROR

SERVER_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 Cards

Card Number

3-D Secure Enrolled

Mastercard

5123450000000008

2223000000000007

5111111111111118

2223000000000023

Visa

4508750015741019

4012000033330026

American Express

345678901234564

371449635398431

Diners Club

30123400000000

36259600000012

JCB

3528000000000007

3528111100000001

Discover

6011003179988686

6011963280099774

Maestro

5000000000000000005

5666555544443333

UATP

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

135492354874528

135420001569134

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

PreviousExternal funding source NextFrom bank account

Last updated 5 months ago