API reference

Radar

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

List all early fraud warnings

GET/v1/radar/early_fraud_warnings

Returns a list of early fraud warnings.

Query parameters

  • chargestring

    Only return early fraud warnings for the charge specified by this charge ID.

  • createdobject | integer

    Only return early fraud warnings that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • payment_intentstring

    Only return early fraud warnings for charges that were created by the PaymentIntent specified by this PaymentIntent ID.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of radar.early_fraud_warning objects.

GET /v1/radar/early_fraud_warnings
curl -G https://api.knoxapi.com/v1/radar/early_fraud_warnings \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/radar/early_fraud_warnings",
  "has_more": false,
  "data": [
    {
      "actionable": true,
      "charge": "ch_1234",
      "created": 1234567890,
      "fraud_type": "misc",
      "id": "issfr_1Pgc79B7WZ01zgkWxwDzEIPX",
      "livemode": false,
      "object": "radar.early_fraud_warning"
    }
  ]
}

Create a Payment Evaluation

POST/v1/radar/payment_evaluations

Request a Radar API fraud risk score from Stripe for a payment before sending it for external processor authorization.

Body parameters

  • customer_detailsobjectRequired

    Details about the customer associated with the payment evaluation.

    Show 5 child parameters
    • customerstring
    • customer_accountstring
    • emailstring
    • namestring
    • phonestring
  • payment_detailsobjectRequired

    Details about the payment.

    Show 7 child parameters
    • amountintegerRequired
    • currencystringRequired
    • payment_method_detailsobjectRequired
      Show 2 child parameters
      • payment_methodstringRequired
      • billing_detailsobject

        Child parameters are listed in the OpenAPI document.

    • descriptionstring
    • money_movement_detailsobject
      Show 2 child parameters
      • money_movement_typestringRequired
        Possible values
        • card
      • cardobject

        Child parameters are listed in the OpenAPI document.

    • shipping_detailsobject
      Show 3 child parameters
      • addressobject

        Child parameters are listed in the OpenAPI document.

      • namestring
      • phonestring
    • statement_descriptorstring
  • client_device_metadata_detailsobject

    Details about the Client Device Metadata to associate with the payment evaluation.

    Show 1 child parameter
    • radar_sessionstringRequired
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

The radar.payment_evaluation object.

POST /v1/radar/payment_evaluations
curl https://api.knoxapi.com/v1/radar/payment_evaluations \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d customer_details= \
  -d "payment_details[amount]=1000" \
  -d "payment_details[currency]=usd" \
  -d "payment_details[payment_method_details][payment_method]=pm_1Pgc75B7WZ01zgkWlHVgdEGJ"
Response
{
  "created_at": 1369680106,
  "events": [],
  "id": "obj_123",
  "livemode": true,
  "metadata": null,
  "object": "radar.payment_evaluation",
  "recommended_action": "block",
  "signals": {
    "fraudulent_payment": {
      "evaluated_at": 403283463,
      "risk_level": "normal",
      "score": 109264530
    }
  }
}

Create a value list item

POST/v1/radar/value_list_items

Creates a new ValueListItem object, which is added to the specified parent value list.

Body parameters

  • valuestringRequired

    The value of the item (whose type must match the type of the parent value list).

  • value_liststringRequired

    The identifier of the value list which the created item will be added to.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The radar.value_list_item object.

POST /v1/radar/value_list_items
curl https://api.knoxapi.com/v1/radar/value_list_items \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d value=1.2.3.4 \
  -d value_list=rsl_1Pgc6xB7WZ01zgkWGZtYN8iP
Response
{
  "created": 1234567890,
  "created_by": "[email protected]",
  "id": "rsli_1Pgc6xB7WZ01zgkWS2KbiAtC",
  "livemode": false,
  "object": "radar.value_list_item",
  "value": "1.2.3.4",
  "value_list": "rsl_1Pgc6xB7WZ01zgkWGZtYN8iP"
}

List all value list items

GET/v1/radar/value_list_items

Returns a list of ValueListItem objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first.

