Risk

Detect and block any fraud.

When it comes to payments, security is of the utmost importance. Set up fraud prevention strategies and keep commerce safe with our Risk solution.

  1. 1
    Create

    Create Risk rules for specific amounts, locations, currency, and other relevant parameters.

  2. 2
    Test

    Explore the results brought up by your rules and understand their efficacy.

  3. 3
    Review, Block, Allow and Enable 3DS

    Devise Risk rules to immediately block dangerous transactions and set dubious payments up for review. There are exceptions to every rule, you can give these a free pass through allow.

The Risk Application exists to keep your transactions safe through straightforward methods that can be easily automated. There are four main stages to the way Switch handles Risk.

  1. 1
    Risk Rule Verification

    Everytime a transaction comes in it gets filtered through your Risk rules. Risk rules outrank all other errors that might be generated by a dubious transaction. The Risk Application validates rules following this specific order: allow, block, and review.

  2. 2
    Risk Metadata and Results

    Metadata refers to a set of parameters, some directly extracted from the transaction, and others computed from those, that are stored for each transaction that is ingested by the Risk API. Everytime a metadata object is created for a transaction, the Risk API will tap into the merchant's Risk rules, and check if the metadata matches any of the conditions. If it does, a result is created. This result includes the reason why the transaction was flagged and the triggered action that was triggered. This means the stored metadata can be linked to Risk rules set by merchant, namely regarding amount, currency, country, etc. At the same time, the Risk metadata can also take into account risk scores and blacklists set by external risk providers.

  3. 3
    Risk Lifecycle Events

    Risk rules have influence over the normal lifecycle of a transaction. This means they generate specific lifecycle events which translate the actions taken on the different elements of a transaction.

  4. 4
    Impact on Other Applications

    After a Risk intervention, the transaction flow may no longer be the same. This means that an element affected by Risk gets handled in different ways through the other applications (e.g. an instrument.risk lifecycle event created upon a block rule prevents the Processing Application from sending the authorization message to the provider).

Risk is present in your transactions from the very start and it defines the ways in which these transactions are processed and settled. The goal of this application is not only to offer constant vigilance over your payment operation, but also aid you in understanding what went wrong and how it can be addressed. Risk rules are designed to trigger the following actions:

  • Allow: Allow the creation of the flagged object;
  • Block: Block the creation of the flagged object;
  • Review: Set the creation of an object up for review;
  • Enable 3DS: Enable request for 3D Secure authentication.

Risk Rules

Risk rules can fit four categories: review, block, allow and enable 3DS. This is the core element of the Risk Application. Rules can be defined around amounts, card types, currency, and instrument details, among many other parameters.

