API docs by Redocly

API catalog (1.0)

In this catalog you can find all nCore platform APIs. In case you need nFront APIs, please refer to this catalog https://nymcard.com/docs/api_nfront.

Note, that all parameters without "required" tag are optional.

Tenant Settings

NymCard offers the flexibility to host a customer's private partition on its multi-tenant secure platform where only physical resources are shared with other tenants with all features supported. Another option is having a standalone single tenant platform dedicated for a single customer that could be used for managing customer's Card Program. NymCard offers for its customers the ability to choose between these 2 options based on their requirements. Test

Get user verification settings

This API is used to get user verification settings.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "KYC": [
    ],
  • "IDV": [
    ]
}

Card Products

Our nCore platform offers the concept of a card product - it acts as a template to define features, rules and behaviors applicable to the cards belonging to that product. Whenever a new card is created, card product is required to be mentioned so that the card is created using the card product template. Each card product has a unique token, the token can be provided by the user creating the card product or the system can auto generate it if not provided by the user. The user also provides a name for the card product which is a mandatory free text value of appropriate length.

Create card product

This API is used to create a new card product.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters ^[a-zA-Z\-0-9]+$

The unique identifier of the card product. If this information is not present in the request, the system generates one automatically.

description
required
string <= 40 characters

The name of the card product. We recommend using a unique string.

status
string (CreateCardProductStatus)
Enum: "INACTIVE" "ACTIVE"

This is the card product status. When card product is created, it has status 'INACTIVE'. Once a card is issued for the card product, the status will become 'ACTIVE'.

required
Array of objects (CurrencySettings) non-empty

An array of currency settings to define the related characteristics such as supported currencies, settlement currencies, priority, currency status, etc. for the card product.

required
object (CardSettings)

An array of card settings to define the related characteristics such as bin, pan length, pan range, card validity code, etc. for the card product.

object (CardProductCreditLimits)

Card product credit limits.

object (AccountSettings)

An array of account settings to define the related characteristics such as link account to card, number of cards per account etc. for the card product.

object (PinSettings)

An array of PIN settings to define the related characteristics such as PIN type, PIN length, and PIN retries for the card product.

object (AuthSettings)

An array of authorization settings to define the related characteristics such as transaction controlling (enabling/disabling), authorization aging, etc. for the card product. Note that auth settings cannot be updated for an ACTIVE card product.

object (OverLimitSettings)

An overlimit settings.

object (CardProductCreditSettings)

Card product credit settings.

pan_format_token
string <= 36 characters

Identifier for the Pan Format Token. If not provided then default PAN format will be used.

track_format_token
string <= 36 characters

Identifier for the Track Format. If not provided then default Track format will be used.

proxy_format_token
string <= 36 characters

Identifier for Proxy format

type
string (CardProductType)
Enum: "PREPAID" "CREDIT"

Card product type.

sub_type
string (CardProductSubType)
Enum: "SECURE" "REVOLVING"

Card product sub-type.

is_multi_currency_product
boolean
Default: false

Indicates whether the product is single currency or multi currency supported.

object (WalletSettings)

Wallet settings. If 'is_multi_currency_product' = true, then it becomes mandatory.

Array of objects (FxRatesSettings)

An array of FX rates settings.

reminder_intervals
Array of integers <int32> [ items <int32 > [ 1 .. 15 ] ]

An array of data.

Responses

Request samples

Content type
application/json
{
  • "id": "cardproduct1",
  • "description": "Some description of the cardproduct1",
  • "status": "INACTIVE",
  • "currency_settings": [
    ],
  • "card_settings": {
    },
  • "credit_limits": {
    },
  • "account_settings": {
    },
  • "pin_settings": {
    },
  • "auth_settings": {
    },
  • "over_limit_settings": {
    },
  • "credit_settings": {
    },
  • "pan_format_token": "default_pan_format",
  • "track_format_token": "default_track_format",
  • "proxy_format_token": "default_proxy_format",
  • "type": "PREPAID",
  • "sub_type": "SECURE",
  • "is_multi_currency_product": true,
  • "wallet_settings": {
    },
  • "fxrates_settings": [
    ],
  • "reminder_intervals": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the card product",
  • "status": "INACTIVE",
  • "currency_settings": [
    ],
  • "card_settings": {
    },
  • "credit_settings": {
    },
  • "account_settings": {
    },
  • "pin_settings": {
    },
  • "auth_settings": {
    },
  • "over_limit_settings": {
    },
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "pan_format_token": "default_pan_format",
  • "track_format_token": "default_track_format",
  • "proxy_format_token": "default_proxy_format",
  • "type": "PREPAID",
  • "sub_type": "SECURE",
  • "is_multi_currency_product": true,
  • "wallet_settings": {
    },
  • "fxrates_settings": [
    ],
  • "reminder_intervals": [
    ],
  • "is_click_to_pay_product": false,
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Get list of all card products

This API is used to get the list of all card products.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get card product

This API is used to return a specific card product using its ID.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the card product",
  • "status": "INACTIVE",
  • "currency_settings": [
    ],
  • "card_settings": {
    },
  • "credit_settings": {
    },
  • "account_settings": {
    },
  • "pin_settings": {
    },
  • "auth_settings": {
    },
  • "over_limit_settings": {
    },
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "pan_format_token": "default_pan_format",
  • "track_format_token": "default_track_format",
  • "proxy_format_token": "default_proxy_format",
  • "type": "PREPAID",
  • "sub_type": "SECURE",
  • "is_multi_currency_product": true,
  • "wallet_settings": {
    },
  • "fxrates_settings": [
    ],
  • "reminder_intervals": [
    ],
  • "is_click_to_pay_product": false,
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Update card product

This API is used to update parameters of a specific card product. You can check what parameters cannot be updated for an ACTIVE/SUSPENDED card product in this doc - https://docs.nymcard.com/get-started/product-management/card-product#update-a-card-product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Request Body schema: application/json
required
description
string

The name of the card product. We recommend using a unique string.

status
string (UpdateCardProductStatus)
Value: "ACTIVE"

This is the card product status. When card product is created, it has status 'INACTIVE'. Once a card is issued for the card product, the status will become 'ACTIVE'.

Array of objects (CurrencySettings)

An array of currency settings to define the related characteristics such as supported currencies, settlement currencies, priority, currency status, etc. for the card product. Already added currencies cannot be deleted but can be marked as inactive. When product status is active then currency fields can't be modified for currency with priority = 1.

object (CardSettingsUpdateRequest)

An array of card settings to define the related characteristics such as bin, pan length, pan range, card validity code, etc. for the card product.

object (AccountSettings)

An array of account settings to define the related characteristics such as link account to card, number of cards per account etc. for the card product.

object (PinSettings)

An array of PIN settings to define the related characteristics such as PIN type, PIN length, and PIN retries for the card product.

object (AuthSettings)

An array of authorization settings to define the related characteristics such as transaction controlling (enabling/disabling), authorization aging, etc. for the card product. Note that auth settings cannot be updated for an ACTIVE card product.

object (OverLimitSettings)

An overlimit settings.

object (CardProductCreditSettings)

Card product credit settings.

pan_format_token
string <= 36 characters

Identifier for the Pan Format Token. If not provided then default PAN format will be used.

track_format_token
string <= 36 characters

Identifier for the Track Format. If not provided then default Track format will be used.

proxy_format_token
string <= 36 characters

Identifier for Proxy format

type
string (CardProductType)
Enum: "PREPAID" "CREDIT"

Card product type.

is_multi_currency_product
boolean

Indicates whether the product is single currency or multi currency supported.

object (WalletSettings)

Wallet settings. If 'is_multi_currency_product' = true, then it becomes mandatory.

Array of objects (FxRatesSettings)

An array of FX rates settings.

reminder_intervals
Array of integers <int32> [ items <int32 > [ 1 .. 15 ] ]

An array of data.

Responses

Request samples

Content type
application/json
{
  • "description": "Some description of the card product",
  • "status": "ACTIVE",
  • "currency_settings": [
    ],
  • "card_settings": {
    },
  • "account_settings": {
    },
  • "pin_settings": {
    },
  • "auth_settings": {
    },
  • "over_limit_settings": {
    },
  • "credit_settings": {
    },
  • "pan_format_token": "default_pan_format",
  • "track_format_token": "default_track_format",
  • "proxy_format_token": "default_proxy_format",
  • "type": "PREPAID",
  • "is_multi_currency_product": true,
  • "wallet_settings": {
    },
  • "fxrates_settings": [
    ],
  • "reminder_intervals": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the card product",
  • "status": "INACTIVE",
  • "currency_settings": [
    ],
  • "card_settings": {
    },
  • "credit_settings": {
    },
  • "account_settings": {
    },
  • "pin_settings": {
    },
  • "auth_settings": {
    },
  • "over_limit_settings": {
    },
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "pan_format_token": "default_pan_format",
  • "track_format_token": "default_track_format",
  • "proxy_format_token": "default_proxy_format",
  • "type": "PREPAID",
  • "sub_type": "SECURE",
  • "is_multi_currency_product": true,
  • "wallet_settings": {
    },
  • "fxrates_settings": [
    ],
  • "reminder_intervals": [
    ],
  • "is_click_to_pay_product": false,
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Get list of velocity limits related to the card product

This API is used to get the list of velocity limits related to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
]

Link velocity limits to the card product

This API is used to link an array of velocity limits to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Request Body schema: application/json
required

An array of velocity limits IDs which require to be linked.

ids
Array of strings

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "velocitylimit04"
]

Unlink velocity limits from the card product

This API is used to unlink a specific velocity limit from a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Request Body schema: application/json
required

An array of velocity limits IDs which require to be unlinked.

ids
Array of strings

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "velocitylimit04"
]

Get advanced velocity limits related to card product

This API is used to retrieve the list of advanced velocity limits related to specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "advancedlimit04"
]

Link advanced velocity limits to card product

This API is used to link an array of advanced velocity limits to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The card product ID.

Request Body schema: application/json
required

The advanced velocity limit ID list to be linked with card product.

ids
Array of strings

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "advancedlimit04"
]

Unlink advanced velocity limits from card product

This API is used to unlink a specific advanced velocity limit from a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The card product ID.

Request Body schema: application/json
required

The velocity limit ID list to be unlinked from card product.

ids
Array of strings

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "advancedlimit04"
]

Get list of balance limits related to the card product

This API is used to get the list of balance limits related to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
]

Link balance limits to the card product

This API is used to link an array of balance limits to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Request Body schema: application/json
required

An array of balance limits IDs which require to be linked.

ids
Array of strings

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
]

Unlink balance limits from the card product

This API is used to unlink an array of balance limits from a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Request Body schema: application/json
required

An array of balance limits IDs which require to be unlinked.

ids
Array of strings

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
]

Get list of fees related to the card product

This API is used to get the list of fees related to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
]

Link fees to the card product

This API is used to link an array of fees to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Request Body schema: application/json
required

An array of fees IDs which require to be linked.

ids
Array of strings

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
]

Unlink fees from the card product

This API is used to unlink a specific fee from a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product.

Request Body schema: application/json
required

An array of fees IDs which require to be unlinked.

ids
Array of strings

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
]

Link charge to card product

This API is used to link an array of charges to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product.

Request Body schema: application/json
required

The charges ID list to be linked with card product.

ids
Array of strings[ items <= 36 characters ]

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
]

Unlink charge from card product

This API is used to unlink charges from a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product.

Request Body schema: application/json
required

The charges ID list to be unlinked from card product.

ids
Array of strings[ items <= 36 characters ]

An array of IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6"
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c3eddd6"
]

Get list of charges related to card product

This API is used to retrieve a list of charges related to specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "4b4eabfc-f839-4e51-9dc1-3dc25c3eddd6"
]

Get holiday calendars linked to card product

This API is used to get holiday calendars linked to card product.

Authorizations:
apikey
path Parameters
id
required
string

Card Product ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "holiday_calendar_ids": [
    ]
}

Link holiday calendar to card product

This API is used to link holiday calendar to card product.

Authorizations:
apikey
path Parameters
id
required
string

Card Product ID.

Request Body schema: application/json
required
holiday_calendar_ids
Array of strings[ items <= 36 characters ]

Responses

Request samples

Content type
application/json
{
  • "holiday_calendar_ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "holiday_calendar_ids": [
    ]
}

Unlink holiday calendar from card product

This API is used to unlink holiday calendar from card product.

Authorizations:
apikey
path Parameters
id
required
string

Card Product ID.

Request Body schema: application/json
required
holiday_calendar_ids
Array of strings[ items <= 36 characters ]

Responses

Request samples

Content type
application/json
{
  • "holiday_calendar_ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "holiday_calendar_ids": [
    ]
}

Get advanced fees linked to card product

This API is used to retrieve a list of advanced fees related to specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "5b4eabfc-f839-4e51-9dc1-3dc25c3eddd6"
]

Link advanced fees to card product

This API is used to link advanced fees to a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product.

Request Body schema: application/json
required

Advanced fee ID list to be linked to a card product.

ids
Array of strings[ items <= 36 characters ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "5b4eabfc-f839-4e51-9dc1-3dc25c3eddd6"
]

Unlink advanced fees from card product

This API is used to unlink advanced fees from a specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card product.

Request Body schema: application/json
required

Advanced fee ID list to be unlinked from a card product.

ids
Array of strings[ items <= 36 characters ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "5b4eabfc-f839-4e51-9dc1-3dc25c3eddd6"
]

Upload card design image for product

This API is used to upload card design image for product.

Authorizations:
apikey
path Parameters
product_id
required
string

The Card Product ID.

Request Body schema: application/x-www-form-urlencoded
card_design_id
string = 10 characters ^[a-zA-Z0-9]{10}$

The design image ID.

file
required
string <binary>

Image file to be uploaded.

is_default
required
boolean

This field indicates if design is default.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "test0",
  • "file_id": "e5a7b3fc-268b-4273-89d3-bc85682b3577.png",
  • "file_name": "accepted_image.png",
  • "content_type": "image/png",
  • "size": 524288,
  • "is_default": true,
  • "product_id": "e5a7b3fc-268b-4273-89d3-bc85682b3577",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get card design file

This API is used to get card design file.

Authorizations:
apikey
path Parameters
product_id
required
string

The Card Product ID.

design_id
required
string

The design image ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "FileUploadContent",
  • "user_id": "user120",
  • "metadata": {
    },
  • "content": "2rl0Dvc1gTrOTTqzgNaK62wj9tT91kEZRjUGF2kWWeBN4BGy7xYdAR7Mc6duajDBLQ_y8pBKeXaxRPUXIcK5K734Z7rmtAYIzMam2RClvKcU"
}

Update card design image for product

This API is used to update card design image for product.

Authorizations:
apikey
path Parameters
product_id
required
string

The Card Product ID.

design_id
required
string

The design image ID.

Request Body schema: application/x-www-form-urlencoded
required
file
required
string <binary>

Image file to be uploaded.

is_default
required
boolean

This field indicates if design is default.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "test0",
  • "file_id": "e5a7b3fc-268b-4273-89d3-bc85682b3577.png",
  • "file_name": "accepted_image.png",
  • "content_type": "image/png",
  • "size": 524288,
  • "is_default": true,
  • "product_id": "e5a7b3fc-268b-4273-89d3-bc85682b3577",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get card designs metadata for product

This API is used to get card designs metadata for product.

Authorizations:
apikey
path Parameters
product_id
required
string

The Card Product ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "product_id": "d294a80f-e641-4045-8a80-54841e4a7458",
  • "values": [
    ]
}

Get list of APR profiles for card product

This API is used to retrieve APR profiles for specific card product.

Authorizations:
apikey
path Parameters
product_id
required
string

The unique identifier of the card product.

query Parameters
apr_name
string

This field optionally returns only apr profiles for specific AprName, like PURCHASE_APR or CASHADVANCE_APR.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "apr_profiles": [
    ],
  • "apr_profiles_with_errors": [
    ]
}

Create APR profile(s) for card product

This API is used to create APR profile for specific card product.

Authorizations:
apikey
path Parameters
product_id
required
string

The unique identifier of the card product.

Request Body schema: application/json
required

The list of apr profiles to create under the card product.

Array
id
string <= 36 characters

Unique ID for APR profile.

profile_name
required
string

Name of the profile.

apr_name
required
string (AprName)
Enum: "PURCHASE_APR" "CASHADVANCE_APR"

The APR name for which the APR profile is being created.

fc_method_name
required
string (AprFcMethodName)
Value: "AVERAGE_DAILY_BALANCE"

Interest calculation method to be used for the APR profile.

apr_type
string (AprType)
Default: "FIXED"
Value: "FIXED"

The type of APR.

apr_value
required
number >= 0

The APR value intended for use with a specific APR ID.

effective_from
required
string (AprEffectiveFrom)
Value: "SPECIFIC_DATE"

Indicate from when this APR should be applied.

effective_date
string <date>

The date when new APR will become applicable. If the effective date is not provided, the system will automatically insert today’s date.

applicable_on
string (AprApplicableOn)
Default: "OVERALL_BALANCE"
Value: "OVERALL_BALANCE"

Indicate the balance on which this APR should be applied.

interest_trigger_date
required
string (AprInterestTriggerDate)
Enum: "DUE_DATE" "TRANSACTION_DATE"

The date from which the interest should be charged.

apply_daily_compounding
boolean

This field indicates if previous daily interest is compounded in the current day's APR calculation.

apply_monthly_compounding
boolean

If true, then system will consider FC balance bucket as part of overall purchase balance when computing interest for the billing period. Only applicable for PURCHASE_APR.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json;charset=UTF-8
{
  • "apr_profiles": [
    ],
  • "apr_profiles_with_errors": [
    ]
}

Get specific APR profile for specific card product

This API is used to retrieve specific APR profile for specific card product.

Authorizations:
apikey
path Parameters
product_id
required
string

The unique identifier of the card product.

profile_id
required
string

The unique identifier of the APR profile.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "profile_name": "profile1",
  • "apr_name": "PURCHASE_APR",
  • "fc_method_name": "AVERAGE_DAILY_BALANCE",
  • "apr_type": "FIXED",
  • "apr_value": 0,
  • "effective_from": "SPECIFIC_DATE",
  • "effective_date": "2022-05-04T19:42:32.987Z",
  • "applicable_on": "OVERALL_BALANCE",
  • "interest_trigger_date": "DUE_DATE",
  • "apply_daily_compounding": false,
  • "apply_monthly_compounding": false
}

Create delinquency

This API is used to create a delinquency.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the charge.

required
Array of objects (DelinquencyAction)

An array of data.

Responses

Request samples

Content type
application/json
{
  • "id": "2",
  • "delinquency_actions": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "1d089a80f-e641-4045-8a80-54841e4a7458",
  • "delinquency_actions": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "updated": "2012-05-04T19:42:32.987Z"
}

Get list of delinquencies

This API is used to retrieve the list of delinquencies.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get specific delinquency

This API is used to retrieve details of specific delinquency.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of delinquency.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "1d089a80f-e641-4045-8a80-54841e4a7458",
  • "delinquency_actions": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "updated": "2012-05-04T19:42:32.987Z"
}

Update delinquency

This API is used to update a specific delinquency.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of delinquency.

Request Body schema: application/json
required
revert_rule_structure
string (DelinquencyRevertRuleStructure)
Enum: "BASIC" "ADVANCED"

Delinquency revert rule structure.

delinquency_days_greater_than
integer <int32>

This field defines the minimum number of delinquent days after which a specific revert rule becomes applicable.

statement_balance_percentage
number <decimal>

This field specifies the percentage of the statement balance that must be paid before the revert action is triggered.

number_of_delinquency_days
integer <int32> [ 0 .. 360 ]

This field specifies the number of delinquency days after which actions will be triggered.

delinquency_action
string (DelinquencyActionType)
Enum: "INACTIVATE_CARD" "FORFEIT_REWARD_POINTS" "SUSPEND_REWARD_POINTS" "MARK_FOR_COLLECTION" "APPLY_PENALTY_APR" "CHARGEOFF_AND_CLOSE_CARD"

Actions to be triggered after the designated delinquency days have elapsed.

delinquency_revert_rule
string (DelinquencyRevertRule)
Enum: "NO._OF_CONSECUTIVE_MINIMUM_PAYMENTS_RECEIVED" "PERCENTAGE_OF_STATEMENT_BALANCE_PAID"

Revert Rule is the condition that should be met to revert the action.

Array of objects (DelinquencyAdvancedRevertRule)

An array of data.

delinquency_revert_action
string (DelinquencyRevertAction)
Enum: "RESTORE_STANDARD_APR" "REACTIVATE_CARD"

The action that should be taken if condition specified in the Revert Rule is met.

number_of_minimum_payments
integer <int32> >= 0

This field specifies number of minimum payments that should be paid in order to revert the delinquency action.

active
boolean

This field indicates whether delinquency is active or not.

Responses

Request samples

Content type
application/json
{
  • "revert_rule_structure": "BASIC",
  • "delinquency_days_greater_than": 30,
  • "statement_balance_percentage": 50,
  • "number_of_delinquency_days": 30,
  • "delinquency_action": "INACTIVATE_CARD",
  • "delinquency_revert_rule": "NO._OF_CONSECUTIVE_MINIMUM_PAYMENTS_RECEIVED",
  • "delinquency_revert_rules": [
    ],
  • "delinquency_revert_action": "RESTORE_STANDARD_APR",
  • "number_of_minimum_payments": 3,
  • "active": true
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "1d089a80f-e641-4045-8a80-54841e4a7458",
  • "delinquency_actions": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "updated": "2012-05-04T19:42:32.987Z"
}

Get delinquency linked to card product

This API is used to retrieve delinquencies linked to specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "delinquency_id": "1d089a80f-e641-4045-8a80-54841e4a7458"
}

Link delinquency to card product

This API is used to link delinquency to specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of card product.

Request Body schema: application/json
required
delinquency_id
required
string <= 36 characters

The unique identifier of delinquency.

Responses

Request samples

Content type
application/json
{
  • "delinquency_id": "1d089a80f-e641-4045-8a80-54841e4a7458"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "delinquency_id": "1d089a80f-e641-4045-8a80-54841e4a7458"
}

Unlink delinquency from card product

This API is used to unlink delinquency from specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of card product.

Request Body schema: application/json
required
delinquency_id
required
string <= 36 characters

The unique identifier of delinquency.

Responses

Request samples

Content type
application/json
{
  • "delinquency_id": "1d089a80f-e641-4045-8a80-54841e4a7458"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "delinquency_id": "1d089a80f-e641-4045-8a80-54841e4a7458"
}

Get list of credit limits of card product

This API is used to retrieve the list of credit limits of specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "min_credit_limit": 5,
  • "max_credit_limit": 15,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "cash_adv_limit_value": 50,
  • "cash_adv_limit_roundup_factor": 10
}

Update credit limits of card product

This API is used to update credit limits of specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of card product.

Request Body schema: application/json
required
min_credit_limit
number

The numeric number which has min credit limit boundary.

max_credit_limit
number

The numeric number which has max credit limit boundary.

cash_adv_limit_type
string (CashAdvLimitType)
Enum: "PERCENTAGE" "FIXED"

The cash advance limit type.

cash_adv_limit_value
number

The value of cash advance limit.

cash_adv_limit_roundup_factor
number

This field defines the round up factor for the cash advance limit as multiples of 1, 10, 100 and 1000s.

Responses

Request samples

Content type
application/json
{
  • "min_credit_limit": 5,
  • "max_credit_limit": 15,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "cash_adv_limit_value": 50,
  • "cash_adv_limit_roundup_factor": 10
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "min_credit_limit": 5,
  • "max_credit_limit": 15,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "cash_adv_limit_value": 50,
  • "cash_adv_limit_roundup_factor": 10
}

Get list of credit settings of card product

This API is used to retrieve credit settings of specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of card product.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "statement_on": 25,
  • "statement_cycle": "MONTHLY",
  • "grace_period": 1,
  • "late_payment_grace_period": 1,
  • "limit_late_payment_to": "REMAINING_MINIMUM_PAYMENT",
  • "delinquency_grace_period": 1,
  • "delinquency_start_after": "DUE_DATE",
  • "allow_account_level_definition": false,
  • "allow_additional_card": false,
  • "payment_due_on": 2,
  • "first_minimum_topup": 1,
  • "notification_send_before": 1,
  • "security_amount": {
    },
  • "delinquency": [
    ],
  • "payment_settings": {
    },
  • "minimum_payment_settings": {
    }
}

Update credit settings of card product

This API is used to update credit settings of specific card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of card product.

Request Body schema: application/json
required
statement_on
number <integer> [ 1 .. 28 ]

Statement day of the month.

grace_period
number <integer> [ 1 .. 27 ]

This field defines the number of days to add in the billing date to calculate the due date of a billing cycle.

late_payment_grace_period
number <integer> [ 1 .. 5 ]

The period of time granted by a financial institution during which a borrower or debtor can make a payment after the due date without late fee.

delinquency_grace_period
number <integer> [ 1 .. 5 ]

The specified period of time granted by a financial institution during which a borrower or debtor can make a payment after the due date without having an impact on their credit score and other punitive actions.

Responses

Request samples

Content type
application/json
{
  • "statement_on": 25,
  • "grace_period": 25,
  • "late_payment_grace_period": 3,
  • "delinquency_grace_period": 3
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "statement_on": 25,
  • "statement_cycle": "MONTHLY",
  • "grace_period": 1,
  • "late_payment_grace_period": 1,
  • "limit_late_payment_to": "REMAINING_MINIMUM_PAYMENT",
  • "delinquency_grace_period": 1,
  • "delinquency_start_after": "DUE_DATE",
  • "allow_account_level_definition": false,
  • "allow_additional_card": false,
  • "payment_due_on": 2,
  • "first_minimum_topup": 1,
  • "notification_send_before": 1,
  • "security_amount": {
    },
  • "delinquency": [
    ],
  • "payment_settings": {
    },
  • "minimum_payment_settings": {
    }
}

Get allowed merchants linked to card product

This API is used to get allowed merchants linked to card product.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The card product ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "allowed_merchants_id": "1136545698"
}

Link allowed merchants to card product

This API is used to link allowed merchants to a card product.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The card product ID.

Request Body schema: application/json
required

Allowed merchants ID to be linked to the card product.

merchant_list_id
required
string

Merchant list Identifier.

Responses

Request samples

Content type
application/json
{
  • "merchant_list_id": "0c0396de-b78f-40cc-93d6-d75387005a0c"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "allowed_merchants_id": "1136545698"
}

Unlink allowed merchants from card product

This API is used to unlink allowed merchants from a card product.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The card product ID.

Request Body schema: application/json
required

Allowed merchants ID to be unlinked from the card product.

merchant_list_id
required
string

Merchant list Identifier.

Responses

Request samples

Content type
application/json
{
  • "merchant_list_id": "0c0396de-b78f-40cc-93d6-d75387005a0c"
}

Link allowed merchant lists to a card product (V2)

Links one or more merchant lists to a card product. All linked lists must share the same type (ALLOWED or BLOCKED). If a list of a different type is already linked, the request will be rejected.

Authorizations:
apikey
path Parameters
id
required
string
Request Body schema: application/json
required

Merchant list IDs to be linked to the card product

merchant_list_ids
required
Array of strings non-empty

List of merchant list identifiers to link

Responses

Request samples

Content type
application/json
{
  • "merchant_list_ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "allowed_merchants_ids": [
    ]
}

Unlink allowed merchant lists from a card product (V2)

Authorizations:
apikey
path Parameters
id
required
string
Request Body schema: application/json
required

Merchant list IDs to be unlinked from the card product

merchant_list_ids
required
Array of strings non-empty

List of merchant list identifiers to link

Responses

Request samples

Content type
application/json
{
  • "merchant_list_ids": [
    ]
}

Get all allowed merchant lists linked to card product (V2)

Authorizations:
apikey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "allowed_merchants_ids": [
    ]
}

Get list of card product FX rates

This API is used to retrieve FX rates of a specific card product.

Authorizations:
apikey
query Parameters
card_product_id
required
string
Example: card_product_id=g189a80f-e641-4045-8a80-54841e4a1234

Card product ID for which FX rates are fetched.

from_currency
string^[A-Z]{3}
Example: from_currency=USD

3-letter ISO_4217 code representing the currency, from which we are converting.

to_currency
string^[A-Z]{3}
Example: to_currency=EUR

3-letter ISO_4217 code representing the currency, to which we are converting.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "fxrates": [
    ]
}

Update FX rates for card product

This API is used to update FX rates for a specific card product.

Authorizations:
apikey
Request Body schema: application/json
required
card_product_id
required
string <= 36 characters

ID of a card product for which FX rates are updated.

required
Array of objects (FxRateUpsert) non-empty

An array of 'fxrates' parameters.

Responses

Request samples

Content type
application/json
{
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "fxrates": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "fxrates": [
    ]
}

Users

Our nCore platform gives a capability to register a new user. This user is an individual to whom cards can be issued, and who can maintain funds in the platform. The system captures information for user identification documents. The supported identification documents are dynamically defined at each tenant level. Such information as ID number, expiration date, and other dynamic fields are captured. The system also provides an option to upload the identification document scanned images. All the user demographic information (like name, email, mobile, DOB etc.) and the identification document information is inherently optional in the 'Create user' API. However, it is defined at the tenant level which demographic and identification document information is mandatory to create a new user profile. The uniqueness criteria for a user is defined dynamically at the tenant level. The uniqueness check is defined on one field (e.g. mobile number) or more than one field (e.g. mobile number and email address).

Get list of all users

This API is used to retrieve all existing users.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

parent_user_id
string

Parent user ID to retrieve child users.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "Durable version of current results",
  • "has_more": true,
  • "data": [
    ]
}

Create user

This API is used to create a new user. You can find all necessary fields for creation of each user type in this GSG doc - https://docs.nymcard.com/get-started/program-management/necessary-parameters-per-user-type.

Authorizations:
apikey
Request Body schema: application/json
required

User information

id
string

Unique identifier of the user. If this information is not present in the request, the system generates one automatically. Please note that this token ID is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

title
string (UserTitle)
Enum: "MR" "MRS" "MISS"

The user's title/prefix.

first_name
required
string <= 60 characters

User's first name. This parameter is optional for 'user_type'=BUSINESS. Note, that when you want to simulate an Identity Verification process, please provide both the user's 'first_name' and 'last_name' parameters. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

middle_name
string <= 60 characters

User's middle name. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

last_name
string <= 60 characters

User's last name. This parameter is mandatory to provide when Identity verification is required. Note, that when you want to simulate an Identity Verification process, please provide both the user's 'first_name' and 'last_name' parameters. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

native_name
string <= 60 characters

Native name of the user. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

native_last_name
string <= 60 characters

Native last name.

date_of_birth
string <date>

The date of birth of the user in the following format - yyyy-mm-dd. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

email
string <= 255 characters

A valid email address for the user.

mobile
string

Mobile number of the user (including area code), appended with "+" symbol and the first three digits to identify the country calling code. Please do not include hyphens, spaces or parentheses.

object (Address)

The details of the address. "ADDRESS" parameter stands for user's address. "COMPANY_ADDRESS" parameter stands for company's address. "LOCAL_ADDRESS" parameter stands for designated address shared in onboarding form for shareholders. It is mandatory to provide "LOCAL_ADDRESS" parameter if 'user_type' is SHAREHOLDER.

gender
string (UserGender)
Enum: "MALE" "FEMALE"

The gender of the user. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

education_level
string <= 50 characters

Education level.

preferred_language
string

A selected language for 3D Secure and digital wallet token notifications sent to this user. By default, notifications are sent in English. The supported value should be provided in ISO language format.

place_of_birth
string

The place of birth of the user. The format should be ISO alpha 3-character country code. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

place_of_birth_city
string <= 50 characters

The city of birth.

nationality
string

Nationality; must be one of ISO alpha 3-character country code. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

parent_user_id
string

Unique identifier of parent user. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

created_by
string <= 50 characters

Identifier of user's creator.

country_residence
string <= 3 characters

The country where the individual user resides or is currently citizen of. The format is ISO alpha 3-character country code. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

country_tax_residence
string <= 3 characters

The country for which the tax rules apply to the individual/business user and the user pays tax according to it. The format is ISO alpha 3-character country code.

employment_type
string (EmploymentType)
Enum: "SALARIED" "SELF_EMPLOYED" "RETIRED" "NOT_EMPLOYED" "BUSINESS_OWNER" "STUDENT" "HOMEMAKER" "OTHER"

The employment type of the individual user.

employment_title
string <= 50 characters

The job title (designation) for user_type = INDIVIDUAL. For user_type = BUSINESS this field can give the designation of the primary contact person of the business.

monthly_salary
number >= 0

The monthly salary of the user_type = INDIVIDUAL.

company_name
string <= 200 characters

The company name for which the individual works for in case of SALARIED or company name that the individual runs in case of SELF-EMPLOYED or BUSINESS_OWNER. This parameter is required if "employment_type" = 'SALARIED", "EMPLOYED" or "BUSINESS_OWNER".

object (Address)

The details of the address. "ADDRESS" parameter stands for user's address. "COMPANY_ADDRESS" parameter stands for company's address. "LOCAL_ADDRESS" parameter stands for designated address shared in onboarding form for shareholders. It is mandatory to provide "LOCAL_ADDRESS" parameter if 'user_type' is SHAREHOLDER.

company_country
string <= 3 characters

Company country in format of ISO alpha 3-character country code. For user_type = INDIVIDUAL this field indicates the country in which the company is registered and conducts its business and activities. For user_type = BUSINESS this field indicates the country in which the business is registered and conducts its activities.

industry_type
string (IndustryType)
Enum: "I01" "I02" "I03" "I04" "I05" "I06" "I07" "I08" "I09" "I11" "I12" "I13" "I14" "I15" "I16" "I17" "I18" "I19" "I20" "I21" "I22" "I23" "I24" "I25" "I26" "I27" "I28" "I29" "I30" "I00"

Type of industry:

  • I01: Gambling/Casinos
  • I02: Defence/Military goods or Arms Dealers and Manufacturers
  • I03: Exchange Companies / Bureaus de Change, Money Changers, Hawala dealers / Other Finance Companies (For e.g. Derivatives Trading, Hedge Funds, Unregistered/Pvt Collective Investment Schemes)
  • I04: Real Estate Brokers / Real Estate Agencies / Real Estate Developers (Non * Govt)
  • I05: Charity Organizations, Religious/Social/Non * Profit Organizations, Cooperative/Social/Professional Societies & associations
  • I06: Auction Houses
  • I07: Dealers in Luxury Goods: (Definition of Luxury Goods include: Precious metals & Stones, Jewelry & Antiques, Art, Furs, Yachts , Executive/Private Jets)
  • I08: Trust Service Providers, Lawyers, Accountants, Tax Advisers, Auditors
  • I09: Private Banking Relationship
  • I11: Agriculture, Forestry, Fishing, and Hunting
  • I12: Mining, Quarrying, and Oil and Gas Extraction
  • I13: Utilities (water, gas, electricity)
  • I14: Telecommunications
  • I15: Construction
  • I16: Manufacturing
  • I17: Wholesale Trade
  • I18: Retail Trade and Commerce
  • I19: Transportation and Warehousing
  • I20: Technology
  • I21: Finance and Insurance
  • I22: Real Estate and Rental and Leasing
  • I23: Professional, Scientific, and Technical Services
  • I24: Management of Companies and Enterprises
  • I25: Educational Services
  • I26: Health Care and Social Assistance
  • I27: Arts, Entertainment, and Recreation
  • I28: Hotels and Food Services
  • I29: Public Administration
  • I30: Administrative and Support and Waste Management
  • I00: Other
expected_monthly_balance
number >= 0

For user_type = INDIVIDUAL this field indicates the expected monthly balance the individual user is planning to maintain in his accounts. For user_type = BUSINESS this field indicates the expected monthly balance the business is planning to maintain in its accounts.

relationship_with_parent
string (RelationshipWithParent)
Enum: "SON" "DAUGHTER" "NEPHEW" "NIECE" "HUSBAND" "WIFE" "FATHER" "MOTHER" "EMPLOYEE" "OTHER"

For a child user this field indicates the relationship of the child user with the parent user.

user_type
string (UserType)
Enum: "INDIVIDUAL" "BUSINESS" "DIRECTOR" "SIGNATURE" "SHAREHOLDER" "SHAREHOLDER_BUSINESS"

The type of the user. You can find all necessary fields per each user type in this GSG doc - https://docs.nymcard.com/get-started/program-management/necessary-parameters-per-user-type.

business_legal_name
string <= 200 characters

The business legal name. This field may be used for KYB verification. Applicable for 'user_type' = BUSINESS.

business_dba_name
string <= 50 characters

The business’s secondary name. This field may be used for KYB verification, if the business name is different from the legal business name. Applicable for 'user_type' = BUSINESS.

date_established
string <date-time>

The established date and time. Applicable for 'user_type' = BUSINESS.

phone_number
string^\+\d+

The telephone number.

website
string <= 50 characters

The website. Applicable for 'user_type' = BUSINESS.

designation
string <= 50 characters

It is mandatory to provide this parameter if 'user_type' is DIRECTOR or SIGNATURE. The valid designation should be provided, such as: CEO, CPO, CEO - (region name).

shares_percentage
number <float>

It is mandatory to provide this parameter if 'user_type' is SHAREHOLDER or SHAREHOLDER_BUSINESS.

share_controller_name
string <= 100 characters

It is mandatory to provide this parameter if 'user_type' is SHAREHOLDER or SHAREHOLDER_BUSINESS.

object (Address)

The details of the address. "ADDRESS" parameter stands for user's address. "COMPANY_ADDRESS" parameter stands for company's address. "LOCAL_ADDRESS" parameter stands for designated address shared in onboarding form for shareholders. It is mandatory to provide "LOCAL_ADDRESS" parameter if 'user_type' is SHAREHOLDER.

incorporation_type
string (UserIncorporationType)
Enum: "LTD" "LLC" "FZE" "FZCO" "FZ-LLC" "INC" "FOUNDATION" "TRUST" "FUND" "PUBLIC_TRADED" "GOVT_OWNED" "LLP" "OTHER"