Query parameters

  • value_liststringRequired

    Identifier for the parent value list this item belongs to.

  • createdobject | integer

    Only return items that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • valuestring

    Return items belonging to the parent list whose value matches the specified value (using an "is like" match).

Returns

A list of radar.value_list_item objects.

GET /v1/radar/value_list_items
curl -G https://api.knoxapi.com/v1/radar/value_list_items \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode value_list=rsl_1Pgc6xB7WZ01zgkWGZtYN8iP
Response
{
  "object": "list",
  "url": "/v1/radar/value_list_items",
  "has_more": false,
  "data": [
    {
      "created": 1234567890,
      "created_by": "[email protected]",
      "id": "rsli_1Pgc6xB7WZ01zgkWS2KbiAtC",
      "livemode": false,
      "object": "radar.value_list_item",
      "value": "1.2.3.4",
      "value_list": "rsl_1Pgc6xB7WZ01zgkWGZtYN8iP"
    }
  ]
}

Create a value list

POST/v1/radar/value_lists

Creates a new ValueList object, which can then be referenced in rules.

Body parameters

  • aliasstringRequired

    The name of the value list for use in rules.

  • namestringRequired

    The human-readable name of the value list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • item_typestring

    Type of the items in the value list. One of card_fingerprint, card_bin, crypto_fingerprint, email, ip_address, country, string, case_sensitive_string, customer_id, account, sepa_debit_fingerprint, or us_bank_account_fingerprint. Use string if the item type is unknown or mixed.

    Possible values
    • account
    • card_bin
    • card_fingerprint
    • case_sensitive_string
    • country
    • crypto_fingerprint
    • customer_id
    • email
    • ip_address
    • sepa_debit_fingerprint
    • string
    • us_bank_account_fingerprint
  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

The radar.value_list object.

POST /v1/radar/value_lists
curl https://api.knoxapi.com/v1/radar/value_lists \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d alias=custom_ip_blocklist \
  -d "name=Custom IP Blocklist"
Response
{
  "alias": "custom_ip_blocklist",
  "created": 1234567890,
  "created_by": "[email protected]",
  "id": "rsl_1Pgc6xB7WZ01zgkWMAqpozsZ",
  "item_type": "ip_address",
  "list_items": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/radar/value_list_items?value_list=rsl_1Pgc6xB7WZ01zgkWMAqpozsZ"
  },
  "livemode": false,
  "metadata": {},
  "name": "Custom IP Blocklist",
  "object": "radar.value_list"
}

List all value lists

GET/v1/radar/value_lists

Returns a list of ValueList objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first.

Query parameters

  • aliasstring

    The alias used to reference the value list when writing rules.

  • containsstring

    A value contained within a value list - returns all value lists containing this value.

  • createdobject | integer

    Only return value lists that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of radar.value_list objects.

GET /v1/radar/value_lists
curl -G https://api.knoxapi.com/v1/radar/value_lists \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/radar/value_lists",
  "has_more": false,
  "data": [
    {
      "alias": "custom_ip_blocklist",
      "created": 1234567890,
      "created_by": "[email protected]",
      "id": "rsl_1Pgc6xB7WZ01zgkWMAqpozsZ",
      "item_type": "ip_address",
      "list_items": {
        "data": [],
        "has_more": false,
        "object": "list",
        "url": "/v1/radar/value_list_items?value_list=rsl_1Pgc6xB7WZ01zgkWMAqpozsZ"
      },
      "livemode": false,
      "metadata": {},
      "name": "Custom IP Blocklist",
      "object": "radar.value_list"
    }
  ]
}

Retrieve an early fraud warning

GET/v1/radar/early_fraud_warnings/{early_fraud_warning}

Retrieves the details of an early fraud warning that has previously been created. Please refer to the early fraud warning object reference for more details.

Path parameters

  • early_fraud_warningstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The radar.early_fraud_warning object.

