Whitelisting

New page added.

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.

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

• 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"
     }
    }
   ]
  }