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
Create
Create Risk rules for specific amounts, locations, currency, and other relevant parameters.
2
Test
Explore the results brought up by your rules and understand their efficacy.
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.

Risk Rules

Risk rules can be set to review, block, allow and enable 3DS in your transactions.

Results

Everytime a transaction is flagged due to a Risk rule previously set, a result is created.

Lists

With lists you can save up information that might come in handy when setting up your Risk rules.

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

Rule	Conditions
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`

Method	Path	Description
GET	Sandbox `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`

Method	Path	Description
POST	Sandbox `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}`

Method	Path	Description
GET	Sandbox `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`

Method	Path	Description
GET	Sandbox `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`

Method	Path	Description
GET	Sandbox `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`

Method	Path	Description
GET	Sandbox `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

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

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`

Method Path Description

GET

Method	Path	Description
GET	Sandbox `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.

Sandbox

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

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`

Method	Path	Description
POST	Sandbox `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`

Method	Path	Description
POST	Sandbox `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 securing cardholder data and storing payment credentials for multichannel use with the Switch Vault.

Risk

Detect and block any fraud.

Create

Test

Review, Block, Allow and Enable 3DS

Risk Rules

Results

Lists

Risk Rule Verification

Risk Metadata and Results

Risk Lifecycle Events

Impact on Other Applications

Risk Rules

GET /v1/risk/rules

Response Parameters

POST /v1/risk/rules

Request Body Parameters

Response Parameters

GET /v1/risk/rules/{id}

Response Parameters

Results

GET /v1/risk/results

Response Parameters

Review

GET /v1/risk/results

Request Parameters

Response Parameters

GET /v1/risk/results

Request Parameters

Response Parameters

Block

GET /v1/risk/results

Request Parameters

Response Parameters

Lists

POST /v1/risk/lists

Request Body Parameters

Response Parameters

POST /v1/risk/lists/items

Request Body Parameters

Response Parameters

Next Steps

GET `/v1/risk/rules`

POST `/v1/risk/rules`

GET `/v1/risk/rules/{id}`

GET `/v1/risk/results`

GET `/v1/risk/results`

GET `/v1/risk/results`

GET `/v1/risk/results`

POST `/v1/risk/lists`

POST `/v1/risk/lists/items`