For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Transaction Risk Analysis

Receive real-time customer exemption eligibility.

Our Exemption Optimization Service (EOS) can perform real-time Transaction Risk Analysis (TRA) and respond with an outcome on exemption eligibility. Once eligibility is confirmed, the exemption can be requested from the Issuer as part of both the 3D Secure 2 authentication and payment authorization, or just in the payment authorization alone.

Submitting the exemption request in both the 3D Secure 2 authentication and payment authorization ensures the best chance that the exemption will be applied. This use case is what we cover in this article, but we also show the payment authorization-only flow.

Both authentication and authorization

In this example, we process a 3D Secure 2 authentication using our 3DS Server. This triggers the following actions:

TRA is performed as part of the authentication process. EOS responds with one of the following outcomes:
- Apply Exemption
- Continue
- Force Secure
- Block
If Apply Exemption is returned, the 3DS Server will process the authentication with the Issuer and include the request for the TRA exemption.
Next, the Issuer analyzes the transaction and determines if the TRA exemption can be applied. The Issuer responds with one of the following outcomes:
- Accepts the TRA exemption request; the authentication is frictionless
- Declines the TRA exemption request but determines that another exemption can be applied; the authentication is frictionless
- Declines the TRA exemption request and determines that no other exemption can be applied; the authentication requires a challenge

Authentication message

Sample request

Sample response

TRA outcomes

The following table describes the various outcomes and actions that can occur based on the EOS response.

Outcome	Description	3DS Server Action
Apply Exemption	Transaction was approved for the TRA exemption.	Includes the appropriate exemption request flag in the authentication message to the Issuer.
Continue	Transaction was not approved for an exemption but was deemed to be relatively low risk.	Proceeds with standard 3D Secure authentication. In this scenario, the Issuer can still choose to apply the exemption.
Force Secure	Transaction was not approved for an exemption and was deemed to be high risk. In this scenario, the Issuer should always apply a Strong Customer Authentication (SCA) challenge to authenticate the cardholder.	Proceeds with 3D Secure authentication. Includes the Challenge Mandated flag in the message to the Issuer.
Block	Transaction was identified as very high risk or known fraud.	Does not proceed with 3D Secure authentication.

Authorization message

Once the exemption is accepted by the Issuer, you can proceed to authorization. In our example, we include the authentication data in the message, along with the relevant exemption.

Sample request

curl --location --request POST 'https://apis.sandbox.globalpay.com/ucp/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer vJCIFsAMxW9PgVBKz91MoOSMvw9p' \
--header 'Accept: application/json' \
--header 'X-GP-Version: 2021-03-22' \
--data-raw '{
    "account_id": "TRA_4d49f5d4e1b84ea4a28c8902a8538375",
    "channel": "CNP",
    "type": "SALE",
    "amount": "100",
    "currency": "EUR",
    "reference": "25576071",
    "country": "IE",
    "payment_method": {
        "name": "James Mason",
        "entry_mode": "ECOM",
        "card": {
            "number": "4263970000005262",
            "expiry_month": "09",
            "expiry_year": "22"
        },
        "authentication": {
            "id": "AUT_1ab42d76-5f0e-4d4b-b3bc-72de7071d61d",
            "three_ds": {
               "message_version":"2.2",
               "exempt_status": "TRANSACTION_RISK_ANALYSIS"
            }
        }
    }
}'

Sample response

