Skip to main content
RoadmapStatusChangelogStart Building Now

Card Fraud Outreach

Card Fraud Outreach is a customizable way to help your end-customers confirm or report suspicious card transactions.

When suspicious card activity is identified, you can programmatically notify your customers by sending them branded messages. These messages enable your customers to confirm or report any suspicious transactions.

Card Fraud Outreach is a part of our card fraud monitoring Card Fraud Monitoring experience. It substitutes communication done by Visa.

Card Fraud Case​

When an authorization or transaction receives a Decline status with a SuspectedFraud reason (Authorization, Card Fraud Monitoring - Transaction Lifecycle, Card Fraud Monitoring - Visa Transaction Scoring), a Fraud Case is automatically created.

Each Card Fraud Case (Transaction / Authorization) is linked to a suspicious transaction and requires customer feedback for resolution within a specified timeframe, typically 72 hours.

This timeframe, referred to as the Card Fraud Case expiration period, is a customizable parameter (caseExpirationPeriodHours) defined by the Client within their Card Fraud Outreach Policy.

If no Customer feedback is received, the Card Fraud Case expires and cannot be acted upon.

note

Once a card fraud case decision is made and a customer feedback is received, the card fraud case is marked as Closed and cannot be reopened.

Get Card Fraud Case by Id​

Get a card fraud case by id.

VerbGET
Urlhttps://api.s.unit.sh/card-fraud-cases/{id}
Timeout (Seconds)5
curl -X GET 'https://api.s.unit.sh/card-fraud-cases/1' \
-H "Authorization: Bearer ${TOKEN}"

Response​

Response is a JSON:API document.

200 OK​

FieldTypeDescription
dataAuthorization Card Fraud Case or Transaction Card Fraud CaseCard Fraud Case resource. Can be either Authorization or Transaction as indicated by the type field.

List Card Fraud Cases​

List card fraud case resources. Paging can be applied.

VerbGET
Urlhttps://api.s.unit.sh/card-fraud-cases
Timeout (Seconds)5

Query Parameters​

FieldTypeDefaultDescription
page[limit]integer100Optional. Maximum number of resources that will be returned. Maximum is 10000 resources. See Pagination.
page[offset]integer0Optional. Number of resources to skip. See Pagination.
filter[cardId]string(empty)Optional. Filter by card id.
filter[accountId]string(empty)Optional. Filter by account id.
filter[customerId]string(empty)Optional. Filter by customer id.
filter[status][]string(empty)Optional. Filter by case status. Can be one of the following values: Created, Active, Closed, Expired.
filter[decision][]string(empty)Optional. Filter by case decision. Can be one of the following values: Pending, Fraud, NoFraud.
sortstringsort=-createdAtOptional. sort=createdAt for ascending order or sort=-createdAt (leading minus sign) for descending order.
curl -X GET 'https://api.s.unit.sh/card-fraud-cases?page[limit]=20&page[offset]=10' \
-H "Authorization: Bearer ${TOKEN}"

Response​

Response is a JSON:API document.

200 OK​