RuleConditions
Amount
Flag transactions depending on the amount being considered.
amount
- Greater than (value)
- Greater than or equals (value)
- Less than (value)
- Less than or equals (value)
Amount higher than maximum
Flag transactions representing amounts above the maximum amount of recent past transactions. maximum set amount.
amount_higher_than_max
- Equals (true; false)
Amount lower than minimum
Flag transactions representing amounts below the minimum amount of recent past transactions.
amount_lower_than_min
- Equals (true; false)
Number of amount standard deviations offset
Consider the amount of variation or dispersion of a set of values. Flag transactions with amounts too close or too far to your mean.
amount_standard_score
- Greater than (value)
- Greater than or equals (value)
- Less than (value)
- Less than or equals (value)
Card BIN
Flag specific BIN numbers or sets of numbers. The term Bank Identification Number (BIN) refers to the initial set of four to six numbers that appear on a payment card. This set of numbers identifies the institution that issues the card and is key in the process of matching transactions to the issuer of the charge card.
card_bin
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Card brand
Flag specific card brands.(e.g. VISA)
card_brand
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Card type
Flag specific card types. (e.g. CREDIT)
card_type
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Card bank
Flag specific banks (e.g. JPMORGAN CHASE BANK, N.A.).
card_bank
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Card expiration month
Flag card within a set of expiration months.
card_expiration_month
Greater than (value)
Greater than or equals (value)
Less than (value)
Less than or equals (value)
Card expiration year
Flag card within a set of expiration years.
card_expiration_year
- Greater than (value)
- Greater than or equals (value)
- Less than (value)
- Less than or equals (value)
Charge type
Flag certain charge types, also known as payment methods (e.g. PAYPAL).
charge_type
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Currency
Flag certain currencies (e.g. EUR).
currency
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Customer IP country matches instrument’s
Flag transactions in which the customer’s IP country does/does not match the instrument country provided (e.g. the customer’s IP does not match the country where the card was issued).
customer_country_match_instrument
- Equals (true; false)
Customer IP
Flag specific customer IP values or sets of values.
customer_ip
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Customer IP country
Flag specific customer IP countries or sets of countries.
customer_ip_country
- In (country selection)
- Not in (country selection)
- In list (country selection)
Creation date
Mark transactions within relevant creation dates.
date
- Greater than or equals (date)
- Less than (date)
- Time before(date)
Previous instrument creation date
Isolate instruments derived from previously created instruments by creation date. With this rule you can single out recurring instruments that have not been reauthorized in a while.
previous_instrument_date
- Greater than or equals (date)
- Less than (date)
- Time before(date)
Failure description
Isolate transactions which match/do not match a specific failure description.
failure_description
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Instrument country
Flag certain countries for the instrument object.
instrument_country_
- In (country selection)
- Not in (country selection)
- In list (country selection)
Instrument fingerprint
The instrument fingerprint is a unique, one-way hash of the instrument data (e.g. payment card number). One-way hash functions are used in digital signatures associated with transactions, they identify the instrument in use without exposing real information. Single out specific instrument fingerprints.
instrument_fingerprint
- Equals (value)
- Not equals (value)
- In (value)
- In list (value)
Instrument fingerprint usages last day
Single out instrument fingerprints that have been used a certain amount of times in the last day.
instrument_fingerprint_usages_daily
- Greater than (value)
- Greater than or equals (value)
- Less than (value)
- Less than or equals (value)
Instrument fingerprint usages last hour
Single out instrument fingerprints that have been used a certain amount of times in the last hour.
instrument_fingerprint_usages_hourly
- Greater than (value)
- Greater than or equals (value)
- Less than (value)
- Less than or equals (value)
Instrument fingerprint usages with same customer IP last day
Single out instrument fingerprints associated with the same customer IP that have been used a certain amount of times in the last day.
instrument_fingerprint_by_customer_ip_usages_daily
- Greater than (value)
- Greater than or equals (value)
- Less than (value)
- Less than or equals (value)
Instrument fingerprint usages with same customer IP last hour
Single out instrument fingerprints associated with the same customer IP that have been used a certain amount of times in the last hour.
instrument_fingerprint_by_customer_ip_usages_hourly
- Greater than (value)
- Greater than or equals (value)
- Less than (value)
- Less than or equals (value)
Amount within top 1% in last day
Single out fund transfers corresponding to amounts in the top 1% of your transactions.
top_one_percent_daily
- Equals (true; false)
Requests from customer IP in last 5 minutes
Group transactions associated with a customer IP that has been used an abnormal number of times in the five minutes previous to the transaction in question.
velocity_customer_ip
- Greater than (value)
- Greater than or equals (value)
- Less than (value)
- Less than or equals (value)
Charge metadata
Flag transactions matching/not matching the charge metadata parameters you previously set.
charge_metadata
- Object key

GET /v1/risk/rules

MethodPathDescription
GETSandbox
https://merchant-api-test.switchpayments.com/v1/risk/rules

Production
https://merchant-api.switchpayments.com/v1/risk/rules
List the available Risk rules.
Response Parameters

collectionArray

List of rule objects.


parametersJSON Object

Conditions considered in this Risk rule.


created_atDate

Date in which the Risk rules were created (ISO 8601).


actionString

Type of risk rule applied and its respective action. Possible risk rule types include: allow, block, review, and enable 3DS.


queryString

Risk rule specifications. You can set multiple conditions per rule, each one corresponds to a query.


merchant_idDatetime

Merchant to which the risk rule is applied to.


idString

