Declined Reasons

Transaction Trust Monitoring (TTM) does not use fixed decline codes. Every decision comes from the rules configured for your account in the Rule Builder. When a rule matches, its action decides the outcome. The reason for a decline is therefore the rule that matched, together with the signals and screening results that made it match.

This page explains how to read the decision and its reason from the Create Transaction response.

Decision Values

The data.approved field holds the decision:

Value	Decision	Meaning
0	Declined	A rule with a decline action matched the transaction.
1	Approved	No rule with a decline, review or custom action matched.
2	Manual review	A rule with a review action matched. Hold the transaction until your team reviews it in the Back Office.
3	Custom action	A rule with a custom action matched. Handle it as agreed for that action.

Where to Find the Reason

Response field	What it tells you
data.rule_hits.decisive_hit	The rule that decided the outcome: rule_name, action, id, short_id and version. It is null when no rule decided the outcome. This is the decline reason.
data.rule_hits.all	Every rule that matched the transaction, including rules that did not decide the outcome.
data.evidence.signals	Risk signals found in the transaction. Signals with type: "bad" raised the risk. related_to lists the datapoints each signal was based on.
data.score	Risk score from 0 (lowest risk) to 1 (highest risk).
data.sanctions_lists.hit	Sanctions list result: HIT, NO_HIT or ERROR. Returned when enabled for your account.
data.aml_screening.hit	AML screening result for the customer: MATCH, POTENTIAL_MATCH, NO_MATCH or ERROR. Returned when enabled for your account and aml_screening was sent in the request.
data.validation	ok: false with an errors list means some datapoints were not valid and could not be used by the rules. Fix these values and resubmit.

Example: Declined by a Rule

declined-response

{
  "status": true,
  "message": "Transaction submitted successfully",
  "data": {
    "transaction_id": "8a401a3f-00fa-404b-63e4-381c3a2acdfe",
    "score": 0.65,
    "approved": 0,
    "rule_hits": {
      "decisive_hit": {
        "id": "5f0c2a8e-1b7d-4c3e-9a62-0d4e8f1b2c3a",
        "short_id": 1,
        "version": 3,
        "action": "reject",
        "rule_name": "Rule_1"
      },
      "all": [
        {
          "id": "5f0c2a8e-1b7d-4c3e-9a62-0d4e8f1b2c3a",
          "short_id": 1,
          "version": 3,
          "action": "reject",
          "rule_name": "Rule_1"
        }
      ]
    },
    "validation": {
      "ok": true
    }
  }
}

Here the transaction was declined because the rule Rule_1 matched. To see the rule's conditions, open it in the Back Office Rule Builder.

Common Decline Reasons

What causes a decline depends on the rules you configure. These are the most common rule categories and what usually triggers them:

Reason	Typical trigger	Datapoints involved
Sanctions match	The customer or beneficiary matches a sanctions list.	aml_screening, beneficiary_aml_screening
PEP or adverse media match	AML screening returns a PEP or adverse media match.	aml_screening, beneficiary_aml_screening
High-risk jurisdiction	The customer, beneficiary, card issuer or IP address is in a high-risk country.	bin_ctry, beneficiary_bin_ctry, ip, cust_nationality, beneficiary_nationality
Amount threshold	The transaction amount is above a configured limit.	trans_amt, trans_currency
Velocity	Too many transactions, or too large a total amount, in a period of time.	cust_id, beneficiary_id, trans_amt, trans_ts
Device risk	The device has a poor reputation or low score.	device_id, device_score, device_reputation, ip
Customer profile	For example, the customer is a minor or the account is very new.	cust_dob, cust_signup_ts
High-risk merchant or industry	The merchant category is high risk.	slr_ind_cat, slr_ind_mcc

note

Rules only evaluate datapoints that are sent in the request. If a datapoint a rule needs is missing or invalid, that rule cannot match. Also make sure you send rule_sets when your rules belong to rule sets; see Rule Sets.

Handling a Declined Transaction

1. Read data.rule_hits.decisive_hit.rule_name to see which rule declined the transaction.
2. Check data.evidence.signals and the screening fields to see what the rule reacted to.
3. Open the transaction in the Back Office under Reports › KYT Reports to see the full details, including the AI summary, AML results and linked transactions.
4. If the decline is a false positive, adjust the rule in the Rule Builder. Do not resubmit the same transaction to get a different result.