API Documentation

This section provides details on the use of APIs, including sample requests and responses.

Environment:

There is basic two environment, PRODUCTION and PROD SANDBOX.
Base url will be shared by Card91 team.

Usage :

API list:

Sr. No.	Method Name	Description
1	Login with authorization token	Use to authenticate the user and fetch its detail
2	Get customer detail	Use to fetch customer detail
3	Get currency list	Use to fetch currency list
4	Get transaction list	Use to fetch transaction list
5	Get Card Settings	Use to fetch card setting
6	Set Card Settings	Use to set the card setting
7	Block Card	Block the card permanently
8	Freeze Card	Suspend the card temporarily
9	Card Load History List	History of card load
10	Get Trip List	Trip history of customer

Method 1: Login with authorization token

Description

This method allows you to authenticate user and respond with user details

Request parameters.

Method

POST

End Point

{baseurl}/mctc/v1/customer/login/token

Parameters

Attribute	Type	Description
mobile	string	Customer mobile number with "91".
sdkAuthToken	string	Token created from client application to get it validated through web hook configured on the the admin portal.
orgId	string	Organization id eg (OID24060#######7ID16561311).

Sample Request


{
    "mobile": "91989###7876",
    "sdkAuthToken": "F9123xyzzxsfswgsfdf",
    "orgId": "OID240605#######ID16561311"
}

Sample Response Header

In header response will contain the customer token on the key "Jwt_token" which then will be used to call rest of the api given below.

Header Name	Value
Jwt_token:	C91IP_NqP44YecjzTTI/TubfPiW*********GmPzRaf0UJJI= (Sample token)

Sample Response

Response contains user personal , document, address, employment detail and card program details.

{
    "documents": [
        {
            "id": 117,
            "validity": null,
            "version": null,
            "docType": "AIR_TICKET",
            "docUrl": "https://card91-np-docs.s3.ap-south-1.amazonaws.com/SANDBOX/FILE240821115921785ID17519472.jpg",
            "countryISOCode": null
        },
        {
            "id": 120,
            "validity": null,
            "version": null,
            "docType": "AIR_TICKET",
            "docUrl": "https://card91-np-docs.s3.ap-south-1.amazonaws.com/SANDBOX/FILE240903115924014ID11012550.png",
            "countryISOCode": null
        }
    ],
    "addresses": [
        {
            "id": 547,
            "addressType": "CURRENT_ADDRESS",
            "address1": "Tirumala P",
            "address2": "Koramangalaa",
            "landmark": "Police station",
            "city": "koramangala",
            "countryISOCode": "IND",
            "pinCode": "560066",
            "state": "Karnataka",
            "status": "ACTIVE"
        }
    ],
    "employmentDetails": [],
    "cardPrograms": [
        {
            "id": "CP240709122046100ID18366231",
            "imageUrl": null,
            "programName": "Sagar Thomas cook ",
            "network": "RUPAY",
            "issuer": "THOMAS COOK",
            "accountId": "767396723544",
            "status": "ACTIVE",
            "orgCardProgramId": 303,
            "cards": [
                {
                    "id": "CID240715054310293ID17085600",
                    "lastFour": "4760",
                    "state": "INACTIVE",
                    "type": "PHYSICAL"
                },
                {
                    "id": "CID240716181359139ID11104872",
                    "lastFour": "7817",
                    "state": "INACTIVE",
                    "type": "VIRTUAL"
                },
                {
                    "id": "CID240913110443475ID16827540",
                    "lastFour": "3359",
                    "state": "BLOCKED",
                    "type": "PHYSICAL"
                }
            ]
        }
    ],
    "id": "CUST2407150445######D15656664",
    "dob": "17-03-2001",
    "gender": "MALE",
    "mobile": "91900###028",
    "email": "[email protected]",
    "firstName": "Rajashekar",
    "internationalMobileNumber": null,
    "middleName": "",
    "lastName": "Manda",
    "nameOnCard": "Raj",
    "status": "APPROVED",
    "currencyCode": "USD",
    "lrsLimit": 250000.00,
    "usedLimit": 0.00,
    "availableLimit": 250000.00,
    "organizationConfig": {
        "selfLoad": false,
        "directLoad": true,
        "selfEncashment": false,
        "directEncashment": true,
        "kycDocRequired": true,
        "travelDocRequired": false,
        "splitTxnAllowed": false,
        "interCurrencyTransferAllowed": false,
        "loadRefNumberRequired": true,
        "encashmentRefNumberRequired": true,
        "defaultEmailAlert": true,
        "defaultDomesticSmsAlert": true,
        "defaultInternationalSmsAlert": false,
        "ecomAllowed": false,
        "atmAllowed": true,
        "posAllowed": true,
        "clAllowed": false,
        "ecomDefault": false,
        "atmDefault": false,
        "posDefault": false,
        "clDefault": false,
        "zoopEnabled": false
    },
    "panValue": "DUMPM6643T",
    "passportValue": "Y1444157",
    "passportFileNumber": "dummy",
    "passportValidity": "17-03-2040"
}}