This parameter indicates whether this business entity is Limited, LLC, Free-zone or anything else.

entity_registered_no
string <= 50 characters

This parameter describes the business/entity registered number.

old_entity_name
string <= 50 characters

This parameter describes the business’s old name.

old_entity_ops_start_date
string <date-time>

It is the start date when the business was operated under old name.

old_entity_ops_end_date
string <date-time>

It is the end date when the business was operated under old name.

regulated_entity
boolean

This parameter indicates if the entity is a regulated entity or no. Possible values are true/false.

regulator_name
string <= 50 characters

This parameter indicates the regulator’s name. It is applicable if 'regulated_entity' parameter is set as 'true'.

business_activities
string <= 1000 characters

This parameter describes the business/entity activities such as Payment Service Provider, IT service provider etc. It can be a comma separated values.

other_operated_countries
string

This parameter indicates the valid country's name(s), where the business is operated.

tax_residence_country
string <= 50 characters

This parameter indicates the name of a country, where the business has a tax residence.

tin
string <= 50 characters

Tax identification number.

external_auditor_name
string <= 50 characters

Name of the external auditor.

director_list
Array of strings

The list of directors. Up to 10 directors can be linked to a business user; but directors should be created prior creating the business user (if providing any ID in the list), else you can link the user later with the business.

signature_list
Array of strings

The list of signatures. Up to 10 signatures can be linked to a business user; but the signatures should be created prior creating the business user (if providing any ID in the list), else you can link the user later with the business.

shareholder_list
Array of strings

The list of shareholders. Up to 50 shareholders can be linked to a business user; but the shareholders should be created prior creating the business user (if providing any ID in the list), else you can link the user later with the business.

company_onbehalf
boolean

This parameter indicates if the company is opened on behalf of another person. Possible values are true/false.

company_onbehalf_relation
string <= 50 characters

In this parameter you should confirm the relationship of the beneficial owner. It is applicable if 'company_onbehalf' parameter is set as 'true'.

object (UserGroupAdditionalInfo)

The additional information, which describes whether entity is a part of a group etc.

object (UserPepCheckInfo)

The information about checking politically exposed persons (“PEPs”) among main shareholders, directors of the entity.

no_of_employees
integer <int32> (UserNoOfEmployees)

This parameter describes the number of employees for the business entity.

accept_cash_check
boolean

This parameter indicates whether the corporate company accepts cash from end users or not. Possible values are true/false.

annual_turnover
number

This parameter describes the annual turnover of the business entity.

source_of_funds
string <= 50 characters

This parameter describes how is the company being funded.

source_fund_uae
boolean

This parameter indicates whether the business source of funds is derived from outside of the UAE or no. Possible values are true/false.

object (UserDueDiligenceDeclaration)

The information about due diligence declaration.

license_type
string <= 100 characters

The license type. This parameter is applicable for 'user_type' = SHAREHOLDER_BUSINESS.

license_expiry
string <date>

The license expiry. This parameter is applicable for 'user_type' = SHAREHOLDER_BUSINESS.

estimated_activity_through_nymcard
string

This parameter is optional and applicable for 'user_type' = BUSINESS.

expected_number_of_cards
integer <int32> >= 0

This parameter is optional and applicable for 'user_type' = BUSINESS.

expected_use_of_ncs_services
string

This parameter is optional and applicable for 'user_type' = BUSINESS.

object

This parameter holds additional fields configured in tenant settings. This parameter is optional.

Responses

Request samples

Content type
application/json
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "title": "MR",
  • "first_name": "John",
  • "middle_name": "Anthony",
  • "last_name": "Smith",
  • "native_name": "John Smith",
  • "native_last_name": "Júañ Hérreró",
  • "date_of_birth": "2012-05-04",
  • "email": "bob@example.com",
  • "mobile": "+551185249635",
  • "address": {
    },
  • "gender": "MALE",
  • "education_level": "Graduate",
  • "preferred_language": "EN",
  • "place_of_birth": "USA",
  • "place_of_birth_city": "Toronto",
  • "nationality": "USA",
  • "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "created_by": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "country_residence": "USA",
  • "country_tax_residence": "USA",
  • "employment_type": "SALARIED",
  • "employment_title": "QAE",
  • "monthly_salary": "12000",
  • "company_name": "Example",
  • "company_address": {
    },
  • "company_country": "USA",
  • "industry_type": "I01",
  • "expected_monthly_balance": "100000",
  • "relationship_with_parent": "SON",
  • "user_type": "INDIVIDUAL",
  • "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",
  • "designation": "CEO",
  • "shares_percentage": 100,
  • "share_controller_name": "Nabil Benaissa",
  • "local_address": {
    },
  • "incorporation_type": "LTD",
  • "entity_registered_no": "2233445533",
  • "old_entity_name": "Old name",
  • "old_entity_ops_start_date": "2012-05-04",
  • "old_entity_ops_end_date": "2014-05-04",
  • "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": [
    ],
  • "signature_list": [
    ],
  • "shareholder_list": [
    ],
  • "company_onbehalf": true,
  • "company_onbehalf_relation": "John Smith",
  • "group_additional_info": {
    },
  • "pep_check_info": {
    },
  • "no_of_employees": 25,
  • "accept_cash_check": true,
  • "annual_turnover": 0,
  • "source_of_funds": "Business",
  • "source_fund_uae": true,
  • "due_diligence_declaration": {
    },
  • "license_type": "Test License Updated",
  • "license_expiry": "2025-06-06",
  • "estimated_activity_through_nymcard": "ABCD",
  • "expected_number_of_cards": "1",
  • "expected_use_of_ncs_services": "ABCD",
  • "custom_info": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "title": "MR",
  • "first_name": "John",
  • "middle_name": "Anthony",
  • "last_name": "Smith",
  • "native_name": "John Smith",
  • "native_last_name": "Júañ Hérreró",
  • "full_legal_name": "John Smith",
  • "full_name_local_language": "Volodymyr",
  • "father_name": "John Smith",
  • "mother_name": "Mary Ann",
  • "grandfather_name": "Andrew",
  • "family_name": "Smith",
  • "marital_status": "Divorced",
  • "employment_status": "Worker",
  • "business_type": "LCC",
  • "legal_form": "Company",
  • "date_of_birth": "2012-05-04",
  • "email": "bob@example.com",
  • "mobile": "+551185249635",
  • "address": {
    },
  • "gender": "MALE",
  • "education_level": "Graduate",
  • "preferred_language": "EN",
  • "place_of_birth": "USA",
  • "place_of_birth_city": "Toronto",
  • "nationality": "USA",
  • "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "created": "2012-05-04T19:42:32.987Z",
  • "created_by": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "modified_by": "API",
  • "country_residence": "USA",
  • "country_tax_residence": "USA",
  • "employment_type": "SALARIED",
  • "employment_title": "QAE",
  • "monthly_salary": "12000",
  • "company_name": "Example",
  • "company_address": {
    },
  • "company_country": "USA",
  • "industry_type": "I01",
  • "expected_monthly_balance": "100000",
  • "relationship_with_parent": "SON",
  • "user_type": "INDIVIDUAL",
  • "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",
  • "status": "PENDINGKYC",
  • "status_reason_code": "I0",
  • "kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY",
  • "designation": "CEO",
  • "shares_percentage": 100,
  • "share_controller_name": "Nabil Benaissa",
  • "local_address": {
    },
  • "incorporation_type": "LTD",
  • "entity_registered_no": "2233445533",
  • "old_entity_name": "Old name",
  • "old_entity_ops_start_date": "2012-05-04",
  • "old_entity_ops_end_date": "2014-05-04",
  • "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": [
    ],
  • "signature_list": [
    ],
  • "shareholder_list": [
    ],
  • "company_onbehalf": true,
  • "company_onbehalf_relation": "John Smith",
  • "group_additional_info": {
    },
  • "pep_check_info": {
    },
  • "no_of_employees": 25,
  • "accept_cash_check": true,
  • "annual_turnover": 0,
  • "source_of_funds": "Business",
  • "source_fund_uae": true,
  • "due_diligence_declaration": {
    },
  • "license_type": "Test License Updated",
  • "license_expiry": "2025-06-06",
  • "estimated_activity_through_nymcard": "ABCD",
  • "expected_number_of_cards": "1",
  • "expected_use_of_ncs_services": "ABCD",
  • "custom_info": {
    }
}

Get user details

This API is used to get the details of a specific user.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the user.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "title": "MR",
  • "first_name": "John",
  • "middle_name": "Anthony",
  • "last_name": "Smith",
  • "native_name": "John Smith",
  • "native_last_name": "Júañ Hérreró",
  • "full_legal_name": "John Smith",
  • "full_name_local_language": "Volodymyr",
  • "father_name": "John Smith",
  • "mother_name": "Mary Ann",
  • "grandfather_name": "Andrew",
  • "family_name": "Smith",
  • "marital_status": "Divorced",
  • "employment_status": "Worker",
  • "business_type": "LCC",
  • "legal_form": "Company",
  • "date_of_birth": "2012-05-04",
  • "email": "bob@example.com",
  • "mobile": "+551185249635",
  • "address": {
    },
  • "gender": "MALE",
  • "education_level": "Graduate",
  • "preferred_language": "EN",
  • "place_of_birth": "USA",
  • "place_of_birth_city": "Toronto",
  • "nationality": "USA",
  • "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "created": "2012-05-04T19:42:32.987Z",
  • "created_by": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "modified_by": "API",
  • "country_residence": "USA",
  • "country_tax_residence": "USA",
  • "employment_type": "SALARIED",
  • "employment_title": "QAE",
  • "monthly_salary": "12000",
  • "company_name": "Example",
  • "company_address": {
    },
  • "company_country": "USA",
  • "industry_type": "I01",
  • "expected_monthly_balance": "100000",
  • "relationship_with_parent": "SON",
  • "user_type": "INDIVIDUAL",
  • "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",
  • "status": "PENDINGKYC",
  • "status_reason_code": "I0",
  • "kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY",
  • "designation": "CEO",
  • "shares_percentage": 100,
  • "share_controller_name": "Nabil Benaissa",
  • "local_address": {
    },
  • "incorporation_type": "LTD",
  • "entity_registered_no": "2233445533",
  • "old_entity_name": "Old name",
  • "old_entity_ops_start_date": "2012-05-04",
  • "old_entity_ops_end_date": "2014-05-04",
  • "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": [
    ],
  • "signature_list": [
    ],
  • "shareholder_list": [
    ],
  • "company_onbehalf": true,
  • "company_onbehalf_relation": "John Smith",
  • "group_additional_info": {
    },
  • "pep_check_info": {
    },
  • "no_of_employees": 25,
  • "accept_cash_check": true,
  • "annual_turnover": 0,
  • "source_of_funds": "Business",
  • "source_fund_uae": true,
  • "due_diligence_declaration": {
    },
  • "license_type": "Test License Updated",
  • "license_expiry": "2025-06-06",
  • "estimated_activity_through_nymcard": "ABCD",
  • "expected_number_of_cards": "1",
  • "expected_use_of_ncs_services": "ABCD",
  • "custom_info": {
    }
}

Update a specific user

Using this API you can update details of a specific user.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the user.

Request Body schema: application/json
required
title
string (UserTitle)
Enum: "MR" "MRS" "MISS"

The user's title/prefix.

first_name
string

User's first name. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

middle_name
string

User's middle name. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

last_name
string

User's last name. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

native_name
string

Native name of the user. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

native_last_name
string <= 60 characters

Native last name.

date_of_birth
string <date>

The date of birth of the user in the following format - yyyy-mm-dd. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

email
string <= 255 characters

A valid email address for the user.

mobile
string

Mobile number of the user (including area code), appended with "+" symbol and the first three digits to identify the country calling code. Please do not include hyphens, spaces or parentheses.

object (Address)

The details of the address. "ADDRESS" parameter stands for user's address. "COMPANY_ADDRESS" parameter stands for company's address. "LOCAL_ADDRESS" parameter stands for designated address shared in onboarding form for shareholders. It is mandatory to provide "LOCAL_ADDRESS" parameter if 'user_type' is SHAREHOLDER.

gender
string (UserGender)
Enum: "MALE" "FEMALE"

The gender of the user. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

education_level
string <= 50 characters

Education level.

preferred_language
string

A selected language for 3D Secure and digital wallet token notifications sent to this user. By default, notifications are sent in English. The supported value should be provided in ISO language format.

place_of_birth
string

The place of birth of the user. The format should be ISO alpha 3-character country code. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

place_of_birth_city
string <= 50 characters

The city of birth.

nationality
string

Nationality; must be one of ISO alpha 3-character country code. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

parent_user_id
string

Unique identifier of parent user. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

country_residence
string <= 3 characters

The country where the individual user resides or is currently citizen of. The format is ISO alpha 3-character country code. Note, that if KYC settings=true at the tenant level, this parameter can not be updated for user with ACTIVE status.

country_tax_residence
string <= 3 characters

The country for which the tax rules apply to the individual/business user and the user pays tax according to it. The format is ISO alpha 3-character country code.

employment_type
string (EmploymentType)
Enum: "SALARIED" "SELF_EMPLOYED" "RETIRED" "NOT_EMPLOYED" "BUSINESS_OWNER" "STUDENT" "HOMEMAKER" "OTHER"

The employment type of the individual user.

employment_title
string <= 50 characters

The job title (designation) for user_type = INDIVIDUAL. For user_type = BUSINESS this field can give the designation of the primary contact person of the business.

monthly_salary
number >= 0

The monthly salary of the user_type = INDIVIDUAL.

company_name
string <= 200 characters

The company name for which the individual works for in case of SALARIED OR company name that the individual runs in case of SELF-EMPLOYED OR BUSINESS_OWNER. This parameter is required if "employment_type" = 'SALARIED", "EMPLOYED" or "BUSINESS_OWNER".

object (Address)

The details of the address. "ADDRESS" parameter stands for user's address. "COMPANY_ADDRESS" parameter stands for company's address. "LOCAL_ADDRESS" parameter stands for designated address shared in onboarding form for shareholders. It is mandatory to provide "LOCAL_ADDRESS" parameter if 'user_type' is SHAREHOLDER.

company_country
string <= 3 characters

Company country in format of ISO alpha 3-character country code. For user_type = INDIVIDUAL this field indicates the country in which the company is registered and conducts its business and activities. For user_type = BUSINESS this field indicates the country in which the Business is registered and conducts its activities.

industry_type
string (IndustryType)
Enum: "I01" "I02" "I03" "I04" "I05" "I06" "I07" "I08" "I09" "I11" "I12" "I13" "I14" "I15" "I16" "I17" "I18" "I19" "I20" "I21" "I22" "I23" "I24" "I25" "I26" "I27" "I28" "I29" "I30" "I00"

Type of industry:

  • I01: Gambling/Casinos
  • I02: Defence/Military goods or Arms Dealers and Manufacturers
  • I03: Exchange Companies / Bureaus de Change, Money Changers, Hawala dealers / Other Finance Companies (For e.g. Derivatives Trading, Hedge Funds, Unregistered/Pvt Collective Investment Schemes)
  • I04: Real Estate Brokers / Real Estate Agencies / Real Estate Developers (Non * Govt)
  • I05: Charity Organizations, Religious/Social/Non * Profit Organizations, Cooperative/Social/Professional Societies & associations
  • I06: Auction Houses
  • I07: Dealers in Luxury Goods: (Definition of Luxury Goods include: Precious metals & Stones, Jewelry & Antiques, Art, Furs, Yachts , Executive/Private Jets)
  • I08: Trust Service Providers, Lawyers, Accountants, Tax Advisers, Auditors
  • I09: Private Banking Relationship
  • I11: Agriculture, Forestry, Fishing, and Hunting
  • I12: Mining, Quarrying, and Oil and Gas Extraction
  • I13: Utilities (water, gas, electricity)
  • I14: Telecommunications
  • I15: Construction
  • I16: Manufacturing
  • I17: Wholesale Trade
  • I18: Retail Trade and Commerce
  • I19: Transportation and Warehousing
  • I20: Technology
  • I21: Finance and Insurance
  • I22: Real Estate and Rental and Leasing
  • I23: Professional, Scientific, and Technical Services
  • I24: Management of Companies and Enterprises
  • I25: Educational Services
  • I26: Health Care and Social Assistance
  • I27: Arts, Entertainment, and Recreation
  • I28: Hotels and Food Services
  • I29: Public Administration
  • I30: Administrative and Support and Waste Management
  • I00: Other
expected_monthly_balance
number >= 0

For user_type = INDIVIDUAL this field indicates the expected monthly balance the individual user is planning to maintain in his accounts. For user_type = BUSINESS this field indicates the expected monthly balance the business is planning to maintain in its accounts.

relationship_with_parent
string (RelationshipWithParent)
Enum: "SON" "DAUGHTER" "NEPHEW" "NIECE" "HUSBAND" "WIFE" "FATHER" "MOTHER" "EMPLOYEE" "OTHER"

For a child user this field indicates the relationship of the child user with the parent user.

business_legal_name
string <= 200 characters

The business legal name. This field may be used for KYB verification. Applicable for 'user_type' = BUSINESS.

business_dba_name
string <= 50 characters

The business’s secondary name. This field may be used for KYB verification, if the business name is different from the legal business name. Applicable for 'user_type' = BUSINESS.

date_established
string <date-time>

The established date and time. Applicable for 'user_type' = BUSINESS.

phone_number
string^\+\d+

The telephone number.

website
string <= 50 characters

The website. Applicable for 'user_type' = BUSINESS.

designation
string <= 50 characters

It is mandatory to provide this parameter if 'user_type' is DIRECTOR or SIGNATURE. The valid designation should be provided, such as: CEO, CPO, CEO - (region name).

shares_percentage
number <float>

It is mandatory to provide this parameter if 'user_type' is SHAREHOLDER or SHAREHOLDER_BUSINESS.

share_controller_name
string <= 100 characters

It is mandatory to provide this parameter if 'user_type' is SHAREHOLDER or SHAREHOLDER_BUSINESS.

object (Address)

The details of the address. "ADDRESS" parameter stands for user's address. "COMPANY_ADDRESS" parameter stands for company's address. "LOCAL_ADDRESS" parameter stands for designated address shared in onboarding form for shareholders. It is mandatory to provide "LOCAL_ADDRESS" parameter if 'user_type' is SHAREHOLDER.

incorporation_type
string (UserIncorporationType)
Enum: "LTD" "LLC" "FZE" "FZCO" "FZ-LLC" "INC" "FOUNDATION" "TRUST" "FUND" "PUBLIC_TRADED" "GOVT_OWNED" "LLP" "OTHER"

This parameter indicates whether this business entity is Limited, LLC, Free-zone or anything else.

entity_registered_no
string <= 50 characters

This parameter describes the business/entity registered number.

old_entity_name
string <= 50 characters

This parameter describes the business’s old name.

old_entity_ops_start_date
string <date-time>

It is the start date when the business was operated under old name.

old_entity_ops_end_date
string <date-time>

It is the end date when the business was operated under old name.

regulated_entity
boolean

This parameter indicates if the entity is a regulated entity or no. Possible values are true/false.

regulator_name
string <= 50 characters

This parameter indicates the regulator’s name. It is applicable if 'regulated_entity' parameter is set as 'true'.

business_activities
string <= 1000 characters

This parameter describes the business/entity activities such as Payment Service Provider, IT service provider etc. It can be a comma separated values.

other_operated_countries
string

This parameter indicates the valid country's name(s), where the business is operated.

tax_residence_country
string <= 50 characters

This parameter indicates the name of a country, where the business has a tax residence.

tin
string <= 50 characters

Tax identification number.

external_auditor_name
string <= 50 characters

Name of the external auditor.

director_list
Array of strings

The list of directors. Up to 10 directors can be linked to a business user; but directors should be created prior creating the business user (if providing any ID in the list), else you can link the user later with the business.

signature_list
Array of strings

The list of signatures. Up to 10 signatures can be linked to a business user; but the signatures should be created prior creating the business user (if providing any ID in the list), else you can link the user later with the business.

shareholder_list
Array of strings

The list of shareholders. Up to 50 shareholders can be linked to a business user; but the shareholders should be created prior creating the business user (if providing any ID in the list), else you can link the user later with the business.

company_onbehalf
boolean

This parameter indicates if the company is opened on behalf of another person. Possible values are true/false.

company_onbehalf_relation
string <= 50 characters

In this parameter you should confirm the relationship of the beneficial owner. It is applicable if 'company_onbehalf' parameter is set as 'true'.

object (UserGroupAdditionalInfo)

The additional information, which describes whether entity is a part of a group etc.

object (UserPepCheckInfo)

The information about checking politically exposed persons (“PEPs”) among main shareholders, directors of the entity.

no_of_employees
integer <int32> (UserNoOfEmployees)

This parameter describes the number of employees for the business entity.

accept_cash_check
boolean

This parameter indicates whether the corporate company accepts cash from end users or not. Possible values are true/false.

annual_turnover
number

This parameter describes the annual turnover of the business entity.

source_of_funds
string <= 50 characters

This parameter describes how is the company being funded.

source_fund_uae
boolean

This parameter indicates whether the business source of funds is derived from outside of the UAE or no. Possible values are true/false.

object (UserDueDiligenceDeclaration)

The information about due diligence declaration.

license_type
string <= 100 characters

The license type. This parameter is applicable for 'user_type' = SHAREHOLDER_BUSINESS.

license_expiry
string <date>

The license expiry. This parameter is applicable for 'user_type' = SHAREHOLDER_BUSINESS.

estimated_activity_through_nymcard
string

This parameter is optional and applicable for 'user_type' = BUSINESS.

expected_number_of_cards
integer <int32> >= 0

This parameter is optional and applicable for 'user_type' = BUSINESS.

expected_use_of_ncs_services
string

This parameter is optional and applicable for 'user_type' = BUSINESS.

object

This parameter holds additional fields configured in tenant settings. This parameter is optional.

Responses

Request samples

Content type
application/json
{
  • "title": "MR",
  • "first_name": "John",
  • "middle_name": "Anthony",
  • "last_name": "Smith",
  • "native_name": "John Smith",
  • "native_last_name": "Júañ Hérreró",
  • "date_of_birth": "2012-05-04",
  • "email": "bob@example.com",
  • "mobile": "+551185249635",
  • "address": {
    },
  • "gender": "MALE",
  • "education_level": "Graduate",
  • "preferred_language": "EN",
  • "place_of_birth": "USA",
  • "place_of_birth_city": "Toronto",
  • "nationality": "USA",
  • "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "country_residence": "USA",
  • "country_tax_residence": "USA",
  • "employment_type": "SALARIED",
  • "employment_title": "QAE",
  • "monthly_salary": "12000",
  • "company_name": "Example",
  • "company_address": {
    },
  • "company_country": "USA",
  • "industry_type": "I01",
  • "expected_monthly_balance": "100000",
  • "relationship_with_parent": "SON",
  • "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",
  • "designation": "CEO",
  • "shares_percentage": 100,
  • "share_controller_name": "Nabil Benaissa",
  • "local_address": {
    },
  • "incorporation_type": "LTD",
  • "entity_registered_no": "2233445533",
  • "old_entity_name": "Old name",
  • "old_entity_ops_start_date": "2012-05-04",
  • "old_entity_ops_end_date": "2014-05-04",
  • "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": [
    ],
  • "signature_list": [
    ],
  • "shareholder_list": [
    ],
  • "company_onbehalf": true,
  • "company_onbehalf_relation": "John Smith",
  • "group_additional_info": {
    },
  • "pep_check_info": {
    },
  • "no_of_employees": 25,
  • "accept_cash_check": true,
  • "annual_turnover": 0,
  • "source_of_funds": "Business",
  • "source_fund_uae": true,
  • "due_diligence_declaration": {
    },
  • "license_type": "Test License Updated",
  • "license_expiry": "2025-06-06",
  • "estimated_activity_through_nymcard": "ABCD",
  • "expected_number_of_cards": "1",
  • "expected_use_of_ncs_services": "ABCD",
  • "custom_info": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "title": "MR",
  • "first_name": "John",
  • "middle_name": "Anthony",
  • "last_name": "Smith",
  • "native_name": "John Smith",
  • "native_last_name": "Júañ Hérreró",
  • "full_legal_name": "John Smith",
  • "full_name_local_language": "Volodymyr",
  • "father_name": "John Smith",
  • "mother_name": "Mary Ann",
  • "grandfather_name": "Andrew",
  • "family_name": "Smith",
  • "marital_status": "Divorced",
  • "employment_status": "Worker",
  • "business_type": "LCC",
  • "legal_form": "Company",
  • "date_of_birth": "2012-05-04",
  • "email": "bob@example.com",
  • "mobile": "+551185249635",
  • "address": {
    },
  • "gender": "MALE",
  • "education_level": "Graduate",
  • "preferred_language": "EN",
  • "place_of_birth": "USA",
  • "place_of_birth_city": "Toronto",
  • "nationality": "USA",
  • "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "created": "2012-05-04T19:42:32.987Z",
  • "created_by": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "modified_by": "API",
  • "country_residence": "USA",
  • "country_tax_residence": "USA",
  • "employment_type": "SALARIED",
  • "employment_title": "QAE",
  • "monthly_salary": "12000",
  • "company_name": "Example",
  • "company_address": {
    },
  • "company_country": "USA",
  • "industry_type": "I01",
  • "expected_monthly_balance": "100000",
  • "relationship_with_parent": "SON",
  • "user_type": "INDIVIDUAL",
  • "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",
  • "status": "PENDINGKYC",
  • "status_reason_code": "I0",
  • "kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY",
  • "designation": "CEO",
  • "shares_percentage": 100,
  • "share_controller_name": "Nabil Benaissa",
  • "local_address": {
    },
  • "incorporation_type": "LTD",
  • "entity_registered_no": "2233445533",
  • "old_entity_name": "Old name",
  • "old_entity_ops_start_date": "2012-05-04",
  • "old_entity_ops_end_date": "2014-05-04",
  • "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": [
    ],
  • "signature_list": [
    ],
  • "shareholder_list": [
    ],
  • "company_onbehalf": true,
  • "company_onbehalf_relation": "John Smith",
  • "group_additional_info": {
    },
  • "pep_check_info": {
    },
  • "no_of_employees": 25,
  • "accept_cash_check": true,
  • "annual_turnover": 0,
  • "source_of_funds": "Business",
  • "source_fund_uae": true,
  • "due_diligence_declaration": {
    },
  • "license_type": "Test License Updated",
  • "license_expiry": "2025-06-06",
  • "estimated_activity_through_nymcard": "ABCD",
  • "expected_number_of_cards": "1",
  • "expected_use_of_ncs_services": "ABCD",
  • "custom_info": {
    }
}

Change user status

This API is used to change user status.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the user.

Request Body schema: application/json
required
status
required
string (UserStatus)
Enum: "PENDINGKYC" "PENDINGKYB" "ACTIVE" "SUSPENDED" "TERMINATED" "PENDINGIDVERIFICATION"

The status of the user.

status_reason_code
required
string (UserStatusReasonCode)
Enum: "I0" "A0" "A1" "A2" "A3" "A4" "A5" "A6" "A7" "A8" "A10" "A1R" "B0" "B1" "B2" "B3" "B4" "B5" "B6" "B7" "B9" "B10" "B1E" "B2E" "B0E" "B9E" "B10E" "B19" "S0" "S1" "S2" "S3" "S4" "S5" "S6" "S7" "S8" "S9" "T0" "T1" "T2" "T3" "T4" "T5" "T6" "T7" "T8" "T9" "S10" "T10" "T11" "T12" "T13" "T12E" "T13E" "O1"

Status Change Reason Code:

  • I0: Initial status.
  • A0: First time activation: when activated from PENDINGKYC to ACTIVE status.
  • A1: Resumed from Suspended status: when user is moved back to ACTIVE status.
  • A2: Admin Activated the user from status suspended.
  • A3: Admin activated the user by manual intervention from the dashboard.
  • A4: Admin Activated the business user from status suspended.
  • A5: Admin Activated.
  • A6: Document expired or about to expire.
  • A7: ID renewed.
  • A8: ID re-verification failed after document expiration.
  • A10: Active, not verified by Host.
  • A1R: Active – Passport Rejected.
  • B0: Documents are uploaded successfully for identity verification.
  • B1: Identity is not verified, manual intervention required.
  • B2: SDK token is no longer valid, please generate a new SDK token.
  • B3: Admin approved, proceed to KYC verification flow.
  • B4: Name mismatched.
  • B5: Identity verification consider with caution status and name mismatched.
  • B6: Identity verification consider.
  • B7: Date of birth consider.
  • B9: Document issuing country mismatch.
  • B10: Identity verification consider with caution status and document issuing country mismatch.
  • B1E: Identity is not verified, manual intervention required in Re-Uploading Case.
  • B2E: Generate SDK token, document expired (same as B2).
  • B0E: Documents re-uploaded after document expiration for identity verification (same as B0).
  • B9E: Document issuing country mismatch upon IDV re-verification after document expiration.
  • B10E: Identity verification consider with caution status and document issuing country mismatch upon IDV re-verification after document expiration.
  • B19: Identity verification consider, contact Admin.
  • S0: Temporary suspension: initiated by the user or system user or the system.
  • S1: Inactivity over time.
  • S2: Suspended by Admin.
  • S3: Suspended by Admin.
  • S4: Suspended by Admin.
  • S5: Suspended by Admin.
  • S6: Suspended by Admin.
  • S7: IDV not renewed and document expiration grace period reached.
  • S8: Allowed number of users per National ID/Passport limit is exceeded.
  • S9: Suspended by Host via manual external creation.
  • S10: Suspended by Host via automatic external creation.
  • T0: Closed by user.
  • T1: Closed by issuer.
  • T2: Failed KYC.
  • T3: Terminated by Admin.
  • T4: Terminated by Admin.
  • T5: Admin terminated due to ID verification failed.
  • T6: Admin terminated due to KYC failed.
  • T7: Admin terminated due to limited time exceeded and action taken for ID verification fail.
  • T8: Terminated by Admin.
  • T9: Admin terminated due to ID verification failed.
  • T10: Admin terminated due to limited time exceeded and action taken for KYB fail.
  • T11: Admin terminated due to certain reason.
  • T12: System terminated due to ID verification rejected.
  • T13: System terminated due to ID verification suspected.
  • 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).
  • O1: Other reason.
note
string

This field is to capture additional information while changing the user status.

modified_by
string
Default: "API"

This field indicates the user who executed the operation.

Responses

Request samples

Content type
application/json
{
  • "status": "PENDINGKYC",
  • "status_reason_code": "I0",
  • "note": "Some note regarding the reason of user status change.",
  • "modified_by": "API"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "title": "MR",
  • "first_name": "John",
  • "middle_name": "Anthony",
  • "last_name": "Smith",
  • "native_name": "John Smith",
  • "native_last_name": "Júañ Hérreró",
  • "full_legal_name": "John Smith",
  • "full_name_local_language": "Volodymyr",
  • "father_name": "John Smith",
  • "mother_name": "Mary Ann",
  • "grandfather_name": "Andrew",
  • "family_name": "Smith",
  • "marital_status": "Divorced",
  • "employment_status": "Worker",
  • "business_type": "LCC",
  • "legal_form": "Company",
  • "date_of_birth": "2012-05-04",
  • "email": "bob@example.com",
  • "mobile": "+551185249635",
  • "address": {
    },
  • "gender": "MALE",
  • "education_level": "Graduate",
  • "preferred_language": "EN",
  • "place_of_birth": "USA",
  • "place_of_birth_city": "Toronto",
  • "nationality": "USA",
  • "parent_user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "created": "2012-05-04T19:42:32.987Z",
  • "created_by": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "modified_by": "API",
  • "country_residence": "USA",
  • "country_tax_residence": "USA",
  • "employment_type": "SALARIED",
  • "employment_title": "QAE",
  • "monthly_salary": "12000",
  • "company_name": "Example",
  • "company_address": {
    },
  • "company_country": "USA",
  • "industry_type": "I01",
  • "expected_monthly_balance": "100000",
  • "relationship_with_parent": "SON",
  • "user_type": "INDIVIDUAL",
  • "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",
  • "status": "PENDINGKYC",
  • "status_reason_code": "I0",
  • "kyc_policy_passed": "UAE_INDIVIDUAL_PRIMARY",
  • "designation": "CEO",
  • "shares_percentage": 100,
  • "share_controller_name": "Nabil Benaissa",
  • "local_address": {
    },
  • "incorporation_type": "LTD",
  • "entity_registered_no": "2233445533",
  • "old_entity_name": "Old name",
  • "old_entity_ops_start_date": "2012-05-04",
  • "old_entity_ops_end_date": "2014-05-04",
  • "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": [
    ],
  • "signature_list": [
    ],
  • "shareholder_list": [
    ],
  • "company_onbehalf": true,
  • "company_onbehalf_relation": "John Smith",
  • "group_additional_info": {
    },
  • "pep_check_info": {
    },
  • "no_of_employees": 25,
  • "accept_cash_check": true,
  • "annual_turnover": 0,
  • "source_of_funds": "Business",
  • "source_fund_uae": true,
  • "due_diligence_declaration": {
    },
  • "license_type": "Test License Updated",
  • "license_expiry": "2025-06-06",
  • "estimated_activity_through_nymcard": "ABCD",
  • "expected_number_of_cards": "1",
  • "expected_use_of_ncs_services": "ABCD",
  • "custom_info": {
    }
}

Get user linked relationships

This API is used to retrieve relationships linked to a specific user.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the user.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "parent_user": "ABC",
  • "child_users": "signature1"
}

Search for users

This API is used to search for users by name, mobile number, and email.

Authorizations:
apikey
Request Body schema: application/json
required
name
string

Filter by first, middle and last names of the user. Search works for complete or partial string.

mobile
string

Filter by mobile number of the user. Search works for complete or partial string.

email
string

Filter by user's email. Search works for complete or partial string.

status
Array of strings
Items Enum: "ACTIVE" "PENDINGKYC" "PENDINGKYB" "PENDINGIDVERIFICATION" "SUSPENDED" "TERMINATED"

Filter by user's status.

user_type
string (UserType)
Enum: "INDIVIDUAL" "BUSINESS" "DIRECTOR" "SIGNATURE" "SHAREHOLDER" "SHAREHOLDER_BUSINESS"

The type of the user. You can find all necessary fields per each user type in this GSG doc - https://docs.nymcard.com/get-started/program-management/necessary-parameters-per-user-type.

business_legal_name
string

Filter by business legal name, search for complete or partial string.

business_dba_name
string

Filter by business DBA name, search for complete or partial string.

website
string

Filter by website, search for complete or partial string.

created_from
string <date-time>

Search users created on this date and onwards.

created_to
string <date-time>

Search users created prior to this date.

modified_from
string <date-time>

Search users modified on this date and onwards.

modified_to
string <date-time>

Search users modified prior to this date.

limit
integer

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

The way results should be sorted.

order_by
string (SortDirection)
Enum: "asc" "desc"

The way results should be ordered (ascending or descending).

Responses

Request samples

Content type
application/json
{
  • "name": "John",
  • "mobile": "+559999999995",
  • "email": "johndoe@example.com",
  • "status": [
    ],
  • "user_type": "INDIVIDUAL",
  • "business_legal_name": "Insurance corporation",
  • "business_dba_name": "John Smith insurance corporation",
  • "website": "example.com",
  • "created_from": "2012-05-04T19:42:32.987Z",
  • "created_to": "2012-05-04T19:42:32.987Z",
  • "modified_from": "2012-05-04T19:42:32.987Z",
  • "modified_to": "2012-05-04T19:42:32.987Z",
  • "limit": "10",
  • "after": "MTA=",
  • "sort_by": "created",
  • "order_by": "asc"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "Durable version of current results",
  • "has_more": true,
  • "data": [
    ]
}

Link user external bank details

This API is used to link user external bank account details so that these details can be used to execute the external transfers.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: a34b6c8e-28e5-4370-8234-aeca2b58c48d

Unique identifier of the user.

Request Body schema: application/json
required
iban
required
string <= 34 characters

IBAN.

swift_code
required
string <= 11 characters

SWIFT code.

bank_name
required
string <= 50 characters

Bank name.

routing_number
string <= 10 characters

Routing number (unique, nine-digit number that functions as an address for the bank).

status
string

User bank account details status.

Responses

Request samples

Content type
application/json
{
  • "iban": "AE460090000000123456789",
  • "swift_code": "CBAUAEAAXXX",
  • "bank_name": "CENTRAL BANK OF THE U.A.E",
  • "routing_number": "800110101",
  • "status": "ACTIVE"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "a34b6c8e-28e5-4370-8234-aeca2b58c48d",
  • "bank_details_id": "c5cebaf4-9b16-4e50-bae6-dca00210283c",
  • "iban": "AE460090000000123456789",
  • "swift_code": "CBAUAEAAXXX",
  • "bank_name": "CENTRAL BANK OF THE U.A.E",
  • "routing_number": "800110101"
}

Get user specific external bank details

This API is used to retrieve user external bank details by its ID.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: a34b6c8e-28e5-4370-8234-aeca2b58c48d

Unique identifier of the user.

bank_details_id
required
string
Example: c5cebaf4-9b16-4e50-bae6-dca00210283c

Unique identifier of the bank details.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "a34b6c8e-28e5-4370-8234-aeca2b58c48d",
  • "bank_details_id": "c5cebaf4-9b16-4e50-bae6-dca00210283c",
  • "iban": "AE460090000000123456789",
  • "swift_code": "CBAUAEAAXXX",
  • "bank_name": "CENTRAL BANK OF THE U.A.E",
  • "routing_number": "800110101"
}

Update user external bank details

This API is used to update user external bank details.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: a34b6c8e-28e5-4370-8234-aeca2b58c48d

Unique identifier of the user.

bank_details_id
required
string
Example: c5cebaf4-9b16-4e50-bae6-dca00210283c