{
    "id": "TRN_p2fjfkU3mfWrRoQvSd6Omskep5SWxY_25576071",
    "time_created": "2022-05-06T17:08:33.816Z",
    "type": "SALE",
    "status": "CAPTURED",
    "channel": "CNP",
    "capture_mode": "AUTO",
    "amount": "100",
    "currency": "EUR",
    "country": "IE",
    "merchant_id": "MER_f414851d386a4e1f9fa4beb56c5e38b9",
    "merchant_name": "Test Merchant",
    "account_id": "TRA_4d49f5d4e1b84ea4a28c8902a8538375",
    "account_name": "internet",
    "reference": "25576071",
    "payment_method": {
        "result": "00",
        "message": "[ test system ] AUTHORISED",
        "entry_mode": "ECOM",
        "authentication": {
            "cavv_result": ""
        },
        "card": {
            "brand": "VISA",
            "masked_number_last4": "XXXXXXXXXXXX5262",
            "authcode": "12345",
            "brand_reference": "ND6ZF7rk03RaqrIJ",
            "brand_time_created": "",
            "provider": {
                "result": "00",
                "cvv_result": "M",
                "avs_address_result": "M",
                "avs_postal_code_result": "M"
            }
        }
    },
    "batch_id": "BAT_1086726",
    "action": {
        "id": "ACT_p2fjfkU3mfWrRoQvSd6Omskep5SWxY",
        "type": "AUTHORIZE",
        "time_created": "2022-05-06T17:08:33.816Z",
        "result_code": "SUCCESS",
        "app_id": "a5f0OOTJdAChObGXIqi8I5eGq6i6sLlJ",
        "app_name": "my_sandbox_app"
    }
}

Sandbox testing

In the Production environment, the TRA outcome is determined by the overall analysis of the provided transaction data. However, for Sandbox testing, you can trigger an outcome by setting the transaction amount value within a specific range, as indicated in the following table.

TRA outcomes

The following table describes the various outcomes and actions that can occur based on the EOS response.

Outcome	Amount Trigger EUR (or converted equivalent)	3DS Server Action
Apply Exemption	amount <= 250	Populates the outbound authentication message with the appropriate exemption flag.
Continue	250 < amount <= 500	Processes the 3D Secure authentication as normal.
Force Secure	500 < amount <= 750	Populates the outbound authentication message indicating that a challenge is mandated. This will always force a challenge to be applied, regardless of the test card used.
Block	750 < amount	Blocks the transaction and returns the appropriate response.

In Sandbox, the Access Control Server simulator does not accept the exemption request and processes the authentication as standard. The Electronic Commerce Indicator and Transaction Status values will remain as described in our Test Cards article.

Authorization only

In this example, we call the EOS directly to perform TRA and request the associated exemption from the Issuer in the authorization message. This triggers the following actions:

The EOS responds with one of the following outcomes:
- Apply Exemption
- Continue
- Force
- Block
If Apply Exemption is returned, you can proceed directly to authorization and include the exemption request in the message.
The Issuer analyzes the transaction and determines if the TRA exemption can be applied. The Issuer responds with one of the following outcomes:
- Accepts the TRA exemption request; the authorization continues as normal
- Declines the TRA exemption request but determines that another exemption can be applied; the authorization continues as normal
- Declines the TRA exemption request and determines that no other exemption can be applied; SCA is required, and a Soft Decline message is returned

Exemption request message

Sample request

curl --location --request POST 'https://apis.sandbox.globalpay.com/ucp/risk-assessments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TrAtA2UcxiCOj097b5d1P4rj1BKx' \
--header 'Accept: application/json' \
--header 'X-GP-Version: 2021-03-22' \
--data-raw '{
    "source": "BROWSER",
    "account_id": "RAA_577f0b7a91ba4dd8b8c0178eee5a973f",
    "country": "IE",
    "order": {
        "amount": 100,
        "currency": "EUR",
        "reference": "8525aa58-e47b-4d04-88a2-4d589b2c78c1"
    },
    "payment_method": {
        "name": "James Mason",
        "card": {
            "brand": "VISA",
            "number": "4012001038488884",
            "expiry_month": "12",
            "expiry_year": "25"
        }
    },
    "browser_data": {
        "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
        "language": "en-US",
        "ip": "123.123.123.123"
    }
}'

Sample response