Method 2: Get customer detail

Description

This method allows you to get user details, the response will remain the same loginwithauthtoken .
This method can act as refresh api as well.

Parameters to call the api.

Method

GET

End Point

{baseurl}/mctc/v1/customer/details?orgId=OID240605060#####7ID16561311

Parameters

Attribute	Type	Description
orgId	string	Organization id eg (OID240######057ID16561311).

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Response

{
    "documents": [ // Basic set of document attached to the user
        {
            "id": 117,
            "validity": null,
            "version": null,
            "docType": "AIR_TICKET",
            "docUrl": "https://card91-np-docs.s3.ap-south-1.amazonaws.com/SANDBOX/FILE240821115921785ID17519472.jpg",
            "countryISOCode": null
        },
        {
            "id": 120,
            "validity": null,
            "version": null,
            "docType": "AIR_TICKET",
            "docUrl": "https://card91-np-docs.s3.ap-south-1.amazonaws.com/SANDBOX/FILE240903115924014ID11012550.png",
            "countryISOCode": null
        }
    ],
    "addresses": [
        {
            "id": 547,
            "addressType": "CURRENT_ADDRESS",
            "address1": "Tirumala P",
            "address2": "Koramangalaa",
            "landmark": "Police station",
            "city": "koramangala",
            "countryISOCode": "IND",
            "pinCode": "560066",
            "state": "Karnataka",
            "status": "ACTIVE"
        }
    ],
    "employmentDetails": [],
    "cardPrograms": [
        {
            "id": "CP24070######D18366231",
            "imageUrl": null,
            "programName": "Sagar Thomas cook ",
            "network": "RUPAY",
            "issuer": "THOMAS COOK",
            "accountId": "767396723544",
            "status": "ACTIVE",
            "orgCardProgramId": 303,
            "cards": [
                {
                    "id": "CID24071###0293ID17085600",
                    "lastFour": "4760",
                    "state": "INACTIVE",
                    "type": "PHYSICAL"
                },
                {
                    "id": "CID2407161###39ID11104872",
                    "lastFour": "7817",
                    "state": "INACTIVE",
                    "type": "VIRTUAL"
                },
                {
                    "id": "CID240913####75ID16827540",
                    "lastFour": "3359",
                    "state": "BLOCKED",
                    "type": "PHYSICAL"
                }
            ]
        }
    ],
    "id": "CUST240715######3610ID15656664",
    "dob": "17-03-2001",
    "gender": "MALE",
    "mobile": "9190###00028",
    "email": "[email protected]",
    "firstName": "Rajashekar",
    "internationalMobileNumber": null,
    "middleName": "",
    "lastName": "Manda",
    "nameOnCard": "Raj",
    "status": "APPROVED",
    "currencyCode": "USD",
    "lrsLimit": 250000.00,
    "usedLimit": 0.00,
    "availableLimit": 250000.00,
    "organizationConfig": {
        "selfLoad": false,
        "directLoad": true,
        "selfEncashment": false,
        "directEncashment": true,
        "kycDocRequired": true,
        "travelDocRequired": false,
        "splitTxnAllowed": false,
        "interCurrencyTransferAllowed": false,
        "loadRefNumberRequired": true,
        "encashmentRefNumberRequired": true,
        "defaultEmailAlert": true,
        "defaultDomesticSmsAlert": true,
        "defaultInternationalSmsAlert": false,
        "ecomAllowed": false,
        "atmAllowed": true,
        "posAllowed": true,
        "clAllowed": false,
        "ecomDefault": false,
        "atmDefault": false,
        "posDefault": false,
        "clDefault": false,
        "zoopEnabled": false
    },
    "panValue": "DUMPM6643T",
    "passportValue": "Y1444157",
    "passportFileNumber": "dummy",
    "passportValidity": "17-03-2040"
}

Method 3: Get currency list

Description

This api allows you to fetch the user currency list associated to the account of the user.
Currency list include the currency code and balance.

Parameters to call the api.

Method

GET

End Point

{baseurl}/mctc/v1/customer/currency/balance?accountId=7673###723544

Parameters

Attribute	Type	Description
accountId	int	User account id (received on login with auth token)

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Response

{
    "accountCurrencyBalanceList": [
        {
            "balance": "0.00",
            "currencyCode": "AED",
            "priority": "1",
            "isActive": "OVERALL_FREEZE"
        }
    ],
    "splitTxnAllowed": false
}

Method 4: Get transaction list

Description

This method allows to fetch all the transaction associated with the user account.

Parameters to call the api.

Method

GET

End Point

{baseurl}/mctc/v1/customer/transactions/list?accountId=767###23544&page=1&perPage=10

Parameters

Attribute	Type	Description
accountId	int	User account id (received on login with auth token)
page	int	For pagination
perPage	int	Number of item per page

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Response

{
    "recordsCurrentPage": 1,
    "currentPage": 1,
    "totalPages": 1,
    "totalRecords": 1,
    "accountId": "767396723544",
    "transactions": [
        {
            "id": 788,
            "txnId": "TXN2407170508286315986972",
            "txnType": "ECOM",
            "txnCategory": "SALE",
            "currencyCode": "AED",
            "amount": 12.00,
            "baseCurrencyAmount": null,
            "baseCurrencyCode": null,
            "exchangeRate": null,
            "overallMarkup": null,
            "stan": "000000962602",
            "rrn": "053984833478",
            "rc": "1806",
            "switch_rc": null,
            "displayMessage": "Card not active",
            "eventType": "TRANSACTION",
            "mid": "6546",
            "tid": "4354",
            "reversalCount": 0,
            "mcc": "2222",
            "refundCount": 0,
            "cardId": "CID2407150###293ID17085600",
            "customerId": null,
            "network": "RUPAY",
            "settled": false,
            "fromAccount": null,
            "toAccount": null,
            "merchantName": "Raj",
            "merchantCity": "Madiwal",
            "merchantRegion": "MH",
            "merchantCountryCode": "IN",
            "merchantAddress": null,
            "merchantPostalCode": "400063",
            "merchantPhone": null,
            "latitude": "",
            "longitude": "",
            "orgCardProgramMapId": null,
            "nameOnCard": null,
            "cardLastFour": "4760",
            "aid": null,
            "tvr": null,
            "settlementDate": null,
            "transmissionDate": "2024-07-17 05:08:28",
            "localTxnDate": null,
            "txnDate": "2024-07-17 05:08:28",
            "orgId": null,
            "switchTxnId": "605747",
            "switchRefTxnId": "",
            "txnStatus": "DECLINED",
            "amountFlow": null,
            "entityType": "CUST",
            "entityId": "767396723544",
            "node": 0,
            "referenceTxnId": null
        }
    ]
}

Method 5: Get Card Settings

Description

This method is order to fetch the a particular card setting. Response include status and amount limits of different type of transaction based on currencies.

Parameters to call the api.

Method

GET

End Point

{baseurl}/mctc/v1/customer/limits/CARD/CID2407150####93ID17085600

Parameters

Attribute	Type	Description
CARD	string	Card id whose setting need to be fetched (eg. CID24071505####3ID17085600)

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Response

{
    "limits": [
        {
            "currency": "AED",
            "perAtmTxnLimit": 0.0000,
            "perOnlineTxnLimit": 0.0000,
            "perPosTxnLimit": 50000.0000,
            "perContactlessTxnLimit": 0.0000,
            "maxPerAtmTxnLimit": 90.0000,
            "maxPerOnlineTxnLimit": 0,
            "maxPerPosTxnLimit": 50000.0000,
            "maxPerContactlessTxnLimit": 0,
            "isContactLessAllowed": false,
            "isAtmLimitEnabled": false,
            "isOnlineLimitEnabled": false,
            "isPosLimitEnabled": true
        }
    ]
}

Method 6: Set Card Settings

Description

This method allows to set the card settings.

Parameters to call the api.

Method

POST

End Point

{baseurl}/mctc/v1/customer/limits/add

Parameters

Attribute	Type	Description
entityType	string	"CARD" in this case.
entityId	string	"Card id whose setting is being done
currency	string	Currency code received on currency list eg. "AED"
isContactLessAllowed	boolean	To enable or disable Contact Less transaction on card
isAtmLimitEnabled	boolean	To enable or disable ATM transaction on card
isOnlineLimitEnabled	boolean	To enable or disable ECOM transaction on card
isPosLimitEnabled	boolean	To enable or disable Point of Sale transaction on card
perAtmTxnLimit	int	Limit amount for ATM
perOnlineTxnLimit	int	Limit amount for ECOM
perPosTxnLimit	int	Limit amount for Point of Sale
perContactlessTxnLimit	int	Limit amount for Contact Less (TAP)

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Request

{
"entityType":"CARD",
"entityId":"CID24071505####ID17085600",
"limits":[
            {
            "currency":"AED",
            "isContactLessAllowed":false,
            "isAtmLimitEnabled":true,
            "isOnlineLimitEnabled":false,
            "isPosLimitEnabled":true,
            "perAtmTxnLimit":80,
            "perOnlineTxnLimit":0,
            "perPosTxnLimit":50000,
            "perContactlessTxnLimit":0
            }
					]
}

Sample Response

{
    "limits": [
        {
            "currency": "AED",
            "perAtmTxnLimit": 0.0000,
            "perOnlineTxnLimit": 0.0000,
            "perPosTxnLimit": 50000.0000,
            "perContactlessTxnLimit": 0.0000,
            "maxPerAtmTxnLimit": 90.0000,
            "maxPerOnlineTxnLimit": 0,
            "maxPerPosTxnLimit": 50000.0000,
            "maxPerContactlessTxnLimit": 0,
            "isContactLessAllowed": false,
            "isAtmLimitEnabled": false,
            "isOnlineLimitEnabled": false,
            "isPosLimitEnabled": true
        }
    ]
}

Method 7: Block card

Description

This method allow to block card.

Parameters to call the api.

Method

PUT

End Point

{baseurl}/mctc/v1/customer/card/CID2407######9ID11104872/status

Parameters

Attribute	Type	Description
CARD	string	Card id whose setting need to be fetched (eg. CID240715####3ID17085600)
status	string	"BLOCKED" needed to passed for this field
blockedReason	string	Pass the possible reason eg ."STOLEN","LOST", "DAMAGED", "NOT_REQUIRED".

Request Json Body

{"status":"BLOCKED","blockedReason":"STOLEN"}

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Request

{
"entityType":"CARD",
"entityId":"CID240715#####293ID17085600",
"limits":[
            {
            "currency":"AED",
            "isContactLessAllowed":false,
            "isAtmLimitEnabled":true,
            "isOnlineLimitEnabled":false,
            "isPosLimitEnabled":true,
            "perAtmTxnLimit":80,
            "perOnlineTxnLimit":0,
            "perPosTxnLimit":50000,
            "perContactlessTxnLimit":0
            }
					]
}

Sample Response

{
    "limits": [
        {
            "currency": "AED",
            "perAtmTxnLimit": 0.0000,
            "perOnlineTxnLimit": 0.0000,
            "perPosTxnLimit": 50000.0000,
            "perContactlessTxnLimit": 0.0000,
            "maxPerAtmTxnLimit": 90.0000,
            "maxPerOnlineTxnLimit": 0,
            "maxPerPosTxnLimit": 50000.0000,
            "maxPerContactlessTxnLimit": 0,
            "isContactLessAllowed": false,
            "isAtmLimitEnabled": false,
            "isOnlineLimitEnabled": false,
            "isPosLimitEnabled": true
        }
    ]
}

Method 8: Freeze and Unfreeze Card Settings

Description

This api allow user to freeze and unfreeze the card.

Parameters to call the api.

Method

PUT

End Point

{baseurl}/mctc/v1/customer/card/CID240####3322747ID17740898/status

Parameters

Attribute	Type	Description
CARD	string	Card id whose setting need to be fetched (eg. CID240715#####93ID17085600)
status	string	"LOCKED" in case of freezing the card, "UNLOCKED" in case of un freezing the card

Request Json Body

{"status":"LOCKED"}

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Response

{"message":"Card status updated successfully"}

Method 9: Card Load History

Description

This method allows you to get user details, the response will remain the same loginwithauthtoken .
This method can act as refresh api as well.

Parameters to call the api.

Method

GET

End Point

{baseurl}/mctc/v1/cards/cardLoad/list?accountId=7673#####723544&page=1&perPage=25

Parameters

Attribute	Type	Description
accountId	string	User account id (received on login with auth token)
page	string	Page for pagination
perPage	int	Number of item per page

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Response

{
    "recordsCurrentPage": 3,
    "currentPage": 1,
    "totalPages": 1,
    "totalRecords": 3,
    "cardLoadList": [
        {
            "baseCurrencyAmount": 713.00,
            "moneyReceivedDate": "2024-09-19T13:35:31.299",
            "account": "813020763672",
            "fxAmount": 713.00,
            "status": "APPROVED",
            "type": "ENCASH",
            "cardLoadId": "ENCSH240919133531160ID12478470",
            "currencyCode": "AED",
            "txnDate": "2024-09-19T13:35:31.299",
            "referenceNumber": "67312"
        },
        {
            "baseCurrencyAmount": 2300.00,
            "moneyReceivedDate": "2024-09-19T13:22:19.338",
            "account": "813020763672",
            "fxAmount": 2300.00,
            "status": "APPROVED",
            "type": "RELOAD",
            "cardLoadId": "CLID240919132219337ID10825880",
            "currencyCode": "AED",
            "txnDate": "2024-09-19T13:22:19.338",
            "referenceNumber": "4631"
        },
        {
            "baseCurrencyAmount": 10000.00,
            "moneyReceivedDate": "2024-09-19T09:17:07.566",
            "account": "813020763672",
            "fxAmount": 10000.00,
            "status": "APPROVED",
            "type": "LOAD",
            "cardLoadId": "CLID240919091707564ID17076760",
            "currencyCode": "AED",
            "txnDate": "2024-09-19T09:17:07.566",
            "referenceNumber": "qwedfv"
        }
    ]
}

Method 10: Get Trip List

Description

This method allows you to get user details, the response will remain the same loginwithauthtoken .
This method can act as refresh api as well.

Parameters to call the api.

Method

GET

End Point

{baseurl}/mctc/v1/customer/trip/CUST240715####503610ID15656664/OID2406#####5057ID16561311?page=1&perPage=25

Parameters

Attribute	Type	Description
Customer ID	string	Add in query parameter eg .CUST240715####0ID15656664
Org ID	string	Org Id -- OID24060#####7ID16561311
page	int	Page for pagination
perPage	int	Number of item per page

Request Header

In header request authorization we have to pass the customer token or "Jwt_token"

Header Name	Value
authorization:	Bearer C91IP_NqP44YecjzTTI/Tubf**GmPzRaf0UJJI= (Sample token)

Sample Response

[
    {
        "id": null,
        "mctcTripId": "TRIP240716125517805ID13084224",
        "status": "APPROVED",
        "customerId": "CUST240715044503610ID15656664",
        "tripStartDate": "2024-12-12",
        "tripEndDate": "2024-12-13",
        "travelPurposeCode": "TP01",
        "orgId": "OID240605060125057ID16561311",
        "destinationCountryCode": "weqwe",
        "tripName": "Trip to weqwe (Business Travel)",
        "maxLoadLimit": 13000.00
    },
    {
        "id": null,
        "mctcTripId": "TRIP240716125612513ID12178300",
        "status": "APPROVED",
        "customerId": "CUST240715044503610ID15656664",
        "tripStartDate": "2024-08-16",
        "tripEndDate": "2024-08-16",
        "travelPurposeCode": "TP05",
        "orgId": "OID240605060125057ID16561311",
        "destinationCountryCode": "USA",
        "tripName": "Trip to USA (Education(Self Funded))",
        "maxLoadLimit": 13000.00
    },
    {
        "id": null,
        "mctcTripId": "TRIP240821115922086ID19751742",
        "status": "APPROVED",
        "customerId": "CUST240715044503610ID15656664",
        "tripStartDate": "2025-01-21",
        "tripEndDate": "2026-12-21",
        "travelPurposeCode": "TP06",
        "orgId": "OID240621070419750ID10693408",
        "destinationCountryCode": "usa",
        "tripName": "Trip to usa (Education(Loan Funded))",
        "maxLoadLimit": 13000.00
    },
    {
        "id": null,
        "mctcTripId": "TRIP240903115924376ID12789250",
        "status": "APPROVED",
        "customerId": "CUST240715044503610ID15656664",
        "tripStartDate": "2024-09-03",
        "tripEndDate": "2024-09-25",
        "travelPurposeCode": "TP06",
        "orgId": "OID240621070419750ID10693408",
        "destinationCountryCode": "USA",
        "tripName": "Trip to USA (Education(Loan Funded))",
        "maxLoadLimit": 13000.00
    },
    {
        "id": null,
        "mctcTripId": "TRIP240906101637354ID19777390",
        "status": "APPROVED",
        "customerId": "CUST240715044503610ID15656664",
        "tripStartDate": "2028-09-06",
        "tripEndDate": "2032-09-06",
        "travelPurposeCode": "TP04",
        "orgId": "OID240605060125057ID16561311",
        "destinationCountryCode": "Uganda",
        "tripName": "Trip to Uganda (Medical)",
        "maxLoadLimit": 13000.00
    }
]

SERVICE RESPONSE CODE DESCRIPTION

Response can be traced on the call back event object Card91RemoteResponse

Response code	Description
200-299	Between 200-299 is considered as success response.
400-499	401 Invalid auth token (unauthorised) token which is passed is incorrect. 403 Forbidden, 400 Request structure is malformed or incorrect (check the request body) 404 Url not found (check the end point of the api url) 415 Missing header request. 429 Too many request sent in limited time frame. etc
500-599	500 - Internal server error 501. - Service not implemented 502 - Bad gateway 503 - Service not available 504 - Gateway time out