# Cards Smart Agent

## Overview

Smart Agent is a security feature that uses advanced transaction monitoring to
help you protect your customers from card fraud. Once you implement Smart Agent,
you can prompt your customers to confirm whether they recognize a transaction
that has been marked as suspicious.

This guide explains how the feature works and how to implement it in your
solution.

## How Smart Agent works

In order to use Smart Agent, you must implement [two webhooks](#webhooks) and
[two API endpoints](#api-endpoints) (described below).

Here is the flow for how to handle fraudulent transactions in your solution
using Smart Agent:

1. Smart Agent flags a card transaction from one of your customers' cards as
suspicious. The transaction is automatically declined.
2. Solaris sends you a `CARD_FRAUD_CASE_PENDING` webhook notification. The
webhook payload contains all of the important information about the
transaction, including:
  - The ID of the fraud case,
  - The ID of the card used,
  - The date and time when the transaction was attempted,
  - The name, category, and location of the merchant where the card was used,
  - The amount of the transaction, and
  - The deadline for the customer to acknowledge the transaction or confirm a fraud case.
3. Based on the information in the webhook payload, display a prompt in the frontend of your solution to the affected customer. Ask them to indicate whether or not they recognize the transaction.
4. If the customer indicates that they recognize the transaction, then call the [POST Allow a transaction that was marked as fraudulent](/api-reference/digital-banking/cards/#tag/Card-transactions/paths/~1v1~1cards~1%7Bcard_id%7D~1fraud_cases~1%7Bid%7D~1whitelist/post) endpoint.
  - This will disable fraud monitoring for the given card for 10 minutes,
during which the transaction can be attempted again. The API will return
the time at which monitoring will resume as the value of the
`whitelisted_until` property.
  - You are **required** to show the customer the `whitelisted_until` date and
time.
5. If the customer indicates that they **do not recognize** the transaction,
then call the [POST Confirm a fraud
case](/api-reference/digital-banking/cards/#tag/Card-transactions/paths/~1v1~1cards~1%7Bcard_id%7D~1fraud_cases~1%7Bid%7D~1confirm/post)
endpoint.
  - This will **block** the customer's card with the status `BLOCKED_BY_SOLARIS`.
  - In this case, the customer **cannot** unblock their own card. Direct the
customer to contact customer support to have a new card issued.
6. If the customer **does not respond** to the fraud case prompt within **30
minutes** of Solaris sending the `CARD_FRAUD_CASE_PENDING` notification, then
the customer's card will be **blocked** with the `BLOCK` status. Solaris
will send a notification on the `CARD_FRAUD_CASE_TIMEOUT` notification. In this
case, the customer can unblock their own card.


## Webhooks

You are **required** to implement the following webhooks:

### CARD_FRAUD_CASE_PENDING

Solaris will send this notification when Smart Agent marks a card transaction as
suspicious. Then, the transaction will be automatically declined.

**Example payload:**


```json
{
  "id": "sample-uid",
  "resolution": "PENDING",
  "respond_until": "2019-05-06T09:20:00+0000",
  "whitelisted_until": "null",
  "card_transaction": {
    "card_id": "53eb3f4b2b2902eea255a54fc06623f1mcrd",
    "type": "E-commerce",
    "status": "DECLINED",
    "attempted_at": "2019-05-06T09:13:24+0000",
    "pos_entry_mode": "CHIP",
    "merchant": {
      "country_code": "DE",
      "category_code": "SUN WORLD INTERNATIONAL",
      "name": "Merchant name",
    },
    "amount": {
      "currency": "EUR",
      "value": 1540
    },
    "original_amount": {
      "currency": "USD",
      "value": 1442
    },
  },
}
```

### CARD_FRAUD_CASE_TIMEOUT

A fraud case that was recorded for a transaction with a customer's card did not
receive a response from the customer within 30 minutes.

**Example payload:**


```json
{
  "id": "sample-uid",
  "resolution": "TIMEOUT",
  "respond_until": "2019-05-06T09:20:00+0000",
  "whitelisted_until": "null",
  "card_transaction": {
    "card_id": "53eb3f4b2b2902eea255a54fc06623f1mcrd",
    "type": "E-commerce",
    "status": "DECLINED",
    "attempted_at": "2019-05-06T09:13:24+0000",
    "pos_entry_mode": "CHIP",
    "merchant": {
      "country_code": "DE",
      "category_code": "SUN WORLD INTERNATIONAL",
      "name": "Merchant name",
    },
    "amount": {
      "currency": "EUR",
      "value": 1540
    },
    "original_amount": {
      "currency": "USD",
      "value": 1442
    },
  },
}
```

## API endpoints

### POST Allow a transaction that was marked as fraudulent

This endpoint confirms that a transaction marked as fraudulent was not actually
fraudulent (i.e., the customer confirms that they made the transaction
themselves or is otherwise aware of the transaction). Once you call this
endpoint, fraud monitoring will be disabled for the card specified in the
request URL for 10 minutes, and the transaction can be attempted again.

**Request URL:**


```shell
POST /v1/cards/{card_id}/fraud_cases/{fraud_case_id}/whitelist
```

**Example response:**


```json
{
  "id": "154dca58bb1b5c8701039fa6514ffc66frdcs",
  "resolution": "WHITELISTED",
  "whitelisted_until": "2020-05-05T11:54:26Z"
}
```

[Click here to view the full API reference.](/api-reference/digital-banking/cards/#tag/Card-transactions/paths/~1v1~1cards~1%7Bcard_id%7D~1fraud_cases~1%7Bid%7D~1whitelist/post)

### POST Confirm fraud

This endpoint confirms to Solaris that a fraud case was indeed fraudulent. The card used to make the fraudulent transaction will be subsequently blocked. You should then redirect your customer to your customer support so that a replacement card can be issued.

**Request URL:**


```shell
POST /v1/cards/{card_id}/fraud_cases/{fraud_case_id}/confirm
```

**Example response:**


```json
{
  "id": "154dca58bb1b5c8701039fa6514ffc66frdcs",
  "resolution": "CONFIRMED"
}
```

[Click here to view the full API reference.](/api-reference/digital-banking/cards/#tag/Card-transactions/paths/~1v1~1cards~1%7Bcard_id%7D~1fraud_cases~1%7Bid%7D~1confirm/post)

### (Sandbox only) POST Create test fraud case

This endpoint is only available on Sandbox.

This endpoint simulates a fraudulent transaction for the card specified in the
request URL. The fraudulent transaction process will begin as a result.

**Request URL:**


```shell
POST /v1/cards/{card_id}/test_fraud_cases
```

**Example response:**


```shell
HTTP/1.1 204 No Content
```

[Click here to view the full API reference.](/api-reference/digital-banking/cards/#tag/Card-transactions-simulation/paths/~1v1~1cards~1%7Bcard_id%7D~1test_fraud_cases/post)

## FAQs

### Smart Agent declined a transaction, but I did not receive a notification. What do I do?

This occurs when there is already another Smart Agent fraud case waiting for the
customer's feedback. Smart Agent does not send new notifications if there are
multiple simultaneous fraud cases. The customer should contact your customer
support so that Solaris can close the fraud cases manually.

### Smart Agent declined a transaction, but the customer did not respond in time. What do I do?

Direct the customer to contact your customer support so that Solaris can
review the case. The transaction can be attempted again once Solaris closes
the case.

If Smart Agent declines the transaction again, ensure that the customer responds
to the notification within 30 minutes so that the card can be whitelisted.

### If Smart Agent declines two transactions in close proximity to one another, will I receive two notifications?

No. Smart Agent only sends a notification for the first declined transaction.