Whitelisting

The Whitelisting feature in ActiveAccess enables cardholders to add 3DS Requestors/merchants to a trusted beneficiaries list. The exposed whitelisting APIs are used to make changes to an issuer's cardholders' whitelisted merchants. Additionally, the APIs enable retrieving data by searching through the whitelists, and provide the ability to access a history of changes applied for cardholders.

Message Format¶

All Whitelisting APIs accept JSON requests and responses. The supported protocol to exchange data is HTTP or HTTPS, depending on the configurations of your application server (e.g Tomcat).

API Description¶

Add Cardholder¶

This API is used to add a new cardholder to the whitelist. A card number can be added to the whitelist of a merchant which is defined for an issuer.

Path: whitelisting/wl/api/merchant/add
Method Type: POST

Request Body (sample):

{
   "merchantName": "Test Merchant",
   "mcc": "3200",
   "merchantCountryCode": "840",
   "acquirerMerchantID": "123456789012345",
   "issuerName": "Any Bank",
   "cardNumber": "12345678905",
   "cardName": "cardholder name"
}

Field Description:
- merchantName: Name of the merchant. This field is required.
- mcc: Merchant Category Code. This field is required.
- merchantCountryCode: Country code of the merchant. This field is required.
- acquirerMerchantID: Acquirer's Merchant ID. This field is required.
- issuerName: Name of the issuer. The issuer must exist on ActiveAccess. Instead of issuerName, you can also pass issuerId which is the Issuer ID of an issuer on ActiveAccess. This field is required.
- cardNumber: Card number of the cardholder. This field is required.
- cardName: Name of the cardholder. This field can be blank, i.e. "cardName" : "". If you do not pass a cardholder name to the API or set a null value for it, it will be assumed that all the cardholder names of the card number should be considered as whitelisted. Additionally, you cannot add any other cards with that card number but different cardholder names to the merchant.
Successful Response:
```
{"status":"SUCCESS"}
```

Error Response - required fields missing:

{
"status": "ERROR",
"messageLabel": "MISSED_REQUIRED_FIELD",
"fields": "merchantName, mcc, merchantCountryCode, acquirerMerchantID, cardNumber, issuerName"
}

Error Response - incorrect issuer name:

{
 "status": "ERROR",
 "messageLabel": "NOT_FOUND",
 "fields": "issuerName"
}

Error Response - incorrect issuer ID:

{
 "status": "ERROR",
 "messageLabel": "NOT_FOUND",
 "fields": "issuerId"
}

Error Response - adding an existing merchant:

 {
    "status": "ERROR",
    "messageLabel": "MERCHANT_CARDHOLDER_ALREADY_EXIST"
 }

Remove Merchant¶

This API is used to remove a merchant from the whitelist.

Warning

When the specified merchant is deleted, it will be removed from the whitelisted merchants of all the cardholders.

Path: whitelisting/wl/api/merchant/remove
Method Type: POST

Request Body (sample):

{
   "merchantName": "Test Merchant",
   "mcc": "3200",
   "merchantCountryCode": "840",
   "acquirerMerchantID": "123456789012345",
   "issuerName": "Any Bank"
}

Fields Description:
- merchantName: Name of the merchant. This field is required.
- mcc: Merchant Category Code. This field is required.
- merchantCountryCode: Country code of the merchant. This field is required.
- acquirerMerchantID: Acquirer's Merchant ID. This field is required.
- issuerName: Name of the issuer. The issuer must exist on ActiveAccess.
Successful Response:
```
{"status":"SUCCESS"}
```

Error Response - required fields missing:

{
 "status": "ERROR",
 "messageLabel": "MISSED_REQUIRED_FIELD",
 "fields": "merchantName, mcc, merchantCountryCode, acquirerMerchantID, issuerName"
}

Error Response - incorrect issuer name:

{
 "status": "ERROR",
 "messageLabel": "NOT_FOUND",
 "fields": "issuerName"
}

Remove Merchant List¶

This API is used to remove a list of merchants from the whitelist.

Warning

When the specified merchant is deleted, it will be removed from the whitelisted merchants of all the cardholders.

Path: whitelisting/wl/api/merchant/removelist
Method Type: POST

Request Body (sample):

[
   {
      "issuerName": "Any Bank",
      "merchantName": "Test Merchant1",
      "mcc": "123",
      "merchantCountryCode": "123",
      "acquirerMerchantID": "89012345"
   },
   {
      "issuerName": "Any Bank",
      "merchantName": "Test Merchant3",
      "merchantCountryCode": "125",
      "acquirerMerchantID": "8901234545",
      "mcc": "125"
   }
]

