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": "accept@gmsectec.com",
        "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": "accept@gmsectec.com",
        "postal_code": "33166"
    }
}
PreviousHow it worksNextUpdate Decision

Last updated

Was this helpful?