Subscribe PANS to watchlist

This API call is used to add a list of PANs to the watchlist. Please notice that when validating a list of PANs, the validation is made asynchronous. The reply is made by notification by those PANs. The flow is defined by the illustration below.

When a PAN is added to the watchlist, the PAN is validated within 24 hours. If the PAN is invalid or already updated by another PAN, an async notification is triggered to the Integrator.

In the response, a unique identifier (named panid) is returned for each PAN. This reference must be stored locally at the Integrator with reference to the PAN, as this will be the reference to the PAN for notification and unsubscribe calls.

Endpoint and method

Method: POST

Endpoint: https://api.cardtokens.io/api/cu/addwatchlist

Request parameters

Name	Type	Description
pans	Array	Required. List of PANs to add to the watchlist.
pans[…].pan	String	Required. The PAN to validate.
pans[…].expmonth	String	Required. The expiry month of the card. Formatted as MM.
pans[…].expyear	String	Required. The expiry year of the card. Formatted as YYYY.
pans[…].customreference	String	Optional. Unique reference to the pan from own system. Maxlength is 64 bytes.
merchantid	String	Required. The unique reference to the merchant in the Cardtokens system.

Response parameters

Name	Type	Description
pans	Array	The list of pans added to the watchlist.
pans[…].pan	String	The PAN added to the list.
pans[…].panid	String	A unique reference to the PAN stored in the watchlist.
pans[…].status	String	If the pan is added to the watchlist. 1: Added. 0: Failed. 2: Already exists (duplicate).
pans[…].customreference	String	Custom reference to the pan from own system.

Example requests

{
  "pans": [
    {
      "pan": "4571233011221122",
      "expmonth": "01",
      "expyear": "2096"
    },
    {
      "pan": "4571233011221121",
      "expmonth": "02",
      "expyear": "2095",
      "customreference": "abcd-efgh-1234-5678"
    }
  ],
  "merchantid": "361ec97b904d406d90d2df47e2f5f955"
}

Example encrypted response

{
"encdata":"TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdCwgc2VkIGRvIGVpdXNtb2QgdGVtcG9yIGl
uY2lkaWR1bnQgdXQgbGFib3JlIGV0IGRvbG9yZSBtYWduYSBhbGlxdWEuIFV0IGVuaW0gYWQgbWluaW0gdmVuaWFtLCBxdWlzIG5vc3RydWQgZXh
lcmNpdGF0aW9uIHVsbGFtY28gbGFib3JpcyBuaXNpIHV0IGFsaXF1aXAgZXggZWEgY29tbW9kbyBjb25zZXF1YXQuIER1aXMgYXV0ZSBpcnVyZSBkb2x
vciBpbiByZXByZWhlbmRlcml0IGluIHZvbHVwdGF0ZSB2ZWxpdCBlc3NlIGNpbGx1bSBkb2xvcmUgZXUgZnVnaWF0IG51bGxhIHBhcmlhdHVyLiBFeGN
lcHRldXIgc2ludCBvY2NhZWNhdCBjdXBpZGF0YXQgbm9uIHByb2lkZW50LCBzdW50IGluIGN1bHBhIHF1aSBvZmZpY2lhIGRlc2VydW50IG1vbGxpdCB
hbmltIGlkIGVzdCBsYWJvcnVtLg=="
}

Example decrypted response

{
  "pans": [
    {
      "pan": "4571233011221122",
      "panid": "901c439afd404f5396e1f3fdf66b1d6f",
      "status": "1"
    },
    {
      "pan": "4571233011221121",
      "panid": "901c439afd404f5396e1f3fdf66b1d6f",
      "status": "1",
      "customreference": "abcd-efgh-1234-5678"
    }
  ]
}