Fields Description:
- merchantName: Name of the merchant. This field is required.
- mcc: Merchant Category Code. This field is required.
- merchantCountryCode: Country code of the merchant. This field is required.
- acquirerMerchantID: Acquirer's Merchant ID. This field is required.
- issuerName: Name of the issuer. The issuer must exist on ActiveAccess.

Successful Response:

{
 "status": "SUCCESS",
 "failedMerchants": []
}

Error Response - required fields missing:

{
 "status": "ERROR",
 "failedMerchants": [
  {
   "resMessageDto": {
   "status": "ERROR",
   "messageLabel": "MISSED_REQUIRED_FIELD",
   "fields": "mcc"
   },
   "reqMerchant": {
      "merchantName": "Test Merchant3",
      "mcc": null,
      "merchantCountryCode": "125",
      "acquirerMerchantID": "8901234545",
      "cardName": null,
      "cardNumber": null,
      "issuerName": "Any Bank"
   }
  }
 ]
}

Error Response - incorrect issuer name:

In the sample response below, all merchants in the request had correct issuer names, except one. All other merchants are deleted successfully.

{
 "status": "ERROR",
 "failedMerchants": [
  {
   "resMessageDto": {
   "status": "ERROR",
   "messageLabel": "NOT_FOUND",
   "fields": "issuerName"
    },
   "reqMerchant": {
      "merchantName": "Test Merchant3",
      "mcc": "125",
      "merchantCountryCode": "125",
      "acquirerMerchantID": "89012345",
      "cardName": null,
      "cardNumber": null,
      "issuerName": "Any Bank2"
   }
  }
 ]
}

Remove Merchant from Card¶

This API is used to remove a merchant from a specific card. In the path, hashed value of card number should use algorithm SHA256.

Path: whitelisting/wl/api/merchant/removeMerFromCard/{cardNumberHash}
Method Type: POST

Request Body (sample):

{
   "merchantName": "Test Merchant",
   "mcc": "3200",
   "merchantCountryCode": "840",
   "acquirerMerchantID": "123456789012345",
   "issuerName": "Any Bank"
}

Fields Description:
- merchantName: Name of the merchant. This field is required.
- mcc: Merchant Category Code. This field is required.
- merchantCountryCode: Country code of the merchant. This field is required.
- acquirerMerchantID: Acquirer's Merchant ID. This field is required.
- issuerName: Name of the issuer. The issuer must exist on ActiveAccess.
Successful Response:
```
{"status":"SUCCESS"}
```

Error Response - required fields missing:

{
 "status": "ERROR",
 "messageLabel": "MISSED_REQUIRED_FIELD",
 "fields": "merchantName, mcc, merchantCountryCode, acquirerMerchantID, issuerName"
}

Error Response - incorrect issuer name:

{
 "status": "ERROR",
 "messageLabel": "NOT_FOUND",
 "fields": "issuerName"
}

Remove Merchant List from Card¶

This API is used to remove a list of merchants from a specific card. In the path, hashed value of card number should use algorithm SHA256.

Path: whitelisting/wl/api/merchant/removeMerListFromCard/{cardNumberHash}
Method Type: POST

Request Body (sample):

[
   {
      "issuerName": "Any Bank",
      "merchantName": "Test Merchant1",
      "mcc": "123",
      "merchantCountryCode": "123",
      "acquirerMerchantID": "89012345"
   },
   {
      "issuerName": "Any Bank",
      "merchantName": "Test Merchant3",
      "merchantCountryCode": "125",
      "acquirerMerchantID": "8901234545",
      "mcc": "125"
   }
]

Fields Description:
- merchantName: Name of the merchant. This field is required.
- mcc: Merchant Category Code. This field is required.
- merchantCountryCode: Country code of the merchant. This field is required.
- acquirerMerchantID: Acquirer's Merchant ID. This field is required.
- issuerName: Name of the issuer. The issuer must exist on ActiveAccess.

Successful Response:

{
 "status": "SUCCESS",
 "failedMerchants": []
}

Search Cardholder¶

This API is used to find cardholders and merchants on the whitelist. There are filters for different fields to fetch the desired results.

Path: whitelisting/wl/api/merchant/getMerchant
Method Type: POST
Query Parameters:
- first: First row which is fetched from the database. It starts from 0.
- size: Maximum number of rows which are fetched from the database.

Request Body (sample):

{
   "issuerName": "Any Bank",
   "merchantName": "Test Merchant",
   "merchantCountryCode": "840",
   "mcc": "3200",
   "acquirerMerchantID": "123456789012345",
   "cardName": "cardholder name"
   "cardNumber": "123456789056789",
   "onlyNullCardName": false
}

