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

> **Note on HTTP method:** The request named the endpoint as `GET`, but the
> `mdes-token-connect.yaml` spec defines this operation (`operationId: getEligibleTokenRequestors`) as **POST** with a mandatory JSON request body.
> These test cases follow the spec (POST). Treat the `GET` reference as a
> documentation discrepancy to reconcile with the API owner.
>
> **Security:** No `securitySchemes`/`security` is declared globally or on this
> operation in the spec, so no authentication (401/403) scenarios are generated.
> In production this API is protected by OAuth 1.0a/mTLS --- add auth-failure cases
> once the security contract is published.

|                                                                                         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--retrieval-with-optional-filter)       | `200`       | Successful retrieval including the optional `supportsTokenConnect` filter      |
| [Scenario 3](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-3--no-eligible-requestors-found)         | `200`       | Successful call where no Token Requestor is eligible (empty result)            |
| [Scenario 4](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-4--missing-required-requestid)           | `400`       | Missing required field `requestId`                                             |
| [Scenario 5](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-5--missing-required-accountranges)       | `400`       | Missing required field `accountRanges`                                         |
| [Scenario 6](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-6--invalid-accountranges-value)          | `400`       | Invalid value for `accountRanges` (start number shorter than 9 digits)         |
| [Scenario 7](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-7--accountranges-exceeds-maximum-items)  | `400`       | `accountRanges` exceeds the maximum of 25 items                                |
| [Scenario 8](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-8--requestid-exceeds-maximum-length)     | `400`       | `requestId` exceeds the maximum length of 64                                   |
| [Scenario 9](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-9--accountranges-minimum-boundary-value) | `200`       | `accountRanges` start number at boundary value (minimum 9 digits)              |
| [Scenario 10](https://developer.mastercard.com/mdes-token-connect/documentation/testing/get-eligible-token-requestors-test-case/index.md#scenario-10--unexpected-server-failure)          | `500`       | Unexpected server-side failure                                                 |

## 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`. 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 -- Retrieval With Optional Filter {#scenario-2--retrieval-with-optional-filter}

**Assumptions**
> Same onboarded Issuer and host as Scenario 1. The (deprecated) optional
> `supportsTokenConnect` filter is supplied with value `true` so the Issuer only
> wants Token Requestors that participate in MDES Token Connect.

**When**
> The Issuer sends a request with all optional fields populated, explicitly
> filtering on `supportsTokenConnect = true` to confirm the field is still
> accepted for backward compatibility.

Sample Request

```json
{
  "requestId": "5d4ecdc5-e6cd-47cc-94fc-d6b2dfd3338c",
  "accountRanges": [
    "5412340000"
  ],
  "supportsTokenConnect": true
}
```

**Then**
> MDES accepts the optional filter and returns only the Token Requestors that
> support Token Connect for the supplied account range.

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

Sample Response

```json
{
  "responseId": "5d4ecdc5-e6cd-47cc-94fc-d6b2dfd3338c",
  "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",
        "EMAIL_ADDRESS"
      ],
      "supportsCardHolderAuthentication": true,
      "supportsTokenConnect": true,
      "supportIssuerInitiatedDigitizationData": true
    }
  ]
}
```

## Scenario 3 -- No Eligible Requestors Found {#scenario-3--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 4 -- Missing Required requestId {#scenario-4--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:** `400`

Sample Response

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

## Scenario 5 -- Missing Required accountRanges {#scenario-5--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:** `400`

Sample Response

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

## Scenario 6 -- Invalid accountRanges Value {#scenario-6--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:** `400`

Sample Response

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

## Scenario 7 -- accountRanges Exceeds Maximum Items {#scenario-7--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:** `400`

Sample Response

```json
{
  "errors": [
    {
      "source": "INPUT",
      "reasonCode": "INVALID_FIELD_LENGTH",
      "description": "Maximum number of items exceeded - accountRanges (max 25)",
      "recoverable": false
    }
  ],
  "responseId": "e5b1c8f2-3d74-4a96-9c0e-1f2a6b8d4e30"
}
```

## Scenario 8 -- requestId Exceeds Maximum Length {#scenario-8--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:** `400`

Sample Response

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

## Scenario 9 -- accountRanges Minimum Boundary Value {#scenario-9--accountranges-minimum-boundary-value}

**Assumptions**
> Same onboarded Issuer and host. An account range start number of exactly 9
> digits is at the documented minimum length; MDES zero-pads it to 19 digits to
> match the enabled account range.

**When**
> The Issuer supplies the shortest legal account range start number (9 digits,
> `541234000`) to confirm boundary acceptance and zero-padding behaviour.

Sample Request

```json
{
  "requestId": "70819234-5a6b-7c8d-9e0f-102132435465",
  "accountRanges": [
    "541234000"
  ]
}
```

**Then**
> MDES accepts the 9-digit value, zero-pads it to 19 digits internally, and
> returns the matching Token Requestor whose `enabledAccountRanges` start number
> equals the padded value.

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

Sample Response

```json
{
  "responseId": "70819234-5a6b-7c8d-9e0f-102132435465",
  "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"
      ],
      "supportsMultiplePushedCards": true,
      "supportedAccountHolderData": [
        "NAME",
        "ADDRESS"
      ],
      "supportsCardHolderAuthentication": true,
      "supportsTokenConnect": true,
      "supportIssuerInitiatedDigitizationData": false
    }
  ]
}
```

## Scenario 10 -- Unexpected Server Failure {#scenario-10--unexpected-server-failure}

**Assumptions**
> Same onboarded Issuer and host. The request is well-formed and valid, but an
> internal MDES dependency (e.g. the Token Requestor eligibility cache) is
> temporarily unavailable.

**When**
> The Issuer submits a valid eligibility request while MDES is experiencing an
> internal processing error.

Sample Request

```json
{
  "requestId": "92a3b4c5-d6e7-f809-1021-324354657687",
  "accountRanges": [
    "5412340000"
  ]
}
```

**Then**
> MDES returns a `default` error wrapper indicating an MDES-sourced internal
> error. The integration team should retry with the same `requestId` after a
> short back-off.

**Expected HTTP Status Code:** `500`

Sample Response

```json
{
  "errors": [
    {
      "source": "MDES",
      "reasonCode": "INTERNAL_ERROR",
      "description": "An unexpected error occurred while processing the request",
      "recoverable": true
    }
  ],
  "responseId": "92a3b4c5-d6e7-f809-1021-324354657687"
}
```