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 and two 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 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 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:

{
  "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:

{
  "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:

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

Example response:

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

Click here to view the full API reference.

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:

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

Example response:

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

Click here to view the full API reference.

(Sandbox only) POST Create test fraud case

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:

POST /v1/cards/{card_id}/test_fraud_cases

Example response:

HTTP/1.1 204 No Content

Click here to view the full API reference.

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.