FieldTypeDescription
dataArray of Authorization Card Fraud Case or Transaction Card Fraud CaseArray of card fraud case resources. Each resource can be either Transaction or Authorization, as indicated by the type field.
metaJSON object that contains pagination dataPagination data includes offset, limit and total (estimated total items).
Example response:
{
  "data": [
    {
      "type": "authorizationCardFraudCase",
      "id": "9",
      "attributes": {
        "createdAt": "2024-07-31T11:02:27.355Z",
        "status": "Closed",
        "decision": "Fraud",
        "expiresAt": "2024-08-03T11:02:27.355Z",
        "cardActivities": [
          {
            "id": "15",
            "createdAt": "2024-07-31T11:02:27.355Z",
            "activityType": "Authorization",
            "cardActivityCreatedAt": "2024-07-31T11:02:27.270Z",
            "cardActivity": "8082294",
            "location": "Cupertino, CA, US",
            "merchant": "Apple Inc.",
            "amount": 2500,
            "decision": "Fraud",
            "updatedAt": "2024-07-31T11:04:43.696Z"
          },
          {
            "id": "16",
            "createdAt": "2024-07-31T11:02:27.355Z",
            "activityType": "Authorization",
            "cardActivityCreatedAt": "2024-07-30T14:40:13.147Z",
            "cardActivity": "8069211",
            "location": "Cupertino, CA, US",
            "merchant": "Apple Inc.",
            "amount": 100,
            "decision": "NoFraud",
            "updatedAt": "2024-07-31T11:04:43.696Z"
          },
          {
            "id": "17",
            "createdAt": "2024-07-31T11:02:27.355Z",
            "activityType": "Transaction",
            "cardActivityCreatedAt": "2024-07-30T14:40:07.534Z",
            "cardActivity": "8069210",
            "location": "Cupertino, CA, US",
            "merchant": "Apple Inc.",
            "amount": 100,
            "decision": "NoFraud",
            "updatedAt": "2024-07-31T11:04:43.696Z"
          }
        ],
        "updatedAt": "2024-07-31T11:04:43.696Z"
      },
      "relationships": {
        "card": {
          "data": {
            "type": "card",
            "id": "2200412"
          }
        },
        "account": {
          "data": {
            "type": "account",
            "id": "49230"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "49430"
          }
        },
        "authorization": {
          "data": {
            "type": "authorization",
            "id": "8082294"
          }
        }
      }
    },
    {
      "type": "transactionCardFraudCase",
      "id": "10",
      "attributes": {
        "createdAt": "2024-07-31T11:02:27.355Z",
        "status": "Closed",
        "decision": "NoFraud",
        "expiresAt": "2024-08-03T11:02:27.355Z",
        "cardActivities": [
          {
            "id": "20",
            "createdAt": "2024-07-31T11:02:27.355Z",
            "activityType": "Authorization",
            "cardActivityCreatedAt": "2024-07-31T11:02:27.270Z",
            "cardActivity": "8082294",
            "location": "Cupertino, CA, US",
            "merchant": "Apple Inc.",
            "amount": 2500,
            "decision": "Fraud",
            "updatedAt": "2024-07-31T11:04:43.696Z"
          },
          {
            "id": "21",
            "createdAt": "2024-07-31T11:02:27.355Z",
            "activityType": "Authorization",
            "cardActivityCreatedAt": "2024-07-30T14:40:13.147Z",
            "cardActivity": "8069211",
            "location": "Cupertino, CA, US",
            "merchant": "Apple Inc.",
            "amount": 100,
            "decision": "NoFraud",
            "updatedAt": "2024-07-31T11:04:43.696Z"
          },
          {
            "id": "22",
            "createdAt": "2024-07-31T11:02:27.355Z",
            "activityType": "Transaction",
            "cardActivityCreatedAt": "2024-07-30T14:40:07.534Z",
            "cardActivity": "8069210",
            "location": "Cupertino, CA, US",
            "merchant": "Apple Inc.",
            "amount": 100,
            "decision": "NoFraud",
            "updatedAt": "2024-07-31T11:04:43.696Z"
          }
        ],
        "updatedAt": "2024-07-31T11:04:43.696Z"
      },
      "relationships": {
        "card": {
          "data": {
            "type": "card",
            "id": "2200412"
          }
        },
        "account": {
          "data": {
            "type": "account",
            "id": "49230"
          }
        },
        "customer": {
          "data": {
            "type": "customer",
            "id": "49430"
          }
        },
        "transaction": {
          "data": {
            "type": "transaction",
            "id": "8069210"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "limit": 100,
      "offset": 0
    }
  }
}

Mark Card Fraud Case as Fraud​

caution

If you are using our White Label Card Fraud Outreach solution, we encourage you not to use this API. The status of the Card Fraud Case will be updated automatically according to its lifecycle stage.

This action is irreversible. Once a card fraud case is marked as Fraud, it cannot be changed back to No Fraud. Calling this action repeatedly for the same card fraud case id will result in an error.

Mark a card fraud case as Fraud.

VerbPOST
Urlhttps://api.s.unit.sh/card-fraud-cases/{id}/fraud
Data TypemarkAsFraudRequest
Timeout (Seconds)5

Attributes​

FieldTypeDescription
fraudulentActivityIdsArray of integersThe ids of the fraudulent activities. The activities are the card activities that are marked as fraudulent. The activities are linked to the card fraud case.
Example Request:
curl -X POST 'https://api.s.unit.sh/card-fraud-cases/1/fraud'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "markAsFraudRequest",
    "attributes": {
      "fraudulentActivityIds": [
        "15",
        "16",
        "17"
      ]
    }
  }
}'

Response​

Response is a JSON:API document.

200 OK​

FieldTypeDescription
dataAuthorization Card Fraud Case or Transaction Card Fraud CaseThe Card Fraud Case resource updated as Fraud. Can be either Authorization or Transaction as indicated by the type field.

Mark Card Fraud Case as No Fraud​

caution

If you are using our White Label Card Fraud Outreach solution, we encourage you not to use this API. The status of the Card Fraud Case will be updated automatically according to its lifecycle stage.

This action is irreversible. Once a card fraud case is marked as No Fraud, it cannot be changed back to Fraud. Calling this action repeatedly for the same card fraud case id will result in an error.

Mark a card fraud case as No Fraud.

VerbPOST
Urlhttps://api.s.unit.sh/card-fraud-cases/{id}/no-fraud
Timeout (Seconds)5
curl -X POST 'https://api.s.unit.sh/card-fraud-cases/1/no-fraud'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{}'

Response​

Response is a JSON:API document.

200 OK​

FieldTypeDescription
dataAuthorization Card Fraud Case or Transaction Card Fraud CaseThe Card Fraud Case resource updated as No Fraud. Can be either Authorization or Transaction as indicated by the type field.

Card Fraud Outreach Policy​

Prior to utilizing the card fraud outreach, clients must configure key parameters governing Card Fraud Case management and customer communication. The card fraud outreach policy is designated to set the rules, configurations and customizations needed for the card fraud outreach process.

Create Policy​

VerbPOST
Urlhttps://api.s.unit.sh/fraud-outreach-policies
Data TypecardFraudOutreachPolicy
Timeout (Seconds)5

Attributes​

FieldtypeDefaultDescription
contactPhonePhone(empty)The client support contact phone number.
contactUrlstring(empty)The client support contact URL. Should be a valid https URL.
activitiesLookBackPeriodHoursinteger72Optional. The period in hours before the card fraud case was created, for which the card fraud case activities will be included in the case. Can be one of the following periods: 12, 24, 48, 72
caseExpirationPeriodHoursinteger72Optional. The period in hours after the card fraud case was created, after which the card fraud case expires. Can be one of the following periods: 12, 24, 48, 72
numberOfActivitiesinteger3Optional. The number of card activities that will be included in the card fraud case. Up to 5 activities max.
idempotencyKeystring(empty)Optional. See Idempotency.

Relationships​

FieldtypeDescription
whiteLabelThemeJSON:API RelationshipOptional. The white-label theme to be used for the policy. See White-Label Theme.
emailOutreachSettingsJSON:API RelationshipOptional. The email outreach settings to be used for the policy.
messageOutreachSettingsJSON:API RelationshipOptional. The message outreach settings to be used for the policy.
Example Request:
curl -X POST 'https://api.s.unit.sh/fraud-outreach-policies'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "cardFraudOutreachPolicy",
    "attributes": {
      "caseExpirationPeriodHours": 72,
      "activitiesLookBackPeriodHours": 72,
      "contactUrl": "https://thisIsMyDomain.unit.co",
      "contactPhone": {
        "countryCode": "213",
        "number": "5350405030"
      },
      "numberOfCardActivities": 3
    },
    "relationships": {
      "emailOutreachSettings": {
        "data": {
          "type": "emailOutreachSettings",
          "id": "10001"
        }
      },
      "messageOutreachSettings": {
        "data": {
          "type": "messageOutreachSettings",
          "id": "10002"
        }
      },
      "whiteLabelTheme": {
        "data": {
          "type": "whiteLabelTheme",
          "id": "10005"
        }
      }
    }
  }
}'

