# Get Eligible Token Requestors
source: https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md

The following table summarizes the test scenarios covered in this document.

|                                                                                         Scenarios                                                                                         | HTTP Status |                                  Description                                   |
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|--------------------------------------------------------------------------------|
| [Scenario 1](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-1--successful-token-requestor-retrieval) | `200`       | Issuer successfully retrieves eligible Token Requestors for its account ranges |
| [Scenario 2](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-2--no-eligible-requestors-found)         | `200`       | Successful call where no Token Requestor is eligible (empty result)            |
| [Scenario 3](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-3--missing-required-requestid)           | `200`       | Missing required field `requestId`                                             |
| [Scenario 4](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-4--missing-required-accountranges)       | `200`       | Missing required field `accountRanges`                                         |
| [Scenario 5](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-5--invalid-accountranges-value)          | `200`       | Invalid value for `accountRanges` (start number shorter than 9 digits)         |
| [Scenario 6](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-6--accountranges-exceeds-maximum-items)  | `200`       | `accountRanges` exceeds the maximum of 25 items                                |
| [Scenario 7](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-7--requestid-exceeds-maximum-length)     | `200`       | `requestId` exceeds the maximum length of 64                                   |

## Scenario 1 -- Successful Token Requestor Retrieval {#scenario-1--successful-token-requestor-retrieval}

**Assumptions**
> The Issuer is onboarded to the MDES Token Connect program and is calling the
> Sandbox host `https://sandbox.api.mastercard.com/mdes/mtf/connect`. At least two Token
> Requestors (a wallet and a merchant) have been enabled for the account range
> start `5412340000000000000`. The path parameter `maj` is set to `1/0`.

**When**
> The Issuer's back-end requests the list of Token Requestors that have been
> enabled for two of its account range start numbers, so it can render the
> available "push to wallet/merchant" options to the cardholder.

Sample Request

```json
{
  "requestId": "a3f1c9e2-1b6d-4f8a-9c2e-7d5b0a4e6f31",
  "accountRanges": [
    "5412340000",
    "5412345678"
  ]
}
```

**Then**
> MDES returns the matching `responseId` and an array of eligible Token
> Requestors, each with its identifier, display name, type, logo asset ID, and
> the account ranges it is enabled for. No PAN data is present in the response.

**Expected HTTP Status Code:** `200`

Sample Response

```json
{
  "responseId": "a3f1c9e2-1b6d-4f8a-9c2e-7d5b0a4e6f31",
  "tokenRequestors": [
    {
      "tokenRequestorId": "50110030273",
      "name": "Sunrise Ave. Ltd",
      "consumerFacingEntityName": "Happy Sunrise Online",
      "imageAssetId": "dbc55444-496a-4896-b41c-5d5e2dd431e2",
      "tokenRequestorType": "WALLET",
      "walletId": "327",
      "enabledAccountRanges": [
        5412340000000000000
      ],
      "supportedPushMethods": [
        "ANDROID",
        "IOS",
        "WEB"
      ],
      "supportsMultiplePushedCards": true,
      "supportedAccountHolderData": [
        "NAME",
        "ADDRESS"
      ],
      "supportsCardHolderAuthentication": true,
      "supportsTokenConnect": true,
      "supportIssuerInitiatedDigitizationData": false
    },
    {
      "tokenRequestorId": "50120912345",
      "name": "Northwind Retail Inc",
      "consumerFacingEntityName": "Northwind Pay",
      "imageAssetId": "554dbc44-496a-4896-b41c-dd431e25d5e4",
      "tokenRequestorType": "MERCHANT",
      "enabledAccountRanges": [
        5412345678000000000
      ],
      "supportedPushMethods": [
        "WEB"
      ],
      "supportsMultiplePushedCards": false,
      "supportedAccountHolderData": [],
      "supportsCardHolderAuthentication": false,
      "supportsTokenConnect": true,
      "supportIssuerInitiatedDigitizationData": false
    }
  ]
}
```

## Scenario 2 -- No Eligible Requestors Found {#scenario-2--no-eligible-requestors-found}

**Assumptions**
> Same onboarded Issuer and host. The account range start `4000123456` is valid
> and well-formed but no Token Requestor has been enabled for it in MDES.

**When**
> The Issuer queries for an account range for which no merchant or wallet has
> been enabled, to confirm the API differentiates "no results" from an error.

Sample Request

```json
{
  "requestId": "f72b8d10-9a44-4c2e-b6d1-3e0c5a9f1d22",
  "accountRanges": [
    "4000123456"
  ]
}
```

**Then**
> The call succeeds and MDES returns the matching `responseId` with an empty
> `tokenRequestors` array (or the array omitted). No error is raised --- there is
> simply nothing eligible to display to the cardholder.

**Expected HTTP Status Code:** `200`

Sample Response

```json
{
  "responseId": "f72b8d10-9a44-4c2e-b6d1-3e0c5a9f1d22",
  "tokenRequestors": []
}
```

## Scenario 3 -- Missing Required requestId {#scenario-3--missing-required-requestid}

**Assumptions**
> Same onboarded Issuer and host. The request payload omits the mandatory
> `requestId` correlation field.

