Skip to main content
POST
/
transactions
Check a transaction's risk
curl --request POST \
  --url https://api.frankiefinancial.io/transaction/v2/transactions \
  --header 'Content-Type: application/json' \
  --header 'X-Frankie-CustomerID: <x-frankie-customerid>' \
  --header 'apiKey: <api-key>' \
  --data '
{
  "riskToken": {
    "sessionKey": "<string>",
    "userId": "<string>"
  },
  "transactionId": "<string>",
  "customer": {
    "customerId": "<string>",
    "customerType": "<string>",
    "dataSource": "<string>",
    "productType": "<string>",
    "entityId": "98ded7ac-2457-4bde-b27c-fcee05301262",
    "frankieId": "98ded7ac-2457-4bde-b27c-fcee05301262",
    "createdDatetime": "2023-11-07T05:31:56Z",
    "firstName": "<string>",
    "middleName": "<string>",
    "lastName": "<string>",
    "dob": "1983-04-22",
    "address": {
      "country": "Testalia",
      "addressId": "<string>",
      "addressType": "RESIDENTIAL",
      "startDate": "2023-12-25",
      "endDate": "2023-12-25",
      "careOf": "<string>",
      "unitNumber": "Suite 1006",
      "streetNumber": "42a",
      "streetName": "Test Eagle",
      "streetType": "Road",
      "buildingName": "Tower of Power",
      "suburb": "Testbeds",
      "town": "Testville",
      "region": "Test County",
      "state": "TST",
      "postalCode": "123-TST"
    },
    "email": "<string>",
    "phone": "<string>",
    "consent": "UNKNOWN",
    "nationalId": "<string>",
    "companyName": "<string>",
    "extraData": {}
  },
  "activity": {
    "activityType": "REGISTRATION",
    "timestamp": "2023-11-07T05:31:56Z",
    "customerTransaction": {
      "paymentRole": "TXN_ROLE_ORIGINATOR",
      "paymentType": "CARD",
      "paymentId": "<string>",
      "paymentAmount": 123,
      "currencyCode": "<string>",
      "accountPan": "<string>",
      "paymentDesc": "<string>",
      "paymentStatus": "<string>",
      "transactionType": "BUY",
      "order": {
        "prevOrderCount": 123,
        "lastOrderDate": "1983-04-22",
        "orderChannel": "<string>",
        "prevUnpaidOrderCount": 123
      },
      "disbursementType": "BILLPAY",
      "merchant": {
        "id": "<string>",
        "mcc": "<string>",
        "category": "<string>"
      },
      "transferType": "ACH",
      "accountType": "CHECKING",
      "hashedPan": "<string>",
      "maskedPan": "<string>",
      "accountRoute": "<string>",
      "accountIban": "<string>",
      "accountSwift": "<string>",
      "accountName": "<string>",
      "accountClass": "PERSONAL",
      "accountExtId": "<string>",
      "accountExtType": "EXTERNAL_IDNO",
      "extraData": {}
    },
    "counterParty": {
      "partyDetails": {
        "customerId": "<string>",
        "customerType": "<string>",
        "dataSource": "<string>",
        "productType": "<string>",
        "entityId": "98ded7ac-2457-4bde-b27c-fcee05301262",
        "frankieId": "98ded7ac-2457-4bde-b27c-fcee05301262",
        "createdDatetime": "2023-11-07T05:31:56Z",
        "firstName": "<string>",
        "middleName": "<string>",
        "lastName": "<string>",
        "dob": "1983-04-22",
        "address": {
          "country": "Testalia",
          "addressId": "<string>",
          "addressType": "RESIDENTIAL",
          "startDate": "2023-12-25",
          "endDate": "2023-12-25",
          "careOf": "<string>",
          "unitNumber": "Suite 1006",
          "streetNumber": "42a",
          "streetName": "Test Eagle",
          "streetType": "Road",
          "buildingName": "Tower of Power",
          "suburb": "Testbeds",
          "town": "Testville",
          "region": "Test County",
          "state": "TST",
          "postalCode": "123-TST"
        },
        "email": "<string>",
        "phone": "<string>",
        "consent": "UNKNOWN",
        "nationalId": "<string>",
        "companyName": "<string>",
        "extraData": {}
      },
      "transactionDetails": {
        "paymentRole": "TXN_ROLE_ORIGINATOR",
        "paymentType": "CARD",
        "paymentId": "<string>",
        "paymentAmount": 123,
        "currencyCode": "<string>",
        "accountPan": "<string>",
        "paymentDesc": "<string>",
        "paymentStatus": "<string>",
        "transactionType": "BUY",
        "order": {
          "prevOrderCount": 123,
          "lastOrderDate": "1983-04-22",
          "orderChannel": "<string>",
          "prevUnpaidOrderCount": 123
        },
        "disbursementType": "BILLPAY",
        "merchant": {
          "id": "<string>",
          "mcc": "<string>",
          "category": "<string>"
        },
        "transferType": "ACH",
        "accountType": "CHECKING",
        "hashedPan": "<string>",
        "maskedPan": "<string>",
        "accountRoute": "<string>",
        "accountIban": "<string>",
        "accountSwift": "<string>",
        "accountName": "<string>",
        "accountClass": "PERSONAL",
        "accountExtId": "<string>",
        "accountExtType": "EXTERNAL_IDNO",
        "extraData": {}
      }
    }
  },
  "checkId": "<string>",
  "device": {
    "id": "<string>",
    "origin": "<string>",
    "os": "<string>",
    "browser": "<string>",
    "platform": "<string>",
    "riskScore": 123,
    "ip": "127.0.0.1",
    "ipGeoAsn": "<string>",
    "ipGeoCity": "<string>",
    "ipGeoCountry": "<string>",
    "ipGeoLat": "<string>",
    "ipGeoLong": "<string>",
    "isBot": true,
    "isRat": true,
    "isMobileBot": true,
    "isRecentRat": true,
    "isSupported": true,
    "isEmulated": true,
    "session": "<string>",
    "activity": "<string>",
    "extraData": {}
  },
  "extraData": {}
}
'
{
  "customerReference": "<string>",
  "result": "SUCCESS",
  "entityId": "98ded7ac-2457-4bde-b27c-fcee05301262",
  "checkId": "7eb4432d-398b-40f7-b24b-7d1208b83e2a",
  "transactionId": "df609f14-b34d-46ad-bf15-09c5f71dda8d",
  "riskScore": 123,
  "riskLevel": "MEDIUM",
  "riskResults": [
    {
      "result": "SUCCESS",
      "subtype": "CUSTOMER",
      "type": "DEVICE",
      "id": "<string>",
      "riskScore": 123,
      "riskLevel": "MEDIUM",
      "indicators": [
        {
          "name": "<string>",
          "id": "<string>",
          "score": 123,
          "value": "<string>",
          "rules": [
            {
              "id": "<string>",
              "name": "<string>",
              "description": "<string>",
              "actions": [
                {
                  "id": "<string>",
                  "value": "<string>",
                  "name": "<string>",
                  "description": "<string>"
                }
              ],
              "type": "<string>"
            }
          ]
        }
      ],
      "source": "<string>",
      "sourceLink": "<string>",
      "extraData": {},
      "recommendedAction": "UNKNOWN"
    }
  ],
  "extraData": {},
  "errors": {
    "commit": "<string>",
    "requestId": "<string>",
    "errorCode": "CORE-5990",
    "errorMsg": "Everything went kaflooey. Stay clam.",
    "issues": [
      {
        "issueLocation": "date_of_birth",
        "issue": "Invalid format. Must be YYYY-MM-DD"
      }
    ]
  }
}