Response​

Response is a JSON:API document.

201 Created​

FieldTypeDescription
dataCardFraudOutreachPolicyThe created CardFraudOutreachPolicy resource.
Example response:
{
  "data": {
    "type": "cardFraudOutreachPolicy",
    "id": "1",
    "attributes": {
      "createdAt": "2024-07-30T14:29:29.986Z",
      "activitiesLookBackPeriodHours": 72,
      "caseExpirationPeriodHours": 72,
      "numberOfActivities": 3,
      "contactPhone": {
        "countryCode": "213",
        "number": "5350405030"
      },
      "contactUrl": "https://thisIsMyDomain.unit.co",
      "enabled": true
    },
    "relationships": {
      "emailOutreachSettings": {
        "data": {
          "type": "emailOutreachSettings",
          "id": "10023"
        }
      },
      "messageOutreachSettings": {
        "data": {
          "type": "messageOutreachSettings",
          "id": "10022"
        }
      },
      "whiteLabelTheme": {
        "data": {
          "type": "whiteLabelTheme",
          "id": "54728"
        }
      }
    }
  }
}

Update Policy​

VerbPATCH
Urlhttps://api.s.unit.sh/fraud-outreach-policies/:policyId
Data TypecardFraudOutreachPolicy
Timeout (Seconds)5