Unique identifier of the bank details.

Request Body schema: application/json
required
iban
string <= 34 characters

IBAN.

swift_code
string <= 11 characters

SWIFT code.

bank_name
string <= 50 characters

Bank name.

routing_number
string <= 10 characters

Routing number (unique, nine-digit number that functions as an address for the bank).

status
string

User bank account details status.

Responses

Request samples

Content type
application/json
{
  • "iban": "AE460090000000123456789",
  • "swift_code": "CBAUAEAAXXX",
  • "bank_name": "CENTRAL BANK OF THE U.A.E",
  • "routing_number": "800110101",
  • "status": "TERMINATED"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "a34b6c8e-28e5-4370-8234-aeca2b58c48d",
  • "bank_details_id": "c5cebaf4-9b16-4e50-bae6-dca00210283c",
  • "iban": "AE460090000000123456789",
  • "swift_code": "CBAUAEAAXXX",
  • "bank_name": "CENTRAL BANK OF THE U.A.E",
  • "routing_number": "800110101"
}

Unlink user external bank details

This API is used to to unlink user external bank account details so that irrelevant information can be removed from user.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: a34b6c8e-28e5-4370-8234-aeca2b58c48d

Unique identifier of the user.

bank_details_id
required
string
Example: c5cebaf4-9b16-4e50-bae6-dca00210283c

Unique identifier of the bank details.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "a34b6c8e-28e5-4370-8234-aeca2b58c48d",
  • "bank_details_id": "c5cebaf4-9b16-4e50-bae6-dca00210283c",
  • "iban": "AE460090000000123456789",
  • "swift_code": "CBAUAEAAXXX",
  • "bank_name": "CENTRAL BANK OF THE U.A.E",
  • "routing_number": "800110101"
}

Re-link cards and accounts to individual users from business user

This API is used to re-link cards and accounts to individual users from business user.

Authorizations:
apikey
path Parameters
user_id
required
string

The unique identifier of the user.

Request Body schema: application/json
required
card_id
string

The unique identifier of card.

account_id
required
string

The unique identifier of the account.

Responses

Request samples

Content type
application/json
{
  • "card_id": "4cc48c09-b5c4-46cf-9e8b-55df2cbf7940",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "card_id": "4cc48c09-b5c4-46cf-9e8b-55df2cbf7940",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95"
}

User documents

Our nCore platform gives an opportunity to upload and manage user identification documents.

Create identification

This API is used to create user identification.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

Request Body schema: application/json
required
type
required
string (IdentificationType)
Enum: "PASSPORT" "VISA" "NATIONAL_ID" "TRADE_LICENSE" "COMMERCIAL_LICENSE" "INCORPORATION_CERT" "INCUMBENCY_CERT" "MEMORANDUM_ARTICLES" "BANK_STATEMENT" "ADDITIONAL"

The identification type of file to be uploaded.

title
string <= 40 characters

The document title.

number
required
string

The document number.

issuance_authority
string

The name of issuance authority.

place_of_issuance
string

The place of issuance.

expiration_date
string

The expiration date of the document.

issuance_date
string

The issuance date of the document.

identification_note
string <= 100 characters

A note, which contains details about the identification type.

Responses

Request samples

Content type
application/json
{
  • "type": "PASSPORT",
  • "title": "SELFIE",
  • "number": "132123123",
  • "issuance_authority": "Ministry of defense",
  • "place_of_issuance": "Lebanon",
  • "expiration_date": "2022-05-04",
  • "issuance_date": "2012-05-04",
  • "identification_note": "Some note"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "3e9392df-4093-4389-a0ad-92456a181b8a",
  • "type": "PASSPORT",
  • "title": "SELFIE",
  • "user_id": "132123123",
  • "number": "132123123",
  • "issuance_authority": "Ministry of defense",
  • "place_of_issuance": "Lebanon",
  • "issuance_date": "2012-05-04T19:42:32.987Z",
  • "expiration_date": "2012-05-04T19:42:32.987Z",
  • "document_status": "PENDINGKYB",
  • "document_status_reason": "I0",
  • "files": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "identification_note": "Some note"
}

Get user identification

This API is used to get user identification information.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get specific identification

This API is used to get identification info.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

identification_id
required
string
Example: 76dcc374-3763-4472-881c-c29bc2398e97

Identification ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "3e9392df-4093-4389-a0ad-92456a181b8a",
  • "type": "PASSPORT",
  • "title": "SELFIE",
  • "user_id": "132123123",
  • "number": "132123123",
  • "issuance_authority": "Ministry of defense",
  • "place_of_issuance": "Lebanon",
  • "issuance_date": "2012-05-04T19:42:32.987Z",
  • "expiration_date": "2012-05-04T19:42:32.987Z",
  • "document_status": "PENDINGKYB",
  • "document_status_reason": "I0",
  • "files": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "identification_note": "Some note"
}

Update user identification

This API is used to update user identification.

Authorizations:
apikey
path Parameters
user_id
required
string

Unique identifier of the user.

identification_id
required
string

Identification ID.

Request Body schema: application/json
required

User identification data

title
string <= 40 characters

The document title.

number
string

The document number.

issuance_authority
string

The name of issuance authority.

place_of_issuance
string

The place of issuance.

expiration_date
string

The expiration date of the document.

issuance_date
string

The issuance date of the document.

identification_note
string <= 100 characters

A note, which contains details about the identification type.

Responses

Request samples

Content type
application/json
{
  • "title": "SELFIE",
  • "number": "132123123",
  • "issuance_authority": "Ministry of defense",
  • "place_of_issuance": "Lebanon",
  • "expiration_date": "2012-05-04",
  • "issuance_date": "2012-05-04",
  • "identification_note": "Some note"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "3e9392df-4093-4389-a0ad-92456a181b8a",
  • "type": "PASSPORT",
  • "title": "SELFIE",
  • "user_id": "132123123",
  • "number": "132123123",
  • "issuance_authority": "Ministry of defense",
  • "place_of_issuance": "Lebanon",
  • "issuance_date": "2012-05-04T19:42:32.987Z",
  • "expiration_date": "2012-05-04T19:42:32.987Z",
  • "document_status": "PENDINGKYB",
  • "document_status_reason": "I0",
  • "files": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "identification_note": "Some note"
}

Search for user identifications

This API is used to search for user identifications.

Authorizations:
apikey
Request Body schema: application/json
required
query
string

A search query.

sort_by
string

The way results should be sorted.

order_by
string (SortDirection)
Enum: "asc" "desc"

The way results should be ordered (ascending or descending).

matcher
string (SearchMatcher)
Enum: "and" "or"

Search matcher.

Array of objects (SearchFilter)

An array of search filters.

object (Cursors)

Cursors

limit
integer <int32>

Search limit.

Responses

Request samples

Content type
application/json
{
  • "query": "Transfer",
  • "sort_by": "By name",
  • "order_by": "asc",
  • "matcher": "and",
  • "filters": [
    ],
  • "cursors": {
    },
  • "limit": 0
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Upload single image of identification

This API is used to upload a single identification file. Max file size - 128Mb. Allowed extensions - pdf, jpg, jpeg, png, bmp, doc, docx.. One user identification can consist of maximum 10 files. For this API to work well, you need to send key-value pair and specify the content type. Key is "file". Content type is "file".

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

identification_id
required
string
Example: 76dcc374-3763-4472-881c-c29bc2398e97

Identification ID.

Request Body schema: application/x-www-form-urlencoded
required
file
required
string <binary>

The file to be uploaded.

file_identification_type
required
string

The identification type of file to be uploaded. Possible values [PASSPORT, VISA, NATIONAL_ID,TRADE_LICENSE, COMMERCIAL_LICENSE, INCORPORATION_CERT, INCUMBENCY_CERT, MEMORANDUM_ARTICLES, BANK_STATEMENT, ADDITIONAL]

file_identification_document_type
string

The identification document type of file to be uploaded. Possible values [NATIONAL_ID_FRONT, NATIONAL_ID_BACK, PASSPORT_PAGE1, PASSPORT_PAGE2, VISA, ADDITIONAL_PAGE_1, ADDITIONAL_PAGE_2]

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "9e354f40-2ea5-43a9-92ec-2f967c3981f9.png",
  • "file_name": "9e354f40-2ea5-43a9-92ec-2f967c3981f9.png",
  • "content_type": "application/pdf",
  • "size": 4562,
  • "identification_type": "PASSPORT",
  • "identification_document_type": "NATIONAL_ID_FRONT",
  • "version": 1,
  • "created": "2012-05-04T19:42:32.987Z",
  • "title": "SELFIE"
}

Upload user identification

This API is used to upload identification files. Max file size - 128Mb. Allowed extensions - pdf, jpg, jpeg, png, bmp, doc, docx.. One user identification can consist of maximum 10 files (5 files per upload). For this API to work well, you need to send key-value pair(s) and specify the content type. Keys are file1, file2, file3, file4, file5, file6, file7, file8, file9 and file10. Value is the actual file to upload. Content type is "file".

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

identification_id
required
string
Example: 76dcc374-3763-4472-881c-c29bc2398e97

Identification ID.

Request Body schema: multipart/form-data
required
file1
required
string <binary>

The file to be uploaded.

file1_identification_type
required
string

The identification type of file to be uploaded. Possible values [PASSPORT, VISA, NATIONAL_ID,TRADE_LICENSE, COMMERCIAL_LICENSE, INCORPORATION_CERT, INCUMBENCY_CERT, MEMORANDUM_ARTICLES, BANK_STATEMENT, ADDITIONAL]

file1_identification_document_type
string

The identification document type of file to be uploaded. Possible values [NATIONAL_ID_FRONT, NATIONAL_ID_BACK, PASSPORT_PAGE1, PASSPORT_PAGE2, VISA, ADDITIONAL_PAGE_1, ADDITIONAL_PAGE_2]

file2
string <binary>

The file to be uploaded.

file2_identification_type
string

The identification type of file to be uploaded. Possible values [PASSPORT, VISA, NATIONAL_ID,TRADE_LICENSE, COMMERCIAL_LICENSE, INCORPORATION_CERT, INCUMBENCY_CERT, MEMORANDUM_ARTICLES, BANK_STATEMENT, ADDITIONAL]

file2_identification_document_type
string

The identification document type of file to be uploaded. Possible values [NATIONAL_ID_FRONT, NATIONAL_ID_BACK, PASSPORT_PAGE1, PASSPORT_PAGE2, VISA, ADDITIONAL_PAGE_1, ADDITIONAL_PAGE_2]

file3
string <binary>

The file to be uploaded.

file3_identification_type
string

The identification type of file to be uploaded. Possible values [PASSPORT, VISA, NATIONAL_ID,TRADE_LICENSE, COMMERCIAL_LICENSE, INCORPORATION_CERT, INCUMBENCY_CERT, MEMORANDUM_ARTICLES, BANK_STATEMENT, ADDITIONAL]

file3_identification_document_type
string

The identification document type of file to be uploaded. Possible values [NATIONAL_ID_FRONT, NATIONAL_ID_BACK, PASSPORT_PAGE1, PASSPORT_PAGE2, VISA, ADDITIONAL_PAGE_1, ADDITIONAL_PAGE_2]

file4
string <binary>

The file to be uploaded.

file4_identification_type
string

The identification type of file to be uploaded. Possible values [PASSPORT, VISA, NATIONAL_ID,TRADE_LICENSE, COMMERCIAL_LICENSE, INCORPORATION_CERT, INCUMBENCY_CERT, MEMORANDUM_ARTICLES, BANK_STATEMENT, ADDITIONAL]

file4_identification_document_type
string

The identification document type of file to be uploaded. Possible values [NATIONAL_ID_FRONT, NATIONAL_ID_BACK, PASSPORT_PAGE1, PASSPORT_PAGE2, VISA, ADDITIONAL_PAGE_1, ADDITIONAL_PAGE_2]

file5
string <binary>

The file to be uploaded.

file5_identification_type
string

The identification type of file to be uploaded. Possible values [PASSPORT, VISA, NATIONAL_ID,TRADE_LICENSE, COMMERCIAL_LICENSE, INCORPORATION_CERT, INCUMBENCY_CERT, MEMORANDUM_ARTICLES, BANK_STATEMENT, ADDITIONAL]

file5_identification_document_type
string

The identification document type of file to be uploaded. Possible values [NATIONAL_ID_FRONT, NATIONAL_ID_BACK, PASSPORT_PAGE1, PASSPORT_PAGE2, VISA, ADDITIONAL_PAGE_1, ADDITIONAL_PAGE_2]

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "3e9392df-4093-4389-a0ad-92456a181b8a",
  • "type": "PASSPORT",
  • "title": "SELFIE",
  • "user_id": "132123123",
  • "number": "132123123",
  • "issuance_authority": "Ministry of defense",
  • "place_of_issuance": "Lebanon",
  • "issuance_date": "2012-05-04T19:42:32.987Z",
  • "expiration_date": "2012-05-04T19:42:32.987Z",
  • "document_status": "PENDINGKYB",
  • "document_status_reason": "I0",
  • "files": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "identification_note": "Some note"
}

Return file metadata

This API is used to get file metadata.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

identification_id
required
string
Example: 76dcc374-3763-4472-881c-c29bc2398e97

Identification ID.

file_id
required
string
Example: 624969e5-1ca2-4a11-b1c2-533eab96fd97

Unique identifier of the file.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "FileUploadContent",
  • "user_id": "user120",
  • "metadata": {
    },
  • "content": "2rl0Dvc1gTrOTTqzgNaK62wj9tT91kEZRjUGF2kWWeBN4BGy7xYdAR7Mc6duajDBLQ_y8pBKeXaxRPUXIcK5K734Z7rmtAYIzMam2RClvKcU"
}

Delete file

This API is used to delete an identification file.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

identification_id
required
string
Example: 76dcc374-3763-4472-881c-c29bc2398e97

Identification ID.

file_id
required
string
Example: 624969e5-1ca2-4a11-b1c2-533eab96fd97

Unique identifier of the file.

Responses

Return file

This API is used to browse file.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

identification_id
required
string
Example: 76dcc374-3763-4472-881c-c29bc2398e97

Identification ID.

file_id
required
string
Example: 624969e5-1ca2-4a11-b1c2-533eab96fd97

Unique identifier of the file.

Responses

Download file

This API is used to download file.

Authorizations:
apikey
path Parameters
user_id
required
string
Example: 4ba3028b-0e38-4113-a90e-5a8cd3fb27a6

Unique identifier of the user.

identification_id
required
string
Example: 76dcc374-3763-4472-881c-c29bc2398e97

Identification ID.

file_id
required
string
Example: 624969e5-1ca2-4a11-b1c2-533eab96fd97

Unique identifier of the file.

Responses

User KYC

Know Your Customer (KYC) is the mandatory process of identifying and verifying the client's identity when opening an account and periodically over time. KYC process helps to establish customer identity and understand the nature of customers’ activities in order to qualify that the source of funds is legitimate. nCore platform offers two KYC policies - individual primary (for a parent user) and individual secondary (for a child user).

Perform KYC of user

This API is used to perform KYC (know your customer) process of a user.

Authorizations:
apikey
path Parameters
id
required
string

Unique identifier of the user. If this information is not present in the request, the system generates one automatically.

Request Body schema: application/json
required
id
string

Unique identifier of the KYC request.

note
string <= 500 characters

KYC note.

kyc_policy
required
string (SupportedKycPolicies) <= 40 characters
Enum: "UAE_INDIVIDUAL_PRIMARY" "UAE_INDIVIDUAL_SECONDARY"

Supported KYC policies.

Responses

Request samples

Content type
application/json
{
  • "id": "6daf85ea-f5f6-4e0b-b381-de5b7a9834e2",
  • "note": "Some note",
  • "kyc_policy": "UAE_INDIVIDUAL_PRIMARY"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "user_id": "055ef899-9650-4700-9497-e71826dd2825",
  • "kyc_policy": "UAE_INDIVIDUAL_PRIMARY",
  • "note": "Some note",
  • "status": "SUBMITTED",
  • "status_reason_code": "S0",
  • "status_reason": "KYC status reason",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get KYC by ID

This API is used to get a specific KYC request by its ID.

Authorizations:
apikey
path Parameters
id
required
string

Unique identifier of the KYC request.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "user_id": "055ef899-9650-4700-9497-e71826dd2825",
  • "kyc_policy": "UAE_INDIVIDUAL_PRIMARY",
  • "note": "Some note",
  • "status": "SUBMITTED",
  • "status_reason_code": "S0",
  • "status_reason": "KYC status reason",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Search for KYC requests

This API is used to search for KYC requests by different criteria.

Authorizations:
apikey
Request Body schema: application/json
required
query
string

A search query.

sort_by
string

The way results should be sorted.

order_by
string (SortDirection)
Enum: "asc" "desc"

The way results should be ordered (ascending or descending).

matcher
string (SearchMatcher)
Enum: "and" "or"

Search matcher.

Array of objects (SearchFilter)

An array of search filters.

object (Cursors)

Cursors

limit
integer <int32>

Search limit.

Responses

Request samples

Content type
application/json
{
  • "query": "Transfer",
  • "sort_by": "By name",
  • "order_by": "asc",
  • "matcher": "and",
  • "filters": [
    ],
  • "cursors": {
    },
  • "limit": 0
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

User IDV

Identity verification (IDV) is the mandatory process of identifying and verifying the client's identity when opening an account and periodically over time. IDV policies help to establish customer identity and understand the nature of customers’ activities in order to qualify that the source of funds is legitimate. nCore platform offers two IDV policies - individual primary (for users without parent user ID or with parent user ID other than individual) and individual secondary (for users with parent user ID of an individual user).

Get all IDV policies

This API is used to get the list of all IDV policies.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get IDV policy by ID

This API is used to get specific IDV policy by its ID.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of IDV policy.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfcf8394e519dc13dc25c5eddd6",
  • "idv_policy_name": "IDV_POLICY_INDIVIDUAL_PRIMARY",
  • "checks": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get user's IDV report details

This API is used to get user’s identification report details. In case the user has more than one report, then all reports will be retrieved.

Authorizations:
apikey
path Parameters
user_id
required
string

The unique identifier of the user.

query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get user verification by reportID

This API is used to get user’s identification report by report_id.

Authorizations:
apikey
path Parameters
user_id
required
string

The unique identifier of the user.

id
required
string

The unique identifier of the report.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "validation_result": {
    },
  • "name": "string",
  • "check_id": "string",
  • "created_at": "2012-05-04T19:42:32.987Z",
  • "result": "string",
  • "status": "string",
  • "sub_result": "string"
}

Accounts

Our nCore platform gives a possibility to create and manage an account. It is typically a general ledger account that keeps track of the account transactions and its balances. Whenever a new prepaid card is issued a GL account is created and linked to the card. Also the platform supports three types of account statuses - Active, Suspended, Terminated. The card account when created is in Active status. While in Active status the account is used for loading/unloading of funds and to process card authorizations and clearings. The account status can be changed from Active to Suspended status. When in Suspended status the account does not allow loading/unloading of funds and to process card authorizations. However, clearings coming from the scheme are processed. The account status can be changed to Terminated status. This is a permanent status; the account status is changed to Terminated status only when card account closure operation is explicitly performed. You can update account status to Terminated if account has no balance or account has no pending authorizations.

Create account

This API is used to create a new account.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the account. If this information is not present in the request,the system generates one automatically.

user_id
required
string

The unique identifier of the user.

card_product_id
required
string

The unique identifier of the card product. This token ID is referred to as an existing card product.

type
required
string (AccountType)
Enum: "PREPAID" "COLLATERAL" "CREDIT" "SECURITY" "MASTER"

The type of account.

currencies
Array of strings

An array of currencies. It is used to create account with several currencies. If currency is not passed in this API, account is created with only 1 currency (base currency).

object (CreditSettingsRequest)

The exposed revolving credit settings.

object (CreditLimitsRequest)

The exposed revolving credit limits.

Responses

Request samples

Content type
application/json
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "gg5a80f-e641-4045-8a80-54841e4a55555",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "type": "PREPAID",
  • "currencies": [
    ],
  • "credit_settings": {
    },
  • "credit_limits": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "gg5a80f-e641-4045-8a80-54841e4a55555",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "type": "PREPAID",
  • "subType": "REVOLVING",
  • "balances": {
    },
  • "ledger_balances": {
    },
  • "status": "ACTIVE",
  • "currencies": [
    ],
  • "wallet_details": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "modified_by": "API",
  • "credit_settings": {
    },
  • "credit_limits": {
    }
}

Get list of accounts

This API is used to retrieve all existitng accounts.

Authorizations:
apikey
query Parameters
user_id
string
Example: user_id=3392abea-4ef6-4645-b254-d8ace60281af

The unique identifier of the user

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "MjAxOC0wMS0wMlQxOTo0MjozMi45ODda",
  • "has_more": true,
  • "data": [
    ]
}

Get account details

This API is used to retrieve a specific account details.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account. This identifier is required in this API to retrieve the account details.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "gg5a80f-e641-4045-8a80-54841e4a55555",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "type": "PREPAID",
  • "subType": "REVOLVING",
  • "balances": {
    },
  • "ledger_balances": {
    },
  • "status": "ACTIVE",
  • "currencies": [
    ],
  • "wallet_details": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "modified_by": "API",
  • "credit_settings": {
    },
  • "credit_limits": {
    }
}

Update account

This API is used to update a specific account. It is applicable when 'is_multi_currency_product'=true for related card product.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account.

Request Body schema: application/json
required

Wallet details.

required
Array of objects (WalletDetails)

An array of wallet details.

object (UpdateAccountCreditSettings)
user_id
string <= 36 characters ^[a-zA-Z\-0-9]+$

User ID to update.

Responses

Request samples

Content type
application/json
{
  • "wallet_details": [
    ],
  • "credit_settings": {
    },
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "gg5a80f-e641-4045-8a80-54841e4a55555",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "type": "PREPAID",
  • "balances": {
    },
  • "ledger_balances": {
    },
  • "status": "ACTIVE",
  • "currencies": [
    ],
  • "wallet_details": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Change account status

This API is used to change the account status.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account. The account identifier is required in this API to change the account status.

Request Body schema: application/json
required
status
required
string (AccountStatus)
Enum: "ACTIVE" "SUSPENDED" "TERMINATED"

Account status.

  1. The card account when created shall be in Active status. While in Active status the account can be used for loading/unloading of funds and to process card authorizations and clearings.

  2. The account status can be changed from Active to Suspended status. When in Suspended status the account does not allow loading/unloading of funds and to process card authorizations. However clearings coming from the scheme are processed. Suspended status is a temporary status and the account status is allowed to change back to Active status.

  3. The account status can be changed to Terminated status. This is a permanent status, the account status can be changed to Terminated status only when card account closure operation is explicitly performed. You can update account status to Terminated if account has no balance or account has no pending authorizations.

modified_by
string
Default: "API"

This field indicates the user who executed the operation.

Responses

Request samples

Content type
application/json
{
  • "status": "ACTIVE",
  • "modified_by": "API"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "gg5a80f-e641-4045-8a80-54841e4a55555",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "type": "PREPAID",
  • "subType": "REVOLVING",
  • "balances": {
    },
  • "ledger_balances": {
    },
  • "status": "ACTIVE",
  • "currencies": [
    ],
  • "wallet_details": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "modified_by": "API",
  • "credit_settings": {
    },
  • "credit_limits": {
    }
}

Get account limits info

This API is used to retrieve the details of all available limits associated with an account.

Authorizations:
apikey
path Parameters
account_id
required
string

The unique identifier of the account.

query Parameters
type
string
Enum: "VELOCITY_LIMITS" "ADVANCED_VELOCITY_LIMITS" "BALANCE_LIMITS"

The type of limit.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "velocity_limits": [
    ],
  • "balance_limits": [
    ],
  • "advanced_velocity_limits": [
    ]
}

Get account limits info (version 2)

This API is used to retrieve the details of all available limits associated with an account.

Authorizations:
apikey
path Parameters
account_id
required
string

The unique identifier of the account.

query Parameters
type
string
Enum: "ADVANCED_VELOCITY_LIMITS" "BALANCE_LIMITS"

The type of limit.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "balance_limits": [
    ],
  • "advanced_velocity_limits": [
    ]
}

Update credit limits of account

This API is used to update credit limits of specific account.

Authorizations:
apikey
path Parameters
id
required
string

Card ID.

Request Body schema: application/json
required
assigned_credit_limit
number <int>

The assigned credit limit.

cash_adv_limit_type
string (CashAdvLimitType)
Enum: "PERCENTAGE" "FIXED"

The cash advance limit type.

cash_adv_limit_value
number <decimal>

The value of cash advance limit.

Responses

Request samples

Content type
application/json
{
  • "assigned_credit_limit": 50,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "cash_adv_limit_value": 50
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "assigned_credit_limit": 50,
  • "cash_adv_limit_value": 50,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "assigned_cash_adv_limit": 20
}

Get credit limits of account

Authorizations:
apikey
path Parameters
id
required
string

Card ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "assigned_credit_limit": 50,
  • "cash_adv_limit_value": 50,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "assigned_cash_adv_limit": 20
}

Get credit settings of account

This API is used to retrieve credit settings of specific account.

Authorizations:
apikey
path Parameters
id
required
string

Account ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "statement_date": "10/01/2023",
  • "created_on": "2012-05-04T19:42:32.987Z",
  • "last_updated_at": "2022-05-04T19:42:32.987Z",
  • "grace_period": 25,
  • "late_payment_grace_period": 1,
  • "delinquency_grace_period": 1
}

Update credit settings of account

This API is used to update credit settings of specific account.

Authorizations:
apikey
path Parameters
id
required
string

Card ID.

Request Body schema: application/json
required
statement_on
number <integer> [ 1 .. 28 ]

Statement day of the month.

grace_period
number <integer> [ 1 .. 27 ]

This field defines the number of days to add in the billing date to calculate the due date of a billing cycle.

late_payment_grace_period
number <integer> [ 1 .. 5 ]

The period of time granted by a financial institution during which a borrower or debtor can make a payment after the due date without late fee.

delinquency_grace_period
number <integer> [ 1 .. 5 ]

The specified period of time granted by a financial institution during which a borrower or debtor can make a payment after the due date without having an impact on their credit score and other punitive actions.

Responses

Request samples

Content type
application/json
{
  • "statement_on": 25,
  • "grace_period": 25,
  • "late_payment_grace_period": 3,
  • "delinquency_grace_period": 3
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "statement_date": "10/01/2023",
  • "created_on": "2012-05-04T19:42:32.987Z",
  • "last_updated_at": "2022-05-04T19:42:32.987Z",
  • "grace_period": 25,
  • "late_payment_grace_period": 1,
  • "delinquency_grace_period": 1
}

Link cards to account

This API is used to link cards to the specific account.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account.

Request Body schema: application/json
required
ids
required
Array of strings

The unique identifier or the proxy number of the card(s).

dry_run
required
boolean
Default: false

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false, and the default value is false.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ],
  • "dry_run": false
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "d089a80f-e641-4045-8a80-54841e4a7458"
]

Link balance limit to account

This API is used to link balance limit to the specific account.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account.

Request Body schema: application/json
required
balance_limit_id
required
string

The unique identifier of the balance limit.

Responses

Request samples

Content type
application/json
{
  • "balance_limit_id": "d089a80f-e641-4045-8a80-54841e4a7458"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "balance_limit_id": "d089a80f-e641-4045-8a80-54841e4a7458"
}

Unlink balance limit from account

This API is used to unlink balance limit from the specific account.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account.

Request Body schema: application/json
required
balance_limit_id
required
string

The unique identifier of the balance limit.

Responses

Request samples

Content type
application/json
{
  • "balance_limit_id": "d089a80f-e641-4045-8a80-54841e4a7458"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "balance_limit_id": "d089a80f-e641-4045-8a80-54841e4a7458"
}

Get balance limits linked to account

This API is used to fetch balance limit from the specific account.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "91fd885d-9db5-48a9-9cfb-c9adbb4f5475"
]

Load account funds

This API can be used to load funds into the account.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account. The account identifier is required in this API to load funds into the account.

header Parameters
X-Nymos-Idempotency-Key
required
string <= 36 characters

Unique transaction identification number, also referred as a Retrieval Reference Number (RRN). This number is used to uniquely identify the transaction. A resource created with a unique RRN can not be created twice.

Request Body schema: application/json
required
currency
required
string^[A-Z]{3}$

3-letter ISO_4217 code representing the currency.

amount
required
number <decimal> [ 0 .. 999999999.99 ]

Funds amount of the operation.

note
string

Additional description to the load account funds operation that is being performed can be added in this field.

dry_run
boolean
Default: false

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false, and the default value is false.

reference_number
string

This parameter is searched against 'transaction_id'. This parameter is optional.

Responses

Request samples

Content type
application/json
{
  • "currency": "USD",
  • "amount": 123.45,
  • "note": "Performing operation for 123.45 USD",
  • "dry_run": false,
  • "reference_number": "3e50d5f7-6c18-4768-81c5-e4bc31f209db"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "transaction_id": "123456789012",
  • "account_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "request": {
    },
  • "result": {
    },
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "source_channel": "DAPI"
}

Unload account funds

This API can be used to unload funds from the account.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account. The account identifier is required in this API to unload funds from the account.

header Parameters
X-Nymos-Idempotency-Key
required
string <= 36 characters

Unique transaction identification number, also referred as a Retrieval Reference Number (RRN). This number is used to uniquely identify the transaction. A resource created with a unique RRN can not be created twice.

Request Body schema: application/json
required
currency
required
string^[A-Z]{3}$

3-letter ISO_4217 code representing the currency.

amount
required
number <decimal> [ 0 .. 999999999.99 ]

Funds amount of the operation.

note
string

Additional description to the load account funds operation that is being performed can be added in this field.

dry_run
boolean
Default: false

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false, and the default value is false.

reference_number
string

This parameter is searched against 'transaction_id'. This parameter is optional.

Responses

Request samples

Content type
application/json
{
  • "currency": "USD",
  • "amount": 123.45,
  • "note": "Performing operation for 123.45 USD",
  • "dry_run": false,
  • "reference_number": "3e50d5f7-6c18-4768-81c5-e4bc31f209db"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "transaction_id": "123456789012",
  • "account_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "request": {
    },
  • "result": {
    },
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "source_channel": "DAPI"
}

Load initial funds

This API is used to perform initial load funds.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account.

header Parameters
X-Nymos-Idempotency-Key
required
string <= 36 characters

Unique transaction ID.

Request Body schema: application/json
required
currency
required
string^[A-Z]{3}$

3-letter ISO_4217 code representing the currency.

amount
required
number <decimal> [ 0 .. 999999999.99 ]

Funds amount of the operation.

note
string

Additional description to the load account funds operation that is being performed can be added in this field.

dry_run
boolean
Default: false

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false, and the default value is false.

reference_number
string

This parameter is searched against 'transaction_id'. This parameter is optional.

Responses

Request samples

Content type
application/json
{
  • "currency": "USD",
  • "amount": 123.45,
  • "note": "Performing operation for 123.45 USD",
  • "dry_run": false,
  • "reference_number": "3e50d5f7-6c18-4768-81c5-e4bc31f209db"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "transaction_id": "123456789012",
  • "account_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "request": {
    },
  • "result": {
    },
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "source_channel": "DAPI"
}

Get cards related to account

This API is used to retrieve cards which are linked to the account.

Authorizations:
apikey
path Parameters
id
required
string
Example: c1971753-2d53-4cc4-9e95-5bcb9a3fef95

The unique identifier of the account. The account identifier is required in this API to retrieve the linked cards.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "f9dc8fb0-ba5b-4d61-83df-7ab821fd02d5"
]

Create account token

This API is used to create an account token for external transactions that are initiated from third parties.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the account.

Request Body schema: application/json
required

The details of the token request.

channel
string (LoadFundsChannel)
Enum: "DAPI" "LEAN"

Load funds channel.

Responses

Request samples

Content type
application/json
{
  • "channel": "DAPI"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "token": "ODjoP1.....k6o=",
  • "expiry": 3600
}

Link source IBAN with SME user/account

This API is used to link source IBAN with SME (nCore) user_id / account_id for validation.

Authorizations:
apikey
Request Body schema: application/json
required
user_id
required
string

The unique identifier of the user.

account_id
string

The unique identifier of the account.

ibans
Array of strings

An array of IBANs.

account_numbers
Array of strings

An array of account numbers.

provider
required
string (IbanProvider)
Value: "MASHREQ"

IBAN provider.

status
string (IbanStatus)
Enum: "PENDING" "APPROVED" "REJECTED" "DELETED"

IBAN status.

Array of objects (IbanDocument)

An array of documents.

Responses

Request samples

Content type
application/json
{
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "ibans": [
    ],
  • "account_numbers": [
    ],
  • "provider": "MASHREQ",
  • "status": "APPROVED",
  • "documents": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Update source IBAN linking with SME user/account

This API is used to update source IBAN linking with SME (nCore) user_id / account_id for validation.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier.

Request Body schema: application/json
required
user_id
string

The unique identifier of the user.

account_id
string

The unique identifier of the account.

iban
string

IBAN.

account_number
string

Account number.

object (IbanDocument)

IBAN document.

provider
string (IbanProvider)
Value: "MASHREQ"

IBAN provider.

status
string (IbanStatus)
Enum: "PENDING" "APPROVED" "REJECTED" "DELETED"

IBAN status.

Responses

Request samples

Content type
application/json
{
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "iban": "AE460090000000123456789",
  • "account_number": "75757577897",
  • "document": {
    },
  • "provider": "MASHREQ",
  • "status": "APPROVED"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "72340b86-f662-4174-8bf2-eb6738a82a00",
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "iban": "AE460090000000123456789",
  • "document": {
    },
  • "account_number": "75757577897",
  • "status": "APPROVED",
  • "reason": "Some info",
  • "provider": "MASHREQ",
  • "tenant_id": "tenant21",
  • "created": "2012-05-04T19:42:32.987Z"
}

Delete source IBAN linking with SME user/account

This API is used to delete source IBAN linking with SME (nCore) user_id / account_id for validation.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "72340b86-f662-4174-8bf2-eb6738a82a00",
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "iban": "AE460090000000123456789",
  • "document": {
    },
  • "account_number": "75757577897",
  • "status": "APPROVED",
  • "reason": "Some info",
  • "provider": "MASHREQ",
  • "tenant_id": "tenant21",
  • "created": "2012-05-04T19:42:32.987Z"
}

Get linked source IBAN with SME user/account

This API is used to retrieve linked source IBAN with SME (nCore) user_id / account_id for validation.

Authorizations:
apikey
query Parameters
iban
string

IBAN.

account_number
string

Account number.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "72340b86-f662-4174-8bf2-eb6738a82a00",
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "iban": "AE460090000000123456789",
  • "document": {
    },
  • "account_number": "75757577897",
  • "status": "APPROVED",
  • "reason": "Some info",
  • "provider": "MASHREQ",
  • "tenant_id": "tenant21",
  • "created": "2012-05-04T19:42:32.987Z"
}

Get source IBAN of SME user/account

This API is used to retrieve source IBAN of with SME (nCore) user_id / account_id for validation.

Authorizations:
apikey
query Parameters
user_id
string

The unique identifier of user.

account_id
string

The unique identifier of account.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Fund Transfers

There is an opportunity to transfer funds from one account to another account so that you can move funds between your own accounts or perform a peer transfer to any other user.

Transfer funds between accounts

This API is used to transfer funds from one account to another account.

Authorizations:
apikey
header Parameters
X-Nymos-Idempotency-Key
required
string <= 36 characters

Unique transaction identification number, also referred as a Retrieval Reference Number (RRN). This number is used to uniquely identify the transaction. A resource created with a unique RRN can not be created twice.

Request Body schema: application/json
required
sender_account_id
required
string

Sender account Identifier.

recipient_account_id
required
string

Recipient account Identifier.

amount
required
number <decimal> [ 0 .. 999999999.99 ]

Amount which should be transfered.

currency
required
string^[A-Z]{3}

3-letter ISO_4217 code representing the currency.

notes
string

Notes about performed transfer request.

dry_run
boolean
Default: false

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false and the default value is false.

internal_markup_amount
number

Total internal markup amount calculated.

external_markup_amount
number

Total external markup amount calculated.

Responses

Request samples

Content type
application/json
{
  • "sender_account_id": "bc121529-e6e9-45f1-b820-8c46ce7f005a",
  • "recipient_account_id": "39dbff34-5505-4181-9e81-727b71e72186",
  • "amount": 12.5,
  • "currency": "USD",
  • "notes": "Performing operation for 12.50 USD",
  • "dry_run": false,
  • "internal_markup_amount": 15,
  • "external_markup_amount": 10
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "transaction_id": "123456789012",
  • "sender_account_id": "bc121529-e6e9-45f1-b820-8c46ce7f005a",
  • "recipient_account_id": "39dbff34-5505-4181-9e81-727b71e72186",
  • "amount": 12.5,
  • "sender_user_id": "hkuser282",
  • "currency": "USD",
  • "fee_amount": 2.5,
  • "fee_details": [
    ],
  • "notes": "Performing operation for 12.50 USD\"",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "source_channel": "DAPI",
  • "receiver_user_id": "g157a80f-e641-7745-8a80-99841e4a1234",
  • "internal_markup_amount": 15,
  • "external_markup_amount": 10
}

Get list of transfers

This API is used to retrieve the list of transfers.

Authorizations:
apikey
query Parameters
sender_account_id
string

Sender account Identifier

recipient_account_id
string

Recipient account Identifier

transfer_date_time_start
string <date-time>

Date and time of a transfer, starting with which you want to filter a list of transfer. This parameter is displayed in the following format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'".

transfer_date_time_end
string <date-time>

Date and time of a transfer, ending with which you want to filter a list of transfer. This parameter is displayed in the following format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'".

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Transfer funds between accounts (version 2)

This API is used to transfer funds between accounts. (Note "This is a version 2 of Transfer funds API")

Authorizations:
apikey
header Parameters
X-Nymos-Idempotency-Key
required
string <= 36 characters

