Restricted merchant

curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "restricted_merchant",
    "input": { "merchant": "DRAFTKINGS", "mcc": "7995" }
  }'

curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "restricted_merchant",
    "input": { "merchant": "TARGET T-1234", "mcc": "5311" }
  }'

curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "restricted_merchant",
    "input": { "merchant": "LUCKY COINS LLC", "mcc": "5816" }
  }'

const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  decision: "restricted_merchant",
  input: { merchant: "DRAFTKINGS", mcc: "7995" },
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();

const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  decision: "restricted_merchant",
  input: { merchant: "TARGET T-1234", mcc: "5311" },
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();

const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  decision: "restricted_merchant",
  input: { merchant: "LUCKY COINS LLC", mcc: "5816" },
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();

import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "decision": "restricted_merchant",
    "input": {"merchant": "DRAFTKINGS", "mcc": "7995"},
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()

import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "decision": "restricted_merchant",
    "input": {"merchant": "TARGET T-1234", "mcc": "5311"},
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()

import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "decision": "restricted_merchant",
    "input": {"merchant": "LUCKY COINS LLC", "mcc": "5816"},
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()

{
  "decision": "restricted_merchant",
  "type": "predicate",
  "answer": true,
  "probability": 0.97,
  "reasons": [
    "mcc_7995",
    "rule_gambling_category",
    "kind_sportsbook"
  ],
  "abstain": false
}

{
  "decision": "restricted_merchant",
  "type": "predicate",
  "answer": false,
  "probability": 0.9,
  "reasons": ["mcc_5311", "kind_not_gambling"],
  "abstain": false
}

{
  "decision": "restricted_merchant",
  "type": "predicate",
  "answer": true,
  "probability": 0.62,
  "reasons": ["mcc_5816", "kind_sweepstakes_casino"],
  "abstain": true
}

# Restricted merchant

Is this merchant a gambling or wagering business? Decision id `restricted_merchant`, a predicate. Answers: `true` or `false`.

Built and tested, not yet deployed. Early access.

## Example

The request for DRAFTKINGS in cURL:

```bash
curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "restricted_merchant",
    "input": { "merchant": "DRAFTKINGS", "mcc": "7995" }
  }'
```

The request for TARGET T-1234 in cURL:

```bash
curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "restricted_merchant",
    "input": { "merchant": "TARGET T-1234", "mcc": "5311" }
  }'
```

The request for LUCKY COINS LLC in cURL:

```bash
curl "$UNDERSTANDING_API_URL/v1/understand" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "restricted_merchant",
    "input": { "merchant": "LUCKY COINS LLC", "mcc": "5816" }
  }'
```

The request for DRAFTKINGS in TypeScript:

```typescript
const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  decision: "restricted_merchant",
  input: { merchant: "DRAFTKINGS", mcc: "7995" },
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();
```

The request for TARGET T-1234 in TypeScript:

```typescript
const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  decision: "restricted_merchant",
  input: { merchant: "TARGET T-1234", mcc: "5311" },
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();
```

The request for LUCKY COINS LLC in TypeScript:

```typescript
const base = process.env.UNDERSTANDING_API_URL;
const key = process.env.UNDERSTANDING_API_KEY;

const body = {
  decision: "restricted_merchant",
  input: { merchant: "LUCKY COINS LLC", mcc: "5816" },
};

const res = await fetch(`${base}/v1/understand`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${key}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
});
const result = await res.json();
```

The request for DRAFTKINGS in Python:

```python
import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "decision": "restricted_merchant",
    "input": {"merchant": "DRAFTKINGS", "mcc": "7995"},
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()
```

The request for TARGET T-1234 in Python:

```python
import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "decision": "restricted_merchant",
    "input": {"merchant": "TARGET T-1234", "mcc": "5311"},
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()
```

The request for LUCKY COINS LLC in Python:

```python
import os
import requests

base = os.environ["UNDERSTANDING_API_URL"]
key = os.environ["UNDERSTANDING_API_KEY"]

body = {
    "decision": "restricted_merchant",
    "input": {"merchant": "LUCKY COINS LLC", "mcc": "5816"},
}

res = requests.post(
    f"{base}/v1/understand",
    headers={"Authorization": f"Bearer {key}"},
    json=body,
    timeout=10,
)
result = res.json()
```

Response: 200 OK (the probability is a stand-in)

The response for DRAFTKINGS:

```json
{
  "decision": "restricted_merchant",
  "type": "predicate",
  "answer": true,
  "probability": 0.97,
  "reasons": [
    "mcc_7995",
    "rule_gambling_category",
    "kind_sportsbook"
  ],
  "abstain": false
}
```

The response for TARGET T-1234:

```json
{
  "decision": "restricted_merchant",
  "type": "predicate",
  "answer": false,
  "probability": 0.9,
  "reasons": ["mcc_5311", "kind_not_gambling"],
  "abstain": false
}
```

The response for LUCKY COINS LLC:

```json
{
  "decision": "restricted_merchant",
  "type": "predicate",
  "answer": true,
  "probability": 0.62,
  "reasons": ["mcc_5816", "kind_sweepstakes_casino"],
  "abstain": true
}
```

## Input

- `merchant` (string, required): The statement descriptor as the card shows it, 1 to 200 characters. Also accepts `merchantName`.
- `mcc` (string, optional): The four-digit merchant category code. Send it as a string: `742` as a number fails, because `"0742"` loses its zero. Also accepts `merchantCategoryCode`.

## What our engine adds

- The category’s description from our table of 981 codes, or “unknown”.
- Two rule checks: whether the category is gambling by definition (the network codes 7995, 7800, 7801, 7802, 7948, 9754) and whether the name matches a known gambling brand.

## What the model is asked

- Whether this is a gambling or wagering business: a casino, sportsbook, lottery, fantasy-sports or prediction-market operator, sweepstakes casino, race wagering or a skin-gambling site. Video game stores and arcades are not.
- What kind of business it is, from eight kinds. The kind comes back as a reason code.

No rule settles this decision: every answer comes from the model.

## Reason codes

| Code | When |
| --- | --- |
| `mcc_<code>` | An MCC was sent, for example `mcc_7995`. |
| `rule_gambling_category` | The MCC is a network gambling code (7995, 7800, 7801, 7802, 7948, 9754). |
| `rule_known_brand` | The name matched our gambling brand list, without a gambling MCC. |
| `kind_sportsbook` | The model’s answer to “what kind of business is this”, when it gave one. |
| `kind_online_casino` | The model’s answer to “what kind of business is this”, when it gave one. |
| `kind_sweepstakes_casino` | The model’s answer to “what kind of business is this”, when it gave one. |
| `kind_lottery` | The model’s answer to “what kind of business is this”, when it gave one. |
| `kind_fantasy_or_prediction_market` | The model’s answer to “what kind of business is this”, when it gave one. |
| `kind_race_wagering` | The model’s answer to “what kind of business is this”, when it gave one. |
| `kind_skin_gambling` | The model’s answer to “what kind of business is this”, when it gave one. |
| `kind_not_gambling` | The model’s answer to “what kind of business is this”, when it gave one. |
| `model_declined` | The model declined the question. |

## Errors

Each is a 400 with `field` naming the part at fault.

- `input.merchant must be text of 1 to 200 characters`
- `input.mcc must be a four-digit merchant category code`

## Planned

When a gambling category code is answered “not gambling”, abstain with `rule_differs`. The switch exists in the code and is off until we decide; today the answer comes back as the model gave it.

## Evaluation

The Understanding API hasn’t been run on our eval yet. [Evaluation](/api/docs/evaluation)

Source: /api/docs/decisions/restricted-merchant