Guides
PortalContact Sales
Start typing to search…
  1. Card Link

With Risk Evaluation

Card Link with Risk extends the standard Card Link integration by allowing the issuer to return a risk decision alongside card details in a single response. Instead of - or in addition to - Apata evaluating the configured Risk Profile, the issuer's own risk engine can directly influence the authentication outcome.

📘

To integrate Card Link with Risk, implement the webhook endpoint according to the Card Link with Risk API reference.

How It Works

Single Request

Card data and risk decision are returned together in one Card Link response, eliminating the need for a separate risk engine call.

Issuer-Controlled Outcome

The issuer's riskAction takes precedence over Apata's Risk Profile rules when set to ACCEPT, CHALLENGE, or REJECT.

Risk Score Passthrough

The issuer can return a numeric Risk Score and category, which Apata uses within its Risk Profile evaluation via a Low-Risk Rule.

Exemption Control

When accepting a transaction, the issuer can specify which exemption to report to the payment scheme, giving full control over the authentication outcome.

The Card Link request is sent synchronously during transaction processing. The issuer must respond within the timeout for their payment scheme.

Visa

Maximum response time: 5 seconds

Mastercard

Maximum response time: 7 seconds

⚠️

If the issuer's endpoint does not respond within the timeout, the transaction is errored with webhook_call_failed and the cardholder cannot complete authentication.

Risk Response Fields

The issuer returns the following risk fields in the Card Link response alongside the standard card details.

riskAction

Controls the authentication outcome directly. When provided, Apata acts on this value before evaluating any Risk Rules.

ValueBehaviour
ACCEPTTransaction is approved as a Frictionless Transaction. Risk Rules are not evaluated.
CHALLENGETransaction is sent to Challenge Flow. Risk Rules are not evaluated.
REJECTTransaction is REJECTED. Risk Rules are not evaluated.
EVALUATEApata evaluates the Risk Profile rules as normal. This is the default if riskAction is not provided.
riskScoreCategory

An optional categorical risk assessment returned by the issuer. Used by Apata's Low-Risk Rule within the Risk Profile when riskAction is EVALUATE or not provided.

ValueDescription
LOWThe issuer's risk engine considers the transaction low risk.
MEDIUMThe issuer's risk engine considers the transaction medium risk.
HIGHThe issuer's risk engine considers the transaction high risk.
riskScore

An optional numeric score between -100 and 100 returned by the issuer's External Risk Engine. Used alongside riskScoreCategory to inform Apata's Risk Profile evaluation.

A lower score indicates lower risk. A higher score indicates higher risk.

exemption

Only applicable when riskAction is ACCEPT. Specifies which exemption Apata reports to the payment scheme for the frictionless transaction. If not provided, defaults to LOW_RISK.

ValueDescription
LOW_RISKTRA exemption. Default if not specified.
LOW_VALUE_PAYMENTLow Value Payment exemption under PSD2.
RECURRINGRecurring Payment exemption.
ACQUIRER_EXEMPTIONAcquirer Exemption.
MERCHANT_INITIATEDMerchant-Initiated Transaction exemption.
ONE_LEG_TRANSACTIONOne-Leg Transaction exemption.
SECURE_CORPORATE_PAYMENTSecure Corporate Payment exemption.
WHITELISTEDWhitelist exemption.
DATA_SHAREData Share only transaction.
NON_PAYMENTNPA transaction.

Decision Flow