Unique transaction ID.

Request Body schema: application/json
required
sender_account_id
required
string

Sender account Identifier.

recipient_account_id
required
string

Recipient account Identifier.

amount
required
number <decimal> [ 0 .. 999999999.99 ]

Amount which should be transfered.

currency
required
string^[A-Z]{3}

3-letter ISO_4217 code representing the currency.

notes
string

Notes about performed transfer request.

dry_run
boolean
Default: false

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false and the default value is false.

original_transaction_id
string

Identifier of the original transaction.

execution_type
string (ExecutionTypeV2)
Enum: "HOLD" "RELEASE" "POST" "SETTLE"

Execution type.

Responses

Request samples

Content type
application/json
{
  • "sender_account_id": "bc121529-e6e9-45f1-b820-8c46ce7f005a",
  • "recipient_account_id": "39dbff34-5505-4181-9e81-727b71e72186",
  • "amount": 12.5,
  • "currency": "USD",
  • "notes": "Performing operation for 12.50 USD",
  • "dry_run": false,
  • "original_transaction_id": "SedT00039",
  • "execution_type": "HOLD"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "transaction_id": "123456789012",
  • "sender_account_id": "bc121529-e6e9-45f1-b820-8c46ce7f005a",
  • "recipient_account_id": "39dbff34-5505-4181-9e81-727b71e72186",
  • "amount": 12.5,
  • "sender_user_id": "hkuser282",
  • "currency": "USD",
  • "fee_amount": 2.5,
  • "fee_details": [
    ],
  • "notes": "Performing operation for 12.50 USD\"",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "source_channel": "DAPI",
  • "receiver_user_id": "g157a80f-e641-7745-8a80-99841e4a1234",
  • "internal_markup_amount": 15,
  • "external_markup_amount": 10
}

Get specific transfer

This API is used to retrieve a specific transfer details.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the transfer. This identifier is required in this API to retrieve the transfer details.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "transaction_id": "123456789012",
  • "sender_account_id": "bc121529-e6e9-45f1-b820-8c46ce7f005a",
  • "recipient_account_id": "39dbff34-5505-4181-9e81-727b71e72186",
  • "amount": 12.5,
  • "sender_user_id": "hkuser282",
  • "currency": "USD",
  • "fee_amount": 2.5,
  • "fee_details": [
    ],
  • "notes": "Performing operation for 12.50 USD\"",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "source_channel": "DAPI",
  • "receiver_user_id": "g157a80f-e641-7745-8a80-99841e4a1234",
  • "internal_markup_amount": 15,
  • "external_markup_amount": 10
}

Orders

nCore platform provides capability to load into Nymcard card account from external funding source so that you can top-up your card account balance using a third-party payment card. For this we have integrated a payment gateway. At the moment we offer such loading method as HOSTED_CHECKOUT.

Create order

This API is used to create an order.

Authorizations:
apikey
Request Body schema: application/json
required
dry_run
boolean
Default: false

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false and the default value is false.

account_id
required
string <= 36 characters

Unique identifier of the account in NymCard platform in which amount will be loaded.

amount
required
number <decimal> [ 0 .. 999999999.99 ]

Amount which should be loaded in the account.

currency
required
string^[A-Z]{3}$

Currency of the amount which should be loaded. The format is 3-letter ISO_4217 code. "AED” is the only supported currency for now.

note
string <= 500 characters

Additional description to the load account funds operation that is being performed.

payment_method
required
string (OrderPaymentMethod)
Value: "HOSTED_CHECKOUT"

The payment gateway loading flow.

redirect_url
string <= 1000 characters

If payment_method is HOSTED_CHECKOUT, then this field is mandatory.

Responses

Request samples

Content type
application/json
{
  • "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"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "order_id": "e82c3059-33af-4ed0-969a-7c23801dd770",
  • "session_id": "SESSION0002034447366K45355737H1",
  • "transaction_id": "111c3059-33af-4ed0-969a-7c23801dd555",
  • "merchant_id": "500532",
  • "merchant_currency": "AED",
  • "reference_number": "1644426451325",
  • "request": {
    },
  • "result": {
    },
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get order

This API is used to retrieve details of a specific order.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "order_id": "e82c3059-33af-4ed0-969a-7c23801dd770",
  • "session_id": "SESSION0002034447366K45355737H1",
  • "transaction_id": "111c3059-33af-4ed0-969a-7c23801dd555",
  • "merchant_id": "500532",
  • "merchant_currency": "AED",
  • "reference_number": "1644426451325",
  • "request": {
    },
  • "result": {
    },
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Create temporary user token

This API is used to create temporary user token for orders in the standard NymCard widget and MPGS.

Authorizations:
apikey
Request Body schema: application/json
required
account_id
required
string

ID of the account, to which funds will be loaded.

Responses

Request samples

Content type
application/json
{
  • "account_id": "e6b500c7-b37b-46cf-baae-e1b4f43e8749"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "token": "42504465-5410-46fc-94e8-aa5bc062ada9%7Ctenant",
  • "expire_at": "2012-05-04T19:42:32.987Z"
}

Create LUT for requested operation

This API is used to create a LUT (Limited Usage Token) for requested operation. It is used for Checkout Widget. LUT has a timeout for 10 minutes.

Authorizations:
apikey
path Parameters
id
required
string

User ID to create LUT for.

Request Body schema: application/json
required
source_id
required
string

The source identifier is used to identify the PCI source to get the cipher key.

operation
required
string (CheckoutLutOperation)
Value: "CHECKOUT_TOKEN"

The LUT operation.

Responses

Request samples

Content type
application/json
{
  • "source_id": "default_pci_source",
  • "operation": "CHECKOUT_TOKEN"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "token": "SMJXdC/sCRogr0K7fuMz0/6QFLBDLglA2rCeZAPgS9Rb04L/BW3mYXkY2L4nab8b"
}

Cards

Using our nCore platform you can issue a physical card or a virtual card for a registered user. The card is created for a card product already defined in the system. The card inherits features/rules applied on the card product level. It is possible to issue a personalized physical card (that is a card personalized with the user name on it) for a registered user. 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 his/her card. You can also create a virtual card for a registered user. The user can retrieve virtual card details (card number, expiry date, CVV2) so that he/she can use the virtual card for online payments.

Link allowed merchant lists to a card (V2)

Links one or more merchant lists to a card. All linked lists must share the same type (ALLOWED or BLOCKED). If a list of a different type is already linked, the request will be rejected.

Authorizations:
apikey
path Parameters
id
required
string
Request Body schema: application/json
required

Merchant list IDs to be linked to the card

merchant_list_ids
required
Array of strings non-empty

List of merchant list identifiers to link

Responses

Request samples

Content type
application/json
{
  • "merchant_list_ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "allowed_merchants_ids": [
    ]
}

Unlink allowed merchant lists from a card (V2)

Authorizations:
apikey
path Parameters
id
required
string
Request Body schema: application/json
required

Merchant list IDs to be unlinked from the card

merchant_list_ids
required
Array of strings non-empty

List of merchant list identifiers to link

Responses

Request samples

Content type
application/json
{
  • "merchant_list_ids": [
    ]
}

Get all allowed merchant lists linked to card (V2)

Authorizations:
apikey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "allowed_merchants_ids": [
    ]
}

Create card

This API is used to create a card.

Authorizations:
apikey
header Parameters
x-nymos-idempotency-key
required
string <= 36 characters

Unique transaction identification number, also referred as a Retrieval Reference Number (RRN). This number is used to uniquely identify the transaction. A resource created with a unique RRN can not be created twice.

Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the card. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls and this value cannot be updated.

user_id
required
string <= 36 characters

Token identifier of the user who owns this card.

card_type
required
string (CardType)
Enum: "PHYSICAL" "VIRTUAL"

The type of the card. Supported values are physical and virtual.

card_product_id
required
string

The unique identifier of the card product. This token id is referred to as an existing card product. The card creating with this card product token will inherit all of its characteristics.

reference_card_id
string <= 36 characters

Token identifier of the card to refer to when creating a card linked to an existing account.

bulk_issuance_id
string <= 36 characters

Token identifier of the bulk issuance request to which this card belongs to.

name_on_card
string <= 20 characters

Name to print on the card and track data. If this field finds empty in the request, then the name of the user profile will be printed on the card.

object (CardShippingDetails)

Details of card shipping destination.

dry_run
boolean

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false and the default value is false.

card_validity_term
integer <int32> [ 1 .. 99 ]

This is the term (in months) for which a newly created card will be valid for. Used to set the expiry date for the card. The expiry date shall be calculated from the date of card creation till the number of months given by this parameter. This field is optional; if it is empty, then card_validity_term from card_product shall be used. Card validity term of the card can not be greater than that of the card product.

extra_embossing_line
string <= 20 characters ^[a-zA-Z0-9\s]+$

Extra embossing line.

object (CreditSettingsRequest)

The exposed revolving credit settings.

object (CreditLimitsRequest)

The exposed revolving credit limits.

design_code
string <= 20 characters

Design code for the card.

external_account_id
string

External account ID.

account_id
string <= 36 characters

Token identifier of the account who owns this card. This parameter is used only for credit cards.

Responses

Request samples

Content type
application/json
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "aabc9d-996azam799-9ac99879b9a9bC99",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "dry_run": false,
  • "card_validity_term": 36,
  • "extra_embossing_line": "CLASSIC",
  • "credit_settings": {
    },
  • "credit_limits": {
    },
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-7880-54841e4a7458",
  • "account_id": "d089a80f-e641-4045-8a80-54841e4a7458"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "status": "INACTIVE",
  • "status_reason": "I0",
  • "fulfillment_status": "CREATED",
  • "bin": "123456",
  • "last_four": "5789",
  • "expiry_date": "01/2025",
  • "pin_retries": 0,
  • "proxy_number": "0000367466",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "activation_date": "2024-03-15T10:32:00.000Z",
  • "modified_by": "API",
  • "extra_embossing_line": "CLASSIC",
  • "card_soft_expiry": "01/2025",
  • "auth_settings": {
    },
  • "is_account_linked": true,
  • "change_to_physical": true,
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-5680-54841e4a7458",
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Get list of cards

This API can be used to retrieve a list of cards. The nCore platform provides you various card retrieval options like to retrieve all cards existing for a tenant, all cards which belong to a single user and all cards that created in a bulk issuance request.

Authorizations:
apikey
query Parameters
user_id
string
Example: user_id=22ed2f6c-9312-4780-8cf7-a2e75f749543

The unique identifier of the user. If included then cards will be retrieved by user id.

bulk_issuance_id
string
Example: bulk_issuance_id=9ea50adf-b70a-4df2-b3a4-83d3cb0a7f9d

The unique identifier of the bulk issuance. If included then cards will be retrieved by the bulk issuance id.

proxy_number
string
Example: proxy_number=0000123456

If included then cards will be filtered by Proxy Number

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "MjAxOC0wMS0wMlQxOTo0MjozMi45ODda",
  • "has_more": true,
  • "data": [
    ]
}

Get card by mobile number

Authorizations:
apikey
query Parameters
mobile_number
required
string

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "string"
]

Get card list balances

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Request Body schema: application/json
card_ids
Array of strings[ items <= 36 characters ^[a-zA-Z\-0-9]+$ ]
expiry_date_from
string^20\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]...
expiry_date_to
string^20\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]...
activation_date_from
string^20\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]...

Return cards activated on or after this date (inclusive).

activation_date_to
string^20\d{2}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]...

Return cards activated on or before this date (inclusive).

statuses
Array of strings (CardStatus)
Items Enum: "INACTIVE" "ACTIVE" "SUSPENDED" "TERMINATED"
card_scopes
Array of strings (CardScope)
Items Enum: "OPEN_LOOP" "CLOSE_LOOP"

Responses

Request samples

Content type
application/json
{
  • "card_ids": [
    ],
  • "expiry_date_from": "2098-12-25",
  • "expiry_date_to": "2098-12-25",
  • "activation_date_from": "2024-01-01",
  • "activation_date_to": "2025-12-31",
  • "statuses": [
    ],
  • "card_scopes": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Update card credit limits

This API is used to update card credit limits.

Authorizations:
apikey
path Parameters
id
required
string

Card ID.

Request Body schema: application/json
required
assigned_credit_limit
number <int>

The assigned credit limit.

cash_adv_limit_type
string (CashAdvLimitType)
Enum: "PERCENTAGE" "FIXED"

The cash advance limit type.

cash_adv_limit_value
number <decimal>

The value of cash advance limit.

Responses

Request samples

Content type
application/json
{
  • "assigned_credit_limit": 50,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "cash_adv_limit_value": 50
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "assigned_credit_limit": 50,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "cash_adv_limit_value": 50,
  • "assigned_cash_adv_limit": 20
}

Get card credit limits

This API is used to get card credit limits.

Authorizations:
apikey
path Parameters
id
required
string

Card ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "assigned_credit_limit": 50,
  • "cash_adv_limit_type": "PERCENTAGE",
  • "cash_adv_limit_value": 50,
  • "assigned_cash_adv_limit": 20
}

Link bulk card to user

This API is used to link bulk card to a user. There are 2 possible scenarios when you want to link bulk card to a user.

  • 1) It is requested to pass 'user_id' and 'activation_token' parameters in the request to link bulk card to a user and the card will be automatically activated.
  • 2) It is requested to pass 'user_id', 'card_id' OR 'proxy_number' and 'activate_card' parameters in the request to link bulk card to a user and the card status will be either ACTIVE or INACTIVE depending on the value given to 'activate_card' parameter.
Authorizations:
apikey
Request Body schema: application/json
required
activation_token
string <= 255 characters

Activation token is a card data encrypted with secure hash algorithm SHA-512. SHA-512 is formed in the following way - (card.pan + card.expiryDate_yyMM + card.cvv2).toUpperCase().

user_id
string

ID of a user to whom the card should be linked.

activate_card
boolean

Set this parameter as 'true' to activate the card.

card_id
string

The unique identifier of the card.

proxy_number
string

The unique short identifier of the card.

Responses

Request samples

Content type
application/json
{
  • "activation_token": "671BD682A4FD7CB04B87EBE005866BF81B706F0AA4A3E5F337E810CEC7074325",
  • "user_id": "c489509d-a973-4892-9135-42c214212cdf",
  • "activate_card": true,
  • "card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "proxy_number": "d089a80f28kl"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "status": "INACTIVE",
  • "status_reason": "I0",
  • "fulfillment_status": "CREATED",
  • "bin": "123456",
  • "last_four": "5789",
  • "expiry_date": "01/2025",
  • "pin_retries": 0,
  • "proxy_number": "0000367466",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "activation_date": "2024-03-15T10:32:00.000Z",
  • "modified_by": "API",
  • "extra_embossing_line": "CLASSIC",
  • "card_soft_expiry": "01/2025",
  • "auth_settings": {
    },
  • "is_account_linked": true,
  • "change_to_physical": true,
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-5680-54841e4a7458",
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Get card details

This API can be used to retrieve a single card by providing a card id to check the card details.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card. This identified is required in this API to retrieve the card details.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "status": "INACTIVE",
  • "status_reason": "I0",
  • "fulfillment_status": "CREATED",
  • "bin": "123456",
  • "last_four": "5789",
  • "expiry_date": "01/2025",
  • "pin_retries": 0,
  • "proxy_number": "0000367466",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "activation_date": "2024-03-15T10:32:00.000Z",
  • "modified_by": "API",
  • "extra_embossing_line": "CLASSIC",
  • "card_soft_expiry": "01/2025",
  • "auth_settings": {
    },
  • "is_account_linked": true,
  • "change_to_physical": true,
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-5680-54841e4a7458",
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Update card

This API can be used to update card details like bulk issuance id, name on the card, and shipping details.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card. This identified is required in this API to update the card details.

Request Body schema: application/json
required
bulk_issuance_id
string <= 36 characters

Token identifier of the bulk issuance request to which this card belongs to.

name_on_card
string <= 20 characters

Name to print on the card and track data. If this field finds empty in the request, then the name of the user profile will be printed on the card.

object (CardShippingDetails)

Details of card shipping destination.

extra_embossing_line
string <= 20 characters ^[a-zA-Z0-9\s]+$

Extra embossing line.

change_to_physical
boolean
object (CreditSettingsRequest)

The exposed revolving credit settings.

object (CreditLimitsRequest)

The exposed revolving credit limits.

fulfillment_status
string (FulfillmentStatus)
Enum: "CREATED" "ORDERED"

Fulfilment status of the card.

user_id
string <= 36 characters

User ID to update.

Responses

Request samples

Content type
application/json
{
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "extra_embossing_line": "CLASSIC",
  • "change_to_physical": true,
  • "credit_settings": {
    },
  • "credit_limits": {
    },
  • "fulfillment_status": "CREATED",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "status": "INACTIVE",
  • "status_reason": "I0",
  • "fulfillment_status": "CREATED",
  • "bin": "123456",
  • "last_four": "5789",
  • "expiry_date": "01/2025",
  • "pin_retries": 0,
  • "proxy_number": "0000367466",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "activation_date": "2024-03-15T10:32:00.000Z",
  • "modified_by": "API",
  • "extra_embossing_line": "CLASSIC",
  • "card_soft_expiry": "01/2025",
  • "auth_settings": {
    },
  • "is_account_linked": true,
  • "change_to_physical": true,
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-5680-54841e4a7458",
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Get card authorization settings data

This API is used to get authorization settings data of a specific card.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "allow_atm": true,
  • "allow_pos": true,
  • "allow_chip": true,
  • "allow_magstripe": true,
  • "allow_chip_fallback": true,
  • "allow_without_pin": true,
  • "allow_ecommerce_non_3DS": true,
  • "allow_ecommerce_3DS": true,
  • "allow_ecommerce_without_CVV": false,
  • "allow_account_verification_without_CVV": false,
  • "allow_quasi_cash": false,
  • "allow_scheme_account_funding": false,
  • "allow_scheme_credits": false,
  • "allow_contactless": true,
  • "allowed_mccs_id": "a8180db3-b2e9-4ae0-93cd-2a0b52a99737",
  • "allowed_countries_id": "8358c501-56a3-43b0-b2b3-a2c49f3c33ab"
}

Update card authorization settings data

This API is used to update authorization settings data of a specific card.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card.

Request Body schema: application/json
required
allow_atm
boolean
Default: true

This parameter indicates if ATM transactions are allowed or not.

allow_pos
boolean
Default: true

This parameter indicates if transactions originating from point of sales are allowed or not.

allow_chip
boolean
Default: true

This parameter indicates if chip transactions are allowed or not.

allow_magstripe
boolean
Default: true

This parameter indicates if magnetic stripe transactions are allowed or not.

allow_chip_fallback
boolean
Default: true

This parameter indicates if chip fallback to magnetic stripe transactions are allowed or not.

allow_without_pin
boolean
Default: true

This parameter indicates if authorization transactions without PIN are allowed or not.

allow_ecommerce_non_3DS
boolean
Default: true

This parameter indicates if e-commerce non-3DS transactions are allowed or not.

allow_ecommerce_3DS
boolean
Default: true

This parameter indicates if e-commerce 3DS transactions are allowed or not.

allow_ecommerce_without_CVV
boolean
Default: false

This parameter indicates if e-commerce transactions without CVV2/CVN2 are allowed or not.

allow_account_verification_without_CVV
boolean
Default: false

This parameter indicates if e-commerce account verification transactions without CVV2/CVN2 are allowed or not.

allow_quasi_cash
boolean
Default: false

This parameter indicates if a quasi cash transaction is allowed or not.

allow_scheme_account_funding
boolean
Default: false

This parameter indicates if a scheme account funding transaction is allowed or not.

allow_scheme_credits
boolean
Default: false

This parameter indicates if scheme credit transactions like Visa OCT or MC MoneySend are allowed or not.

allow_contactless
boolean
Default: true

This parameter indicates if contactless transactions are allowed or not.

allowed_mccs_id
string <= 36 characters

Allowed MCCS identifier.

allowed_countries_id
string <= 36 characters

Allowed countries identifier.

Responses

Request samples

Content type
application/json
{
  • "allow_atm": true,
  • "allow_pos": true,
  • "allow_chip": true,
  • "allow_magstripe": true,
  • "allow_chip_fallback": true,
  • "allow_without_pin": true,
  • "allow_ecommerce_non_3DS": true,
  • "allow_ecommerce_3DS": true,
  • "allow_ecommerce_without_CVV": false,
  • "allow_account_verification_without_CVV": false,
  • "allow_quasi_cash": false,
  • "allow_scheme_account_funding": false,
  • "allow_scheme_credits": false,
  • "allow_contactless": true,
  • "allowed_mccs_id": "a8180db3-b2e9-4ae0-93cd-2a0b52a99737",
  • "allowed_countries_id": "8358c501-56a3-43b0-b2b3-a2c49f3c33ab"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "allow_atm": true,
  • "allow_pos": true,
  • "allow_chip": true,
  • "allow_magstripe": true,
  • "allow_chip_fallback": true,
  • "allow_without_pin": true,
  • "allow_ecommerce_non_3DS": true,
  • "allow_ecommerce_3DS": true,
  • "allow_ecommerce_without_CVV": false,
  • "allow_account_verification_without_CVV": false,
  • "allow_quasi_cash": false,
  • "allow_scheme_account_funding": false,
  • "allow_scheme_credits": false,
  • "allow_contactless": true,
  • "allowed_mccs_id": "a8180db3-b2e9-4ae0-93cd-2a0b52a99737",
  • "allowed_countries_id": "8358c501-56a3-43b0-b2b3-a2c49f3c33ab"
}

Show card secret data

This API can be used to retrieve and see card's secret data, e.g. PAN (Primary Account Number), CVV2 (Card Verification Value 2), Card expiry date, and Pin retries. This API can be used by a PCI Compliant user, if a non-complaint user is calling this API, then request error 403 (Forbidden) will appear.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card. This identifier is required in this API to retrieve the card's secret data.

query Parameters
show_cvv2
boolean

This query parameter is used to decide whether to see a clear CVV2 (Card Verification Value) or not. Applicable values are true/false.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "status": "INACTIVE",
  • "status_reason": "I0",
  • "fulfillment_status": "CREATED",
  • "bin": "123456",
  • "last_four": "5789",
  • "expiry_date": "01/2025",
  • "pin_retries": 0,
  • "proxy_number": "0000367466",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "activation_date": "2024-03-15T10:32:00.000Z",
  • "modified_by": "API",
  • "extra_embossing_line": "CLASSIC",
  • "card_soft_expiry": "01/2025",
  • "auth_settings": {
    },
  • "is_account_linked": true,
  • "change_to_physical": true,
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-5680-54841e4a7458",
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ],
  • "number": "9999999999999999",
  • "cvv2": "999"
}

Replace card to non-personalized bulk card

This API is used to replace a terminated card (physical or virtual) to a non-personalized physical bulk card so that you can use the replaced card to perform transactions. The replaced card should have status “TERMINATED”.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$
Example: d089a80f-e641-4045-8a80-54841e4a7458

Card ID from bulk to replace referenced card.

Request Body schema: application/json
required
reference_card_id
required
string

Original terminated card ID for replacement. The replaced card should have status “TERMINATED”.

activate_card
boolean
Default: true

This parameter is used to activate a card. The default value is 'true'.

Responses

Request samples

Content type
application/json
{
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7459",
  • "activate_card": true
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "status": "INACTIVE",
  • "status_reason": "I0",
  • "fulfillment_status": "CREATED",
  • "bin": "123456",
  • "last_four": "5789",
  • "expiry_date": "01/2025",
  • "pin_retries": 0,
  • "proxy_number": "0000367466",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "activation_date": "2024-03-15T10:32:00.000Z",
  • "modified_by": "API",
  • "extra_embossing_line": "CLASSIC",
  • "card_soft_expiry": "01/2025",
  • "auth_settings": {
    },
  • "is_account_linked": true,
  • "change_to_physical": true,
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-5680-54841e4a7458",
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Create LUT for requested operation

This API is used to create a LUT (Limited Usage Token) for operations like view clear card details, retrieve clear card PIN, change a card PIN or activate a card. LUT has a timeout of 5 minutes before getting used. If the user does not use the LUT within 5 minutes, it will get expired. Each LUT is for one time use.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card. The card identifier is required in this API to create LUT for the specific secure card operations provided in field 'operation'.

Request Body schema: application/json
required
source_id
required
string

The source identifier is used to identify the PCI source to get the cipher key.

operation
required
string (LutOperation)
Enum: "SHOW_CLEAR_CARD_DETAILS" "GET_PIN" "ACTIVATE_CARD" "CHANGE_PIN"

The LUT creation is based on the supported operations such as, "show_clear_card_details", "get_pin", "activate_card", and "change_pin".

Responses

Request samples

Content type
application/json
{
  • "source_id": "ae31cd18-7ed6-4b03-8e6b-4857f11d380d",
  • "operation": "SHOW_CLEAR_CARD_DETAILS"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "token": "152e8a03-719e-40b6-a901-ed981d31d52f"
}

Change card status

This API is used to change a card status.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card. The card identifier is required in this API to change the card status.

Request Body schema: application/json
required
status
required
string (CardStatus)
Enum: "INACTIVE" "ACTIVE" "SUSPENDED" "TERMINATED"

The status of a card.

status_reason_code
required
string (StatusChangeReason)
Enum: "A0" "A1" "A3" "AT" "S0" "S1" "S2" "S3" "S4" "S5" "S6" "S7" "ST" "T0" "T1" "T2" "T3" "T4" "T5" "T7" "T8" "T9" "T10" "T11" "T12" "T13" "T14" "T15" "T16" "T17" "T18"

Status Change Reason Code:

  • A0: First time activation: when activated from INACTIVE to ACTIVE status.
  • A1: Resumed from Suspended status: when card is moved back to ACTIVE status.
  • A3: Activated by admin.
  • AT: Active in transition phase.
  • S0: Temporary suspension: initiated by the user or system user or the system.
  • S1: PIN retries exhausted: when bad PIN retries are exhausted.
  • S2: Card validity expired.
  • S3: Admin rejected due to ID verification failed.
  • S4: Suspended by admin.
  • S5: Admin rejected due to ID verification failed.
  • S6: Suspended by admin.
  • S7: Admin suspended due to being delinquent for a certain amount of time
  • ST: Suspended in transition phase.
  • T0: Card is lost.
  • T1: Card is stolen.
  • T2: Card is expired.
  • T3: Card is damaged.
  • T4: Card is closed by user.
  • T5: Card is closed by issuer.
  • T7: Admin terminated due to limited time exceeded and action taken for ID verification fail.
  • T8: Terminated by admin.
  • T9: Admin terminated due to ID verification failed.
  • T10: Admin terminated due to limited time exceeded and action taken for KYB fail.
  • T11: Terminated by Admin.
  • T12: System terminated due to ID verification rejected.
  • T13: System terminated due to ID verification suspected.
  • T14: Failed KYC.
  • T15: Terminated by admin.
  • T16: Terminated by admin.
  • T17: Admin terminated due to ID verification failed.
  • T18: Admin terminated due to KYC failed.
object (CoreNote)

This field is to capture additional information by the user while changing the card status. E.g. how the card got stolen, what is the reason behind a damage, etc.

modified_by
string
Default: "API"

This field indicates the user who executed the operation.

Responses

Request samples

Content type
application/json
{
  • "status": "INACTIVE",
  • "status_reason_code": "A0",
  • "note": {
    },
  • "modified_by": "API"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "status": "INACTIVE",
  • "status_reason": "I0",
  • "fulfillment_status": "CREATED",
  • "bin": "123456",
  • "last_four": "5789",
  • "expiry_date": "01/2025",
  • "pin_retries": 0,
  • "proxy_number": "0000367466",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "activation_date": "2024-03-15T10:32:00.000Z",
  • "modified_by": "API",
  • "extra_embossing_line": "CLASSIC",
  • "card_soft_expiry": "01/2025",
  • "auth_settings": {
    },
  • "is_account_linked": true,
  • "change_to_physical": true,
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-5680-54841e4a7458",
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Set card soft expiry

This API is used to change a card soft expiry.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card.

Request Body schema: application/json
required
period
string (CardSoftExpiryPeriod)
Value: "MONTH"

Card soft expiry period.

extend_soft_expiry
integer >= 1

Card soft expiry period number. The unit of this value depends on provided period unit.

note
string

An optional note.

modified_by
string <= 50 characters
Default: "API"

This field indicates Who updated card's soft expiry setting. Default is 'API'.

soft_expiry_date
string

The soft expiry date.

Responses

Request samples

Content type
application/json
{
  • "period": "MONTH",
  • "extend_soft_expiry": 1,
  • "note": "Some info",
  • "modified_by": "API",
  • "soft_expiry_date": "06/2025"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_type": "PHYSICAL",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "reference_card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "bulk_issuance_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name_on_card": "John Smith",
  • "shipping_details": {
    },
  • "status": "INACTIVE",
  • "status_reason": "I0",
  • "fulfillment_status": "CREATED",
  • "bin": "123456",
  • "last_four": "5789",
  • "expiry_date": "01/2025",
  • "pin_retries": 0,
  • "proxy_number": "0000367466",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "activation_date": "2024-03-15T10:32:00.000Z",
  • "modified_by": "API",
  • "extra_embossing_line": "CLASSIC",
  • "card_soft_expiry": "01/2025",
  • "auth_settings": {
    },
  • "is_account_linked": true,
  • "change_to_physical": true,
  • "design_code": "a2sd34a32s",
  • "external_account_id": "d055a80f-e641-4045-5680-54841e4a7458",
  • "allowed_merchants_id": "string",
  • "allowed_merchants_ids": [
    ]
}

Get accounts related to card

This API is used to retrieve accounts which are linked to the card.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card. The card identifier is required in this API to retrieve the linked accounts.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "b6822247-052d-4bb1-ad49-5e46f7c8fdd0"
]

Get card PIN

This API is used to retrieve the card secure PIN.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card. The card identifier is required in this API to retrieve the card PIN.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "enc_pin": "ncrypt:2:xKzHT-2NJ8yCZIv7Ra9oFQ:VETEcevv-ZyndOeLF7CqO-4aNJ6Z5Tha0wcMFoJEDAJAoLsst1ccMSeeMdbJUwq1GfKjCpm5mMwkEn51ZAFqLW43EcNkapSiPPVRJtU5V1z9u4ZGEXi4swPVzY2j0NfaM4a4aGM_WdpKSx6r7m86vhjI5901GXRd2vpyGAztfL9krOMA7KgLGaVlqj1i-xIaxvGbIDhFVepIWcxTxiSHqwZxLMN1HMojtf2pJacwoq5nOBP3DX3DgdapIdJN8AWCSIpZ8M6nwf4-2Wr8GGTJrUChU1eJiALKZ-lliP8RvIERG9zP3Z41kQDoWP9JlEFr547xREvXIf6IS4a_ixuwrg:1Ya9e6e0Los"
}

Change card PIN

This API is used to change the card PIN.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card. The card identifier is required in this API to change the card PIN.

Request Body schema: application/json
required
enc_pin
required
string

Encrypted card PIN.

Responses

Request samples

Content type
application/json
{
  • "enc_pin": "ncrypt:2:bP6dZTzopk6TTYeP4lETrw:kjQRz3M9wzOFPU3cphAomtHoMv3aC2-CkMtAgiLvYfpy1cEwTm3ag7_caXHFThWN_SBxHpj9aviki9rr7okJKN-BqdO46d7Uu4Bx9dNo0_Tn9ZcKV7X-dAGLgNViYeAaGbA2jlcESYZZLecqPBqBADQ12DdGV4VfRtEb3pDZRO3VRP1hXL4VgN_H1vRwIwT5vTyBLuzQA3Lh3xqrlVrrRFHah42oH3YkgaY6M8mc3r3e3pBItNMiwW10wjfO50z7dy2O0yAGyy-QSWqu4LQYMLKMAPx4wsuEcAQg3Xpmnv3GmP_goAvu88ASH9u4iKWGh0OtrldQZlmUqiYcq9mWMQ:Ok9OebFuRwQ"
}

Validate card PIN

This API is used to validate the card PIN.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier or the proxy number of the card. The card identifier is required in this API to validate the card PIN.

Request Body schema: application/json
required
enc_pin
required
string

Encrypted card PIN.

Responses

Request samples

Content type
application/json
{
  • "enc_pin": "ncrypt:2:bP6dZTzopk6TTYeP4lETrw:kjQRz3M9wzOFPU3cphAomtHoMv3aC2-CkMtAgiLvYfpy1cEwTm3ag7_caXHFThWN_SBxHpj9aviki9rr7okJKN-BqdO46d7Uu4Bx9dNo0_Tn9ZcKV7X-dAGLgNViYeAaGbA2jlcESYZZLecqPBqBADQ12DdGV4VfRtEb3pDZRO3VRP1hXL4VgN_H1vRwIwT5vTyBLuzQA3Lh3xqrlVrrRFHah42oH3YkgaY6M8mc3r3e3pBItNMiwW10wjfO50z7dy2O0yAGyy-QSWqu4LQYMLKMAPx4wsuEcAQg3Xpmnv3GmP_goAvu88ASH9u4iKWGh0OtrldQZlmUqiYcq9mWMQ:Ok9OebFuRwQ"
}

Get card limits info

This API is used to fetch all limits associated with card.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card.

query Parameters
type
string
Enum: "ADVANCED_VELOCITY_LIMIT" "VELOCITY_LIMITS" "BALANCE_LIMITS"

The type of limit.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "velocity_limits": [
    ],
  • "balance_limits": [
    ],
  • "advanced_velocity_limits": [
    ]
}

Get card limits info (version 2)

This API is used to fetch all limits associated with card.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier or the proxy number of the card.

query Parameters
type
string
Enum: "ADVANCED_VELOCITY_LIMITS" "BALANCE_LIMITS"

The limit type.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "balance_limits": [
    ],
  • "advanced_velocity_limits": [
    ]
}

Get card tracking details

This API is used to retrieve cards tracking details.

Authorizations:
apikey
query Parameters
user_id
required
string

Customer’s unique ID.

card_id
string

The unique identifier of the card.

status
string

This field is used to filter tracking records by status (Pending, In Transit, Delivered).

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "tracking_details": [
    ]
}

Get card delivery status

This API is used to retrieve card delivery status.

Authorizations:
apikey
query Parameters
tracking_id
required
string

Customer's tracking ID (AWB).

last_tracking_update_only
required
boolean

This field is used to get the complete history or only last status.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "tracking_id": "44262738730",
  • "history": [
    ]
}

Get list of cards for renewal

This API is used to retrieve the list of cards for renewal.

Authorizations:
apikey
query Parameters
product_id
required
string

The unique identifier of the card product.

start_date
string <date-time>

The start date.

end_date
string <date-time>

The end date.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "MjAxOC0wMS0wMlQxOTo0MjozMi45ODda",
  • "has_more": true,
  • "data": [
    ]
}

Mark cards for renewal

This API is used to mark cards for renewal.

Authorizations:
apikey
Request Body schema: application/json
required
product_id
required
string

The unique identifier of the card product.

cards
required
Array of strings

An array of data.

Responses

Request samples

Content type
application/json
{
  • "product_id": "aabc9d-996azam799-9ac99879b9a9bC99",
  • "cards": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "2ca78c19-5a4e-4123-a069-6d84f6aa1b54",
  • "product_id": "aabc9d-996azam799-9ac99879b9a9bC99",
  • "cards": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2024-01-02T19:42:32.987Z",
  • "maker_id": "system",
  • "checker_id": "system",
  • "status": "PENDING",
  • "error_description": "Some info about error"
}

Get card credit settings

This API is used to retrieve credit settings of a specific card.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "statement_on": 25,
  • "payment_due_on": 27,
  • "delinquency_period_passed": 28,
  • "last_notification_sent": "Sent",
  • "amount_due": 50,
  • "amount_due_detail": {
    },
  • "next_due_date": "2018-01-02T19:42:32.987Z",
  • "grace_period": 25,
  • "late_payment_grace_period": 3,
  • "delinquency_grace_period": 3
}

Update card credit settings

This API is used to update credit settings of a specific card.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the card.

Request Body schema: application/json
required
statement_on
number <integer> [ 1 .. 28 ]

Statement day of the month.

grace_period
number <integer> [ 1 .. 27 ]

This field defines the number of days to add in the billing date to calculate the due date of a billing cycle.

late_payment_grace_period
number <integer> [ 1 .. 5 ]

The period of time granted by a financial institution during which a borrower or debtor can make a payment after the due date without late fee.

delinquency_grace_period
number <integer> [ 1 .. 5 ]

The specified period of time granted by a financial institution during which a borrower or debtor can make a payment after the due date without having an impact on their credit score and other punitive actions.

Responses

Request samples

Content type
application/json
{
  • "statement_on": 25,
  • "grace_period": 25,
  • "late_payment_grace_period": 3,
  • "delinquency_grace_period": 3
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "statement_on": 25,
  • "payment_due_on": 27,
  • "delinquency_period_passed": 28,
  • "last_notification_sent": "Sent",
  • "amount_due": 50,
  • "amount_due_detail": {
    },
  • "next_due_date": "2018-01-02T19:42:32.987Z",
  • "grace_period": 25,
  • "late_payment_grace_period": 3,
  • "delinquency_grace_period": 3
}

Set velocity limits for card

This API is used to set velocity limits for a specific card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier or the proxy number of the card.

Request Body schema: application/json
required
ids
Array of strings

Velocity limits IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "velocitylimit02"
]

Remove velocity limits for card

This API is used to remove velocity limits from a specific card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier or the proxy number of the card.

Request Body schema: application/json
required
ids
Array of strings

Velocity limits IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "velocitylimit02"
]

Get velocity limits linked to card

This API is used to retrieve the list of velocity limits linked to a specific card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier or the proxy number of the card.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "velocitylimit02"
]

Get advanced velocity limits linked to card

This API is used to retrieve the list of advanced velocity limits linked to a specific card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier or the proxy number of the card.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • "advancedlimit04"
]

Link advanced velocity limits to card

