Create decision

Creates a new fraud decision to evaluate a transaction.

Endpoint: POST /v1/risk

Headers

Content-Type: application/json
x-api-key: <YOUR_API_KEY>

Request Body

{
    "transaction_info": {
        "type": "create_decision",
        "reference_code": "123456789"
    },
    "card": {
        "number": "{{token_id : detokenize}}",
        "expiration_date": "{{token_id : detokenize}}"
    },
    "order_info": {
        "amount_details": {
            "total_amount": "1000",
            "currency": "USD"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1001 FALCON AVE",
        "address_2": "Unit 2",
        "city": "Miami",
        "state": "FL",
        "phone_number": "50762987635",
        "email": "[e-mail]",
        "postal_code": "33166"
    },
    "device_info": {
        "fingerprint_session_id": "1713211198904",
        "ip_address": "190.123.237.237",
        "http_browser_color_depth": "24",
        "http_browser_java_enabled": false,
        "http_browser_js_enabled": true,
        "http_browser_screen_height": "1050",
        "http_browser_screen_width": "1680",
        "http_browser_time_offset": "240",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
        "cookies_accepted": true,
        "http_browser_language": "en-US"
    },
    "merchant_defined_info": [
        {
            "key": "1",
            "value": "1"
        },
        {
            "key": "2",
            "value": "test number 2"
        },
        {
            "key": "3",
            "value": "test number 3"
        },
        {
            "key": "4",
            "value": "test number 4"
        },
        {
            "key": "5",
            "value": "test number 5"
        }
    ]
}

Parameters

Field	Type	Required	Description
transaction_info.type	string	Yes	Must be "create_decision"
transaction_info.reference_code	string	Yes	Unique transaction reference code
card.number	string	Yes	Card number (can be permanent token, temporal token, or valid card number string)
card.expiration_date	string	Yes	Expiration date (can be tokenized or in MM/YY format)
order_info.amount_details.total_amount	string	Yes	Total transaction amount
order_info.amount_details.currency	string	Yes	ISO currency code (e.g., USD, EUR)
bill_to	object	Yes	Customer billing information
device_info	object	Yes	User device information
merchant_defined_info	array	Optional	Additional merchant-defined information

Card Information Formats

The card.number field accepts three different formats:

• Permanent Token: "{{token_id : detokenize}}" - For permanent tokens

• Temporal Token: "{{temp_token_id : transaction}}" - For one-time use tokens

• Card Number: "4111111111111111" - Plain card number string

The card.expiration_date field accepts:

• Permanent Token: "{{token_id : detokenize}}" - For permanent tokens

• Temporal Token: "{{temp_token_id : transaction}}" - For one-time use tokens

• Plain Format: "12/25" - MM/YY format

Example of the JSON response

{
  "status": "success",
  "message": "Transaction rejected",
  "data": {
    "transaction_info": {
      "type": "create_decision_response",
      "reference_code": "80caa37c-da4f-476a-950b-7679e2f45bb9",
      "transaction_id": "0001711566838525825990",
      "request_id": "7115668389676468804951",
      "status": "Rejected",
      "created_at": "2024-03-27T19:13:59Z"
    },
    "payment_information": {
      "scheme": "VISA DEBIT",
      "bin": "462294",
      "accountType": "Visa Classic",
      "issuer": "INTL HDQTRS-CENTER OWNED",
      "binCountry": "US"
    },
    "risk_info": {
      "score": "82",
      "model_used": "default",
      "info_codes": {
        "address": [
          "COR-BA"
        ],
        "phone": [
          "UNV-PH"
        ],
        "globalVelocity": [
          "VEL-ADDR",
          "VEL-NAME",
          "VELI-CC",
          "VELL-CC",
          "VELL-FP",
          "VELL-TIP",
          "VELS-CC",
          "VELS-FP",
          "VELS-TIP",
          "VELV-CC"
        ],
        "suspicious": [
          "MUL-EM"
        ],
        "identityChange": [
          "ID-X-NEG",
          "MORPH-C",
          "MORPH-FE"
        ],
        "internet": [
          "INTL-IPCO",
          "MM-IPBCO"
        ]
      },
      "profile": {
        "earlyDecision": "REJECT"
      },
      "providers": {
        "fingerprint": {
          "first_encounter": "03/12/2024",
          "smart_id": "53994e7085084e218ab52635913e5035",
          "true_ipaddress_country": "PA",
          "device_match": "success",
          "true_ipaddress_city": "panama",
          "time_on_page": "5012",
          "cookies_enabled": "true",
          "device_match_again": "success",
          "flash_enabled": "false",
          "profile_duration": "68",
          "screen_resolution": "1920x1080",
          "true_ipaddress": "190.123.237.237",
          "test_risk_rating": "neutral",
          "agent_type": "browser_computer",
          "images_enabled": "true",
          "javascript_enabled": "true",
          "date_time": "2024-03-27T191354Z",
          "strong_id": "bd55bc3065d5bc45390b298dfd16e2ef9c7ce418",
          "browser_language": "en-US,en;q=0.9",
          "hash": "7c66d47f14024a1080dc19d4e18a13ed",
          "smart_id_confidence_level": "100.00"
        }
      },
      "case_priority": "1"
    }
  }
}}