Authorizations

​
apiKey
string
header
required

API key issued by FrankieOne. This will rotate regularly.

Headers

​
X-Frankie-CustomerID
string
required

Your Customer ID provided by FrankieOne

Example:

"12345678-1234-1234-1234-123456789012"

​
X-Frankie-CustomerChildID
string

Your Customer Child ID provided by FrankieOne

Example:

"87654321-4321-4321-4321-210987654321"

​
X-Frankie-Background
enum<integer>

If this header parameter is supplied and set to 1, then the request will not wait for the process to finish, and will return a 202 if there are no obvious errors in the input. The request will then run in the background and send a notification back to the customer. See our callback API for details on this.

Available options:
0,
1

Body

application/json

A recorded activity that is/has been assessed by the Transaction Monitoring Service

​
riskToken
object
required

Includes any data required for authorizations by upstream services. To confirm if this is required, please reach out to the FrankieOne Support team.

​
transactionId
string
required

Identifier for the transaction monitoring check, should be unique per transaction

​
customer
object
required

A party describes the details of one of the parties in a given assessment. It can be used to describe any participant.

​
activity
object
required
​
checkId
string
deprecated

(Deprecated in favor of transactionId)

​
device
object

Wrapper that will contain additional device data for a given transaction. This may be captured through 3rd party services

​
extraData
object

A generic map of Key/Value's that can be used to define custom properties.

Response

The request was valid and able to be processed in some fashion. Results may or may not be successful, but it was completed as far as practical with no actual errors. Returns the entity object as it stands now. No docScan file data from any attached ID documents will be returned unless the /full variant is requested.

The resulting payload from a transaction risk check request.

​
customerReference
string

The customer's reference value

​
result
enum<string>

The overall result of the transaction check, this will be based on the successful completion of a check to an upstream vendor for the transaction check

Available options:
SUCCESS,
SUCCESS_WITH_ERRORS,
FAILED
​
entityId
string

The unique identifier for a FrankieOne entity construct

Example:

"98ded7ac-2457-4bde-b27c-fcee05301262"

​
checkId
string

The unique identifier for a transaction monitoring check that was execute for a transaction

Example:

"7eb4432d-398b-40f7-b24b-7d1208b83e2a"

​
transactionId
string

The unique identifier of a transaction as identified within the FrankieOne Transaction Monitoring system

Example:

"df609f14-b34d-46ad-bf15-09c5f71dda8d"

​
riskScore
number

Risk score as determined by the checking service

​
riskLevel
enum<string>

Level of risk as determined by the service.

Available options:
NONE,
LOW,
MEDIUM,
HIGH,
VERY_HIGH
Example:

"MEDIUM"

​
riskResults
object[]

All the result sets available for the check, such as customer, device, and transaction

​
extraData
object

A generic map of Key/Value's that can be used to define custom properties.

​
errors
object