GET /v1/radar/early_fraud_warnings/{early_fraud_warning}
curl https://api.knoxapi.com/v1/radar/early_fraud_warnings/issfr_1Pgc79B7WZ01zgkWxwDzEIPX \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "actionable": true,
  "charge": "ch_1234",
  "created": 1234567890,
  "fraud_type": "misc",
  "id": "issfr_1Pgc79B7WZ01zgkWxwDzEIPX",
  "livemode": false,
  "object": "radar.early_fraud_warning"
}

Retrieve a value list item

GET/v1/radar/value_list_items/{item}

Retrieves a ValueListItem object.

Path parameters

  • itemstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The radar.value_list_item object.

GET /v1/radar/value_list_items/{item}
curl https://api.knoxapi.com/v1/radar/value_list_items/li_1Pgc73B7WZ01zgkWx8kcmZPK \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "created": 1234567890,
  "created_by": "[email protected]",
  "id": "rsli_1Pgc6xB7WZ01zgkWS2KbiAtC",
  "livemode": false,
  "object": "radar.value_list_item",
  "value": "1.2.3.4",
  "value_list": "rsl_1Pgc6xB7WZ01zgkWGZtYN8iP"
}

Delete a value list item

DELETE/v1/radar/value_list_items/{item}

Deletes a ValueListItem object, removing it from its parent value list.

Path parameters

  • itemstringRequired

Returns

The deleted_radar.value_list_item object.

DELETE /v1/radar/value_list_items/{item}
curl -X DELETE https://api.knoxapi.com/v1/radar/value_list_items/li_1Pgc73B7WZ01zgkWx8kcmZPK \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "rsli_1Pgc6xB7WZ01zgkWS2KbiAtC",
  "object": "radar.value_list_item"
}

Update a value list

POST/v1/radar/value_lists/{value_list}

Updates a ValueList object by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Note that item_type is immutable.

Path parameters

  • value_liststringRequired

Body parameters

  • aliasstring

    The name of the value list for use in rules.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • namestring

    The human-readable name of the value list.

Returns

The radar.value_list object.

POST /v1/radar/value_lists/{value_list}
curl https://api.knoxapi.com/v1/radar/value_lists/rsl_1Pgc6xB7WZ01zgkWMAqpozsZ \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "alias": "custom_ip_blocklist",
  "created": 1234567890,
  "created_by": "[email protected]",
  "id": "rsl_1Pgc6xB7WZ01zgkWMAqpozsZ",
  "item_type": "ip_address",
  "list_items": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/radar/value_list_items?value_list=rsl_1Pgc6xB7WZ01zgkWMAqpozsZ"
  },
  "livemode": false,
  "metadata": {},
  "name": "Custom IP Blocklist",
  "object": "radar.value_list"
}

Retrieve a value list

GET/v1/radar/value_lists/{value_list}

Retrieves a ValueList object.

Path parameters

  • value_liststringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The radar.value_list object.

GET /v1/radar/value_lists/{value_list}
curl https://api.knoxapi.com/v1/radar/value_lists/rsl_1Pgc6xB7WZ01zgkWMAqpozsZ \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "alias": "custom_ip_blocklist",
  "created": 1234567890,
  "created_by": "[email protected]",
  "id": "rsl_1Pgc6xB7WZ01zgkWMAqpozsZ",
  "item_type": "ip_address",
  "list_items": {
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/radar/value_list_items?value_list=rsl_1Pgc6xB7WZ01zgkWMAqpozsZ"
  },
  "livemode": false,
  "metadata": {},
  "name": "Custom IP Blocklist",
  "object": "radar.value_list"
}

Delete a value list

DELETE/v1/radar/value_lists/{value_list}

Deletes a ValueList object, also deleting any items contained within the value list. To be deleted, a value list must not be referenced in any rules.

Path parameters

  • value_liststringRequired

Returns

The deleted_radar.value_list object.

DELETE /v1/radar/value_lists/{value_list}
curl -X DELETE https://api.knoxapi.com/v1/radar/value_lists/rsl_1Pgc6xB7WZ01zgkWMAqpozsZ \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "deleted": true,
  "id": "rsl_1Pgc6xB7WZ01zgkWMAqpozsZ",
  "object": "radar.value_list"
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.