Attributes​

FieldTypeDescription
contactPhonePhoneOptional. The client support contact phone number.
contactUrlstringOptional. The client support contact URL. Should be a valid https URL.
activitiesLookBackPeriodHoursintegerOptional. The period in hours before the card fraud case was created, for which the card fraud case activities will be included in the case. Can be one of the following periods: 12, 24, 48, 72.
caseExpirationPeriodHoursintegerOptional. The period in hours after the card fraud case was created, after which the card fraud case expires. Can be one of the following periods: 12, 24, 48, 72.
numberOfActivitiesintegerOptional. The number of card activities that will be included in the card fraud case. Up to 5 activities max.
emailOutreachSettingsstringOptional. The id of the email outreach settings to be used for the policy.
messageOutreachSettingsstringOptional. The id of the message outreach settings to be used for the policy.
whiteLabelThemestringOptional. The id of the white-label theme to be used for the policy.
Example Request:
curl -X PATCH 'https://api.s.unit.sh/fraud-outreach-policies/:policyId'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "cardFraudOutreachPolicy",
    "attributes": {
      "caseExpirationPeriodHours": 72,
      "activitiesLookBackPeriodHours": 72,
      "contactUrl": "https://thisIsMyDomain.unit.co",
      "contactPhone": {
        "countryCode": "213",
        "number": "5350405030"
      },
      "numberOfCardActivities": 3,
      "emailOutreachSettings": "10001",
      "messageOutreachSettings": "10002",
      "whiteLabelTheme": "100081"
    }
  }
}'

Response​

Response is a JSON:API document.

200 Ok​

FieldTypeDescription
dataCardFraudOutreachPolicyThe updated CardFraudOutreachPolicy resource.
Example response:
{
  "data": {
    "type": "cardFraudOutreachPolicy",
    "id": "1",
    "attributes": {
      "createdAt": "2024-07-30T14:29:29.986Z",
      "activitiesLookBackPeriodHours": 72,
      "caseExpirationPeriodHours": 72,
      "numberOfActivities": 3,
      "contactPhone": {
        "countryCode": "213",
        "number": "5350405030"
      },
      "contactUrl": "https://thisIsMyDomain.unit.co",
      "enabled": true
    },
    "relationships": {
      "emailOutreachSettings": {
        "data": {
          "type": "emailOutreachSettings",
          "id": "10023"
        }
      },
      "messageOutreachSettings": {
        "data": {
          "type": "messageOutreachSettings",
          "id": "10022"
        }
      },
      "whiteLabelTheme": {
        "data": {
          "type": "whiteLabelTheme",
          "id": "54728"
        }
      }
    }
  }
}

Get Policy by Id​

Get a card fraud outreach policy by id.

VerbGET
Urlhttps://api.s.unit.sh/fraud-outreach-policies/{id}
Timeout (Seconds)5
curl -X GET 'https://api.s.unit.sh/fraud-outreach-policies/1' \
-H "Authorization: Bearer ${TOKEN}"

Response​

Response is a JSON:API document.

200 OK​

FieldTypeDescription
dataCardFraudOutreachPolicyThe requested CardFraudOutreachPolicy resource.