# Create decision

## **Endpoint:** <mark style="color:purple;">`POST /v1/risk`</mark>

### **Headers**

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

### **Request Body**

{% code overflow="wrap" %}

```json
{
    "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"
        }
    ]
}
```

{% endcode %}

#### Parameters

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

**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

<details>

<summary>Example of the JSON response</summary>

```json
{
  "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"
    }
  }
}}

```

</details>

### 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**

<table><thead><tr><th width="119.81640625">Status</th><th width="225.9453125">Message</th><th width="264.61328125">Description</th></tr></thead><tbody><tr><td><code>success</code></td><td><code>"Transaction accepted"</code></td><td>Transaction was approved</td></tr><tr><td><code>success</code></td><td><code>"Transaction in review"</code></td><td>Transaction requires manual review</td></tr><tr><td><code>success</code></td><td><code>"Transaction rejected"</code></td><td>Transaction was declined</td></tr></tbody></table>

**Response Example**

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

<table><thead><tr><th width="151.71484375">Status</th><th width="378.43359375">Description</th></tr></thead><tbody><tr><td><code>Accepted</code></td><td>Transaction accepted</td></tr><tr><td><code>Rejected</code></td><td>Transaction rejected</td></tr><tr><td><code>Review</code></td><td>Transaction requires manual review</td></tr></tbody></table>

### Usage Examples

cURL - Create Decision

````json
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"
    }
}
````