Transaction 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

    START([AReq received from DS]) --> BIN{BIN range found?}
    BIN -->|No| ERR1([error: no_such_card_range]):::error
    BIN -->|Yes| CL[Send Card Link request to Issuer]:::process
    CL --> TOUT{Issuer responds in time?}
    TOUT -->|No| ERR2([error: webhook_call_failed]):::error
    TOUT -->|Yes| RESOLVE["Resolve Card Program<br/>Risk Profile · Challenge Profile"]:::process
    RESOLVE --> CLRISK{Card Link with Risk?}
    CLRISK -->|Standard or EVALUATE| RULES[Evaluate Risk Rules]:::process
    CLRISK -->|ACCEPT| FRIC
    CLRISK -->|CHALLENGE| CHAL
    CLRISK -->|REJECT| REJNODE
    RULES -->|Frictionless| FRIC["Generate Authentication Value<br/>ARes: transStatus Y"]:::process
    RULES -->|Challenge| CHAL[ARes: transStatus C]:::process
    RULES -->|Reject| REJNODE[ARes: transStatus R]:::process
    FRIC --> SUC1([SUCCEEDED · Finalised Event]):::success
    REJNODE --> REJ([REJECTED · Finalised Event]):::terminal
    CHAL --> CREQ{CReq received within 30s?}
    CREQ -->|No| ABT([ABORTED · Finalised Event]):::terminal
    CREQ -->|Yes| CHALLENGE[Run Challenge Methods]:::process
    CHALLENGE --> PASS{Challenge passed?}
    PASS -->|No| FAIL([FAILED · Finalised Event]):::terminal
    PASS -->|Yes| AUTHVAL["Generate Authentication Value<br/>RReq to DS"]:::process
    AUTHVAL --> SUC2([SUCCEEDED · Finalised Event]):::success

1. Receiving the Authentication Request

When a cardholder initiates a payment, the merchant's 3DS Server sends an AReq to the DS, which forwards it to the Apata ACS. This routing happens because the issuer has registered their BIN ranges in the DS pointing to the Apata ACS URL.

Apata uses the acctNumber field in the AReq, which contains the cardholder's PAN, to identify the matching BIN or Card Range.

⚠️

If no matching BIN or Card Range is found, Apata errors the transaction immediately with errorCode: no_such_card_range.

2. Card Resolution via Card Link

Once the BIN range is identified, Apata determines how to resolve the card details. Card Link configuration is checked at two levels in order:

1. The organisation-level Card Link configuration, if present
2. The Card Link configuration set on the individual BIN range

Using the resolved configuration, Apata sends a Card Link request to the issuer's Webhook endpoint.

⚠️

If the issuer's endpoint does not respond within the timeout, Apata errors the transaction with errorCode: webhook_call_failed.

For a full reference of Card Link request and response options, see the Card Link guide.

3. Card Program Lookup

After a successful Card Link response, Apata resolves the Card Program to use for the transaction. The lookup follows a priority order:

Once the Card Program is resolved, Apata applies the Risk Profile and Challenge Profile configured on that program for all subsequent evaluation.

💡

You can inspect which Card Program, Risk Profile, and Challenge Profile were used for any transaction via the transaction details page in the Portal, or by checking the transaction.cardProgramId, transaction.riskProfileId, and challenges.challengeProfileId fields in the Finalised Event.

4. Risk Evaluation

How risk is evaluated depends on whether the issuer is using standard Card Link or Card Link with Risk.

5. Transaction Outcome

Risk evaluation produces one of three outcomes. Each follows a distinct path.

📘

In all terminal outcomes, the issuer receives a Finalised Event notification containing the complete transaction record. See the Finalised Event reference for the full payload schema.