{
   "id":"RAS_Wrr413lAtzVWmuS5W3LcIX72cQDyVn",
   "time_created":"2022-04-11T09:22:40.850Z",
   "status":"ACCEPTED",
   "amount":"100",
   "currency":"EUR",
   "merchant_id":"MER_c4c0df11039c48a9b63701adeaa296c3",
   "merchant_name":"Sandbox_merchant_2",
   "account_id":"RAA_577f0b7a91ba4dd8b8c0178eee5a973f",
   "account_name":"exemptions",
   "reference":"8525aa58-e47b-4d04-88a2-4d589b2c78c1",
   "result":"Apply Exemption",
   "message":"Apply Exemption",
   "payment_method":{
      "card":{
         "masked_number_last4":"XXXXXXXXXXXX8884",
         "brand":"VISA",
         "bin":"",
         "bin_country":"",
         "account_type":"",
         "issuer":""
      }
   },
   "raw_response":{
      "platform":"EOS",
      "data":{
         "action_applied":"APPLY_EXEMPTION",
         "transaction_id":"3400dd37-101d-4940-be15-3c963b6109b3",
         "request_id":"dab03eb5-a34a-431f-89c3-a2c45fba530b",
         "matched_rule":{
            "id":42831,
            "title":"Apply Exemption",
            "action_applied":"APPLY_EXEMPTION"
         }
      }
   },
   "action":{
      "id":"ACT_Wrr413lAtzVWmuS5W3LcIX72cQDyVn",
      "type":"ASSESS",
      "time_created":"2022-04-11T09:22:40.850Z",
      "result_code":"SUCCESS",
      "app_id":"U1lRHKomEn7DN907RCDPxVhyMfiMLcfy",
      "app_name":"dev_portal_demo"
   }
}

TRA outcomes

The following table describes the various outcomes and actions that can occur based on the EOS response. It also includes our recommended actions.

Outcome	Description	Recommended Action
Apply Exemption	Transaction was approved for the TRA exemption.	Include the appropriate exemption request flag in the authorization message.
Continue	Transaction was not approved for an exemption but was deemed to be relatively low risk.	Proceed with a standard 3D Secure authentication with the 3DS Server.
Force Secure	Transaction was not approved for an exemption and was deemed to be high risk. In this scenario, the Issuer should always apply a SCA challenge to authenticate the cardholder.	Proceeds with 3D Secure authentication. Include the Challenge Mandated flag in the message to the 3DS Server. For more information, see our 3D Secure documentation.
Block	The transaction was identified as very high risk or known fraud.	Halt the transaction and take appropriate action.

Authorization message

In this example, EOS returned Apply Exemption, so we proceed directly to authorization and bypass 3D Secure authentication. As noted earlier, requesting the exemption in both the authentication and authorization messages is best practice; however, there may be specific use cases that call for authorization only.

Sample request

curl --location --request POST 'https://apis.sandbox.globalpay.com/ucp/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer vJCIFsAMxW9PgVBKz91MoOSMvw9p' \
--header 'Accept: application/json' \
--header 'X-GP-Version: 2021-03-22' \
--data-raw '{
    "account_id": "TRA_4d49f5d4e1b84ea4a28c8902a8538375",
    "channel": "CNP",
    "type": "SALE",
    "amount": "100",
    "currency": "EUR",
    "reference": "25576071",
    "country": "IE",
    "payment_method": {
        "name": "James Mason",
        "entry_mode": "ECOM",
        "card": {
            "number": "4263970000005262",
            "expiry_month": "09",
            "expiry_year": "22"
        },
        "authentication": {
            "three_ds": {
               "message_version":"2.2",
               "exempt_status": "TRANSACTION_RISK_ANALYSIS"   
            }
        }
    }
}'

Sample response