This API is used to link an array of advanced velocity limits to a specific card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the card.

Request Body schema: application/json
required

The advanced velocity limit ID list to be linked with the card.

ids
Array of strings

Velocity limits IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "advancedlimit04"
]

Unlink advanced velocity limits from card

This API is used to unlink an array of advanced velocity limits from a specific card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the card.

Request Body schema: application/json
required

The advanced velocity limit ID list to be unlinked from the card.

ids
Array of strings

Velocity limits IDs.

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
[
  • "advancedlimit04"
]

Link allowed merchants to card

This API is used to link allowed merchants to card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the card.

Request Body schema: application/json
required

Allowed merchants ID to be linked to the card.

merchant_list_id
required
string

Merchant list identifier.

Responses

Request samples

Content type
application/json
{
  • "merchant_list_id": "d089a80f-e641-4045-8a80-54841e4a7459"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "allowed_merchants_id": "1136545698"
}

Unlink allowed merchants from card

This API is used to unlink allowed merchants from card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the card.

Request Body schema: application/json
required

Allowed merchants ID to be unlinked from the card.

merchant_list_id
required
string

Merchant list identifier.

Responses

Request samples

Content type
application/json
{
  • "merchant_list_id": "d089a80f-e641-4045-8a80-54841e4a7459"
}

Get allowed merchants linked to card

This API is used to get allowed merchants linked to card.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the card.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "allowed_merchants_id": "1136545698"
}

Card Bulk Issuances

Nymcard offers the possibility to create cards in bulk by providing the card product and the number of cards to be created in that bulk request. 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, and created cards will have this value as the initial amount. 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.

List all bulk issuance card requests

This API is used to retrieve all the existing bulk issuance card requests.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "MjAyMS0wMy0yOVQxNToyMjo1Mi40NDJa",
  • "has_more": true,
  • "data": [
    ]
}

Create bulk issuance card request

This API is used to create more than one non-personalized physical cards in a single request.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the bulk issuance card request. If you do not include a token, the system generates one automatically. This token is necessary for use in other API calls and this value cannot be updated.

card_product_id
required
string <= 36 characters

ID of a card product for which card will be created.

number_of_cards
required
integer <int32> [ 0 .. 5000 ]

Number of cards to create. Can be 0 only for draft bulk issuance to create an open bulk card order. The maximum amount is up to 5000 cards.

amount
number <decimal> [ 0 .. 999999999.99 ]

The amount which shall be preloaded on card. If set, then currency is required.

currency
string^[A-Z]{3}$

3-letter ISO_4217 code representing the currency. If set, then amount is required.

name_on_card
string <= 20 characters

Name on card to be printed. For example, GIFT CARD, DRIVER CARD, TRAVEL CARD etc.. If not provided, then name from the product definition will be taken.

card_validity_term
integer <int32> [ 1 .. 99 ]

Number of months of expiry. If not provided, then value from the product definition will be taken.

status
string (CardBulkIssuanceStatusCreateRequest)
Enum: "DRAFT" "SUBMITTED"

Status of bulk issuance request.

object (CardShippingDetails)

Details of card shipping destination.

dry_run
boolean
Default: false

This field value decides whether to create a resource or not after performing all necessary operations. Applicable values for this field are true/false and the default value is false.

extra_embossing_line
string <= 20 characters ^[a-zA-Z0-9\s]+$

Extra embossing line.

card_type
string (CardType)
Enum: "PHYSICAL" "VIRTUAL"

The type of the card. Supported values are physical and virtual.

Responses

Request samples

Content type
application/json
{
  • "id": "2ca78c19-5a4e-4123-a069-6d84f6aa1b54",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "number_of_cards": 1000,
  • "amount": 100,
  • "currency": "USD",
  • "name_on_card": "Gift Card",
  • "card_validity_term": 36,
  • "status": "DRAFT",
  • "shipping_details": {
    },
  • "dry_run": false,
  • "extra_embossing_line": "CLASSIC",
  • "card_type": "PHYSICAL"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "2ca78c19-5a4e-4123-a069-6d84f6aa1b54",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "number_of_cards": 1000,
  • "amount": 123.45,
  • "currency": "USD",
  • "name_on_card": "Diamond Card",
  • "card_validity_term": 36,
  • "status": "DRAFT",
  • "shipping_details": {
    },
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "extra_embossing_line": "CLASSIC"
}

Get specific bulk issuance card request

This API is used to retrieve a specific bulk issuance card request.

Authorizations:
apikey
path Parameters
id
required
string
Example: 639d0cb5-45df-4898-903b-dbaa389224bf

The unique identifier of the bulk issuance card request. This identified is required in this API to retrieve the specific bulk issuance cards details.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "2ca78c19-5a4e-4123-a069-6d84f6aa1b54",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "number_of_cards": 1000,
  • "amount": 123.45,
  • "currency": "USD",
  • "name_on_card": "Diamond Card",
  • "card_validity_term": 36,
  • "status": "DRAFT",
  • "shipping_details": {
    },
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "extra_embossing_line": "CLASSIC",
  • "card_type": "PHYSICAL"
}

Update bulk issuance card request

This API is used to update a specific bulk issuance card request.

Authorizations:
apikey
path Parameters
id
required
string
Example: 639d0cb5-45df-4898-903b-dbaa389224bf

The unique identifier of the bulk issuance card. This identifier is required in this API to update the existing bulk issuance request details.

Request Body schema: application/json
required
card_product_id
string <= 36 characters

The unique identifier of the card product. This token id is referred to as an existing card product. The cards in bulk creating with this card product token will inherit all of its characteristics.

number_of_cards
integer <int32> [ 0 .. 5000 ]

Number of cards to create. The maximum amount is up to 5000 cards. Can be zero for an open bulk card order. Submitted card bulk issuance request must have 'number of cards' higher than 0, or it must have at least 1 personalized card in the card bulk issuance request.

amount
number <decimal> [ 0 .. 999999999.99 ]

The amount which shall be preloaded on card. If set, then currency is required.

currency
string^[A-Z]{3}$

3-letter ISO_4217 code representing the currency. If set, then amount is required.

name_on_card
string <= 20 characters

Name on card to be printed. For example, GIFT CARD, DRIVER CARD, TRAVEL CARD etc.. If not provided, then name from the product definition will be taken.

card_validity_term
integer <int32> [ 1 .. 99 ]

Number of months of expiry. If not provided, then value from the product definition will be taken.

status
string (CardBulkIssuanceStatusUpdateRequest)
Default: "SUBMITTED"
Enum: "SUBMITTED" "CANCELLED"

Status of bulk issuance request. Default status is 'SUBMITTED'.

object (CardShippingDetails)

Details of card shipping destination.

extra_embossing_line
string <= 20 characters ^[a-zA-Z0-9\s]+$

Extra embossing line.

card_type
string (CardType)
Enum: "PHYSICAL" "VIRTUAL"

The type of the card. Supported values are physical and virtual.

Responses

Request samples

Content type
application/json
{
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "number_of_cards": 1000,
  • "amount": 123.45,
  • "currency": "USD",
  • "name_on_card": "Diamond Card",
  • "card_validity_term": 36,
  • "status": "SUBMITTED",
  • "shipping_details": {
    },
  • "extra_embossing_line": "CLASSIC",
  • "card_type": "PHYSICAL"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "2ca78c19-5a4e-4123-a069-6d84f6aa1b54",
  • "card_product_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "number_of_cards": 1000,
  • "amount": 123.45,
  • "currency": "USD",
  • "name_on_card": "Diamond Card",
  • "card_validity_term": 36,
  • "status": "SUBMITTED",
  • "shipping_details": {
    },
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "extra_embossing_line": "CLASSIC"
}

Velocity Limits

The velocity limit defines the cumulative amount and the number of transactions that can be performed within a period of time which can be daily, monthly, yearly, or for the lifetime. The calculation of period (daily, monthly, yearly, lifetime) is based on the local time of the tenant which can be identified using the time zone offset defined in the tenant settings. Another variation of the velocity limit is the per transaction amount limit. The per transaction amount limit gives the maximum amount or minimum amount (or both) a single transaction can have. Frequency is irrelevant in case of per transaction amount limit. Note, that 'type' = PER_TRANSACTION and PER_USER work well with all 'transaction_scope' values. But 'type' = PER_CARD works well only with 'transaction_scope' = WITHDRAWALS, PURCHASES, PURCHASES_CONTACTLESS_NO_PIN, QUASHI_CASH, SCHEME_CREDITS, SCHEME_ACCOUNT_FUNDING. And 'type' = PER_ACCOUNT works well only with 'transaction_scope' = INCOMING_TRANSFERS, OUTGOING_TRANSFERS, LOADS, UNLOADS.

Create velocity limit

This API is used to create a velocity limit.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the velocity limit. If this information is not present in the request, the system generates one automatically.

description
required
string <= 40 characters

The name of the velocity limit. We recommend using a unique string.

active
boolean

This parameter defines whether the velocity limits are going to be activated or not at the time of its creation. By default the velocity limit is activated on its creation.

type
required
string (VelocityLimitType)
Enum: "PER_TRANSACTION" "PER_CARD" "PER_ACCOUNT" "PER_USER"

Type of velocity limit.

min_amount
number <decimal> [ 0 .. 999999999.99 ]

The minimum amount of a transaction. The transaction amount can not be lesser than the amount defined here.

max_amount
number <decimal> [ 0 .. 999999999.99 ]

The maximum amount of a transaction. The transaction amount can not be greater than the amount defined here.

currency
required
string <iso-4217> ^[A-Z]{3}$

3-letter ISO_4217 code representing the currency.

frequency
integer [ 0 .. 999999999 ]

It restricts a number of transactions a user can perform within a specified period of time.

period
string (Period)
Enum: "DAILY" "MONTHLY" "YEARLY" "ALL_TIME" "NUM_OF_DAYS"

It specifies the time period of the velocity limit for the transaction frequency.

num_of_days
integer [ 0 .. 999999999 ]

During transaction, it will bring the transaction data starting from the ‘currentDay - numberOfDays’ and apply the limit accordingly. This field will only be used when ‘period’ = ‘NUM_OF_DAYS’.

transaction_scope
required
Array of strings (TransactionScope) non-empty
Items Enum: "WITHDRAWALS" "PURCHASES" "OUTGOING_TRANSFERS" "UNLOADS" "SCHEME_ACCOUNT_FUNDING" "QUASI_CASH" "PURCHASES_CONTACTLESS_NO_PIN" "LOADS" "INCOMING_TRANSFERS" "SCHEME_CREDITS" "INITIAL_LOAD"

This parameter is to define a transaction scope for this velocity limit.

channel_scope
string (ChannelScopeValues)
Enum: "VISA" "MASTERCARD" "WESTERNUNION"

This parameter is used to create a velocity limit for the channels defined in the system.

Responses

Request samples

Content type
application/json
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the velocity Limit",
  • "active": true,
  • "type": "PER_TRANSACTION",
  • "min_amount": 1500.1,
  • "max_amount": 1500.1,
  • "currency": "EUR",
  • "frequency": 999999999,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "transaction_scope": [
    ],
  • "channel_scope": "VISA"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the velocity Limit",
  • "active": true,
  • "type": "PER_TRANSACTION",
  • "min_amount": 100,
  • "max_amount": 1000,
  • "currency": "EUR",
  • "frequency": 0,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "transaction_scope": [
    ],
  • "channel_scope": "VISA",
  • "program_level": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get list of all velocity limits

This API is used to get the list of all velocity limits.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "has_more": true,
  • "data": [
    ]
}

Update velocity limit

This API is used to update parameters of a specific velocity limit.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the velocity limit. This token id is referred to as an existing velocity limit.

Request Body schema: application/json
required
description
string <= 40 characters

Velocity limit description

active
boolean

This parameter describes if velocity limit is activated or not.

type
string (VelocityLimitType)
Enum: "PER_TRANSACTION" "PER_CARD" "PER_ACCOUNT" "PER_USER"

Type of velocity limit.

min_amount
number <decimal> [ 0 .. 999999999.99 ]

The minimum amount of a transaction. The transaction amount can not be lesser than the amount defined here.

max_amount
number <decimal> [ 0 .. 999999999.99 ]

The maximum amount of a transaction. The transaction amount can not be greater than the amount defined here.

currency
string <iso-4217> ^[A-Z]{3}$

3-letter ISO_4217 code representing the currency

frequency
integer [ 0 .. 999999999 ]

It restricts a number of transactions a user can perform within a specified period of time.

period
string (Period)
Enum: "DAILY" "MONTHLY" "YEARLY" "ALL_TIME" "NUM_OF_DAYS"

It specifies the time period of the velocity limit for the transaction frequency.

num_of_days
integer [ 0 .. 999999999 ]

During transaction, it will bring the transaction data starting from the ‘currentDay - numberOfDays’ and apply the limit accordingly. This field will only be used when ‘period’ = ‘NUM_OF_DAYS’’

transaction_scope
Array of strings (TransactionScope) non-empty
Items Enum: "WITHDRAWALS" "PURCHASES" "OUTGOING_TRANSFERS" "UNLOADS" "SCHEME_ACCOUNT_FUNDING" "QUASI_CASH" "PURCHASES_CONTACTLESS_NO_PIN" "LOADS" "INCOMING_TRANSFERS" "SCHEME_CREDITS" "INITIAL_LOAD"

This parameter array contains the transaction scope for this velocity limit.

channel_scope
string (ChannelScopeValues)
Enum: "VISA" "MASTERCARD" "WESTERNUNION"

This parameter is used to create a velocity limit for the channels defined in the system.

Responses

Request samples

Content type
application/json
{
  • "description": "Some description of the velocity Limit",
  • "active": true,
  • "type": "PER_TRANSACTION",
  • "min_amount": 1500.1,
  • "max_amount": 1500.1,
  • "currency": "EUR",
  • "frequency": 999999999,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "transaction_scope": [
    ],
  • "channel_scope": "VISA"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the velocity Limit",
  • "active": true,
  • "type": "PER_TRANSACTION",
  • "min_amount": 100,
  • "max_amount": 1000,
  • "currency": "EUR",
  • "frequency": 0,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "transaction_scope": [
    ],
  • "channel_scope": "VISA",
  • "program_level": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get velocity limit

This API is used to return a specific velocity limit using its ID.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the velocity limit. This token id is referred to as an existing velocity limit.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the velocity Limit",
  • "active": true,
  • "type": "PER_TRANSACTION",
  • "min_amount": 100,
  • "max_amount": 1000,
  • "currency": "EUR",
  • "frequency": 0,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "transaction_scope": [
    ],
  • "channel_scope": "VISA",
  • "program_level": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Advanced velocity limits

This section contains advanced velocity limits APIs.

Create advanced velocity limit

This API is used to create an advanced velocity limit.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

Unique ID for the advanced velocity limit.

name
required
string [ 1 .. 100 ] characters

The name of advanced velocity limit.

type
required
string (AdvancedVelocityLimitType)
Enum: "PER_CARD" "PER_ACCOUNT" "PER_USER"

Type of advanced velocity limit.

description
string [ 1 .. 400 ] characters

The additional information.

currency
required
string <iso-4217> ^[A-Z]{3}$

3-letter ISO_4217 code representing the currency.

transaction_scope
required
Array of strings (TransactionScope)
Items Enum: "WITHDRAWALS" "PURCHASES" "OUTGOING_TRANSFERS" "UNLOADS" "SCHEME_ACCOUNT_FUNDING" "QUASI_CASH" "PURCHASES_CONTACTLESS_NO_PIN" "LOADS" "INCOMING_TRANSFERS" "SCHEME_CREDITS" "INITIAL_LOAD"

The transaction scope.

active
boolean
Default: true

This parameter describes if advanced velocity limit is activated or not.

object (PerTransaction)

This parameter defines the per transaction limit. The fields defined under this parameter will be applied only on the single transaction.

amount
number <decimal> [ 0 .. 999999999.99 ]

The maximum amount of a transaction. The transaction amount can not be greater than the amount defined here.

frequency
integer [ 0 .. 999999999 ]

It restricts a number of transactions a user can perform within a specified period of time.

period
string (AdvancedVelocityLimitPeriod)
Enum: "DAILY" "WEEKLY" "MONTHLY" "YEARLY" "ALL_TIME" "NUM_OF_DAYS"

It specifies the time period of the advanced velocity limit for the transaction frequency.

num_of_days
integer [ 0 .. 999999999 ]

During transaction, it will bring the transaction data starting from the ‘currentDay - numberOfDays’ and apply the limit accordingly. This field will only be used when ‘period’ = ‘num_of_days’

effective_from
string <date-time>

The date and time from which the limit is effective.

effective_to
string <date-time>
Default: "2099-12-31T11:59:59.999Z"

The date and time to which the limit is effective.

Array of objects (Conditions)

An array of conditions.

group
string (Group)
Enum: "SINGLE" "AGGREGATE"

The advanced velocity limit group.

Responses

Request samples

Content type
application/json
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "name": "limit1",
  • "type": "PER_CARD",
  • "description": "Some description",
  • "currency": "EUR",
  • "transaction_scope": [
    ],
  • "active": true,
  • "per_transaction": {
    },
  • "amount": 1500.1,
  • "frequency": 999999999,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "effective_from": "2018-01-02T19:42:32.987Z",
  • "effective_to": "2018-01-02T19:42:32.987Z",
  • "conditions": [
    ],
  • "group": "SINGLE"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "name": "limit1",
  • "type": "PER_CARD",
  • "description": "Some description",
  • "currency": "EUR",
  • "transaction_scope": [
    ],
  • "active": true,
  • "per_transaction": {
    },
  • "amount": 1500.1,
  • "frequency": 999999999,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "effective_from": "2018-01-02T19:42:32.987Z",
  • "effective_to": "2018-01-02T19:42:32.987Z",
  • "program_level": false,
  • "conditions": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "group": "SINGLE"
}

Get list of advanced velocity limits

This API is used to retrieve a list of advanced velocity limits.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get specific advanced velocity limit

This API is used to retrieve details of specific advanced velocity limit.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the advanced velocity limit.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "name": "limit1",
  • "type": "PER_CARD",
  • "description": "Some description",
  • "currency": "EUR",
  • "transaction_scope": [
    ],
  • "active": true,
  • "per_transaction": {
    },
  • "amount": 1500.1,
  • "frequency": 999999999,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "effective_from": "2018-01-02T19:42:32.987Z",
  • "effective_to": "2018-01-02T19:42:32.987Z",
  • "program_level": false,
  • "conditions": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "group": "SINGLE"
}

Update advanced velocity limit

This API is used to update specific advanced velocity limit.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the advanced velocity limit.

Request Body schema: application/json
required
name
string [ 1 .. 100 ] characters

The name of advanced velocity limit.

type
string (AdvancedVelocityLimitType)
Enum: "PER_CARD" "PER_ACCOUNT" "PER_USER"

Type of advanced velocity limit.

description
string [ 1 .. 400 ] characters

The additional information.

currency
string <iso-4217> ^[A-Z]{3}$

3-letter ISO_4217 code representing the currency.

transaction_scope
Array of strings (TransactionScope)
Items Enum: "WITHDRAWALS" "PURCHASES" "OUTGOING_TRANSFERS" "UNLOADS" "SCHEME_ACCOUNT_FUNDING" "QUASI_CASH" "PURCHASES_CONTACTLESS_NO_PIN" "LOADS" "INCOMING_TRANSFERS" "SCHEME_CREDITS" "INITIAL_LOAD"

The transaction scope.

active
boolean
Default: true

This parameter describes if advanced velocity limit is activated or not.

object (PerTransaction)

This parameter defines the per transaction limit. The fields defined under this parameter will be applied only on the single transaction.

amount
number <decimal> [ 0 .. 999999999.99 ]

The maximum amount of a transaction. The transaction amount can not be greater than the amount defined here.

frequency
integer [ 0 .. 999999999 ]

It restricts a number of transactions a user can perform within a specified period of time.

period
string (AdvancedVelocityLimitPeriod)
Enum: "DAILY" "WEEKLY" "MONTHLY" "YEARLY" "ALL_TIME" "NUM_OF_DAYS"

It specifies the time period of the advanced velocity limit for the transaction frequency.

num_of_days
integer [ 0 .. 999999999 ]

During transaction, it will bring the transaction data starting from the ‘currentDay - numberOfDays’ and apply the limit accordingly. This field will only be used when ‘period’ = ‘num_of_days’

effective_from
string <date-time>

The date and time from which the limit is effective.

effective_to
string <date-time>

The date and time to which the limit is effective.

Array of objects (Conditions)

An array of conditions.

group
string (Group)
Enum: "SINGLE" "AGGREGATE"

The advanced velocity limit group.

Responses

Request samples

Content type
application/json
{
  • "name": "limit1",
  • "type": "PER_CARD",
  • "description": "Some description",
  • "currency": "EUR",
  • "transaction_scope": [
    ],
  • "active": true,
  • "per_transaction": {
    },
  • "amount": 1500.1,
  • "frequency": 999999999,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "effective_from": "2018-01-02T19:42:32.987Z",
  • "effective_to": "2018-01-02T19:42:32.987Z",
  • "conditions": [
    ],
  • "group": "SINGLE"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "name": "limit1",
  • "type": "PER_CARD",
  • "description": "Some description",
  • "currency": "EUR",
  • "transaction_scope": [
    ],
  • "active": true,
  • "per_transaction": {
    },
  • "amount": 1500.1,
  • "frequency": 999999999,
  • "period": "DAILY",
  • "num_of_days": 15,
  • "effective_from": "2018-01-02T19:42:32.987Z",
  • "effective_to": "2018-01-02T19:42:32.987Z",
  • "program_level": false,
  • "conditions": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "group": "SINGLE"
}

Balance Limits

The balance limit defines the maximum balance or the minimum balance (or both) the account can hold. The balance limit is checked whenever a change in balance is to happen, for instance during scheme authorizations (purchases, withdrawals etc.). The balance limit is checked on an individual account of the user or it is possible to check the balance limit across all the accounts of the user. In order to define the maximum balance limit at tenant level, please approach to your NymCard assigned project manager. Maximum balance limit at tenant level is only applicable at account level and for currency of priority = 1 of the card product.

Create balance limit

This API is used to create a new balance limit.

Authorizations:
apikey
Request Body schema: application/json
required
id
string

The unique identifier of the balance limit. If this information is not present in the request, the system generates one automatically.

description
required
string

The name of the balance limit. We recommend using a unique string.

active
boolean

This parameter defines whether the balance limits are going to be activated or not at the time of its creation. By default the balance limit is activated on its creation.

type
required
string (BalanceLimitType)
Value: "PER_ACCOUNT"

Type of balance limit.

min_amount
required
number <decimal> [ 0 .. 999999999.99 ]

The minimum balance an account can hold.

max_amount
required
number <decimal> [ 0 .. 999999999.99 ]

The maximum balance an account can hold.

currency
required
string <iso-4217> ^[A-Z]{3}$

3-letter ISO_4217 code representing the currency

Responses

Request samples

Content type
application/json
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the balance limit",
  • "active": true,
  • "type": "PER_ACCOUNT",
  • "min_amount": 1500.1,
  • "max_amount": 1500.1,
  • "currency": "EUR"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the balance limit",
  • "active": true,
  • "type": "PER_ACCOUNT",
  • "min_amount": 1500.1,
  • "max_amount": 1500.1,
  • "currency": "EUR",
  • "program_level": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get list of all balance limits

This API is used to get the list of all balance limits.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "has_more": true,
  • "data": [
    ]
}

Update balance limit

This API is used to edit parameters of a specific balance limit.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the balance limit. This token id is referred to as an existing balance limit.

Request Body schema: application/json
required
description
string

The name of the balance limit. We recommend using a unique string.

active
boolean

This parameter defines whether the balance limits are going to be activated or not at the time of its creation. By default the balance limit is activated on its creation.

type
string (BalanceLimitType)
Value: "PER_ACCOUNT"

Type of balance limit.

min_amount
number <decimal> [ 0 .. 999999999.99 ]

The minimum balance an account can hold.

max_amount
number <decimal> [ 0 .. 999999999.99 ]

The maximum balance an account can hold.

currency
string <iso-4217> ^[A-Z]{3}$

3-letter ISO_4217 code representing the currency

Responses

Request samples

Content type
application/json
{
  • "description": "Some description of the balance limit",
  • "active": true,
  • "type": "PER_ACCOUNT",
  • "min_amount": 1500.1,
  • "max_amount": 1500.1,
  • "currency": "EUR"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the balance limit",
  • "active": true,
  • "type": "PER_ACCOUNT",
  • "min_amount": 1500.1,
  • "max_amount": 1500.1,
  • "currency": "EUR",
  • "program_level": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get balance limit

This API is used to return a specific balance limit using its ID.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the balance limit. This token id is referred to as an existing balance limit.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Some description of the balance limit",
  • "active": true,
  • "type": "PER_ACCOUNT",
  • "min_amount": 1500.1,
  • "max_amount": 1500.1,
  • "currency": "EUR",
  • "program_level": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Fees

Our nCore platform supports defining various types of fees charged on transactions and other functions/events. A fee can be linked to one or more card products. We have multiple types of fees, such as flat, percentage, range etc.. Fee can be marked as 'Active/Inactive'. If a fee is marked as 'Inactive' then this fee shall not be charged until it is set to 'Active' again. The applied fee details are recorded with the other transaction details so that complete financial information related to the transaction is available.

Get list of fees

This API is used to get the list of all fees.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "has_more": true,
  • "after": "MjAxOC0wMS0wMlQxOTo0MjozMi45ODda",
  • "data": [
    ]
}

Create fee

This API is used to create a new fee.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the fee. If this information is not present in the request, the system generates one automatically.

description
required
string <= 50 characters

The name of the fee. We recommend using a unique string.

type
required
string (FeeType)
Enum: "FLAT" "PERCENTAGE" "MAX_PERC_OR_FLAT" "MIN_PERC_OR_FLAT" "MAX_PERC_OR_FLAT_W_CAP" "MIN_PERC_OR_FLAT_W_CAP" "RANGE" "RANGE_FLAT" "RANGE_PERCENTAGE" "RANGE_MAX_PERC_OR_FLAT" "RANGE_MIN_PERC_OR_FLAT" "RANGE_MAX_PERC_OR_FLAT_W_CAP" "RANGE_MIN_PERC_OR_FLAT_W_CAP"

Fee types:

  • FLAT: A flat fee refers to a fixed amount a cardholder pays for performing a transaction regardless of a transaction amount.In case of single currency products, the currency of the flat fee is the one supported by the card product.
  • PERCENTAGE: A percentage fee applied on the transaction amount a cardholder pays for performing a transaction. The fee is calculated by applying the percentage to ISO field 6 billing amount coming in authorization from the payment scheme.
  • MAX_PERC_OR_FLAT: A maximum fee selects between an applied percentage fee and flat fee a cardholder pays for performing a transaction.
  • MIN_PERC_OR_FLAT: A minimum fee selects between an applied percentage fee and flat fee a cardholder pays for performing a transaction.
  • MAX_PERC_OR_FLAT_W_CAP: A maximum fee selects between an applied percentage fee and a flat fee. Note that the configured maximum cap limit fee will be applied if the selected fee is greater than the configured cap limit fee.
  • MIN_PERC_OR_FLAT_W_CAP: A minimum fee selects between an applied percentage fee and a flat fee. Note that the configured miminum cap limiy fee will be applied if the selected fee is lesser than the configured cap limit fee.
  • RANGE: Transaction amount based fee slabs where each slab has a configured flat fee or a percentage fee.
  • RANGE_FLAT: Transaction amount based fee slabs where each slab has a configured flat fee.
  • RANGE_PERCENTAGE: Transaction amount based fee slabs where each slab has a configured percentage fee.
  • RANGE_MAX_PERC_OR_FLAT: Transaction amount based fee slabs where each slab has a flat fee and a percentage fee configured and the the maximum fee between the two is applied.
  • RANGE_MIN_PERC_OR_FLAT: Transaction amount based fee slabs where each slab has a flat fee and a percentage fee configured and the the minimum fee between the two is applied.
  • RANGE_MAX_PERC_OR_FLAT_W_CAP: A maximum fee selects between an applied percentage fee and a flat fee based on transaction amount range. Note that the configured maximum cap limit fee will be applied if the selected fee is greater than the configured cap limit fee.
  • RANGE_MIN_PERC_OR_FLAT_W_CAP: A minimum fee selects between an applied percentage fee and a flat fee based on transaction amount range. Note that the configured minimum cap limit fee will be applied if the selected fee is lesser than the configured cap limit fee.
currency
required
string^([\*]{3}|[A-Z]{3})$

Currency code or ***. Value *** is only applicable for transaction types 'PURCHASE_FOREIGN_CURRENCY' and 'WITHDRAWAL_FOREIGN_CURRENCY'.

amount
number [ 0 .. 999999999.99 ]

Fee amount. It is applicable if fee type includes flat option.

percentage
number [ 0 .. 100 ]

Fee percentage. It is applicable if fee type includes percentage option.

Array of objects (Range)

Array of ranges where fee is applicable.

transaction_type
required
string (TransactionType)
Enum: "WITHDRAWALS" "PURCHASES" "BALANCE_INQUIRIES" "TRANSFERS" "LOADS" "UNLOADS" "PURCHASE_FOREIGN_CURRENCY" "WITHDRAWAL_FOREIGN_CURRENCY"

The type of transaction. 'PURCHASE_FOREIGN_CURRENCY' is only applicable to 'PURCHASES' in foreign currencies. 'WITHDRAWAL_FOREIGN_CURRENCY' is only applicable to 'WITHDRAWALS' in foreign currencies.

transaction_origin
string (TransactionOrigin)
Enum: "DOMESTIC" "FOREIGN" "ANY"

Origin of transaction. This field is applicable for transaction types 'WITHDRAWALS', 'PURCHASES', 'PURCHASE_FOREIGN_CURRENCY' and 'WITHDRAWAL_FOREIGN_CURRENCY'.

source_channel
string (SourceChannel)
Enum: "ANY" "MPGS" "DAPI" "LEAN"

Type of source channel only applicable for transaction_type = TRANSFERS. Default value is "ANY".

Responses

Request samples

Content type
application/json
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Withdrawal Fee",
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "transaction_type": "WITHDRAWALS",
  • "transaction_origin": "DOMESTIC",
  • "source_channel": "ANY"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Withdrawal Fee",
  • "active": true,
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "transaction_type": "WITHDRAWALS",
  • "transaction_origin": "DOMESTIC",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "source_channel": "ANY"
}

Get a specific fee

This API is used to return a specific fee using its ID.

Authorizations:
apikey
path Parameters
fee_id
required
string

The unique identifier of the fee. This token id is referred to as an existing fee.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Withdrawal Fee",
  • "active": true,
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "transaction_type": "WITHDRAWALS",
  • "transaction_origin": "DOMESTIC",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "source_channel": "ANY"
}

Update fee

This API is used to update parameters of a specific fee.

Authorizations:
apikey
path Parameters
fee_id
required
string

The unique identifier of the fee. This token id is referred to as an existing fee.

Request Body schema: application/json
required
description
string <= 50 characters

Fee description.

active
boolean

Fee status.

type
string (FeeType)
Enum: "FLAT" "PERCENTAGE" "MAX_PERC_OR_FLAT" "MIN_PERC_OR_FLAT" "MAX_PERC_OR_FLAT_W_CAP" "MIN_PERC_OR_FLAT_W_CAP" "RANGE" "RANGE_FLAT" "RANGE_PERCENTAGE" "RANGE_MAX_PERC_OR_FLAT" "RANGE_MIN_PERC_OR_FLAT" "RANGE_MAX_PERC_OR_FLAT_W_CAP" "RANGE_MIN_PERC_OR_FLAT_W_CAP"

Fee types:

  • FLAT: A flat fee refers to a fixed amount a cardholder pays for performing a transaction regardless of a transaction amount.In case of single currency products, the currency of the flat fee is the one supported by the card product.
  • PERCENTAGE: A percentage fee applied on the transaction amount a cardholder pays for performing a transaction. The fee is calculated by applying the percentage to ISO field 6 billing amount coming in authorization from the payment scheme.
  • MAX_PERC_OR_FLAT: A maximum fee selects between an applied percentage fee and flat fee a cardholder pays for performing a transaction.
  • MIN_PERC_OR_FLAT: A minimum fee selects between an applied percentage fee and flat fee a cardholder pays for performing a transaction.
  • MAX_PERC_OR_FLAT_W_CAP: A maximum fee selects between an applied percentage fee and a flat fee. Note that the configured maximum cap limit fee will be applied if the selected fee is greater than the configured cap limit fee.
  • MIN_PERC_OR_FLAT_W_CAP: A minimum fee selects between an applied percentage fee and a flat fee. Note that the configured miminum cap limiy fee will be applied if the selected fee is lesser than the configured cap limit fee.
  • RANGE: Transaction amount based fee slabs where each slab has a configured flat fee or a percentage fee.
  • RANGE_FLAT: Transaction amount based fee slabs where each slab has a configured flat fee.
  • RANGE_PERCENTAGE: Transaction amount based fee slabs where each slab has a configured percentage fee.
  • RANGE_MAX_PERC_OR_FLAT: Transaction amount based fee slabs where each slab has a flat fee and a percentage fee configured and the the maximum fee between the two is applied.
  • RANGE_MIN_PERC_OR_FLAT: Transaction amount based fee slabs where each slab has a flat fee and a percentage fee configured and the the minimum fee between the two is applied.
  • RANGE_MAX_PERC_OR_FLAT_W_CAP: A maximum fee selects between an applied percentage fee and a flat fee based on transaction amount range. Note that the configured maximum cap limit fee will be applied if the selected fee is greater than the configured cap limit fee.
  • RANGE_MIN_PERC_OR_FLAT_W_CAP: A minimum fee selects between an applied percentage fee and a flat fee based on transaction amount range. Note that the configured minimum cap limit fee will be applied if the selected fee is lesser than the configured cap limit fee.
currency
string^([\*]{3}|[A-Z]{3})$

Currency code or ***. Value *** is only applicable for transaction types 'PURCHASE_FOREIGN_CURRENCY' and 'WITHDRAWAL_FOREIGN_CURRENCY'.

amount
number [ 0 .. 999999999.99 ]

Fee amount. It is applicable if fee type includes flat option.

percentage
number [ 0 .. 100 ]

Fee percentage. It is applicable if fee type includes percentage option.

Array of objects (Range)

Array of ranges where fee is applicable.

transaction_type
string (TransactionType)
Enum: "WITHDRAWALS" "PURCHASES" "BALANCE_INQUIRIES" "TRANSFERS" "LOADS" "UNLOADS" "PURCHASE_FOREIGN_CURRENCY" "WITHDRAWAL_FOREIGN_CURRENCY"

The type of transaction. 'PURCHASE_FOREIGN_CURRENCY' is only applicable to 'PURCHASES' in foreign currencies. 'WITHDRAWAL_FOREIGN_CURRENCY' is only applicable to 'WITHDRAWALS' in foreign currencies.

transaction_origin
string (TransactionOrigin)
Enum: "DOMESTIC" "FOREIGN" "ANY"

Origin of transaction. This field is applicable for transaction types 'WITHDRAWALS', 'PURCHASES', 'PURCHASE_FOREIGN_CURRENCY' and 'WITHDRAWAL_FOREIGN_CURRENCY'.

source_channel
string (SourceChannel)
Enum: "ANY" "MPGS" "DAPI" "LEAN"

Type of source channel only applicable for transaction_type = TRANSFERS. Default value is "ANY".

Responses

Request samples

Content type
application/json
{
  • "description": "Withdrawal Fee",
  • "active": true,
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "transaction_type": "WITHDRAWALS",
  • "transaction_origin": "DOMESTIC",
  • "source_channel": "ANY"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "description": "Withdrawal Fee",
  • "active": true,
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "transaction_type": "WITHDRAWALS",
  • "transaction_origin": "DOMESTIC",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "source_channel": "ANY"
}

Advanced Fees

These APIs allows you to configure fees along with the dynamic conditions.

Get list of advanced fees

This API is used to get the list of all advanced fees.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "has_more": true,
  • "after": "string",
  • "data": [
    ]
}

Create advanced fee

This API is used to create a new advanced fee.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the advanced fee.

name
required
string <= 100 characters

Advanced fee name.

type
required
string (FeeType)
Enum: "FLAT" "PERCENTAGE" "MAX_PERC_OR_FLAT" "MIN_PERC_OR_FLAT" "MAX_PERC_OR_FLAT_W_CAP" "MIN_PERC_OR_FLAT_W_CAP" "RANGE" "RANGE_FLAT" "RANGE_PERCENTAGE" "RANGE_MAX_PERC_OR_FLAT" "RANGE_MIN_PERC_OR_FLAT" "RANGE_MAX_PERC_OR_FLAT_W_CAP" "RANGE_MIN_PERC_OR_FLAT_W_CAP"

Fee types:

  • FLAT: A flat fee refers to a fixed amount a cardholder pays for performing a transaction regardless of a transaction amount.In case of single currency products, the currency of the flat fee is the one supported by the card product.
  • PERCENTAGE: A percentage fee applied on the transaction amount a cardholder pays for performing a transaction. The fee is calculated by applying the percentage to ISO field 6 billing amount coming in authorization from the payment scheme.
  • MAX_PERC_OR_FLAT: A maximum fee selects between an applied percentage fee and flat fee a cardholder pays for performing a transaction.
  • MIN_PERC_OR_FLAT: A minimum fee selects between an applied percentage fee and flat fee a cardholder pays for performing a transaction.
  • MAX_PERC_OR_FLAT_W_CAP: A maximum fee selects between an applied percentage fee and a flat fee. Note that the configured maximum cap limit fee will be applied if the selected fee is greater than the configured cap limit fee.
  • MIN_PERC_OR_FLAT_W_CAP: A minimum fee selects between an applied percentage fee and a flat fee. Note that the configured miminum cap limiy fee will be applied if the selected fee is lesser than the configured cap limit fee.
  • RANGE: Transaction amount based fee slabs where each slab has a configured flat fee or a percentage fee.
  • RANGE_FLAT: Transaction amount based fee slabs where each slab has a configured flat fee.
  • RANGE_PERCENTAGE: Transaction amount based fee slabs where each slab has a configured percentage fee.
  • RANGE_MAX_PERC_OR_FLAT: Transaction amount based fee slabs where each slab has a flat fee and a percentage fee configured and the the maximum fee between the two is applied.
  • RANGE_MIN_PERC_OR_FLAT: Transaction amount based fee slabs where each slab has a flat fee and a percentage fee configured and the the minimum fee between the two is applied.
  • RANGE_MAX_PERC_OR_FLAT_W_CAP: A maximum fee selects between an applied percentage fee and a flat fee based on transaction amount range. Note that the configured maximum cap limit fee will be applied if the selected fee is greater than the configured cap limit fee.
  • RANGE_MIN_PERC_OR_FLAT_W_CAP: A minimum fee selects between an applied percentage fee and a flat fee based on transaction amount range. Note that the configured minimum cap limit fee will be applied if the selected fee is lesser than the configured cap limit fee.