Response

The API returns a standardized response structure with the following attributes:

• status: string - The status is a string result that only has three possible values: "success", "fail" or "error"

• message: string - The message value represents a short description about the status received

• data: object - The data variable represents the information expected from the request made. This contains the payment information and the decision of the transaction

Response Messages

Status	Message	Description
success	"Transaction accepted"	Transaction was approved
success	"Transaction in review"	Transaction requires manual review
success	"Transaction rejected"	Transaction was declined

Response Example

{
    "status": "success",
    "message": "Transaction accepted",
    "data": {
        "transaction_info": {
            "type": "create_decision_response",
            "reference_code": "123456789",
            "request_id": "0001750957860619700081",
            "decision_id": "7509578607956359904807",
            "status": "Accepted",
            "created_at": "2025-06-26T17:11:01Z"
        },
        "payment_information": {
            "scheme": "VISA DEBIT",
            "bin": "462294",
            "accountType": "Visa Classic",
            "issuer": "INTL HDQTRS-CENTER OWNED",
            "binCountry": "US"
        },
        "risk_info": {
            "score": "93",
            "model_used": "default",
            "info_codes": {
                "address": [
                    "COR-BA"
                ],
                "phone": [
                    "UNV-PH"
                ],
                "globalVelocity": [
                    "VEL-ADDR",
                    "VEL-NAME",
                    "VELI-CC",
                    "VELL-CC",
                    "VELS-CC",
                    "VELV-CC"
                ],
                "suspicious": [
                    "MUL-EM"
                ],
                "identityChange": [
                    "ID-M-HPOS",
                    "ID-X-NEG",
                    "MORPH-C"
                ],
                "internet": [
                    "INTL-IPCO",
                    "MM-IPBCO"
                ]
            },
            "profile": {
                "earlyDecision": "ACCEPT"
            },
            "providers": {
                "fingerprint": {
                    "profile_duration": "5",
                    "test_risk_rating": "neutral"
                }
            },
            "case_priority": "1"
        }
    }
}

Transaction Status Values

The data.transaction_info.status field indicates the final decision:

Status	Description
Accepted	Transaction accepted
Rejected	Transaction rejected
Review	Transaction requires manual review

Usage Examples

cURL - Create Decision

curl --location 'https://api.firstoken.co/v1/risk' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "transaction_info": {
        "type": "create_decision",
        "reference_code": "123456789"
    },
```json
{
    "transaction_info": {
        "type": "create_decision",
        "reference_code": "123456789"
    },
    "card": {
        "number": "4111111111111111",
        "expiration_date": "12/25"
    },
    "order_info": {
        "amount_details": {
            "total_amount": "1000",
            "currency": "USD"
        }
    },
    "bill_to": {
        "first_name": "John",
        "last_name": "Doe",
        "country": "US",
        "address_1": "1001 FALCON AVE",
        "city": "Miami",
        "state": "FL",
        "phone_number": "50762987635",
        "email": "[e-mail]",
        "postal_code": "33166"
    }
}