{
    "id": "TRN_p2fjfkU3mfWrRoQvSd6Omskep5SWxY_25576071",
    "time_created": "2022-05-06T17:08:33.816Z",
    "type": "SALE",
    "status": "CAPTURED",
    "channel": "CNP",
    "capture_mode": "AUTO",
    "amount": "100",
    "currency": "EUR",
    "country": "IE",
    "merchant_id": "MER_f414851d386a4e1f9fa4beb56c5e38b9",
    "merchant_name": "Test Merchant",
    "account_id": "TRA_4d49f5d4e1b84ea4a28c8902a8538375",
    "account_name": "internet",
    "reference": "25576071",
    "payment_method": {
        "result": "00",
        "message": "[ test system ] AUTHORISED",
        "entry_mode": "ECOM",
        "authentication": {
            "cavv_result": ""
        },
        "card": {
            "brand": "VISA",
            "masked_number_last4": "XXXXXXXXXXXX5262",
            "authcode": "12345",
            "brand_reference": "ND6ZF7rk03RaqrIJ",
            "brand_time_created": "",
            "provider": {
                "result": "00",
                "cvv_result": "M",
                "avs_address_result": "M",
                "avs_postal_code_result": "M"
            }
        }
    },
    "batch_id": "BAT_1086726",
    "action": {
        "id": "ACT_p2fjfkU3mfWrRoQvSd6Omskep5SWxY",
        "type": "AUTHORIZE",
        "time_created": "2022-05-06T17:08:33.816Z",
        "result_code": "SUCCESS",
        "app_id": "a5f0OOTJdAChObGXIqi8I5eGq6i6sLlJ",
        "app_name": "my_sandbox_app"
    }
}

Soft decline

What is a soft decline?

A soft decline is a response we get when a customers issuing bank are not willing to provide an SCA exemption to the transaction you're processing.

By requesting an exemption in the authorization only, the Issuer might reject the exemption request and respond with what’s known as a soft decline: result code 111. If you receive a soft decline, you can then proceed with standard 3D Secure authentication and a second authorization.

The examples used in this guide involve one authentication message and two authorization messages. In using this logic, you might incur additional transaction fees. For more information, contact your account manager.

Sample response

{
    "id": "TRN_aUZq8cKq57ur5RyiI9PQwQJheFxVXI_58657811",
    "time_created": "2022-05-09T12:58:04.224Z",
    "type": "SALE",
    "status": "DECLINED",
    "channel": "CNP",
    "capture_mode": "LATER",
    "amount": "",
    "currency": "",
    "country": "US",
    "merchant_id": "MER_f414851d386a4e1f9fa4beb56c5e38b9",
    "merchant_name": "Test Merchant",
    "account_id": "TRA_4d49f5d4e1b84ea4a28c8902a8538375",
    "account_name": "internet",
    "reference": "58657811",
    "payment_method": {
        "result": "111",
        "message": "[ test system ] Strong Customer Authentication Required",
        "entry_mode": "ECOM",
        "card": {
            "brand": "VISA",
            "masked_number_last4": "XXXXXXXXXXXX0091",
            "authcode": "",
            "brand_reference": "cl3De8e1TAQzttFT",
            "brand_time_created": "",
            "cvv_result": "NOT_MATCHED",
            "avs_address_result": "NOT_CHECKED",
            "avs_postal_code_result": "NOT_CHECKED",
            "avs_action": "",
            "provider": {
                "result": "111",
                "cvv_result": "N",
                "avs_address_result": "U",
                "avs_postal_code_result": "U"
            }
        }
    },
    "batch_id": "",
    "action": {
        "id": "ACT_aUZq8cKq57ur5RyiI9PQwQJheFxVXI",
        "type": "PREAUTHORIZE",
        "time_created": "2022-05-09T12:58:04.224Z",
        "result_code": "DECLINED",
        "app_id": "a5f0OOTJdAChObGXIqi8I5eGq6i6sLlJ",
        "app_name": "my_sandbox_app"
    }
}

Policies

Connect

Additional Resources

Transaction Risk Analysis

Both authentication and authorization

Authentication message

Sample request

Sample response

TRA outcomes

Authorization message

Sample request

Sample response

Sandbox testing

TRA outcomes

Authorization only

Exemption request message

Sample request

Sample response

TRA outcomes

Authorization message

Sample request

Sample response

Soft decline

What is a soft decline?

Sample response