Identification of the Risk rule.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/risk/rules?merchant_id=accountId -u accountId:APIKey
RESPONSE: HTTP 200
{
"collection": [
{
"parameters": {
"enable3ds": true
},
"created_at": "2020-08-06T10:06:01.789000+00:00",
"action": "SET_PARAMETERS",
"query": {
"top_one_percent_daily": true
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "e75863c03276b74fe573d7e806f2f20008d29cbc5f2bd609"
},
{
"parameters": null,
"created_at": "2020-08-06T10:05:38.614000+00:00",
"action": "REVIEW",
"query": {
"amount_standard_score__gt": 42
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "031c16823237e255b4530ca890e84b5682ed8a225f2bd5f2"
},
{
"parameters": null,
"created_at": "2020-08-06T10:05:07.790000+00:00",
"action": "BLOCK",
"query": {
"amount__gt": 1000
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "64434e11611eff49b13b52d3c0675e546276eacf5f2bd5d3"
},
{
"parameters": null,
"created_at": "2020-08-06T10:04:43.762000+00:00",
"action": "ALLOW",
"query": {
"instrument_fingerprint_by_customer_ip_usages_daily__lte": 42
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "3fef59f4ca3be4c29dd4293e7d9cd9bad5153dac5f2bd5bb"
}
]
}

POST /v1/risk/rules

MethodPathDescription
POSTSandbox
https://merchant-api-test.switchpayments.com/v1/risk/rules

Production
https://merchant-api.switchpayments.com/v1/risk/rules
Create a new Risk rule.
Request Body Parameters

actionStringRequired

Type of risk rule applied and its respective action. Possible risk rule types include: allow, block, review, and enable 3DS.


queryStringRequired

Risk rule specifications. You can set multiple conditions per rule, each one corresponds to a query.


amount__gtNumberRequired

Example of a condition that can be applied on a Risk rule, this case translates a “block translations with amounts greater than 2000” rule.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/risk/rules?merchant_id=accountId -u accountId:APIKey
{
"action": "BLOCK",
"query": {
"amount__gt": 2000
}
}
Response Parameters

parametersJSON Object

Conditions considered in this Risk rule.


created_atDate

Date in which the Risk rule was created (ISO 8601).


actionString

Type of risk rule applied and its respective action. Possible Risk rule types include: allow, block, review, and enable 3DS.


queryString

Risk rule specifications. You can set multiple conditions per rule, each one corresponds to a query.


merchant_idDate

Merchant to which the Risk rule is applied to.


idString

Identification of the Risk rule.

RESPONSE: HTTP 200
{
"parameters": null,
"created_at": "2020-08-06T10:44:58.717000+00:00",
"action": "BLOCK",
"query": {
"amount__gt": 2000
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWCvzOuGBs0W89Gx60LneC7os9",
"id": "fdb4d81954a43975570cd60e4d179343e3f797d15f2bdf2a"
}

GET /v1/risk/rules/{id}

MethodPathDescription
GETSandbox
https://merchant-api-test.switchpayments.com/v1/risk/rules/{id}

Production
https://merchant-api.switchpayments.com/v1/risk/rules/{id}
Get the details of a specific Risk rule.
Response Parameters

collectionArray

List of rules objects.


parametersString

Conditions considered in this Risk rule.


created_atDate

Date in which the Risk rule was created (ISO 8601).


actionString

Type of Risk rule applied and its respective action. Possible risk rule types include: allow, block, review, and enable 3DS.


queryString

Risk rule specifications. You can set multiple conditions per rule, each one corresponds to a query.


merchant_idString

Merchant to which the Risk rule is applied to.


idString

Identification of the Risk rule.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/risk/rules/{id}?merchant_id=accountId -u accountId:APIKey
RESPONSE: HTTP 200
{
"parameters": {
"enable3ds": true
},
"created_at": "2020-08-06T10:06:01.789000+00:00",
"action": "SET_PARAMETERS",
"query": {
"top_one_percent_daily": true
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWCvzOuGBs0W89Gx60LneC7os9",
"id": "e75863c03276b74fe573d7e806f2f20008d29cbc5f2bd609"
}

Results

Everytime a metadata object is created for a transaction, the Risk API will tap into the merchant's Risk rules, and check if the metadata matches any of the conditions. If it does, a result is created. This result includes the reasons why the transaction was flagged and the consequent triggered action. You are able to consult blocked results and filter between results reviewed and results still up for review, as well as simply tap into the entire list of results.

GET /v1/risk/results

MethodPathDescription
GETSandbox
https://merchant-api-test.switchpayments.com/v1/risk/results

Production
https://merchant-api.switchpayments.com/v1/risk/results
List all the available Risk results.
Response Parameters

collectionArray

Collection of Risk results.


parametersJSON Object

Parameters associated with the transaction.


created_atDate

Date in which the result were created (ISO 8601).


actionString

Type of risk rule applied and its respective action. Possible risk rule types include: allow, block, review, and enable 3DS.


queryString

Risk rule specifications. You can set multiple conditions per rule, each one corresponds to a query.


merchant_idString

Merchant that produced this result.


idString

Identification of the Risk result.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/risk/results?merchant_id=accountId -u accountId:APIKey
RESPONSE: HTTP 200
{
"collection": [
{
"parameters": {
"enable3ds": true
},
"created_at": "2020-08-06T10:06:01.789000+00:00",
"action": "SET_PARAMETERS",
"query": {
"top_one_percent_daily": true
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "e75863c03276b74fe573d7e806f2f20008d29cbc5f2bd609"
},
{
"parameters": null,
"created_at": "2020-08-06T10:05:38.614000+00:00",
"action": "REVIEW",
"query": {
"amount_standard_score__gt": 42
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "031c16823237e255b4530ca890e84b5682ed8a225f2bd5f2"
},
{
"parameters": null,
"created_at": "2020-08-06T10:05:07.790000+00:00",
"action": "BLOCK",
"query": {
"amount__gt": 1000
},
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "64434e11611eff49b13b52d3c0675e546276eacf5f2bd5d3"
}
}

Review

Transactions set up for review still carry their normal course, this means that a transaction in review is not left on standby. The review Risk rule allows you to to double-check transactions and, if proven necessary, proceed with a refund before a chargeback is needed.

GET /v1/risk/results

MethodPathDescription
GETSandbox
https://merchant-api-test.switchpayments.com/v1/risk/results?action=REVIEW

Production
https://merchant-api.switchpayments.com/v1/risk/results?action=REVIEW
List all the available Risk results up for review.
Request Parameters

actionString

Type of risk rule applied and its respective action. Possible risk rule types include: allow, block, review, and enable 3DS. In this case, since we are searching for results under review, the parameter should be set to REVIEW.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/risk/results?action=REVIEW&merchant_id=accountId -u accountId:APIKey
Response Parameters

paginationJSON Object

Distribution of Risk results per page.


filtersJSON Object

Filters applied to the result search.


collectionArray

Collection of Risk rules.


matchesJSON Object

List of Risk rules that match the transaction.


assessmentJSON Object

Result assessment. It includes the action triggered by the Risk rules, the reasoning associated with it and the respective Risk rule applied.


SET_PARAMETERSArray

Type of Risk Rule applied and the respective conditions applied. In this example the rule applied is enable 3DS.


created_atDate

Date in which the result was created (ISO 8601).


review_actionString

Actions implemented on review.


reviewedBoolean

Whether the result in question was already reviewed or not. true: the result has been reviewed already. In this case it should present a review_action describing the conclusions after review. false: the result still awaits review.


merchant_idString

Merchant to which the result belongs.


idString

Identification of the Risk result.


metadataJSON Object

Parameters associated with the instrument corresponding to this result.

RESPONSE: HTTP 201
{
"pagination": {
"per_page": 20,
"min_remaining_pages": 0,
"page": 1
},
"filters": {
"action": "REVIEW",
"object_type": "instrument",
"object_id": null,
"reviewed": null
},
"collection": [
{
"matches": {
"assessment": {
"action": "REVIEW",
"reason": {
"amount__gt": 50
},
"rule_id": "7bf29b8711e6d70018e3708bcb9224"
},
"SET_PARAMETERS": [
{
"action": "SET_PARAMETERS",
"reason": {
"amount__gt": 30
},
"rule_id": "14a928ee879d4e9e82e5d0f24e12b",
"parameters": {
"enable3ds": true
}
}
]
},
"created_at": "2020-04-28T14:16:21.798000+00:00",
"review_action": null,
"reviewed": false,
"merchant_id": "wI8JVJXVUsd2OfOIwyrWCnpsGjl0G1daXHKZDLC",
"id": "c881af9e393c618816238285",
"metadata": {
"top_one_percent_daily": true,
"instrument_fingerprint_by_customer_ip_usages_daily": 1,
"amount_lower_than_min": false,
"customer_country_match_instrument": false,
"instrument_fingerprint_usages_hourly": 1,
"amount_higher_than_max": false,
"transaction_fields": {
"instrument_fingerprint": "1151c9d887d34ee6bc36b162efdbf7fd",
"charge_type": "card_onetime",
"card_bin": "423564",
"card_bank": "H P COLORADO F.C.U. (CLOSED)",
"object_type": "instrument",
"customer_ip_country": "PT",
"amount": 58.18,
"object_id": "04e66780dad0621877bccccd8445",
"customer_ip": "94.61.247.128",
"card_type": "CREDIT",
"currency": "EUR",
"instrument_country": "US",
"card_brand": "VISA",
"date": "2020-04-28T14:16:21.697000+00:00",
"card_expiration_year": 2020,
"merchant_id": "wI8JVJXVUsd2OfOIwyrWCnpsGjl0G1daXHKZDLC",
"card_expiration_month": 12
},
"instrument_fingerprint_usages_daily": 2,
"instrument_fingerprint_by_customer_ip_usages_hourly": 1,
"velocity_customer_ip": 2,
"id": "d2e89f26d79f4cb0792724023f1c83a3893ed9035ea83ab5"
}
}
}

GET /v1/risk/results

MethodPathDescription
GETSandbox
https://merchant-api-test.switchpayments.com/v1/risk/results?action=REVIEW&reviewed=true

Production
https://merchant-api.switchpayments.com/v1/risk/results?action=REVIEW&reviewed=true
List all the available Risk results already reviewed.
Request Parameters

actionString

Type of risk rule applied and its respective action. Possible risk rule types include: allow, block, review, and enable 3DS. In this case, since we are searching for results under review, the parameter should be set to REVIEW.


reviewedBoolean

Filtering results under review to reviewed or not yet reviewed. true: the list includes only results already reviewed. false: the list included results not yet reviewed.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/risk/results?action=REVIEW&reviewed=true&merchant_id=accountId -u accountId:APIKey
Response Parameters

paginationJSON Object

Distribution of Risk results per page.


filtersJSON Object

Filters applied to the result search.


collectionArray

Collection of Risk rules.


matchesJSON Object

List of Risk rules that match the transaction.


assessmentJSON Object

Result assessment. It includes the action triggered by the Risk rules, the reasoning associated with it and the respective Risk rule applied.


created_atDate

Date in which the result was created (ISO 8601).


review_actionString

Actions implemented on review.


reviewedBoolean

Whether the result in question was already reviewed or not. true: the result has been reviewed already. In this case it should present a review_action describing the conclusions after review. false: the result still awaits review.


merchant_idString

Merchant to which the result belongs.


idString

Identification of the Risk result.


metadataJSON Object

Parameters associated with the instrument corresponding to this result.

RESPONSE: HTTP 201
{
"pagination": {
"per_page": 20,
"min_remaining_pages": 0,
"page": 1
},
"filters": {
"action": "REVIEW",
"object_type": "instrument",
"object_id": null,
"reviewed": true
},
"collection": [
{
"matches": {
"assessment": {
"action": "REVIEW",
"reason": {
"amount__gt": 40
},
"rule_id": "e62dea5351a818451c8395e427b3fde867baa7a45d8ba649"
}
},
"created_at": "2019-09-25T17:40:54.315000+00:00",
"review_action": "This result is in accordance what our policies.",
"reviewed": true,
"merchant_id": "wI8JVJXVUsd2OfOIwyrWCnpsGjl0G1daXHKZDLC",
"id": "3dcc1bb137fa4dae99bad5e7ad1af717b67c67495d8ba6a6",
"metadata": {
"top_one_percent_daily": true,
"instrument_fingerprint_by_customer_ip_usages_daily": 1,
"amount_lower_than_min": false,
"customer_country_match_instrument": false,
"instrument_fingerprint_usages_hourly": 1,
"amount_higher_than_max": false,
"transaction_fields": {
"instrument_fingerprint": "947cc6e0e908f1e7c2670a4e44a819439",
"charge_type": "card_onetime",
"card_bin": "411111",
"card_bank": "JPMORGAN CHASE BANK, N.A.",
"object_type": "instrument",
"customer_ip_country": "PT",
"amount": 48.18,
"object_id": "c2ef6cdd03ebf3b971e59e688d",
"customer_ip": "149.90.219.7",
"card_type": "CREDIT",
"currency": "EUR",
"instrument_country": "US",
"card_brand": "VISA",
"date": "2019-09-25T17:40:54.252000+00:00",
"card_expiration_year": 2020,
"merchant_id": "wI8JVJXVUsd2OfOIwyrWCnpsGjl0G1daXHKZDLC",
"card_expiration_month": 12
},
"instrument_fingerprint_usages_daily": 5,
"instrument_fingerprint_by_customer_ip_usages_hourly": 1,
"velocity_customer_ip": 0,
"id": "39aa358d3e5f294451bdf1c51ee37ae1ef9d46e45d8ba6a6"
}
}
}

Block

Blocked transactions are classified as invalid and cannot be completed. Under a blocked transaction result you can find the associated failure description to better understand why the transaction was invalidated.

GET /v1/risk/results

MethodPathDescription
GETSandbox

https://merchant-api-test.switchpayments.com/v1/risk/results?action=BLOCK

Production

https://merchant-api.switchpayments.com/v1/risk/results?action=BLOCK
List the available blocked Risk results.
Request Parameters

actionString

Type of risk rule applied and its respective action. Possible risk rule types include: allow, block, review, and enable 3DS. In this case, since we are searching for blocked transactions, the parameter should be set to BLOCK.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/risk/results?action=BLOCK&merchant_id=accountId -u accountId:APIKey
Response Parameters

paginationJSON Object

Distribution of Risk results per page.


filtersJSON Object

Filters applied to the result search.


collectionArray

Collection of Risk rules.


matchesJSON Object

List of Risk rules that match the transaction.


assessmentJSON Object

Result assessment. It includes the action triggered by the Risk rules, the reasoning associated with it and the respective Risk rule applied.


SET_PARAMETERSArray

Type of Risk Rule applied and the respective conditions applied. In this example the rule applied is enable 3DS.


created_atDate

Date in which the result was created (ISO 8601).


review_actionString

Actions implemented on review.


reviewedBoolean

Whether the result in question was already reviewed or not. true: the result has been reviewed already. In this case it should present a review_action describing the conclusions after review. false: the result still awaits review.


merchant_idString

Merchant to which the result belongs.


idString

Identification of the Risk result.


metadataJSON Object

Parameters associated with the instrument corresponding to this result.

RESPONSE: HTTP 201
{
"pagination": {
"per_page": 20,
"min_remaining_pages": 0,
"page": 1
},
"filters": {
"action": "BLOCK",
"object_type": "instrument",
"object_id": null,
"reviewed": null
},
"collection": [
{
"matches": {
"assessment": {
"action": "BLOCK",
"reason": {
"amount__gt": 400
},
"rule_id": "486c17721fcc56f3fc79e559437e5b2c62fb8d0e5f294f0b"
},
"SET_PARAMETERS": [
{
"action": "SET_PARAMETERS",
"reason": {
"amount__gt": 100
},
"rule_id": "f76b2ca6bcf4d65121508864f826fbd678217d795ee3563c",
"parameters": {
"enable3ds": true
}
}
]
},
"created_at": "2020-08-05T15:18:44.702000+00:00",
"review_action": null,
"reviewed": null,
"merchant_id": "wI8JVJXVUsd2OfOIwyrWCnpsGjl0G1daXHKZDLC2J3csV5vZ5Rq7LHZgrm8uH4s",
"id": "588056115b22dd5bc0390612f9b4964cd34f212f5f2acdd4",
"metadata": {
"top_one_percent_daily": true,
"instrument_fingerprint_by_customer_ip_usages_daily": 1,
"amount_lower_than_min": false,
"instrument_fingerprint_usages_hourly": 1,
"amount_higher_than_max": false,
"transaction_fields": {
"instrument_fingerprint": "",
"charge_type": "offline_bank_transfer",
"charge_metadata": {
"orderId": 22
},
"object_type": "instrument",
"customer_ip_country": "PT",
"object_id": "d7ea04750ebe0469fd334fb337bd0613c53686395f2acdd4",
"customer_ip": "94.61.247.128",
"currency": "EUR",
"amount": 1234.0,
"date": "2020-08-05T15:18:44.639000+00:00",
"merchant_id": "wI8JVJXVUsd2OfOIwyrWCnpsGjl0G1daXHKZDLC2J3csV5vZ5Rq7LHZgrm8uH4s"
},
"instrument_fingerprint_usages_daily": 8,
"instrument_fingerprint_by_customer_ip_usages_hourly": 1,
"velocity_customer_ip": 1,
"id": "45a5351fdccea029b43bb5f930be5679ed0043e45f2acdd4"
}
}
}

Lists

With lists you can save up information to be considered when setting up and applying your Risk Rules. Examples of use include a list of specific card numbers to block, or a series of customer IPs that should always be allowed. You can add new lists and edit values included in pre-existing lists. To apply a list, you simply need to create a rule with an in list condition and select the list to be used.

POST /v1/risk/lists

MethodPathDescription
POSTSandbox
https://merchant-api-test.switchpayments.com/v1/risk/lists

Production
https://merchant-api.switchpayments.com/v1/risk/lists
Create a new list.
Request Body Parameters

nameString

Designation attributed to the new Risk list.

REQUEST
$ curl -vX GET https://merchant-api.switchpayments.com/v1/risk/lists?merchant_id=accountId -u accountId:APIKey
{
"name": "New List"
}
Response Parameters

created_atDate

Date in which the list was created (ISO 8601).


merchant_idString

Merchant account associated with this list.


idString

The ID attributed to the list.


nameString

Designation attributed to the Risk list.

RESPONSE: HTTP 200
{
"created_at": "2020-08-07T11:39:08.523000+00:00",
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "3d2f076041ac35bbd3ec2fb347000f89eaeec3905f2d3d5c",
"name": "New List"
}

POST /v1/risk/lists/items

MethodPathDescription
POSTSandbox
https://merchant-api-test.switchpayments.com/v1/risk/lists/{id}/items

Production
https://merchant-api.switchpayments.com/v1/risk/lists/{id}/items
Add items to an existing list.
Request Body Parameters

valueString

Value you intend to add to the list.

REQUEST
$ curl -vX POST https://merchant-api.switchpayments.com/v1/risk/lists/{id}/items?merchant_id=accountId -u accountId:APIKey
{
"value": "new value"
}
Response Parameters

created_atDate

Date in which the list item was added (ISO 8601).


merchant_idString

Merchant account associated with this list.


idString

The ID attributed to the list item.


list_idString

ID of the list the item belongs to.

RESPONSE: HTTP 200
{
"created_at": "2020-08-07T14:44:45.935000+00:00",
"merchant_id": "IdxIqq9YYvmQ4izAw6DZpm3nfhUGxHD1MnHTPZWC",
"id": "bfe2440a6b335d74d73e9b97530a4fb395f08dd55f2d68dd",
"value": "new value",
"list_id": "0bb77148184677f58c26254ecd4cde638133ec655f2d66b5"
}

Next Steps

Learn more about the valuable insights you can extract from your transaction by using our Analytics Application.