flowchart TD
    classDef error fill:#fde8e8,stroke:#e53e3e,color:#9b2335
    classDef success fill:#e6ffed,stroke:#38a169,color:#276749
    classDef terminal fill:#fff5f5,stroke:#fc8181,color:#c53030
    classDef process fill:#ebf8ff,stroke:#4299e1,color:#2c5282
    CL([Card Link response received]) --> RA{riskAction?}
    RA -->|ACCEPT| ACC["Apply specified exemption<br/>Generate Authentication Value"]:::process
    RA -->|CHALLENGE| CHAL[Proceed to Challenge Flow]:::process
    RA -->|REJECT| REJ[ARes: transStatus R]:::process
    RA -->|"EVALUATE or not set"| SCORE{Risk score returned?}
    SCORE -->|Yes| RULES["Pass score to Risk Profile<br/>Evaluate Risk Rules"]:::process
    SCORE -->|No| RULES2[Evaluate Risk Rules normally]:::process
    ACC --> SUC([SUCCEEDED · Finalised Event]):::success
    REJ --> REJOUT([REJECTED · Finalised Event]):::terminal
    RULES --> OUT{Outcome}
    RULES2 --> OUT
    OUT -->|Frictionless| SUC2([SUCCEEDED · Finalised Event]):::success
    OUT -->|Challenge| CF([Challenge Flow · Finalised Event]):::process
    OUT -->|Reject| REJ2([REJECTED · Finalised Event]):::terminal
    CHAL --> CF2([Challenge Flow · Finalised Event]):::process

Example Responses

The issuer instructs Apata to challenge the cardholder regardless of Risk Rule outcomes.

{
  "financialInstitutionId": "f88458df-20ea-49b7-b890-119c2f5e8c6e",
  "externalId": "card-external-id-1234",
  "language": "en-GB",
  "riskAction": "CHALLENGE"
}

Authentication Flows

Challenge Flow

The issuer returns riskAction: CHALLENGE in the Card Link response. Apata skips Risk Rule evaluation and proceeds directly to the Challenge Flow.

sequenceDiagram
    autonumber
    participant ch as Cardholder
    participant 3ds as 3DS Server
    participant ds as Directory Server
    participant acs as Apata ACS
    participant issuer as Issuer
    ch->>3ds: Initiate transaction
    3ds->>ds: AReq
    ds->>acs: AReq
    acs->>issuer: Card Link request
    issuer->>acs: Card details + riskAction CHALLENGE
    acs->>ds: ARes (transStatus C)
    ds->>3ds: ARes (transStatus C)
    3ds->>acs: CReq
    acs->>ch: Deliver OTP and render Challenge Interface
    ch->>acs: Submit OTP
    acs->>acs: Verify OTP
    acs->>ds: RReq
    ds->>3ds: RReq
    3ds->>ds: RRes
    ds->>acs: RRes
    acs->>ch: Redirect to merchant
    opt Finalised Event
        acs->>issuer: Finalised Event notification
    end

Frictionless Flow (Accept)

The issuer returns riskAction: ACCEPT. Apata approves the transaction frictionlessly and reports the specified exemption to the payment scheme.

sequenceDiagram
    autonumber
    participant ch as Cardholder
    participant 3ds as 3DS Server
    participant ds as Directory Server
    participant acs as Apata ACS
    participant issuer as Issuer
    ch->>3ds: Initiate transaction
    3ds->>ds: AReq
    ds->>acs: AReq
    acs->>issuer: Card Link request
    issuer->>acs: Card details + riskAction ACCEPT + exemption
    acs->>acs: Generate Authentication Value
    acs->>ds: ARes (transStatus Y)
    ds->>3ds: ARes (transStatus Y)
    opt Finalised Event
        acs->>issuer: Finalised Event notification
    end

Benefits

Single API Call

Card data and risk decision are combined into one response, reducing integration complexity and latency.

Override When Needed

The issuer can bypass Apata's Risk Rules entirely for specific cards or transaction patterns.

Granular Scoring

Returning a numeric Risk Score gives Apata's Risk Profile richer signal for threshold-based decisions.

Exemption Reporting

Control which exemption is reported to the payment scheme for every frictionless transaction the issuer approves.

Scheme Compliance

Issuer-driven exemptions ensure correct ECI and Authentication Value values are generated for each approval type.

No Pre-Enrolment

Like standard Card Link, no cards need to be pre-enrolled in Apata.

Updated 24 days ago