description
required
string <= 400 characters

Fee description.

currency
required
string^([\*]{3}|[A-Z]{3})$

Currency code or ***. *** is applicable for transaction types PURCHASE_FOREIGN_CURRENCY, WITHDRAWAL_FOREIGN_CURRENCY

transaction_type
required
string (AdvancedTransactionTypeValue)
Enum: "WITHDRAWALS" "PURCHASES" "BALANCE_INQUIRIES" "TRANSFERS" "LOADS" "UNLOADS" "OUTGOING_TRANSFERS" "INCOMING_TRANSFERS" "SCHEME_ACCOUNT_FUNDING" "SCHEME_CREDITS" "QUASI_CASH" "PURCHASES_CONTACTLESS_NO_PIN"

Advanced transaction type.

active
boolean

Fee status (whether it is active or not). Default value is "true".

amount
number [ 0 .. 999999999.99 ]

Fee amount (applicable if fee type includes flat option).

percentage
number [ 0 .. 100 ]

Fee percentage (applicable if fee type includes percentage option).

Array of objects (Range)

An array of ranges where fee is applicable.

Array of objects (AdvancedCondition)

An array of conditions.

enforce_this_fee
boolean

When true, this fee takes priority over other matching fees: if multiple fees are fetched for a transaction and at least one has enforce_this_fee = true, only fee(s) with enforce_this_fee = true are applied and the rest are skipped. If all fetched fees have enforce_this_fee = false or null, all of them are applied (current behaviour). A null value is treated as false. Default value is "false".

is_forex_fee
boolean

Indicates whether fee is a forex fee.

Responses

Request samples

Content type
application/json
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "name": "withdrawal-fee",
  • "type": "FLAT",
  • "description": "Withdrawal Fee",
  • "currency": "USD",
  • "transaction_type": "WITHDRAWALS",
  • "active": true,
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "conditions": [
    ],
  • "enforce_this_fee": true,
  • "is_forex_fee": true
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "name": "withdrawal-fee",
  • "type": "FLAT",
  • "description": "Withdrawal Fee",
  • "currency": "USD",
  • "transaction_type": "WITHDRAWALS",
  • "active": true,
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "conditions": [
    ],
  • "enforce_this_fee": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "is_forex_fee": true
}

Get specific advanced fee

This API is used to return a specific advanced fee using its ID.

Authorizations:
apikey
path Parameters
fee_id
required
string

The unique identifier of the advanced fee. This token ID is referred to as an existing advanced fee.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "name": "withdrawal-fee",
  • "type": "FLAT",
  • "description": "Withdrawal Fee",
  • "currency": "USD",
  • "transaction_type": "WITHDRAWALS",
  • "active": true,
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "conditions": [
    ],
  • "enforce_this_fee": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "is_forex_fee": true
}

Update advanced fee

This API is used to update parameters of a specific advanced fee.

Authorizations:
apikey
path Parameters
fee_id
required
string

The unique identifier of the advanced fee. This token ID is referred to as an existing advanced fee.

Request Body schema: application/json
required
name
string <= 100 characters

Unique advanced fee name.

type
string (FeeType)
Enum: "FLAT" "PERCENTAGE" "MAX_PERC_OR_FLAT" "MIN_PERC_OR_FLAT" "MAX_PERC_OR_FLAT_W_CAP" "MIN_PERC_OR_FLAT_W_CAP" "RANGE" "RANGE_FLAT" "RANGE_PERCENTAGE" "RANGE_MAX_PERC_OR_FLAT" "RANGE_MIN_PERC_OR_FLAT" "RANGE_MAX_PERC_OR_FLAT_W_CAP" "RANGE_MIN_PERC_OR_FLAT_W_CAP"

Fee types:

  • FLAT: A flat fee refers to a fixed amount a cardholder pays for performing a transaction regardless of a transaction amount.In case of single currency products, the currency of the flat fee is the one supported by the card product.
  • PERCENTAGE: A percentage fee applied on the transaction amount a cardholder pays for performing a transaction. The fee is calculated by applying the percentage to ISO field 6 billing amount coming in authorization from the payment scheme.
  • MAX_PERC_OR_FLAT: A maximum fee selects between an applied percentage fee and flat fee a cardholder pays for performing a transaction.
  • MIN_PERC_OR_FLAT: A minimum fee selects between an applied percentage fee and flat fee a cardholder pays for performing a transaction.
  • MAX_PERC_OR_FLAT_W_CAP: A maximum fee selects between an applied percentage fee and a flat fee. Note that the configured maximum cap limit fee will be applied if the selected fee is greater than the configured cap limit fee.
  • MIN_PERC_OR_FLAT_W_CAP: A minimum fee selects between an applied percentage fee and a flat fee. Note that the configured miminum cap limiy fee will be applied if the selected fee is lesser than the configured cap limit fee.
  • RANGE: Transaction amount based fee slabs where each slab has a configured flat fee or a percentage fee.
  • RANGE_FLAT: Transaction amount based fee slabs where each slab has a configured flat fee.
  • RANGE_PERCENTAGE: Transaction amount based fee slabs where each slab has a configured percentage fee.
  • RANGE_MAX_PERC_OR_FLAT: Transaction amount based fee slabs where each slab has a flat fee and a percentage fee configured and the the maximum fee between the two is applied.
  • RANGE_MIN_PERC_OR_FLAT: Transaction amount based fee slabs where each slab has a flat fee and a percentage fee configured and the the minimum fee between the two is applied.
  • RANGE_MAX_PERC_OR_FLAT_W_CAP: A maximum fee selects between an applied percentage fee and a flat fee based on transaction amount range. Note that the configured maximum cap limit fee will be applied if the selected fee is greater than the configured cap limit fee.
  • RANGE_MIN_PERC_OR_FLAT_W_CAP: A minimum fee selects between an applied percentage fee and a flat fee based on transaction amount range. Note that the configured minimum cap limit fee will be applied if the selected fee is lesser than the configured cap limit fee.
description
string <= 400 characters

Fee description.

currency
string^([\*]{3}|[A-Z]{3})$

Currency code or ***. *** is applicable for transaction types PURCHASE_FOREIGN_CURRENCY, WITHDRAWAL_FOREIGN_CURRENCY

transaction_type
string (AdvancedTransactionTypeValue)
Enum: "WITHDRAWALS" "PURCHASES" "BALANCE_INQUIRIES" "TRANSFERS" "LOADS" "UNLOADS" "OUTGOING_TRANSFERS" "INCOMING_TRANSFERS" "SCHEME_ACCOUNT_FUNDING" "SCHEME_CREDITS" "QUASI_CASH" "PURCHASES_CONTACTLESS_NO_PIN"

Advanced transaction type.

active
boolean

Fee status (whether it is active or not). Default value is "true".

amount
number [ 0 .. 999999999.99 ]

Fee amount (applicable if fee type includes flat option).

percentage
number [ 0 .. 100 ]

Fee percentage (applicable if fee type includes percentage option).

Array of objects (Range)

An array of ranges where fee is applicable.

Array of objects (AdvancedCondition)

An array of conditions.

enforce_this_fee
boolean

When true, this fee takes priority over other matching fees: if multiple fees are fetched for a transaction and at least one has enforce_this_fee = true, only fee(s) with enforce_this_fee = true are applied and the rest are skipped. If all fetched fees have enforce_this_fee = false or null, all of them are applied (current behaviour). A null value is treated as false.

is_forex_fee
boolean

Indicates whether fee is a forex fee.

Responses

Request samples

Content type
application/json
{
  • "name": "withdrawal-fee",
  • "type": "FLAT",
  • "description": "Withdrawal Fee",
  • "currency": "USD",
  • "transaction_type": "WITHDRAWALS",
  • "active": true,
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "conditions": [
    ],
  • "enforce_this_fee": true,
  • "is_forex_fee": true
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "name": "withdrawal-fee",
  • "type": "FLAT",
  • "description": "Withdrawal Fee",
  • "currency": "USD",
  • "transaction_type": "WITHDRAWALS",
  • "active": true,
  • "amount": 2,
  • "percentage": 5,
  • "range": [
    ],
  • "conditions": [
    ],
  • "enforce_this_fee": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "is_forex_fee": true
}

Find applicable advanced fees

This API is used to calculate and return advance fees against several specific parameters.

Authorizations:
apikey
Request Body schema: application/json
required
card_id
string

The unique identifier of the card. Either card or account should be provided.

account_id
string

The unique identifier of the account. Either card or account should be provided.

amount
required
number [ 0 .. 999999999.99 ]

Transaction amount on which fee will be calculated.

transaction_type
required
string (AdvancedTransactionType)
Enum: "TRANSFERS" "LOADS" "UNLOADS"

The type of transaction.

recipient_account_id
string

The unique identifier of the recipient account. This field is mandatory in case of transaction_type is TRANSFERS.

currency
required
string^([\*]{3}|[A-Z]{3})$

The currency code.

to_currency
string^([\*]{3}|[A-Z]{3})$

The currency code. Applicable in case of transaction_type is TRANSFERS (same in case of normal transfer; different in case of multi-currency).

Array of objects (AdvancedFeeCondition)

An array of data.

Responses

Request samples

Content type
application/json
{
  • "card_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "account_id": "686eabfc-f839-4e51-9dc1-3dc25c5ejjd6",
  • "amount": 2,
  • "transaction_type": "TRANSFERS",
  • "recipient_account_id": "686eabfc-f839-4e51-9dc1-3dc25c5ejjd6",
  • "currency": "USD",
  • "to_currency": "USD",
  • "conditions": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "card_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "account_id": "686eabfc-f839-4e51-9dc1-3dc25c5ejjd6",
  • "amount": 2,
  • "currency": "USD",
  • "fee_amount": 2,
  • "fee_details": [
    ]
}

Charges

Our system supports various types of charges so that it can be applied, for example, when physical or virtual cards are issued to cardholder for the first time.

Get list of charges

This API is used to get the list of card issuance charges.

Authorizations:
apikey
query Parameters
charge_type
string
Example: charge_type=PHYSICAL_CARD_ISSUANCE

The type of the charge.

ids
string

The list of the charge unique identifiers.

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "has_more": true,
  • "after": "string",
  • "data": [
    ]
}

Create charge

This API is used to create card issuance charge.

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the charge.

description
required
string <= 50 characters

Description of the charge.

type
required
string (Type)
Enum: "FLAT" "PERCENTAGE" "MAX_PERC_OR_FLAT" "MIN_PERC_OR_FLAT"

The charge type.

currency
required
string^[A-Z]{3}$

The charge currency.

amount
number [ 0 .. 999999999.99 ]

The charge amount.

percentage
number [ 0 .. 100 ]

Percentage of the charge.

active
boolean

The charge status.

charge_type
required
string (ChargesType)
Enum: "PHYSICAL_CARD_ISSUANCE" "VIRTUAL_CARD_ISSUANCE" "PHYSICAL_CARD_REPLACEMENT" "VIRTUAL_CARD_REPLACEMENT" "MAINTENANCE" "CHANGE_PIN" "LATE_PAYMENT" "DELIVERY" "FINANCIAL_CHARGES" "CARD_ACTIVATION_CHARGES" "DIGITAL_CARD_ISSUANCE" "DELIVERY" "CARD_ACTIVATION_CHARGES"

The type of charge operation.

frequency
string (ChargesFrequency)
Enum: "MONTHLY" "YEARLY"

Frequency of charging.

application_type
string (ChargesApplicationType)
Default: "SCHEDULED"
Enum: "INSTANT" "SCHEDULED"

Charges application type. If "application_type" is "INSTANT", "account_type" should be "MASTER".

account_type
string (ChargesAccountType)
Enum: "PREPAID" "MASTER"

Charges account type.

allow_overdraft
boolean
Default: false

This field indicates whether overdraft is allowed or not. The default value is 'false'.

Responses

Request samples

Content type
application/json
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "description": "Withdrawal charges",
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 15,
  • "active": true,
  • "charge_type": "PHYSICAL_CARD_ISSUANCE",
  • "frequency": "MONTHLY",
  • "application_type": "INSTANT",
  • "account_type": "PREPAID",
  • "allow_overdraft": false
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "description": "Withdrawal charges",
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 15,
  • "active": true,
  • "charge_type": "PHYSICAL_CARD_ISSUANCE",
  • "frequency": "MONTHLY",
  • "application_type": "INSTANT",
  • "account_type": "PREPAID",
  • "allow_overdraft": false,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get a specific charge

This API is used to get specific card issuance charge by ID.

Authorizations:
apikey
path Parameters
charges_id
required
string

The unique identifier of the charge.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "description": "Withdrawal charges",
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 15,
  • "active": true,
  • "charge_type": "PHYSICAL_CARD_ISSUANCE",
  • "frequency": "MONTHLY",
  • "application_type": "INSTANT",
  • "account_type": "PREPAID",
  • "allow_overdraft": false,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Update charge

This API is used to update card issuance charge.

Authorizations:
apikey
path Parameters
charges_id
required
string

The unique identifier of the charge.

Request Body schema: application/json
required
description
string <= 50 characters

Description of the charge.

type
string (Type)
Enum: "FLAT" "PERCENTAGE" "MAX_PERC_OR_FLAT" "MIN_PERC_OR_FLAT"

The charge type.

currency
string^[A-Z]{3}$

The charge currency.

amount
number [ 0 .. 999999999.99 ]

The charge amount.

percentage
number [ 0 .. 100 ]

Percentage of the charge.

active
boolean

The charge status.

charge_type
string (ChargesType)
Enum: "PHYSICAL_CARD_ISSUANCE" "VIRTUAL_CARD_ISSUANCE" "PHYSICAL_CARD_REPLACEMENT" "VIRTUAL_CARD_REPLACEMENT" "MAINTENANCE" "CHANGE_PIN" "LATE_PAYMENT" "DELIVERY" "FINANCIAL_CHARGES" "CARD_ACTIVATION_CHARGES" "DIGITAL_CARD_ISSUANCE" "DELIVERY" "CARD_ACTIVATION_CHARGES"

The type of charge operation.

frequency
string (ChargesFrequency)
Enum: "MONTHLY" "YEARLY"

Frequency of charging.

application_type
string (ChargesApplicationType)
Default: "SCHEDULED"
Enum: "INSTANT" "SCHEDULED"

Charges application type. If "application_type" is "INSTANT", "account_type" should be "MASTER".

account_type
string (ChargesAccountType)
Enum: "PREPAID" "MASTER"

Charges account type.

allow_overdraft
boolean
Default: false

This field indicates whether overdraft is allowed or not. The default value is 'false'.

Responses

Request samples

Content type
application/json
{
  • "description": "Withdrawal charges",
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 15,
  • "active": true,
  • "charge_type": "PHYSICAL_CARD_ISSUANCE",
  • "frequency": "MONTHLY",
  • "application_type": "INSTANT",
  • "account_type": "PREPAID",
  • "allow_overdraft": false
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "description": "Withdrawal charges",
  • "type": "FLAT",
  • "currency": "USD",
  • "amount": 2,
  • "percentage": 15,
  • "active": true,
  • "charge_type": "PHYSICAL_CARD_ISSUANCE",
  • "frequency": "MONTHLY",
  • "application_type": "INSTANT",
  • "account_type": "PREPAID",
  • "allow_overdraft": false,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Notification Templates

The notification template APIs are used to create and manage SMS templates for the authentication methods like 3D secure OTP (Three Domain Secure One Time PIN) in multiple languages. By using these notification APIs, SMS templates can be created in multiple languages for each card product. Note, that the strings , , and should be uppercase in SMS template body.

Get list of templates

This API is used to retrieve the list of all existing notification templates.

Authorizations:
apikey
query Parameters
language
string

The language used in the template.

card_product_id
string

The notification template is linked with the card product id shared in this parameter.

category
string
Enum: "THREE_D_SECURE_OTP" "ITSP_OTP"

The type of event to which the template is associated.

walletProvider
string
Enum: "APPLEPAY" "SAMSUNGPAY" "GOOGLEPAY"

Wallet provider field applicable for ITSP_OTP category.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Create template

This API is used to create a SMS notification template.

Authorizations:
apikey
Request Body schema: application/json
required
language
required
string

A language attribute identifying the language used in the template. ISO language codes are used.

text
required
string

A free text field for defining the SMS text.

category
required
string (NotificationTemplatesCategory)
Enum: "THREE_D_SECURE_OTP" "ITSP_OTP"

A notification category field that informs about the type of event to which this template is associated.

card_product_id
required
string

The notification template is linked with the card product id shared in this parameter.

wallet_provider
string (WalletProvider)
Enum: "APPLEPAY" "SAMSUNGPAY" "GOOGLEPAY"

The wallet provider.

object (EmailData)

Optional email OTP template. It is applicable for ITSP_OTP category only.

Responses

Request samples

Content type
application/json
{
  • "language": "EN",
  • "text": "Dear Customer, OTP for the online transaction from <MERCHANT_NAME> of <TRANSACTION_AMOUNT> on your card ending with <CARD_LAST4_DIGITS> is <OTP>. If you did not initiate this transaction, call +97144111000.",
  • "category": "THREE_D_SECURE_OTP",
  • "card_product_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "wallet_provider": "APPLEPAY",
  • "email": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "language": "EN",
  • "text": "Dear Customer, OTP for the online transaction from <MERCHANT_NAME> of <TRANSACTION_AMOUNT> on your card ending with <CARD_LAST4_DIGITS> is <OTP>. If you did not initiate this transaction, call +97144111000.",
  • "category": "THREE_D_SECURE_OTP",
  • "card_product_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "wallet_provider": "APPLEPAY",
  • "email": {
    }
}

Get specific template

This API is used to retrieve a specific notification template.

Authorizations:
apikey
path Parameters
template_id
required
string

ID of the template

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "language": "EN",
  • "text": "Dear Customer, OTP for the online transaction from <MERCHANT_NAME> of <TRANSACTION_AMOUNT> on your card ending with <CARD_LAST4_DIGITS> is <OTP>. If you did not initiate this transaction, call +97144111000.",
  • "category": "THREE_D_SECURE_OTP",
  • "card_product_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "wallet_provider": "APPLEPAY",
  • "email": {
    }
}

Update template

This API is used to update the existing notification template.

Authorizations:
apikey
path Parameters
template_id
required
string

ID of the template

Request Body schema: application/json
required
language
string

A language attribute identifying the language used in the template. ISO language codes are used.

text
string

A free text field for defining the SMS text.

category
string (NotificationTemplatesCategory)
Enum: "THREE_D_SECURE_OTP" "ITSP_OTP"

A notification category field that informs about the type of event to which this template is associated.

card_product_id
string

ID of the card product.

wallet_provider
string (WalletProvider)
Enum: "APPLEPAY" "SAMSUNGPAY" "GOOGLEPAY"

The wallet provider.

object (EmailData)

Optional email OTP template. It is applicable for ITSP_OTP category only.

Responses

Request samples

Content type
application/json
{
  • "language": "EN",
  • "text": "Dear Customer, OTP for the online transaction from <MERCHANT_NAME> of <TRANSACTION_AMOUNT> on your card ending with <CARD_LAST4_DIGITS> is <OTP>. If you did not initiate this transaction, call +97144111000.",
  • "category": "THREE_D_SECURE_OTP",
  • "card_product_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "wallet_provider": "APPLEPAY",
  • "email": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "language": "EN",
  • "text": "Dear Customer, OTP for the online transaction from <MERCHANT_NAME> of <TRANSACTION_AMOUNT> on your card ending with <CARD_LAST4_DIGITS> is <OTP>. If you did not initiate this transaction, call +97144111000.",
  • "category": "THREE_D_SECURE_OTP",
  • "card_product_id": "4b4eabfc-f839-4e51-9dc1-3dc25c5eddd6",
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z",
  • "wallet_provider": "APPLEPAY",
  • "email": {
    }
}

Delete template

This API is used to delete the existing notification template.

Authorizations:
apikey
path Parameters
template_id
required
string

ID of the template

Responses

Create marketing campaign

This API is used to create marketing campaign.

Authorizations:
apikey
Request Body schema: application/json
required
type
required
string (MarketingCampaignType)
Value: "PUSH_NOTIFICATIONS"

The marketing campaign type.

recipients
Array of strings

User IDs to target (required when audience=FIXED).

scope
required
string (MarketingCampaignScope)
Enum: "ALL" "FIXED"

The marketing campaign scope.

title
string

The marketing campaign title.

message
string

The marketing campaign message.

icon_url
string

The icon URL.

Responses

Request samples

Content type
application/json
{
  • "type": "PUSH_NOTIFICATIONS",
  • "recipients": [
    ],
  • "scope": "FIXED",
  • "title": "Some title",
  • "message": "Some text",
  • "icon_url": "test.com"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "type": "PUSH_NOTIFICATIONS",
  • "recipients": [
    ],
  • "scope": "FIXED",
  • "title": "Some title",
  • "message": "Some text",
  • "icon_url": "test.com",
  • "is_active": true,
  • "status": "CREATED",
  • "updated_at": "2025-09-15T15:30:00Z",
  • "created_at": "2025-09-15T15:30:00Z"
}

Update marketing campaign

This API is used to update marketing campaign.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the marketing campaign.

Request Body schema: application/json
required
title
string

The marketing campaign title.

message
string

The marketing campaign message.

icon_url
string

The icon URL.

is_active
boolean
Default: true

This parameter defines whether this marketing campaign is currently active.

Responses

Request samples

Content type
application/json
{
  • "title": "Some title",
  • "message": "Some text",
  • "icon_url": "test.com",
  • "is_active": true
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "type": "PUSH_NOTIFICATIONS",
  • "recipients": [
    ],
  • "scope": "FIXED",
  • "title": "Some title",
  • "message": "Some text",
  • "icon_url": "test.com",
  • "is_active": true,
  • "status": "CREATED",
  • "updated_at": "2025-09-15T15:30:00Z",
  • "created_at": "2025-09-15T15:30:00Z"
}

Load campaign result

This API is used to load campaign result.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the marketing campaign.

query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

user_id
string

The unique identifier of the user.

status
string

The status.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "campaign": {
    },
  • "after": "string",
  • "has_more": true,
  • "data": null
}

Execute marketing campaign

This API is used to execute marketing campaign.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the marketing campaign.

Responses

Retry marketing campaign

This API is used to retry marketing campaign.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the marketing campaign.

Responses

Webhooks

Webhooks help to keep you aware of what's happening in your card program. nCore uses webhooks to notify you when events occur so that you can take required actions. Our platform sends these notifications to an endpoint hosted on customer’s environment and configured to receive and process them.

Create webhook

This API is used to create a webhook.

Authorizations:
apikey
Request Body schema: application/json
required
endpoint
required
string

The enpoint to which the message will be delivered.

events
required
Array of strings (WebhookEvent)
Items Enum: "CARD_STATUS_CHANGE" "TRANSACTION" "KYC_RESULT" "USER_CREATED" "USER_STATUS_CHANGE" "USER_DOCUMENT_ALERT" "IDENTITY_VERIFICATION" "PIN_CHANGE" "EXPIRED_AUTH" "CHARGE_APPLIED" "ACCOUNT_STATUS_CHANGE" "CARD_PROVISIONING" "TOKEN_NOTIFICATION" "SUCCESSFULLY_CREATED" "CARD_DELIVERY_PARTNER_ASSIGNED" "CARD_DELIVERY_STATUS_CHANGED" "MISSED_PAYMENT" "STATEMENT_AVAILABLE" "PAYMENT_REMINDER" "SUCCESSFUL_PAYMENT" "THREE_DS_ENCRYPTED_OTP" "ITSP_ENCRYPTED_OTP" "RENEWAL_AND_REPLACEMENT"

Events to which you can subscribe. Please note that CARD_PROVISIONING event is only applicable for VISA at the moment.

object (WebhooksConfig)

Authentication config, supports basic auth and custom headers.

Responses

Request samples