Fields Description:
- merchantName: Name of the merchant.
- mcc: Merchant Category Code.
- merchantCountryCode: Country code of the merchant.
- acquirerMerchantID: Acquirer's Merchant ID.
- issuerName: Name of the issuer. The issuer must exist on ActiveAccess. This field is required if cardName and cardNumber are being used in the search.
- cardNumber: Card number of the cardholder.
- cardName: Name of the cardholder. By default, cardholders with a null cardholder name value are included in the results.
- onlyNullCardName: This field is used to specify whether the results should include data where cardName is null. If onlyNullCardName is set to true, only cards with a null cardName are included in the results. If onlyNullCardName is set to false, cards with a null cardName are not included in the results.

Successful Response:

{
 "status": "SUCCESS",
 "response": [
   {
     "merchantName": "Test Merchant1",
     "mcc": "123",
     "merchantCountryCode": "123",
     "acquirerMerchantID": "89012345",
     "cardName": "cardholder name",
     "cardNumber": "123456789056789",
     "issuerName": "Any Bank"
  },
  {
     "merchantName": "Test Merchant1",
     "mcc": "123",
     "merchantCountryCode": "123",
     "acquirerMerchantID": "89012345",
     "cardName": null,
     "cardNumber": "123456789056789",
     "issuerName": "Any Bank"
  }
]
}

Error Response - cardName or cardNumber are in the request, however issuerName does not exist:

{
 "status": "ERROR",
 "messageLabel": "MISSED_ISSUER_FOR_CARD",
 "fields": "issuerName"
}

Error Response - cardName is null and onlyNullCardName does not exist

{
 "status": "ERROR",
 "messageLabel": "MISSED_ISSUER_FOR_CARD",
 "fields": "onlyNullCardName"
}

Search Cardholder History¶

This API is used to find a history of insertions and deletions of cardholders and merchants on the whitelist. There are filters for different fields to fetch the desired results.

Path: whitelisting/wl/api/merchant/getMerchantHistory
Method Type: POST
Query Parameters:
- first: First row which is fetched from the database. It starts from 0.
- size: Maximum number of rows which are fetched from the database.

Request Body (sample):

{
   "issuerName": "Any Bank",
   "merchantName": "Test Merchant",
   "merchantCountryCode": "840",
   "mcc": "3200",
   "acquirerMerchantID": "123456789012345",
   "cardName": "cardholder name"
   "cardNumber": "123456789056789",
   "onlyNullCardName": false,
   "fromDate": 1619385552712,
   "toDate": 1619385601308
}

Fields Description:
- merchantName: Name of the merchant.
- mcc: Merchant Category Code.
- merchantCountryCode: Country code of the merchant.
- acquirerMerchantID: Acquirer's Merchant ID.
- issuerName: Name of the issuer. The issuer must exist on ActiveAccess. This field is required if cardName and cardNumber are being used in the search.
- cardNumber: Card number of the cardholder.
- cardName: Name of the cardholder. By default, cardholders with a null cardholder name value are included in the results.
- onlyNullCardName: This field is used to specify whether the results should include data where cardName is null. If onlyNullCardName is set to true, only cards with a null cardName are included in the results. If onlyNullCardName is set to false, cards with a null cardName are not included in the results.

Successful Response:

  {
     "status": "SUCCESS",
     "response": [
        {
           "merchantName": "Test Merchant",
           "mcc": "3200",
           "merchantCountryCode": "840",
           "acquirerMerchantID": "123456789012345",
           "cardName": "cardholder name"
           "cardNumber": "12345678905",
           "issuerName": "Any Bank",
           "auditOperation": "INSERTED",
           "actionTime": "2021-04-25T21:19:36.063+00:00"
        },
        {
           "merchantName": "Test Merchant",
           "mcc": "3200",
           "merchantCountryCode": "840",
           "acquirerMerchantID": "123456789012345",
           "cardName": "cardholder name"
           "cardNumber": "12345678905",
           "issuerName": "Any Bank",
           "auditOperation": "DELETED",
           "actionTime": "2021-04-25T21:20:01.308+00:00"
        }
      ]
  }

The auditOperation property indicates whether the merchant has been inserted or deleted.

Error Response - cardName or cardNumber are in the request, however issuerName does not exist:

 {
    "status": "ERROR",
    "messageLabel": "MISSED_ISSUER_FOR_CARD",
    "fields": "issuerName"
 }

Error Response - cardName is null and onlyNullCardName does not exist

{
 "status": "ERROR",
 "messageLabel": "MISSED_ISSUER_FOR_CARD",
 "fields": "onlyNullCardName"
}