**When**
> The Issuer's back-end sends a request that contains `accountRanges` but is
> missing `requestId`, which is required for request/response correlation.

Sample Request

```json
{
  "accountRanges": [
    "5412340000"
  ]
}
```

**Then**
> MDES rejects the request as malformed input and returns an error wrapper
> indicating the missing mandatory field. No Token Requestor data is returned.

**Expected HTTP Status Code:** `200`

Sample Response

```json
{
  "errors": [
    {
      "source": "INPUT",
      "reasonCode": "MISSING_REQUIRED_FIELD",
      "description": "Missing required field - requestId"      
    }
  ],
  "responseId": "b1f9c2a4-7e3d-4a1b-9c5e-2f6d8a0b3c11"
}
```

## Scenario 4 -- Missing Required accountRanges {#scenario-4--missing-required-accountranges}

**Assumptions**
> Same onboarded Issuer and host. The request payload omits the mandatory
> `accountRanges` array.

**When**
> The Issuer sends a request with a valid `requestId` but no `accountRanges`, so
> MDES has no account range start numbers to evaluate eligibility against.

Sample Request

```json
{
  "requestId": "c8e4a1d6-2f7b-4e90-8a13-9b6c0d2e5f47"
}
```

**Then**
> MDES rejects the request and returns an error wrapper indicating the missing
> mandatory `accountRanges` field.

**Expected HTTP Status Code:** `200`

Sample Response

```json
{
  "errors": [
    {
      "source": "INPUT",
      "reasonCode": "MISSING_REQUIRED_FIELD",
      "description": "Missing required field - accountRanges"
    }
  ],
  "responseId": "c8e4a1d6-2f7b-4e90-8a13-9b6c0d2e5f47"
}
```

## Scenario 5 -- Invalid accountRanges Value {#scenario-5--invalid-accountranges-value}

**Assumptions**
> Same onboarded Issuer and host. Each account range start number must be a
> numeric string between 9 and 19 digits in length.

**When**
> The Issuer supplies an account range start number of only 6 digits
> (`541234`), violating the documented minimum length of 9.

Sample Request

```json
{
  "requestId": "d2a9f3b7-5c81-4e62-a0d4-7f1e8c3b2a96",
  "accountRanges": [
    "541234"
  ]
}
```

**Then**
> MDES rejects the request and returns an error wrapper indicating the field
> length constraint was violated.

**Expected HTTP Status Code:** `200`

Sample Response

```json
{
  "errors": [
    {
      "source": "INPUT",
      "reasonCode": "INVALID_FIELD_LENGTH",
      "description": "Invalid Field Length - accountRanges"
    }
  ],
  "responseId": "d2a9f3b7-5c81-4e62-a0d4-7f1e8c3b2a96"
}
```

## Scenario 6 -- accountRanges Exceeds Maximum Items {#scenario-6--accountranges-exceeds-maximum-items}

**Assumptions**
> Same onboarded Issuer and host. The `accountRanges` array supports a maximum
> of 25 items per request.

**When**
> The Issuer submits 26 account range start numbers in a single request,
> exceeding the documented maximum of 25 items.

Sample Request

```json
{
  "requestId": "e5b1c8f2-3d74-4a96-9c0e-1f2a6b8d4e30",
  "accountRanges": [
    "5412340001", "5412340002", "5412340003", "5412340004", "5412340005",
    "5412340006", "5412340007", "5412340008", "5412340009", "5412340010",
    "5412340011", "5412340012", "5412340013", "5412340014", "5412340015",
    "5412340016", "5412340017", "5412340018", "5412340019", "5412340020",
    "5412340021", "5412340022", "5412340023", "5412340024", "5412340025",
    "5412340026"
  ]
}
```

**Then**
> MDES rejects the request and returns an error wrapper indicating the maximum
> number of items for `accountRanges` was exceeded.

**Expected HTTP Status Code:** `200`

Sample Response

```json
{
  "errors": [
    {
      "source": "INPUT",
      "reasonCode": "INVALID_ARRAY_SIZE",
      "description": "Invalid Array Size - accountRanges"
    }
  ],
  "responseId": "e5b1c8f2-3d74-4a96-9c0e-1f2a6b8d4e30"
}
```

## Scenario 7 -- requestId Exceeds Maximum Length {#scenario-7--requestid-exceeds-maximum-length}

**Assumptions**
> Same onboarded Issuer and host. `requestId` has a maximum length of 64
> characters.

**When**
> The Issuer sends a `requestId` of 65 characters (one over the documented
> maximum) together with a valid account range.

Sample Request

```json
{
  "requestId": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "accountRanges": [
    "5412340000"
  ]
}
```

**Then**
> MDES rejects the request and returns an error wrapper indicating the
> `requestId` length constraint was violated.

**Expected HTTP Status Code:** `200`

Sample Response

```json
{
  "errors": [
    {
      "source": "INPUT",
      "reasonCode": "INVALID_FIELD_LENGTH",
      "description": "Invalid Field Length - requestId"
    }
  ],
  "responseId": "9f0c1a2b-3d4e-5f60-7182-93a4b5c6d7e8"
}
```