Content type
application/json
{
  • "endpoint": "https://example.com/",
  • "events": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "b012776c-ab74-4ece-8403-0bbb9130508c",
  • "active": true,
  • "events": [
    ],
  • "endpoint": "https://example.com/",
  • "config": {
    },
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get list of webhooks

This API is used to get list of webhooks.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get specific webhook

This API is used to return a specific webhook.

Authorizations:
apikey
path Parameters
id
required
string

Unique identifier for the webhook.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "b012776c-ab74-4ece-8403-0bbb9130508c",
  • "active": true,
  • "events": [
    ],
  • "endpoint": "https://example.com/",
  • "config": {
    },
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Update webhook

This API is used to update a webhook.

Authorizations:
apikey
path Parameters
id
required
string

Unique identifier for the webhook.

Request Body schema: application/json
required
endpoint
required
string

The enpoint to which the message will be delivered.

events
required
Array of strings (WebhookEvent)
Items Enum: "CARD_STATUS_CHANGE" "TRANSACTION" "KYC_RESULT" "USER_CREATED" "USER_STATUS_CHANGE" "USER_DOCUMENT_ALERT" "IDENTITY_VERIFICATION" "PIN_CHANGE" "EXPIRED_AUTH" "CHARGE_APPLIED" "ACCOUNT_STATUS_CHANGE" "CARD_PROVISIONING" "TOKEN_NOTIFICATION" "SUCCESSFULLY_CREATED" "CARD_DELIVERY_PARTNER_ASSIGNED" "CARD_DELIVERY_STATUS_CHANGED" "MISSED_PAYMENT" "STATEMENT_AVAILABLE" "PAYMENT_REMINDER" "SUCCESSFUL_PAYMENT" "THREE_DS_ENCRYPTED_OTP" "ITSP_ENCRYPTED_OTP" "RENEWAL_AND_REPLACEMENT"

Events to which you can subscribe. Please note that CARD_PROVISIONING event is only applicable for VISA at the moment.

object (WebhooksConfig)

Authentication config, supports basic auth and custom headers.

Responses

Request samples

Content type
application/json
{
  • "endpoint": "https://example.com/",
  • "events": [
    ],
  • "config": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "b012776c-ab74-4ece-8403-0bbb9130508c",
  • "active": true,
  • "events": [
    ],
  • "endpoint": "https://example.com/",
  • "config": {
    },
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Delete webhook

This API is used to delete a webhook.

Authorizations:
apikey
path Parameters
id
required
string

Unique identifier for the webhook.

Responses

Ping webhook

This API is used to ping webhook for testing purposes.

Authorizations:
apikey
path Parameters
id
required
string

Unique identifier for the webhook.

Request Body schema: application/json
required
string

Responses

Request samples

Content type
application/json
"string"

Trigger expired webhooks

This API is used to trigger expired webhook notifications. It is also possible to send just one notification by ID.

Authorizations:
apikey
query Parameters
notification_id
string

Unique identifier for the webhook notification.

Responses

Search webhooks

This API is used to search webhooks by different criteria.

Authorizations:
apikey
Request Body schema: application/json
required

Search criteria.

query
string

A search query.

sort_by
string

The way results should be sorted.

order_by
string (SortDirection)
Enum: "asc" "desc"

The way results should be ordered (ascending or descending).

matcher
string (SearchMatcher)
Enum: "and" "or"

Search matcher.

Array of objects (SearchFilter)

An array of search filters.

object (Cursors)

Cursors

limit
integer <int32>

Search limit.

Responses

Request samples

Content type
application/json
{
  • "query": "Transfer",
  • "sort_by": "By name",
  • "order_by": "asc",
  • "matcher": "and",
  • "filters": [
    ],
  • "cursors": {
    },
  • "limit": 0
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "paging": {
    },
  • "data": [
    ]
}

Transactions

Our platform provides a set of APIs, through which transactions that are being processed by the platform can be retrieved by the platform API user.

Get transaction details

This API is used to retrieve details of a specific transaction.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the transaction.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "LoadTransaction01",
  • "transaction_timestamp": "2021-12-16T14:04:24.593Z",
  • "parent_transaction_id": "5efss08-0558-47ac-b722-4e45r176fb4f",
  • "network": "VISA",
  • "message_type": "API",
  • "transaction_type": "WALLET_CREDIT",
  • "transaction_description": "Wallet Credit",
  • "transmission_date_time": "2018-01-02T19:42:32.987Z",
  • "date_time_acquirer": "2018-01-02T19:42:32.987Z",
  • "card_id": "45678912314567891231456789123121",
  • "card_first_6_digits": "494964",
  • "card_last_4_digits": "6404",
  • "card_expiry_date": "052022",
  • "user_id": "5c0afa53-6ec0-4b08-a180-199352385c9b",
  • "account_id1": "5c0sds53-6ec0-4b08-a180-199352385c9b",
  • "card_product_1": "dfgafa53-6ec0-4b08-a180-199352385c9b",
  • "account_id2": "thfafa53-6ec0-4b08-a180-199352385c9b",
  • "card_product_2": "8uhafa53-6ec0-4b08-a180-199352385c9b",
  • "acquirer_id": "12345678901",
  • "merchant_id": "CARD ACCEPTOR",
  • "mcc": "5947",
  • "merchant_name": "ACQUIRER NAME",
  • "merchant_city": "CITY NAME",
  • "merchant_country": "USA",
  • "terminal_id": "TERMID01",
  • "stan": "000042",
  • "rrn": "13501404242y",
  • "auth_id_response": "476628",
  • "network_transaction_id": "234551234561008",
  • "transaction_amount": 500,
  • "transaction_currency": "USD",
  • "billing_amount": 4,
  • "billing_currency": "USD",
  • "billing_amount_account": 4,
  • "billing_currency_account": "USD",
  • "conversion_rate_billing_account": 4,
  • "acquirer_fee_amount": 2,
  • "conversion_rate_billing": "61000000",
  • "fee_amount": 2,
  • "fee_details": [
    ],
  • "original_amount": 2,
  • "original_amount_billing": "4",
  • "status_code": "0000",
  • "status_description": "Transaction approved",
  • "sender_user_id": "hkuser282",
  • "transfer_id": "234551234561008",
  • "load_id": "LoadTransaction01",
  • "unload_id": "234551234561008",
  • "eci": "05",
  • "ecommerce_security_level": "3DS1",
  • "card_entry": "Physical entry",
  • "pos_environment": "E-Commerce",
  • "fallback": false,
  • "pin_present": false,
  • "moto": false,
  • "recurring": false,
  • "installment_transaction": false,
  • "auth_expired_at": "2018-01-02T19:42:32.987Z",
  • "auth_expired_by": "AUTO",
  • "is_reversed": "YES",
  • "is_settled": "YES",
  • "source_channel": "DAPI",
  • "notes": "Performing operation for 12.50 USD",
  • "reference_number": "04a466da-cbab-11ed-afa1-0242ac120002",
  • "sweep_details": [
    ],
  • "type": "HOLD",
  • "quote_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "receiver_user_id": "g157a80f-e641-7745-8a80-99841e4a1234",
  • "acquirer_country": "USA"
}

Search for transactions

This API is used to search for transactions by different criteria.

Authorizations:
apikey
Request Body schema: application/json
required
query
string

A search query.

sort_by
string

The way results should be sorted.

order_by
string (SortDirection)
Enum: "asc" "desc"

The way results should be ordered (ascending or descending).

matcher
string (SearchMatcher)
Enum: "and" "or"

Search matcher.

Array of objects (SearchFilter)

An array of search filters.

object (Cursors)

Cursors

limit
integer <int32>

Search limit.

Responses

Request samples

Content type
application/json
{
  • "query": "Transfer",
  • "sort_by": "By name",
  • "order_by": "asc",
  • "matcher": "and",
  • "filters": [
    ],
  • "cursors": {
    },
  • "limit": 0
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "paging": {
    },
  • "data": "NymcardTransactionIndexCollection"
}

Simulate authorization transaction

This API is used to simulate authorization transaction. Below you can find prerequisite steps -

  • create a card (for 'Simulate authorization transaction' API to return successful response, BIN used in card product needs to be defined at NymCard's side first so we can route the transaction to your own tenant. If the network scheme is "VISA", then BIN should start from 4. In case it is "MASTERCARD", then BIN should start from 5 or 2);
  • activate card (if not active by default);
  • load the corresponding card account with funds;
  • use "Show card secret data" API to reveal card info;
  • use card info (PAN, EXPIRY [YYMM], CVV2) in simulate transaction request.
Authorizations:
apikey
Request Body schema: application/json
required
message_type
string (SimulateTransactionMessageType)
Value: "AUTHORIZATION"

The type of transaction simulation message.

transaction_type
string (SimulateTransactionTransactionType)
Enum: "PURCHASE" "CASH_WITHDRAWAL" "REFUND" "BALANCE_INQUIRY" "ACCOUNT_VERIFICATION"

The type of transaction simulation.

card_number
string

The card number.

card_expiry_date
string

The card expiry date in 'yymm' format.

cvv2
string

The card CVV.

transaction_amount
integer

The amount of transaction.

transaction_currency
string

The currency of the transaction.

billing_amount
integer

The billing amount.

billing_currency
string

The billing currency.

date_time_acquirer
string

The date of the transaction at the acquirer end when this transaction was performed. The format is "mmddhhmmss" (MonthDateHoursSec).

network
string

The network scheme.

network_transaction_id
string <= 25 characters

The unique transaction ID filled by the Network/Scheme. This field is only applicable for "MASTERCARD" network scheme.

terminal_id
string

The unique identifier of the merchant's terminal.

merchant_id
string

The unique identifier of the merchant.

mcc
string

The merchant category code.

merchant_name
string <= 25 characters

The merchant name.

merchant_country
string

The merchant country in 3 digit ISO Alpha country code format.

merchant_city
string <= 13 characters

The merchant city.

pin
string

The card PIN.

auth_id_response
string

auth_id_response received in response of auth transcation (used in unionpay cancellation).

Responses

Request samples

Content type
application/json
{
  • "message_type": "AUTHORIZATION",
  • "transaction_type": "PURCHASE",
  • "card_number": "4434221121121123",
  • "card_expiry_date": "2212",
  • "cvv2": "642",
  • "transaction_amount": 20,
  • "transaction_currency": "USD",
  • "billing_amount": 20,
  • "billing_currency": "USD",
  • "date_time_acquirer": "0928201947",
  • "network": "VISA",
  • "network_transaction_id": "234551234561008",
  • "terminal_id": "TERMID01",
  • "merchant_id": "MERCHID01",
  • "mcc": "5411",
  • "merchant_name": "ACQUIRER NAME",
  • "merchant_country": "USA",
  • "merchant_city": "New York",
  • "pin": "2341",
  • "auth_id_response": "123456"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "message_type": "AUTHORIZATION",
  • "transaction_type": "PURCHASE",
  • "transaction_amount": 20,
  • "transaction_currency": "USD",
  • "billing_amount": 20,
  • "billing_currency": "USD",
  • "date_time_acquirer": "0928201947",
  • "network": "VISA",
  • "network_transaction_id": "234551234561008",
  • "terminal_id": "TERMID01",
  • "merchant_id": "MERCHID01",
  • "mcc": "5411",
  • "merchant_name": "ACQUIRER NAME",
  • "merchant_country": "USA",
  • "merchant_city": "New York",
  • "id": "135015000017",
  • "status_code": "00",
  • "status_description": "Approved",
  • "available_balance": "9900.00",
  • "ledger_balance": "10000.00",
  • "stan": "000017",
  • "rrn": "135015000017",
  • "auth_id_response": "575620",
  • "sweep_details": [
    ]
}

Allowed Lists

Our platform supports the functionality to create and manage lists of allowed countries and MCCs (merchant category codes). These lists of allowed countries and MCCs can be used during authorization to check if the merchant country or MCC coming in authorization is allowed (whitelisted) or restricted (blacklisted).

Create list of allowed countries

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the allowed countries list.

name
required
string [ 1 .. 50 ] characters

The country list name.

allow
required
boolean

If this parameter is set as 'true', then it is a whitelist of country codes. If it is set as 'false', then it is a blacklist of country codes.

active
boolean

If this parameter is set as 'true', then the country list must be checked. If it is set as 'false', then the country list must not be checked. Default value is 'true'.

country_codes
required
Array of strings non-empty

ISO alpha 3-character country codes (e.g. USA, CAN etc.). At least one country code should be provided.

Responses

Request samples

Content type
application/json
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Country list 1",
  • "allow": true,
  • "active": true,
  • "country_codes": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Country list 1",
  • "allow": true,
  • "active": true,
  • "country_codes": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get list of allowed countries

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get allowed countries list by ID

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the allowed countries list

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Country list 1",
  • "allow": true,
  • "active": true,
  • "country_codes": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Update allowed countries list by ID

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the allowed countries list

Request Body schema: application/json
required
name
string [ 1 .. 50 ] characters

The country list name.

allow
boolean

If this parameter is set as 'true', then it is a whitelist of country codes. If it is set as 'false', then it is a blacklist of country codes.

active
boolean

If this parameter is set as 'true', then the country list must be checked. If it is set as 'false', then the country list must not be checked. Default value is 'true'.

country_codes
Array of strings

ISO alpha 3-character country codes (e.g. USA, CAN etc.). At least one country code should be provided.

Responses

Request samples

Content type
application/json
{
  • "name": "Country list 1",
  • "allow": true,
  • "active": true,
  • "country_codes": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Country list 1",
  • "allow": true,
  • "active": true,
  • "country_codes": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Create list of allowed MCCs

Authorizations:
apikey
Request Body schema: application/json
required
id
string <= 36 characters

The unique identifier of the allowed MCCs list.

name
required
string [ 1 .. 50 ] characters

The MCC list name.

active
boolean

If this parameter is set as 'true', then the MCC list must be checked. If it is set as 'false', then the MCC list must not be checked. Default value is 'true'.

required
Array of objects (MccInfo)

The MCC information.

Responses

Request samples

Content type
application/json
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "MCC List 01",
  • "active": true,
  • "mccs": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "MCC List 01",
  • "active": true,
  • "mccs": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get list of allowed MCCs

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get allowed MCCs list by ID

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the allowed MCCs list

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "MCC List 01",
  • "active": true,
  • "mccs": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Update allowed MCCs list by ID

This API is used to update allowed MCCs list.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of the allowed MCCs list

Request Body schema: application/json
required
active
boolean

If this parameter is set as 'true', then the MCC list must be checked. If it is set as 'false', then the MCC list must not be checked. Default value is 'true'.

Array of objects (MccInfo)

The MCC information.

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "mccs": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "MCC List 01",
  • "active": true,
  • "mccs": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Create allowed merchants list

This API is used to create allowed merchants list.

Authorizations:
apikey
Request Body schema: application/json
required
name
required
string [ 1 .. 50 ] characters

Merchants list name.

active
boolean

If this parameter is set as 'true', then the merchant list must be checked. If it is set as 'false', then the merchant list must not be checked. Default value is 'true'.

required
Array of objects (AllowedMerchantsRequestItem) non-empty

An array of data.

Responses

Request samples

Content type
application/json
{
  • "name": "Merchants List 01",
  • "active": true,
  • "merchants": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Merchant list 1",
  • "type": "ALLOWED",
  • "active": true,
  • "merchants": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get list of allowed merchants

This API is used to get list of allowed merchants.

Authorizations:
apikey
query Parameters
active
boolean

Filter by active status.

name
string

Filter by merchant list name.

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Update allowed merchants list

This API is used to update allowed merchants list.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9_]+$

The unique identifier of allowed merchants list.

Request Body schema: application/json
required
name
required
string [ 1 .. 50 ] characters

Merchants list name.

active
boolean

If this parameter is set as 'true', then the merchant list must be checked. If it is set as 'false', then the merchant list must not be checked. Default value is 'true'.

required
Array of objects (AllowedMerchantsRequestItem) non-empty

An array of data.

Responses

Request samples

Content type
application/json
{
  • "name": "Merchants List 01",
  • "active": true,
  • "merchants": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Merchant list 1",
  • "type": "ALLOWED",
  • "active": true,
  • "merchants": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get specific allowed merchants list

This API is used to get specific allowed merchants list.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier of allowed merchants list.

query Parameters
allow
boolean

Filter by allow/deny status.

merchant_id
string

Filter by specific merchant ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Merchant list 1",
  • "type": "ALLOWED",
  • "active": true,
  • "merchants": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Create a new allowed merchants list (V2)

V2 of the create allowed merchants endpoint. Supports the new type field and per-merchant active flag, replacing the deprecated allow field.

Authorizations:
apikey
Request Body schema: application/json
required
name
required
string [ 1 .. 50 ] characters

Merchants list name

type
required
string (AllowedMerchantsType)
Enum: "ALLOWED" "BLOCKED"
active
boolean
Default: true
required
Array of objects (AllowedMerchantsV2RequestItem) non-empty

Responses

Request samples

Content type
application/json
{
  • "name": "Merchants List 01",
  • "type": "ALLOWED",
  • "active": true,
  • "merchants": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Merchant list 1",
  • "type": "ALLOWED",
  • "active": true,
  • "merchants": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Returns list of allowed merchants (V2)

Authorizations:
apikey
query Parameters
active
boolean

Filter by active status

name
string

Filter by merchant list name

type
string
Enum: "ALLOWED" "BLOCKED"

Filter by merchant list type

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get allowed merchants by id (V2)

Authorizations:
apikey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Merchant list 1",
  • "type": "ALLOWED",
  • "active": true,
  • "merchants": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Update allowed merchants by id (V2)

Authorizations:
apikey
path Parameters
id
required
string
Request Body schema: application/json
required
name
string [ 1 .. 50 ] characters

Merchants list name

type
string (AllowedMerchantsType)
Enum: "ALLOWED" "BLOCKED"
active
boolean
Array of objects (AllowedMerchantsV2RequestItem) non-empty

Replaces the full merchant list. Each entry must include merchantId; active defaults to true.

Responses

Request samples

Content type
application/json
{
  • "name": "Merchants List 01",
  • "type": "ALLOWED",
  • "active": true,
  • "merchants": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "name": "Merchant list 1",
  • "type": "ALLOWED",
  • "active": true,
  • "merchants": [
    ],
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

VTS Tokens

nCore platform gives a possibility to store the payment card for future purchases and usage via VISA tokenization service. Tokenization protects card data by substituting a card's PAN with a unique, randomly-generated sequence of numbers called token. The generated number is the same length and format as the original PAN.

Get all digital wallet tokens

This API is used to get the list of all tokens.

Authorizations:
apikey
query Parameters
token_reference_id
string

If included then tokens will be filtered by token reference ID.

card_id
string

If included then tokens will be filtered by card ID.

pan_reference_id
string

If included then tokens will be filtered by PAN reference ID.

token_requestor_id
string

If included then tokens will be filtered by token requestor ID.

wallet_provider
string

If included then information of all the digital wallet tokens will be returned

token_type
string

If included then tokens will be filtered by token type.

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get token by ID

This API is used to get the specific token by its ID.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the token.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "202ff34d-8d6f-42f3-b728-4c59f2158591",
  • "token_requestor_id": "40000073",
  • "token_reference_id": "DNI...04",
  • "pan_reference_id": "V-420...90",
  • "client_wallet_account_id": "897...31",
  • "lifecycle_trace_id": 0,
  • "card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "pan_source": "KEY_ENTERED",
  • "card_last_four": "4587",
  • "consumer_entry_mode": "CAMERA_CAPTURED",
  • "token_info": {
    },
  • "device_info": {
    },
  • "created": "2018-01-02T19:42:32.987Z",
  • "updated": "2018-01-02T19:42:32.987Z"
}

Change token status

This API is used to change the status of the token.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the token.

Request Body schema: application/json
required
status
required
string (StatusToChange)
Enum: "ACTIVE" "SUSPENDED" "TERMINATED"

New status.

status_reason_code
required
string (StatusReasonCodeToChange)
Enum: "A0" "A1" "S0" "T0" "T1"

New Status Reason Code:

  • A0: First time activation: when activated from INACTIVE to ACTIVE status.
  • A1: Resumed from Suspended status: when token is moved back to ACTIVE status.
  • S0: Temporary suspension: initiated by the user or system user or the system.
  • T0: Token is closed by user.
  • T1: Token is closed by issuer.
note
string <= 254 characters

Some additional notes.

Responses

Request samples

Content type
application/json
{
  • "status": "ACTIVE",
  • "status_reason_code": "A0",
  • "note": "Additional info"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "202ff34d-8d6f-42f3-b728-4c59f2158591",
  • "token_requestor_id": "40000073",
  • "token_reference_id": "DNI...04",
  • "pan_reference_id": "V-420...90",
  • "client_wallet_account_id": "897...31",
  • "lifecycle_trace_id": 0,
  • "card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "user_id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "pan_source": "KEY_ENTERED",
  • "card_last_four": "4587",
  • "consumer_entry_mode": "CAMERA_CAPTURED",
  • "token_info": {
    },
  • "device_info": {
    },
  • "created": "2018-01-02T19:42:32.987Z",
  • "updated": "2018-01-02T19:42:32.987Z"
}

Get encrypted card details

This API is used to get encrypted card details, which will be used when calling SDK.

Authorizations:
apikey
path Parameters
id
required
string^[a-zA-Z\-0-9]+$

The unique identifier or the proxy number of the card.

query Parameters
nonce_jws
required
string <= 256 characters

Base64 encoded payload of signed nonce. It is generated with the help of SDK.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "status": "SUCCESS",
  • "status_reason_code": "F0",
  • "card_details": "encrypted_card_details"
}

MDES Tokens

nCore platform gives a possibility to store the payment card for future purchases and usage via MDES tokenization service. Tokenization protects card data by substituting a card's PAN with a unique, randomly-generated sequence of numbers called token. The generated number is the same length and format as the original PAN.

Change token status

This API is used to change token status.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of the token.

Request Body schema: application/json
required
status
required
string (MdesStatusToChange)
Enum: "ACTIVE" "SUSPENDED" "UNSUSPENDED" "TERMINATED"

The change status.

status_reason_code
required
string (MdesStatusReasonCodeToChange)
Enum: "A0" "A2" "A3" "A4" "A5" "S0" "S1" "S2" "S3" "T0" "T1" "T2" "T3" "T4" "T5" "T6"

New Status Reason Code.

  • A0 First time activation - when activated from INACTIVE to ACTIVE status by customer service agent.
  • A2 First time activation - when activated from INACTIVE to ACTIVE status and user was authenticated with an activation method.
  • S0 Temporary suspension - Cardholder reported token device lost.
  • S1 Temporary suspension - Cardholder reported token device stolen.
  • S2 Temporary suspension - Issue or cardholder reported fraudulent token transactions.
  • S3 Temporary suspension - Other.
  • A3 Resumed from Suspended status - Cardholder reported token device found or not stolen.
  • A4 Resumed from Suspended status - Issuer or cardholder confirmed no fraudulent token transactions.
  • A5 Resumed from Suspended status - Other.
  • T0 Terminated - Cardholder confirmed token device lost.
  • T1 Terminated - Cardholder confirmed token device stolen.
  • T2 Terminated - Issuer or cardholder confirmed fraudulent token transactions (Deprecated).
  • T3 Terminated - Issuer or cardholder confirmed fraudulent token transactions.
  • T4 Terminated - Account closed.
  • T5 Terminated - Issuer consumer deleted.
  • T6 Terminated - Other.
note
string <= 450 characters

The additional information.

Responses

Request samples

Content type
application/json
{
  • "status": "SUSPENDED",
  • "status_reason_code": "A0",
  • "note": "Some text"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "fceb7dc9-9795-4a7b-a091-94a5074cd78f",
  • "request_id": "65d42717-c804-4cde-a71f-0ce2b6db4d00",
  • "tenant_id": "tenant21",
  • "api_name": "AUTHORIZE_SERVICE",
  • "created": "2023-09-05T13:01:55.309Z",
  • "services": [
    ],
  • "token_unique_reference": "DSAPMC0000324984865fc4106a624a7dae0445bb1fab78b6",
  • "pan_unique_reference": "FHAPMC5678324984865fc4106a624a7dae0445bb1fab78b6",
  • "source": "94.206.96.76",
  • "data_valid_until_timestamp": "2023-09-05T13:31:50.272Z",
  • "account_number_last_four": "0013",
  • "financial_account_id": "65d47865-c804-4cde-a71f-0ce2b6db4d00",
  • "interbank_card_association_id": "57832717-c804-4cde-a71f-0ce2b6db4d00",
  • "country_code": "USA",
  • "token": "123CCB2F30BA420B22B0B2231BD58EEADD2FCC7F0039199BBF461EAE60A88460",
  • "expiry_month": "June",
  • "expiry_year": "2024",
  • "sequence_number": "4",
  • "payment_account_reference": "23",
  • "account_holder_name": "John Smith",
  • "line1": "Jellow",
  • "line2": "Stone",
  • "city": "Paris",
  • "country_subdivision": "US",
  • "postal_code": "79000",
  • "country": "USA",
  • "source_ip": "94.206.96.76",
  • "device_location": "Town",
  • "consumer_identifier": "TCCA",
  • "account_holder_email_address": "example@gmail.com",
  • "country_dial_in_code": "380",
  • "phone_number": "575930304",
  • "correlation_id": "D0000061238490",
  • "token_requestor_id": "50139059239",
  • "wallet_id": "217",
  • "payment_app_instance_id": "5MTUwNzI0MDEwMDAwODMyMzc3003XPzFWpzQ0yBkGWpdp8iKQ",
  • "account_id_hash": "123CCB2F30BA420B22B0B2231BD58EEADD2FCC7F0039199BBF461EAE60A88460",
  • "mobile_number_suffix": "501390",
  • "active_token_count": "0",
  • "device_name": "Mastercard Samsung",
  • "serial_number": "M988575524e47423039",
  • "form_factor": "PHONE",
  • "iso_device_type": "21",
  • "os_name": "ANDROID",
  • "os_version": "8.0.0",
  • "imei": "87576457646746",
  • "msisdn": "8988753",
  • "payment_types": [
    ],
  • "storage_technology": "TEE",
  • "card_capture_technology": "GE",
  • "recommended_decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
  • "recommendation_standard_version": "01",
  • "device_score": "5",
  • "account_score": "3",
  • "phone_number_score": "1",
  • "account_lifetime": "16",
  • "recommendation_reasons": [
    ],
  • "token_type": "EMBEDDED_SE",
  • "consumer_facing_entity_name": "Samsung Pay",
  • "user_id": "e898a182-ddd3-4993-83c4-3b6e370700ff",
  • "mobile_number": "+971525080230",
  • "email": "example@gmail.com",
  • "card_id": "4cc48c09-b5c4-46cf-9e8b-55df2cbf7940",
  • "decision": "REQUIRE_ADDITIONAL_AUTHENTICATION",
  • "cvcResponse": "MATCH",
  • "errorCode": "01",
  • "errorDescription": "Some error",
  • "secureElementId": "4cc48c09-b5c4-46cf-9e8b-55df2cbf7940",
  • "accountPanSuffix": "4cc48c",
  • "serviceRequestDateTime": "2023-09-05T13:01:55.309Z",
  • "termsAndConditionsAssetId": "4c55df2cbf7940",
  • "termsAndConditionsAcceptedTimestamp": "2023-09-05T13:01:55.309Z",
  • "productConfigurationId": "4c5bf7940",
  • "consumerLanguage": "ENG",
  • "decisionMadeBy": "person",
  • "tokenActivatedDateTime": "2023-09-05T13:01:55.309Z",
  • "numberOfActivationAttempts": "1",
  • "numberOfActiveTokens": "1",
  • "tokenAssuranceLevel": "2",
  • "requestStatus": "T5",
  • "status": "5",
  • "status_reason_code": "2T",
  • "note": "some info",
  • "status_updated_on": "2023-09-05T13:01:55.309Z",
  • "notify_token_reason": "STATUS_UPDATE",
  • "token_provisioning_status": "ABANDONED"
}

Get all MDES tokens

This API is used to get the list of all MDES tokens.

Authorizations:
apikey
query Parameters
correlation_id
string

If provided then tokens will be filtered by 'correlation_id'.

card_id
string

If provided then tokens will be filtered by 'card_id'.

pan_unique_reference
string

If provided then tokens will be filtered by 'pan_unique_reference'.

token_requestor_id
string

If provided then tokens will be filtered by 'token_requestor_id'.

token_type
string

If provided then tokens will be filtered by 'token_type'.

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

FX rates

nCore platform gives a possibility to define custom FX rate providers, groups and quotes, which are used for multi-currency functionality. You can find more info about multi-currency feature in the following GSG document https://docs.nymcard.com/get-started/product-management/multi-currency.

Get list of FX rate providers

This API is used to get the list of FX rate providers.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "data": [
    ]
}

Get list of FX rate groups (version 2)

This API is used to get the list of FX rate groups.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "data": [
    ]
}

Get specific FX rate group (version 2)

This API is used to retrieve the details of a specific FX rate group.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of FX rate group.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "providerId": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "providerGroupId": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "decimal_places": 4,
  • "markups": [
    ],
  • "status": "ACTIVE",
  • "isDefault": true,
  • "created": "2018-01-02T19:42:32.987Z",
  • "modified": "2018-01-02T19:42:32.987Z"
}

Get specific FX rate provider

This API is used to retrieve the details of a specific FX rate provider.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of FX rate provider.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "provider_id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "provider_name": "Converter",
  • "type": "INTERNAL",
  • "status": "ACTIVE",
  • "rate_expiry_buffer_time": 0,
  • "fxrate_mode": [
    ],
  • "fxrate_provider_groups": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get list of FX rate quotes

This API is used to get the list of FX rate quotes.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get specific FX rate quote

This API is used to retrieve the details of a specific FX rate quote.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of FX rate quote.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "id_external": "2",
  • "status": "OFFERED",
  • "ts": "2012-05-04T19:42:32.987Z",
  • "expiry": "2012-05-04T19:42:32.987Z",
  • "booking_ts": "2012-05-04T19:42:32.987Z",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "recipient_account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "fxprovider_id": "34",
  • "fxrate_mode": "ONLINE",
  • "rate_group_id": "R34",
  • "rate_group_id_external": "P1",
  • "from_currency": "AED",
  • "from_amount": 57,
  • "to_currency": "USD",
  • "to_amount": 14.82,
  • "to_amount_applied": 14.82,
  • "exchange_rate_id": "2",
  • "exchange_rate": 0.26,
  • "exchange_rate_applied": 0.26,
  • "markup_type": "DEFAULT",
  • "markup_value": 5,
  • "transaction_id": "111c3059-33af-4ed0-969a-7c23801dd555",
  • "derived_rate": 2,
  • "final_rate": 5,
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "transaction_type": "TRANSFERS",
  • "markup_amount": 50,
  • "internal_markup_amount": 15,
  • "external_markup_amount": 10,
  • "total_internal_markup": 10,
  • "total_external_markup": 15
}

Request FX rate quote

This API is used to request FX rate quote.

Authorizations:
apikey
Request Body schema: application/json
required
account_id
required
string

The unique identifier of the account.

recipient_account_id
string

The unique identifier of the recipient account. This parameter is used for fund transfer between accounts of different wallet currencies.

from_currency
required
string^[A-Z]{3}$

3-letter ISO_4217 code representing the selling currency.

to_currency
required
string^[A-Z]{3}$

3-letter ISO_4217 code representing the buying currency.

amount
required
number [ 0 .. 999999999.99 ]

The amount which should be converted.

amount_type
string (FxRateAmountType)
Enum: "FROM" "TO"

FX rate amount type.

dry_run
boolean
Default: false

Decides whether to create a FX Rates quote or not after performing all necessary operations.

transaction_type
string (FxRateTransactionType)
Default: "TRANSFERS"
Enum: "TRANSFERS" "SWEEP" "UNLOADS" "LOADS"

FX rate transaction type.

markup_amount
number

Total markup amount calculated.

internal_markup_amount
number

Total internal markup amount calculated.

external_markup_amount
number

Total external markup amount calculated.

Responses

Request samples

Content type
application/json
{
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "recipient_account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "from_currency": "AED",
  • "to_currency": "USD",
  • "amount": 50,
  • "amount_type": "FROM",
  • "dry_run": false,
  • "transaction_type": "TRANSFERS",
  • "markup_amount": 50,
  • "internal_markup_amount": 15,
  • "external_markup_amount": 10
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "ts": "2012-05-04T19:42:32.987Z",
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "recipient_account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "from_currency": "AED",
  • "from_amount": 57,
  • "to_currency": "USD",
  • "to_amount": 14.82,
  • "exchange_rate": 0.26,
  • "status": "OFFERED",
  • "expiry": "2012-05-04T19:42:32.987Z",
  • "fxrate_provider_id": "34",
  • "fxrate_provider_name": "Converter",
  • "markup_value": 5,
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "transaction_type": "TRANSFERS",
  • "markup_amount": 5
}

Book FX rate quote

This API is used to book a FX rate quote.

Authorizations:
apikey
path Parameters
quoteId
required
string

The unique identifier of FX rate quote.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "g189a80f-e641-4045-8a80-54841e4a1234",
  • "ts": "2012-05-04T19:42:32.987Z",
  • "quote_booking_ts": "2012-05-04T19:42:32.987Z",
  • "from_currency": "AED",
  • "from_amount": 57,
  • "to_currency": "USD",
  • "to_amount": 14.82,
  • "exchange_rate": 0.26,
  • "status": "OFFERED",
  • "expiry": "2012-05-04T19:42:32.987Z",
  • "transaction_id": "111c3059-33af-4ed0-969a-7c23801dd555",
  • "fxrate_provider_id": "34",
  • "fxrate_provider_name": "Converter",
  • "markup_value": 5,
  • "fee_amount": 2.5,
  • "fee_details": [
    ],
  • "account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "recipient_account_id": "c1971753-2d53-4cc4-9e95-5bcb9a3fef95",
  • "booking_ts": "2012-05-04T19:42:32.987Z",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "markup_amount": 5,
  • "markup_details": [
    ]
}

Remittance - Western Union

nCore platform gives a possibility to integrate with Western Union to conduct remittances.

Get origination currencies

This API is used to get list of possible origination currencies.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get partner statuses

This API is used to get list of possible partner statuses.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get country and currencies for specific origination country

This API is used to get possible country and currencies for specific origination country.

Authorizations:
apikey
query Parameters
originationCurrency
required
string

Origination currency.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get delivery services

This API is used to get possible delivery services between given countries and currencies.

Authorizations:
apikey
query Parameters
originationCurrency
required
string

Origination currency.

destinationCountry
required
string

Destination country.

destinationCurrency
required
string

Destination currency.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get delivery option template

This API is used to get possible delivery option template for destination country and currency.

Authorizations:
apikey
query Parameters
destinationCountry
required
string

Destination country.

destinationCurrency
required
string

Destination currency.

templateId
required
string

Delivery service template ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get cascade list values

This API is used to get cascade list values.

Authorizations:
apikey
query Parameters
cmbCode
required
string

CMB code for selected country.

firstLevelValue
string

Value from 'Get combo first level' API response. You can find more info in this document https://docs.nymcard.com/get-started/funding-and-transfers/western-union-apis#get-cascade-list-values-api.

secondLevelValue
string

Value from 'Get combo second level' API response. You can find more info in this document https://docs.nymcard.com/get-started/funding-and-transfers/western-union-apis#get-cascade-list-values-api.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get reversal reasons

This API is used to get list of reversal reasons.

Authorizations:
apikey
query Parameters
reversalType
required
string (ReversalType)
Enum: "CANCEL" "REFUND"
Example: reversalType=CANCEL

The type of reversal.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get list of states

This API is used to get list of states.

Authorizations:
apikey
query Parameters
countryCode
required
string (CountryCode)
Enum: "CA" "MX" "US"
Example: countryCode=CA

The country code.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Create fee inquiry

This API is used to create a fee inquiry.

Authorizations:
apikey
Request Body schema: application/json
required

Fee inquiry request.

senderId
required
string <= 36 characters

The unique identifier of sender.

transactionType
required
string (WuTransactionType)
Enum: "WMF" "WMN" "WMO" "MOD" "MOR" "MOP"

WU transaction type.

required
object (PaymentDetailsBaseRequest)

The payment details.

hostBasedTaxes
required
string (HostBasedTaxes)
Enum: "Y" "N"

The host based taxes.

Responses

Request samples

Content type
application/json
{
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "transactionType": "WMF",
  • "paymentDetails": {
    },
  • "hostBasedTaxes": "Y"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "testQuestionFlag": "Y",
  • "serviceOptions": [
    ]
}

Refund transaction

This API is used to refund transaction.

Authorizations:
apikey
Request Body schema: application/json
required

Refund transaction request.

accountId
required
string <= 36 characters

Unique account number identifying the financial account.

senderId
required
string <= 36 characters

The unique identifier of sender.

refundReasonCode
required
string <= 6 characters

Refund reason code.This code should be provided by NymCard’s Customer from Get Reason List dictionary API.

Responses

Request samples

Content type
application/json
{
  • "accountId": "9675496749769476974",
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "refundReasonCode": "4874"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "accountId": "9675496749769476974",
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "transactionId": "9675496749769476",
  • "refundReasonCode": "4874",
  • "status": {
    },
  • "dateTime": "2012-05-04T19:42:32.987Z"
}

Send money validation request to Western Union

This API is used to send money validation request to Western Union.

Authorizations:
apikey
Request Body schema: application/json
required

Send money validation request.

accountId
required
string <= 36 characters

The unique identifier of account.

senderId
required
string <= 36 characters

The unique identifier of sender.

required
object (Receiver)

The receiver details.

smsNotificationFlag
required
string (SmsNotificationFlag)
Enum: "Y" "N"

SMS notification flag.

object (BankAccount)

The bank account details.

hostBasedTaxes
required
string (HostBasedTaxes)
Enum: "Y" "N"

The host based taxes.

required
object (Product)

WU product details.

senderEmploymentPositionLevel
required
string

Additional field for development purpose. Possible values are - Entry Level, Mid-Level/Supervisory/Management, Senior Level/Executive, Owner.

senderOccupation
required
string

Additional field for development purpose. Possible values are -

  • Airline/Maritime Employee
  • Art/Entertainment/Media
  • Civil/Government Employee
  • Domestic Helper
  • Driver
  • Teacher/Educator
  • Hotel/Restaurant/Leisure
  • Housewife/Child Care
  • IT and Tech Professional
  • Laborer-Agriculture
  • Laborer-Construction
  • Laborer-Manufacturing
  • Laborer- Oil/Gas/Mining
  • Medical/Health Care
  • Non-profit/Volunteer
  • Cosmetic/Personal Care
  • Law Enforcement/Military
  • Office Professional
  • Religious/Church Servant
  • Retail Sales
  • Retired
  • Sales/Insurance/Real Estate
  • Science/Research Professional
  • Security Guard
  • Self-Employed
  • Skilled Trade/Specialist
  • Student
  • Unemployed
sourceOfFunds
required
string <= 30 characters

Source of funds.

transactionReason
required
string <= 50 characters

Reason for transaction. Possible values are -

  • Family Support/Living Expenses
  • Saving/Investments
  • Gift
  • Goods & Services payment
  • Travel expenses
  • Education/School Fee
  • Rent/Mortgage
  • Emergency/Medical Aid
  • Charity/Aid Payment
  • Employee Payroll/Employee Expense
  • Prize or Lottery Fees/Taxes
required
object (PaymentDetailsBaseRequest)

The payment details.

Responses

Request samples

Content type
application/json
Example
{
  • "accountId": "cf2fgj3b-ac68-441b-bc54-21de60014d57",
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "receiver": {
    },
  • "smsNotificationFlag": "Y",
  • "bankAccount": {
    },
  • "hostBasedTaxes": "Y",
  • "product": {
    },
  • "senderEmploymentPositionLevel": "string",
  • "senderOccupation": "string",
  • "sourceOfFunds": "Source",
  • "transactionReason": "Gift",
  • "paymentDetails": {
    },
  • "type": "SendMoneyValidateRequest"
}

Response samples

Content type
application/json;charset=UTF-8
Example
{
  • "accountId": "cf2fgj3b-ac68-441b-bc54-21de60014d57",
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "receiver": {
    },
  • "smsNotificationFlag": "Y",
  • "bankAccount": {
    },
  • "hostBasedTaxes": "Y",
  • "product": {
    },
  • "senderEmploymentPositionLevel": "string",
  • "senderOccupation": "string",
  • "sourceOfFunds": "Source",
  • "transactionReason": "Gift",
  • "paymentDetails": {
    },
  • "type": "SendMoneyValidateRequest"
}

Send money store request to Western Union

This API is used to send money store request to Western Union.

Authorizations:
apikey
path Parameters
transactionAction
required
string (TransactionAction)
Enum: "HOLD" "RELEASE" "CANCEL"
Example: HOLD

Transaction action.

Request Body schema: application/json
required

Send money store request.

accountId
required
string <= 36 characters

The unique identifier of account.

senderId
required
string <= 36 characters

The unique identifier of sender.

required
object (Receiver)

The receiver details.

smsNotificationFlag
required
string (SmsNotificationFlag)
Enum: "Y" "N"

SMS notification flag.

object (BankAccount)

The bank account details.

hostBasedTaxes
required
string (HostBasedTaxes)
Enum: "Y" "N"

The host based taxes.

required
object (Product)

WU product details.

senderEmploymentPositionLevel
required
string

Additional field for development purpose. Possible values are - Entry Level, Mid-Level/Supervisory/Management, Senior Level/Executive, Owner.

senderOccupation
required
string

Additional field for development purpose. Possible values are -

  • Airline/Maritime Employee
  • Art/Entertainment/Media
  • Civil/Government Employee
  • Domestic Helper
  • Driver
  • Teacher/Educator
  • Hotel/Restaurant/Leisure
  • Housewife/Child Care
  • IT and Tech Professional
  • Laborer-Agriculture
  • Laborer-Construction
  • Laborer-Manufacturing
  • Laborer- Oil/Gas/Mining
  • Medical/Health Care
  • Non-profit/Volunteer
  • Cosmetic/Personal Care
  • Law Enforcement/Military
  • Office Professional
  • Religious/Church Servant
  • Retail Sales
  • Retired
  • Sales/Insurance/Real Estate
  • Science/Research Professional
  • Security Guard
  • Self-Employed
  • Skilled Trade/Specialist
  • Student
  • Unemployed
sourceOfFunds
required
string <= 30 characters

Source of funds.

transactionReason
required
string <= 50 characters

Reason for transaction. Possible values are -

  • Family Support/Living Expenses
  • Saving/Investments
  • Gift
  • Goods & Services payment
  • Travel expenses
  • Education/School Fee
  • Rent/Mortgage
  • Emergency/Medical Aid
  • Charity/Aid Payment
  • Employee Payroll/Employee Expense
  • Prize or Lottery Fees/Taxes
required
object (PaymentDetailsBaseRequest)

The payment details.

Responses

Request samples

Content type
application/json
Example
{
  • "accountId": "cf2fgj3b-ac68-441b-bc54-21de60014d57",
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "receiver": {
    },
  • "smsNotificationFlag": "Y",
  • "bankAccount": {
    },
  • "hostBasedTaxes": "Y",
  • "product": {
    },
  • "senderEmploymentPositionLevel": "string",
  • "senderOccupation": "string",
  • "sourceOfFunds": "Source",
  • "transactionReason": "Gift",
  • "paymentDetails": {
    },
  • "type": "SendMoneyValidateRequest"
}

Response samples

Content type
application/json;charset=UTF-8
Example
{
  • "accountId": "cf2fgj3b-ac68-441b-bc54-21de60014d57",
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "receiver": {
    },
  • "smsNotificationFlag": "Y",
  • "bankAccount": {
    },
  • "hostBasedTaxes": "Y",
  • "product": {
    },
  • "senderEmploymentPositionLevel": "string",
  • "senderOccupation": "string",
  • "sourceOfFunds": "Source",
  • "transactionReason": "Gift",
  • "paymentDetails": {
    },
  • "type": "SendMoneyValidateRequest"
}

Send cancel transaction request to Western Union

This API is used to send cancel transaction request to Western Union.

Authorizations:
apikey
Request Body schema: application/json
required

Cancel transaction request.

accountId
required
string <= 36 characters

Unique account number identifying the financial account.

cancelReasonCode
required
string <= 3 characters

Cancel reason code.

reverseFees
required
boolean

This field indicates whether fees should be returned.

Responses

Request samples

Content type
application/json
{
  • "accountId": "9675496749769476974",
  • "cancelReasonCode": "66",
  • "reverseFees": true
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "accountId": "9675496749769476974",
  • "transactionId": "9675496749769476",
  • "cancelReasonCode": "66",
  • "reverseFees": true,
  • "cancelStatus": "SUCCESS"
}

Generate OTP and send it to customer

This API is used to generate OTP and send it to customer.

Authorizations:
apikey
Request Body schema: application/json
required

Generate OTP request.

senderId
required
string <= 36 characters

The unique identifier of sender.

Responses

Request samples

Content type
application/json
{
  • "senderId": "cf2de83b-ac68-441b-bc54-21de60014d57"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "initiationId": "3e9392df-4093-4389-a0ad-92456a181b8a"
}

Remittance - Mastercard

nCore platform 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.

Get indicative rates

This API is used to check indicative exchange rates, fees and sent/received amount before sending remittance for Mastercard cross border.

Authorizations:
apikey
query Parameters
receiver_currency_code
required
string

Receiver currency code in 3-letter ISO_4217 code format.

receiver_country_code
required
string

Receiver country code in ISO alpha 2-character code format.

source_currency_code
required
string

Source currency code in 3-letter ISO_4217 code format.

receive_amount
number [ 0 .. 999999999.99 ]

Received amount.

sent_amount
number [ 0 .. 999999999.99 ]

Sent amount.

bank_id
string

The unique identifier of the bank.

payment_mode_id
required
string

The unique identifier of the payment mode.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "tran_amount": 110,
  • "tran_fee_amount": 10,
  • "original_tran_amount": 100,
  • "receiver_amount": 217,
  • "receiver_currency_code": "INR",
  • "receiver_country_code": "IN",
  • "source_currency_code": "USD",
  • "transaction_rate": 2.17
}

Get list of required fields

This API is used to retrieve list of required fields.

Authorizations:
apikey
query Parameters
payer_branch_id
string

Payer Branch ID (Pay-out location).

payer_bank_id
string

Payer Bank ID.

receiver_country_iso_code
required
string

Receiver Country ISO Code.

receiver_currency_iso_code
required
string

Receiver Currency ISO Code.

payment_mode_id
required
string

Mode ID of the delivery.

source_currency_iso_code
required
string

Source Currency ISO Code.

payer_id
string

Payer ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "Fields": [
    ]
}

Get list of receiver countries

This API is used to get the list of allowed countries where you can send remittance via Mastercard cross border.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "countries": [
    ]
}

Load countries supporting cash pickup

This API is used to get the list of countries supporting cash pickup anywhere nationwide.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "countries": [
    ]
}

Get country details

This API is used to get details of a specific country using a country code.

Authorizations:
apikey
query Parameters
country_code
required
string^[A-Za-z]{2}$

Country code in ISO alpha 2-character code format.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "country_code": "AL",
  • "states": [
    ],
  • "id_types": [
    ],
  • "remittance_purposes": [
    ],
  • "source_of_funds": [
    ]
}

Get list of cities

This API is used to retrieve the list of cities by country code.

Authorizations:
apikey
query Parameters
country_code
required
string

Country code in ISO alpha 2-character code format.

state_id
string

The unique identifier of the state.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "total_count": "1",
  • "cities": [
    ]
}

Get payment modes and currencies

This API is used to retrieve payment modes and designated currencies for selected country for Mastercard cross border.

Authorizations:
apikey
query Parameters
country_code
required
string

Country code in ISO alpha 2-character code format.

city_id
string

The unique identifier of the city.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "country_code": "US",
  • "cash_pickup_anywhere": true,
  • "payment_modes": [
    ]
}

Get payer details

This API is used to retrieve the payer details.

Authorizations:
apikey
query Parameters
city_id
required
integer <int32>

City ID.

town_id
string

Town ID.

country_iso_code
required
string

Country ISO Code.

payment_mode_id
required
string

Payment Mode ID.

receive_currency_iso_code
required
string

Receive Currency ISO Code.

source_currency_iso_code
required
string

Source Currency ISO Code.

bank_id
string

Bank ID.

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "has_more": true,
  • "after": "string",
  • "data": [
    ]
}

Get list of relationship with sender

This API is used to retrieve the list of relationship with sender.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Get list of banks

This API is used to retrieve the list of banks using a country code.

Authorizations:
apikey
query Parameters
country_code
required
string

Country code in ISO alpha 2-character code format.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "totalCount": 3,
  • "banks": [
    ]
}

Get bank branches

This API is used to retrieve the list of bank branches.

Authorizations:
apikey
query Parameters
bank_id
required
string

The unique identifier of the bank.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "totalCount": 2,
  • "getBankBranch": [
    ]
}

Get transaction details

This API is used to retrieve transaction details by TfPin or reference number.

Authorizations:
apikey
query Parameters
key
required
string
Enum: "tfpin" "refnumber"

Tfpin (transaction number) or refnumber (reference number).

value
required
string

Unique transaction number, which depends on the provided key.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "status_name": "PENDING RELEASE",
  • "status_id": "R",
  • "tf_pin": "33TF119564665",
  • "cancellation_reason": "01",
  • "transaction_date": "2023-07-07T14:41:29.723-04:00",
  • "sender": {
    },
  • "receiver": {
    },
  • "transaction_info": {
    },
  • "compliance": {
    }
}

Initiate transaction to Mastercard

This API is used to initiate transaction to Mastercard.

Authorizations:
apikey
header Parameters
x-nymos-idempotency-key
required
string <= 36 characters
Request Body schema: application/json
required
required
object (InitiateTransactionSender)

Transaction sender info.

required
object (InitiateTransactionReceiver)

Transaction receiver info.

required
object (InitiateTransactionInfo)

Transaction info.

object (InitiateTransactionCompliance)

Transaction compliance info.

Responses

Request samples

Content type
application/json
{
  • "sender": {
    },
  • "receiver": {
    },
  • "transaction_info": {
    },
  • "compliance": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "cf2de83b-ac68-441b-bc54-21de60014d57",
  • "StatusName": "R",
  • "StatusId": "38634869",
  • "TfPin": "0000045",
  • "TransactionDate": "2023-06-01T00:00:00.000-04:00",
  • "CanBeCancelled": false,
  • "RequiresPreAml": false,
  • "RequiresPostAml": false,
  • "Sender": {
    },
  • "Receiver": {
    },
  • "TransactionInfo": {
    }
}

Edit transaction details

This API is used to edit details of a specific transaction.

Authorizations:
apikey
Request Body schema: application/json
required
tfPin
required
string

Tfpin (Transaction number).

object (TransactionReceiverUpdateRequest)

Transaction receiver's info.

object (TransactionInfoUpdateRequest)

Transaction info.

Responses

Request samples

Content type
application/json
{
  • "tfPin": "33TF010994059",
  • "receiver": {
    },
  • "transaction_info": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "message": "Some text"
}

Remittance - VISA Direct

Visa Direct offers real-time push payment capabilities that utilize Visa’s global payment system.

Pull funds transaction

This API is used to pull funds transaction.

Authorizations:
apikey
Request Body schema: application/json
required

Pull funds request.

cardId
required
string

The card ID.

amount
required
number <decimal> >= 0

Transaction amount.

senderPrimaryAccountNumber
required
string^\d{13,19}$

External PAN to pull funds from.

senderCardExpiryDate
required
string^\d{4}-(0[1-9]|1[0-2])$

External PAN expiry in YYMM format.

senderCurrencyCode
required
string

3-letter ISO currency code (e.g., USD, AED).

initiationId
string

Optional OTP initiation ID for request.

otpCode
string

Optional OTP for added security (if enforced).

Responses

Request samples

Content type
application/json
{
  • "cardId": "60428fb-0b16-4d72-854a-1f70adde6435",
  • "amount": 100,
  • "senderPrimaryAccountNumber": "4123709730000007",
  • "senderCardExpiryDate": "2026-08",
  • "senderCurrencyCode": "AED",
  • "initiationId": "4ed51ccf-d178-4c41-98d0-1397ff4ee329",
  • "otpCode": "632618"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "cardId": "60428fb-0b16-4d72-854a-1f70adde6435",
  • "amount": 100,
  • "senderPrimaryAccountNumber": "4123709730000007",
  • "senderCardExpiryDate": "2026-08",
  • "senderCurrencyCode": "AED",
  • "initiationId": "4ed51ccf-d178-4c41-98d0-1397ff4ee329",
  • "otpCode": "632618"
}

Get list of VISA funds sources

This API is used to retrieve the list of VISA funds sources.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "sourceOfFunds": [
    ]
}

Get list of VISA payment purposes

This API is used to retrieve the list of VISA payment purposes.

Authorizations:
apikey

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "remittancePurposes": [
    ]
}

Get indicative rates

This API is used to check indicative exchange rates.

Authorizations:
apikey
Request Body schema: application/json
required

Indicative rates request.

destination_currency_code
required
string

ISO_4217 numeric currency code.

source_currency_code
required
string

ISO_4217 numeric currency code.

source_amount
string

Source amount for conversion.

destination_amount
string

Destination amount for conversion.

payout_method
string (VisaDirectPayoutMethod)
Enum: "B" "W"

Visa Direct Payout Method.

quote_id_required
boolean
Default: false

Optional field with default value as false.

Responses

Request samples

Content type
application/json
{
  • "destination_currency_code": "840",
  • "source_currency_code": "784",
  • "source_amount": "string",
  • "destination_amount": "string",
  • "payout_method": "B",
  • "quote_id_required": false
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "destination_currency_code": "840",
  • "source_currency_code": "784",
  • "source_amount": "string",
  • "destination_amount": "string",
  • "conversion_rate": "string",
  • "quote_id": "string",
  • "quote_id_expiry_date_time": "2019-08-24T14:15:22Z"
}

Push funds transaction

This API is used to push funds transaction.

Authorizations:
apikey
Request Body schema: application/json
required

Push funds request.

cardId
required
string

Sender card ID, that is used to fetch sender information along with for amount debit purpose.

initiationId
string

The unique OTP identifier of the sender.

otpCode
string

OTP code.

recipientType
required
string (PushFundsRecipientType)
Enum: "PAN" "ALIAS"

Either “PAN” or “Alias” to identify recipient card.

amount
required
number decimal places <= 3 [ 0 .. 999999999.999 ]

The transaction amount to be delivered to the recipient.

recipientAccountType
required
string
Default: "00"

This is used to identify the account type of the recipientPrimaryAccountNumber in the request (00-Not applicable, 10-Saving account, 20-Checking account, 30-Credit card account, 40-Universal account).

recipientPrimaryAccountNumber
required
string

PAN or Alias (if “recipientType” is Alias than Alias value and if “recipientType” is PAN than PAN value).

recipientName
required
string

This field contains the recipient's name and is required for cross-border enhanced money transfer done with Visa cards.

sourceOfFundsCode
required
string

Visa prepaid.

purposeOfPayment
required
string

This is an alphanumeric value. Purpose of payment is required in certain markets to clearly identify the purpose of the payment based on the standard values defined for respective market.

Responses

Request samples

Content type
application/json
{
  • "cardId": "60428fb-0b16-4d72-854a-1f70adde6435",
  • "initiationId": "a33c1cc7-f565-4c3d-8147-c70b9db00e0f",
  • "otpCode": "480212",
  • "recipientType": "PAN",
  • "amount": 3,
  • "recipientAccountType": "10",
  • "recipientPrimaryAccountNumber": "4060320000000127",
  • "recipientName": "Jamie M Bakari",
  • "sourceOfFundsCode": "03",
  • "purposeOfPayment": "Gift"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "actionCode": "00",
  • "responseCode": "V",
  • "transactionIdentifier": 4060320000000126,
  • "transmissionDateTime": "2018-11-09T22:52:46.000Z",
  • "prepaidBalance": "100",
  • "prepaidBalanceCurrency": "AED"
}

Get push funds transaction

This API is used to get push funds transaction status in case of asynchronous processing.

Authorizations:
apikey
path Parameters
statusIdentifier
required
string

Status identifier.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "actionCode": "00",
  • "responseCode": "V",
  • "transactionIdentifier": 4060320000000126,
  • "transmissionDateTime": "2018-11-09T22:52:46.000Z"
}

Validate payout transaction

This API used to validate VISA Payout Transaction.

Authorizations:
apikey
Request Body schema: application/json
required

Validate payout request.

payoutMethod
required
string (VisaDirectPayoutMethod)
Enum: "B" "W"

Visa Direct Payout Method.

required
object (VisaDirectPayoutRecipientDetail)

Payout Recipient Details.

object (VisaDirectPayoutSenderDetail)
required
object (VisaDirectPayoutTransactionDetail)

Transaction Details.

cardId
string

Unique identifier of the card. One of cardId or walletId must be provided.

walletId
string

Unique identifier of the wallet. One of cardId or walletId must be provided.

Array of objects (VisaDirectExternalFeeDetail)

An array of data.

Responses

Request samples

Content type
application/json
{
  • "payoutMethod": "B",
  • "recipientDetail": {
    },
  • "senderDetail": {
    },
  • "transactionDetail": {
    },
  • "cardId": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "walletId": "4de56088-fdfc-31f2-83fa-fe6c3f66389a",
  • "externalFeeDetails": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "validationResultCode": "VALID",
  • "validationDetails": [
    ]
}

Perform Payout Transaction

This API used to perform VISA Payout Transaction.

Authorizations:
apikey
Request Body schema: application/json
required

Payout request.

payoutMethod
required
string (VisaDirectPayoutMethod)
Enum: "B" "W"

Visa Direct Payout Method.

required
object (VisaDirectPayoutRecipientDetail)

Payout Recipient Details.

object (VisaDirectPayoutSenderDetail)
required
object (VisaDirectPayoutTransactionDetail)

Transaction Details.

cardId
string

Unique identifier of the card. One of cardId or walletId must be provided.

walletId
string

Unique identifier of the wallet. One of cardId or walletId must be provided.

initiationId
string

Unique identifier of the OTP verification..

otpCode
string

OTP Code value.

quoteId
string

Optional unique identifier of FX rate quote.

referenceId
string <= 100 characters

Optional reference identifier (This field can be used to link payout transaction with invoice or order).

Array of objects (VisaDirectExternalFeeDetail)

Optional external fee details.

Responses

Request samples

Content type
application/json
{
  • "payoutMethod": "B",
  • "recipientDetail": {
    },
  • "senderDetail": {
    },
  • "transactionDetail": {
    },
  • "cardId": "8a54f913-b036-4bfa-8a3b-35fe2b9e1538",
  • "walletId": "8a54f913-b036-4bfa-8a3b-35fe2b9e1538",
  • "initiationId": "af3934dc-7648-48b1-ae5a-4d118493adea",
  • "otpCode": "8781080",
  • "quoteId": "b33934dc-7648-48b1-ae5a-4d118493ad12",
  • "referenceId": "TRX-12345689",
  • "externalFeeDetails": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "transactionDetail": {
    }
}

Get VisaDirect payout transaction details

This API used to retrieve VisaDirect payout transaction details.

Authorizations:
apikey
query Parameters
id
required
string

ID value.

idType
required
string

ID type (CLIENT_REFERENCE_ID, PAYOUT_ID).

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "payoutMethod": "B",
  • "transactionDetail": {
    }
}

Delete VisaDirect payout transaction

This API used to delete a VisaDirect payout transaction.

Authorizations:
apikey
query Parameters
id
required
string

ID value.

idType
required
string

ID type (CLIENT_REFERENCE_ID, PAYOUT_ID).

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "transactionDetail": {
    }
}

Get VisaDirect corridor config

This API is used to retrieve VisaDirect corridor config.

Authorizations:
apikey
query Parameters
corridor
required
string
Example: corridor=Pakistan

The corridor.

entity
required
string
Example: entity=SENDER

The entity.

entity_type
string
Example: entity_type=I

Applicable only when entity is SENDER or RECIPIENT.

currency
string

Recipient currency. Example EUR

use_base_currency_for_non_ach
boolean

applicable only when currency is provided.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "corridor": "Pakistan",
  • "entity": "SENDER",
  • "entity_type": "I",
  • "fields": [
    ],
  • "conditional_fields": [
    ],
  • "active": true,
  • "currency": "string",
  • "ach_type": "ACH",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get VisaDirect corridor config by country code

This API is used to retrieve VisaDirect corridor config by country code.

Authorizations:
apikey
query Parameters
country_code
required
string

The country code.

entity
required
string

The entity.

entity_type
string

Applicable only when entity is SENDER or RECIPIENT.

currency
string

Recipient currency. Example EUR

use_base_currency_for_non_ach
boolean

applicable only when currency is provided.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "corridor": "Pakistan",
  • "entity": "SENDER",
  • "entity_type": "I",
  • "fields": [
    ],
  • "conditional_fields": [
    ],
  • "active": true,
  • "currency": "string",
  • "ach_type": "ACH",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z"
}

Get VisaDirect purpose of payment list

This API is used to retrieve VisaDirect purpose of payment list.

Authorizations:
apikey
query Parameters
corridor
required
string
Example: corridor=India

The corridor.

sender_type
required
string
Example: sender_type=I

The sender type.

recipient_type
required
string
Example: recipient_type=C

The recipient type.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "corridor": "Pakistan",
  • "payment_purposes": [
    ]
}

Invoice management

This section includes invoice management related APIs.

Get payment invoice details

This API is used to get payment invoice details.

Authorizations:
apikey
query Parameters
invoice_id
string

The unique identifier of invoice.

beneficiary_id
string

The unique identifier of beneficiary.

invoice_processing_id
string

Invoice processing ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "invoice_id": "INV-001",
  • "invoice_processing_id": "68e5092dd01a2b40b52dabb5",
  • "invoice_translation_id": "68e97639406790346b5",
  • "beneficiary_id": "4dc61d1d-afe5-4378-ab97-3812d5dee596",
  • "payment_method": "VISA_DIRECT",
  • "invoice_validity": "2012-05-04",
  • "transaction_amount_in_fc": 123.45,
  • "transaction_amount_in_lc": 123.45,
  • "original_invoice_data": {
    },
  • "version": 0,
  • "upload_refs": [
    ],
  • "upload_versioned_refs": [
    ],
  • "status": "PENDING_PROCESSING",
  • "remarks": "Some info",
  • "normalized_invoice_data": {
    },
  • "validation_details": [
    ],
  • "ml_extraction_results": "Some results",
  • "payment_details": "Some payment details",
  • "invoice_details": "Some invoice details"
}

Update payment invoice status

This API is used to update payment invoice status.

Authorizations:
apikey
path Parameters
invoice_processing_id
required
string

Invoice processing ID.

Request Body schema: application/json
required
remarks
string

Free form text to log remarks.

status
required
string (InvoiceProcessingStatus)
Enum: "PENDING_PROCESSING" "PENDING_REVIEW" "APPROVED" "REJECTED"

Invoice Processing Status.

Responses

Request samples

Content type
application/json
{
  • "remarks": "Some info",
  • "status": "PENDING_PROCESSING"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "invoice_id": "INV-001",
  • "invoice_processing_id": "68e5092dd01a2b40b52dabb5",
  • "invoice_translation_id": "68e97639406790346b5",
  • "beneficiary_id": "4dc61d1d-afe5-4378-ab97-3812d5dee596",
  • "payment_method": "VISA_DIRECT",
  • "invoice_validity": "2012-05-04",
  • "transaction_amount_in_fc": 123.45,
  • "transaction_amount_in_lc": 123.45,
  • "original_invoice_data": {
    },
  • "version": 0,
  • "upload_refs": [
    ],
  • "upload_versioned_refs": [
    ],
  • "status": "PENDING_PROCESSING",
  • "remarks": "Some info",
  • "normalized_invoice_data": {
    },
  • "validation_details": [
    ],
  • "ml_extraction_results": "Some results",
  • "payment_details": "Some payment details",
  • "invoice_details": "Some invoice details"
}

Upload payment invoice

This API is used to upload payment invoice.

Authorizations:
apikey
Request Body schema: multipart/form-data
required
invoice_id
required
string

The unique identifier of invoice.

beneficiary_id
required
string

The unique identifier of beneficiary.

payment_method
string

The payment method.

invoice_validity
string <date>

Invoice validity date.

total_amount
number <decimal>

The total amount.

payment_currency
string

The payment currency.

vendor_name
string

The vendor name.

bill_date
string <date>

The billing date.

invoice_number
string

The invoice number.

vendor_address
string

The transaction code.

bill_number
string

The billing number.

description_of_goods_and_services
string

The vendor email address.

vendor_trn_number
string

The vendor TRN number.

vendor_country
string

The vendor country.

vendor_city
string

The vendor city.

vendor_account_number
string

The vendor account number.

vendor_account_name
string

The vendor account name.

vendor_iban
string

The vendor IBAN.

vendor_bank_address
string

The vendor bank address.

vendor_branch_name
string

The vendor branch name.

vendor_branch_address
string

The vendor branch address.

final_destination_country
string

The final destination country.

transaction_amount_in_lc
number <decimal>

The transaction amount in local currency.

transaction_amount_in_fc
number <decimal>

The transaction amount in foreign currency.

payment_destination_id
string

The payment destination id.

file1
string <binary>

The file to be uploaded.

file2
string <binary>

The file to be uploaded.

file3
string <binary>

The file to be uploaded.

file4
string <binary>

The file to be uploaded.

file5
string <binary>

The file to be uploaded.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "invoice_id": "INV-001",
  • "invoice_processing_id": "68e5092dd01a2b40b52dabb5",
  • "invoice_translation_id": "68e97639406790346b5",
  • "beneficiary_id": "4dc61d1d-afe5-4378-ab97-3812d5dee596",
  • "payment_method": "VISA_DIRECT",
  • "invoice_validity": "2012-05-04",
  • "transaction_amount_in_fc": 123.45,
  • "transaction_amount_in_lc": 123.45,
  • "original_invoice_data": {
    },
  • "version": 0,
  • "upload_refs": [
    ],
  • "upload_versioned_refs": [
    ]
}

Upload payment invoice

This API is used to re-uploading payment invoice.

Authorizations:
apikey
Request Body schema: multipart/form-data
required
invoice_id
required
string

The unique identifier of invoice.

beneficiary_id
required
string

The unique identifier of beneficiary.

payment_method
string

The payment method.

invoice_validity
string <date>

Invoice validity date.

total_amount
number <decimal>

The total amount.

payment_currency
string

The payment currency.

vendor_name
string

The vendor name.

bill_date
string <date>

The billing date.

invoice_number
string

The invoice number.

vendor_address
string

The vendor address.

vendor_phone_number
string

The vendor phone number.

vendor_email_address
string

The vendor email address.

vendor_trn_number
string

The vendor TRN number.

vendor_country
string

The vendor country.

vendor_city
string

The vendor city.

vendor_account_number
string

The vendor account number.

vendor_account_name
string

The vendor account name.

vendor_iban
string

The vendor IBAN.

vendor_bank_address
string

The vendor bank address.

vendor_branch_name
string

The vendor branch name.

vendor_branch_address
string

The vendor branch address.

final_destination_country
string

The final destination country.

transaction_amount_in_lc
number <decimal>

The transaction amount in local currency.

transaction_amount_in_fc
number <decimal>

The transaction amount in foreign currency.

file1
string <binary>

The file to be uploaded.

file2
string <binary>

The file to be uploaded.

file3
string <binary>

The file to be uploaded.

file4
string <binary>

The file to be uploaded.

file5
string <binary>

The file to be uploaded.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "invoice_id": "INV-001",
  • "invoice_processing_id": "68e5092dd01a2b40b52dabb5",
  • "invoice_translation_id": "68e97639406790346b5",
  • "beneficiary_id": "4dc61d1d-afe5-4378-ab97-3812d5dee596",
  • "payment_method": "VISA_DIRECT",
  • "invoice_validity": "2012-05-04",
  • "transaction_amount_in_fc": 123.45,
  • "transaction_amount_in_lc": 123.45,
  • "original_invoice_data": {
    },
  • "version": 0,
  • "upload_refs": [
    ],
  • "upload_versioned_refs": [
    ]
}

Get list of uploaded invoices

This API is used to get list of uploaded invoices.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

beneficiary_id
string

The unique identifier of beneficiary.

status
string

The status.

invoice_id
string

The unique identifier of invoice.

date
string <date>

The date.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Process invoice payment

This API is used to process invoice payment.

Authorizations:
apikey
path Parameters
invoice_id
required
string

The unique identifier of invoice.

beneficiary_id
required
string

The unique identifier of beneficiary.

Request Body schema: application/json
required
payment_method
required
string (InvoicePaymentMethod)
Value: "VISADIRECT"

Invoice Payment Method.

payment_destination_id
string

Conditional field, required only if beneficiary has multiple payment destinations

object (VisaPaymentDetails)

Responses

Request samples

Content type
application/json
{
  • "payment_method": "VISADIRECT",
  • "payment_destination_id": "string",
  • "visa_payment_details": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "transaction_id": "5efss08-0558-47ac-b722-4e45r176fb4f",
  • "status": "COMPLETED",
  • "payment_method": "VISADIRECT",
  • "visa_response": {
    }
}

Get corporate beneficiary document processing details

This API is used to retrieve corporate beneficiary document processing details.

Authorizations:
apikey
query Parameters
beneficiary_id
string

The unique identifier of beneficiary.

processing_id
string

The processing ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Create corporate beneficiary

This API is used to create corporate beneficiary.

Authorizations:
apikey
Request Body schema: application/json
required
user_id
required
string

Unique identifier of the user.

business_type
required
string (CorporateBeneficiaryBusinessType)
Enum: "BUSINESS" "INDIVIDUAL"
beneficiary_name
string

Beneficiary name.

legal_business_name
string

Legal business name.

business_registration_number
string

Business registration number.

country_of_incorporation
string

Country of incorporation.

address
string

Beneficiary address.

email
string <= 80 characters ^[_A-Za-z0-9-\+]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0...

Beneficiary email.

object (CorporateBeneficiaryPaymentDetails)

Corporate Beneficiary Payment Details.

Array of objects (CorporateBeneficiaryPaymentDetails) non-empty

Responses

Request samples

Content type
application/json
{
  • "user_id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "business_type": "BUSINESS",
  • "beneficiary_name": "Ben_Test_109",
  • "legal_business_name": "BL01",
  • "business_registration_number": "7458",
  • "country_of_incorporation": "UKR",
  • "address": "string",
  • "email": "string",
  • "payment_details": {
    },
  • "advanced_payment_details": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "user_id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "business_type": "BUSINESS",
  • "beneficiary_name": "Ben_Test_109",
  • "legal_business_name": "BL01",
  • "business_registration_number": "7458",
  • "country_of_incorporation": "UKR",
  • "address": "WSx",
  • "payment_details": {
    },
  • "advanced_payment_details": [
    ],
  • "status": "IN_REVIEW",
  • "status_reason_code": "R1",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "uploaded_duration_in_hours": "N/A"
}

Get list of corporate beneficiaries

This API is used to get list of corporate beneficiaries.

Authorizations:
apikey
query Parameters
user_id
required
string

User ID to filter beneficiaries.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "beneficiaries": [
    ]
}

Update corporate beneficiary

This API is used to update corporate beneficiary.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of corporate beneficiary.

Request Body schema: application/json
required
business_type
string (CorporateBeneficiaryBusinessType)
Enum: "BUSINESS" "INDIVIDUAL"
beneficiary_name
string

Beneficiary name.

legal_business_name
string

Legal business name.

business_registration_number
string

Business registration number.

country_of_incorporation
string

Country of incorporation.

address
string

Beneficiary address.

email
string <= 80 characters ^[_A-Za-z0-9-\+]+(\.[_A-Za-z0-9-]+)*@[A-Za-z0...

Email.

object (CorporateBeneficiaryPaymentDetails)

Corporate Beneficiary Payment Details.

Array of objects (CorporateBeneficiaryPaymentDetails) non-empty

Responses

Request samples

Content type
application/json
{
  • "business_type": "BUSINESS",
  • "beneficiary_name": "Ben_Test_109",
  • "legal_business_name": "BL01",
  • "business_registration_number": "7458",
  • "country_of_incorporation": "UKR",
  • "address": "WSx",
  • "email": "telol@wwa.in",
  • "payment_details": {
    },
  • "advanced_payment_details": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "user_id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "business_type": "BUSINESS",
  • "beneficiary_name": "Ben_Test_109",
  • "legal_business_name": "BL01",
  • "business_registration_number": "7458",
  • "country_of_incorporation": "UKR",
  • "address": "WSx",
  • "payment_details": {
    },
  • "advanced_payment_details": [
    ],
  • "status": "IN_REVIEW",
  • "status_reason_code": "R1",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "uploaded_duration_in_hours": "N/A"
}

Get specific corporate beneficiary

This API is used to get specific corporate beneficiary.

Authorizations:
apikey
path Parameters
id
required
string

Beneficiary ID to retrieve.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "user_id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "business_type": "BUSINESS",
  • "beneficiary_name": "Ben_Test_109",
  • "legal_business_name": "BL01",
  • "business_registration_number": "7458",
  • "country_of_incorporation": "UKR",
  • "address": "WSx",
  • "payment_details": {
    },
  • "advanced_payment_details": [
    ],
  • "status": "IN_REVIEW",
  • "status_reason_code": "R1",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "uploaded_duration_in_hours": "N/A"
}

Update corporate beneficiary status

This API is used to update corporate beneficiary status.

Authorizations:
apikey
path Parameters
id
required
string

The unique identifier of corporate beneficiary.

Request Body schema: application/json
required
status
required
string (CorporateBeneficiaryStatus)
Enum: "IN_REVIEW" "APPROVED" "REJECTED" "SUSPENDED" "ARCHIVED" "TERMINATED"

Corporate Beneficiary Status.

status_reason_code
required
string (CorporateBeneficiaryStatusReasonCode)
Enum: "R1" "A1" "AR" "S1" "SR" "T1" "D1" "T2"

Corporate Beneficiary Status Reason Code.

Responses

Request samples

Content type
application/json
{
  • "status": "IN_REVIEW",
  • "status_reason_code": "R1"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "user_id": "5de56088-fdfc-31f2-83fa-fe6c3f66389b",
  • "business_type": "BUSINESS",
  • "beneficiary_name": "Ben_Test_109",
  • "legal_business_name": "BL01",
  • "business_registration_number": "7458",
  • "country_of_incorporation": "UKR",
  • "address": "WSx",
  • "payment_details": {
    },
  • "advanced_payment_details": [
    ],
  • "status": "IN_REVIEW",
  • "status_reason_code": "R1",
  • "created": "2012-05-04T19:42:32.987Z",
  • "modified": "2012-05-04T19:42:32.987Z",
  • "uploaded_duration_in_hours": "N/A"
}

Download invoice file

This API is used to download invoice file.

Authorizations:
apikey
path Parameters
beneficiary_id
required
string

Unique identifier of the beneficiary.

invoice_id
required
string

Invoice ID.

file_id
required
string

Unique identifier of the file.

Responses

Download document file

This API is used to download beneficiary document file.

Authorizations:
apikey
path Parameters
beneficiary_id
required
string

Unique identifier of the beneficiary.

document_id
required
string

Beneficiary document ID.

Responses

Upload corporate beneficiary document

This API is used to upload corporate beneficiary document.

Authorizations:
apikey
Request Body schema: multipart/form-data
required
specify_type
string

Specify type.

summary_provided
string

Provided summary.

word_count
integer

Word count.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "beneficiary_id": "4dc61d1d-afe5-4378-ab97-3812d5dee596",
  • "processing_id": "68e5092dd01a2b40b52dabb5",
  • "document_id": "967584896945"
}

Credit

This section includes credit related APIs.

Create holiday calendar

This API is used to create a holiday calendar.

Authorizations:
apikey
Request Body schema: application/json
required

Creates new holiday calendar setting

id
string <= 36 characters

A unique identifier of the profile.

calendar_year
required
integer [ 2000 .. 3000 ]

Specifies the year for which the calendar applies.

calendar_description
string

Brief description of the calendar's purpose.

non_business_days
Array of strings (WeekDays)
Items Enum: "MONDAY" "TUESDAY" "WEDNESDAY" "THURSDAY" "FRIDAY" "SATURDAY" "SUNDAY"

The non business days types.

shift_holiday_to_next_working_day
boolean

Specifies whether the holiday should be automatically moved to the next working day if it falls on a non-business day. A value of "(Y)es" indicates that the holiday will be shifted to the next business day.

copy_calendar_from_last_year
boolean

Determines whether the holiday calendar should automatically carry over the same dates and settings from the previous year. A value of "(Y)es" will duplicate last year’s calendar for the current year.

auto_sync_calendar_from_external_source
boolean

Indicates if the holiday calendar should synchronize automatically with an external calendar source. A value of "(Y)es" enables automatic syncing, ensuring the holiday calendar stays updated.

is_active
boolean

Defines whether the holiday calendar is currently active. An active calendar is used for due date calculations and holiday scheduling, while an inactive calendar is disregarded by the system.

select_source
string

Specifies the external source from which the holiday calendar will sync.

Array of objects (Holiday)

An array of data.

Responses

Request samples

Content type
application/json
{
  • "id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "calendar_year": 2026,
  • "calendar_description": "Some info",
  • "non_business_days": [
    ],
  • "shift_holiday_to_next_working_day": "Yes",
  • "copy_calendar_from_last_year": "Yes",
  • "auto_sync_calendar_from_external_source": "Yes",
  • "is_active": "Yes",
  • "select_source": "Google Calendar",
  • "holidays": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "b66d3442-3197-4a05-b91e-7f4bf56dec69",
  • "calendar_year": 2026,
  • "calendar_description": "Some info",
  • "non_business_days": [
    ],
  • "shift_holiday_to_next_working_day": "Yes",
  • "copy_calendar_from_last_year": "Yes",
  • "auto_sync_calendar_from_external_source": "Yes",
  • "is_active": "Yes",
  • "select_source": "Google Calendar",
  • "holidays": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "updated": "2012-05-04T19:42:32.987Z"
}

Get list of holiday calendars

This API is used to get list of holiday calendars.

Authorizations:
apikey
query Parameters
limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

sort_by
string

Using this parameter you can sort by field name.

order_by
string
Enum: "ASC" "DESC"

Using this parameter you can make ascending or descending order.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get specific holiday calendar

This API is used to get specific holiday calendars.

Authorizations:
apikey
path Parameters
id
required
string

Holiday calendar ID.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "b66d3442-3197-4a05-b91e-7f4bf56dec69",
  • "calendar_year": 2026,
  • "calendar_description": "Some info",
  • "non_business_days": [
    ],
  • "shift_holiday_to_next_working_day": "Yes",
  • "copy_calendar_from_last_year": "Yes",
  • "auto_sync_calendar_from_external_source": "Yes",
  • "is_active": "Yes",
  • "select_source": "Google Calendar",
  • "holidays": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "updated": "2012-05-04T19:42:32.987Z"
}

Update holiday calendar

This API is used to update specific holiday calendar.

Authorizations:
apikey
path Parameters
id
required
string

Holiday Calendar ID.

Request Body schema: application/json
required

Updates holiday calendar setting.

calendar_id
string <= 36 characters

A unique identifier of the calendar.

calendar_year
required
integer [ 2000 .. 3000 ]

Specifies the year for which the calendar applies.

calendar_description
string

Brief description of the calendar's purpose.

non_business_days
Array of strings (WeekDays)
Items Enum: "MONDAY" "TUESDAY" "WEDNESDAY" "THURSDAY" "FRIDAY" "SATURDAY" "SUNDAY"

The non business days types.

shift_holiday_to_next_working_day
boolean

Specifies whether the holiday should be automatically moved to the next working day if it falls on a non-business day. A value of "(Y)es" indicates that the holiday will be shifted to the next business day.

copy_calendar_from_last_year
boolean

Determines whether the holiday calendar should automatically carry over the same dates and settings from the previous year. A value of "(Y)es" will duplicate last year’s calendar for the current year.

auto_sync_calendar_from_external_source
boolean

Indicates if the holiday calendar should synchronize automatically with an external calendar source. A value of "(Y)es" enables automatic syncing, ensuring the holiday calendar stays updated.

is_active
boolean

Defines whether the holiday calendar is currently active. An active calendar is used for due date calculations and holiday scheduling, while an inactive calendar is disregarded by the system.

select_source
string

Specifies the external source from which the holiday calendar will sync.

Array of objects (Holiday)

An array of data.

Responses

Request samples

Content type
application/json
{
  • "calendar_id": "d066a80f-e641-4045-8a80-54841e4a7458",
  • "calendar_year": 2026,
  • "calendar_description": "Some info",
  • "non_business_days": [
    ],
  • "shift_holiday_to_next_working_day": "Yes",
  • "copy_calendar_from_last_year": "Yes",
  • "auto_sync_calendar_from_external_source": "Yes",
  • "is_active": "Yes",
  • "select_source": "Google Calendar",
  • "holidays": [
    ]
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "id": "b66d3442-3197-4a05-b91e-7f4bf56dec69",
  • "calendar_year": 2026,
  • "calendar_description": "Some info",
  • "non_business_days": [
    ],
  • "shift_holiday_to_next_working_day": "Yes",
  • "copy_calendar_from_last_year": "Yes",
  • "auto_sync_calendar_from_external_source": "Yes",
  • "is_active": "Yes",
  • "select_source": "Google Calendar",
  • "holidays": [
    ],
  • "created": "2012-05-04T19:42:32.987Z",
  • "updated": "2012-05-04T19:42:32.987Z"
}

Get holiday calendar setting by year

This API is used to get holiday calendar setting by year.

Authorizations:
apikey
path Parameters
year
required
string

Holiday calendar year.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Get list of cardholder statement stats

This API is used to retrieve cardholder statement statistics.

Authorizations:
apikey
Request Body schema: application/json
required
account_id
required
string

Identifier for the account to which the statement is attached.

statements_limit
integer [ 1 .. 12 ]

Number of statements to be retrieved.

statement_date
string <date>

Statement date from which statements will be retrieved. In MM/DD/YYYY format.

Responses

Request samples

Content type
application/json
{
  • "account_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "statements_limit": 1,
  • "statement_date": "10/01/2023"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "account_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "statementCurrencyCode": "USD",
  • "statement_stats": [
    ]
}

Dispute credit card transaction

This API is used to dispute a credit card transaction.

Authorizations:
apikey
Request Body schema: application/json
required
account_id
required
string

The identifier of the account for which a dispute is to be filed.

card_id
required
string

The identifier of the card for which a dispute is to be filed.

transaction_id
required
string

The identifier of the transaction for which a dispute is to be filed.

dispute_amount
required
number <decimal>

Transaction amount to be disputed. It should be greater than zero and less than or equal to transaction amount.

dispute_reason
required
string (DisputeReason)
Enum: "DUP" "CHR" "MDR" "MNR" "MDD" "OCT" "CPS" "POM" "APD" "AND" "UTC" "CSC" "CWC" "OTR"

DUP - CHARGED_TWICE_FOR_THE_SAME_TRANSACTION(DUPLICATE)

CHR - CANCELLATION(HOTEL,GOOD,SERVICES)

MDR - MERCHANDISE_WAS_RETURNED

MNR - MERCHANDISE_NOT_RECEIVED

MDD - MERCHANDISE_WAS_EITHER_DAMAGED_OR_DEFECTIVE

OCT - OVERCHARGED_FOR_A_TRANSACTION

CPS - CREDIT_POSTED_AS_A_SALE

POM - TRANSACTION_PAID_BY_OTHER_MEANS

APD - ATM(PARTIAL_DISPENSED)

AND - ATM(NON_DISPENSED)

UTC - UNAUTHORIZED_CHARGE

CSC - CHARGED_AFTER_SUBSCRIPTION_CANCELLATION

CWC - CHARGED_WITHOUT_CONSENT

OTR - OTHERS

dispute_description
string

Free form text description for this dispute.

Responses

Request samples

Content type
application/json
{
  • "account_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_id": "8889a80f-e641-4045-8a80-54841e4a7458",
  • "transaction_id": "d909a80f-e641-4045-8a80-54841e4a7458",
  • "dispute_amount": 100,
  • "dispute_reason": "DUP",
  • "dispute_description": "Some info"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "dispute_id": "d294a80f-e641-4045-8a80-54841e4a7458",
  • "status": "LOGGED",
  • "log_date_time": "2012-05-04T19:42:32.987Z"
}

Get details of disputed transactions

This API is used to get the details of disputed transactions.

Authorizations:
apikey
query Parameters
card_id
string

The identifier of the card for which a dispute is filed.

account_id
string

The identifier of the account for which a dispute is filed.

transaction_id
string

The identifier of the transaction for which a dispute is filed.

dispute_id
string

A unique identifier of the dispute that is filed.

date_from
string <date>

A date from which dispute was filed.

date_to
string <date>

A date to which dispute was filed.

Responses

Response samples

Content type
application/json;charset=UTF-8
[
  • {
    }
]

Update details of disputed transactions

This API is used to update details of disputed transactions.

Authorizations:
apikey
path Parameters
dispute_id
required
string

A unique identifier of the dispute that is filed.

Request Body schema: application/json
required
status
string (DisputeStatus)
Enum: "LOGGED" "IN_PROGRESS" "CARDHOLDER_WON" "MERCHANT_WON" "CARDHOLDER_WON_FRAUD_LOSS"

Dispute status.

remarks
string

Free-text comments or resolution notes.

resolution_date
string <date-time>

Date and time of resolution.

Responses

Request samples

Content type
application/json
{
  • "status": "LOGGED",
  • "remarks": "Some info",
  • "resolution_date": "2012-05-04T19:42:32.987Z"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "card_id": "d294a80f-e641-4045-8a80-t4841e4a7458",
  • "transaction_id": "8894a80f-e641-4045-8a80-54841e4a7458",
  • "dispute_id": "dhhha80f-e641-4045-8a80-54841e4a7458",
  • "dispute_date": "09/30/2023",
  • "dispute_status": "LOGGED",
  • "dispute_amount": 100,
  • "dispute_reason": "DUP",
  • "dispute_description": "Some info"
}

Visa Click to Pay

APIs for managing Visa Click to Pay enrollments, including creating, updating, deleting, and synchronizing consumer and payment instrument data.

Retrieve Click to Pay enrollment details

Retrieves Click to Pay enrollment details for users and their associated cards. The endpoint can return all enrollments or filter results using query parameters.

Authorizations:
apikey
query Parameters
user_id
string

Filter results by user ID.

card_id
string

Filter results by card ID.

scheme
string
Enum: "VISA" "MASTERCARD"

Filter results by card scheme.

status
string
Enum: "ACTIVE" "DELETED"

Filter results by user or card status.

limit
integer <int32>

This is the maximum number of objects that may be returned. A query may return fewer than the value of limit once reached the end of the list of data.

after
string

This is the cursor that points to the end of the page of data that has been returned.

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "after": "string",
  • "has_more": true,
  • "data": [
    ]
}

Create Visa Click to Pay enrollment data

Authorizations:
apikey
Request Body schema: application/json
required
card_id
required
string

Unique identifier of the card

object (VisaCtPBillingAddress)

Responses

Request samples

Content type
application/json
{
  • "card_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "billing_address": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "token": "string",
  • "status": "string"
}

Delete Visa Click to Pay enrollment data

Authorizations:
apikey
Request Body schema: application/json
required
user_id
required
string

Unique identifier of the user

card_id
string

Unique identifier of the card

Responses

Request samples

Content type
application/json
{
  • "user_id": "d089a80f-e641-4045-8a80-54841e4a7458",
  • "card_id": "d089a80f-e641-4045-8a80-54841e4a7458"
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "token": "string",
  • "status": "string"
}

Synchronize Visa Click to Pay consumer data

Triggers an asynchronous synchronization of the consumer's profile with Visa Click to Pay. This endpoint updates user-related information (e.g., identity or contact details) for an already enrolled user. The operation is processed in the background and does not affect

Authorizations:
apikey
path Parameters
userId
required
string

Unique identifier of the user

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "token": "string",
  • "status": "string"
}

Update Visa Click to Pay payment instruments

Authorizations:
apikey
path Parameters
cardId
required
string

Unique identifier of the card

Request Body schema: application/json
object (VisaCtPBillingAddress)

Responses

Request samples

Content type
application/json
{
  • "billing_address": {
    }
}

Response samples

Content type
application/json;charset=UTF-8
{
  • "token": "string",
  • "status": "string"
}

Retrieve Visa Click to Pay enrollment by user ID

Authorizations:
apikey
path Parameters
userId
required
string

Enrollment ID

Responses

Response samples

Content type
application/json;charset=UTF-8
{
  • "data": [
    ]
}