Standard

📘

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

How It Works

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

⚠️

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.

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]) --> CL[Send Card Link request to issuer]:::process
    CL --> RESP{Issuer responds in time?}
    RESP -->|No| ERR([error: webhook_call_failed]):::error
    RESP -->|Yes| CP{cardProgramId returned?}
    CP -->|Yes| CPID[Use specified Card Program]:::process
    CP -->|No| BIN[Use BIN range default Card Program]:::process
    CPID --> STORE{Storage Mode}
    BIN --> STORE
    STORE -->|Enrol| EN[Store as Enrolment]:::process
    STORE -->|Temp| TMP[Use for this transaction only]:::process
    STORE -->|"Temp With Backup"| BKP["Use for this transaction,<br/>save backup copy"]:::process
    EN --> RISK[Evaluate Risk Profile]:::process
    TMP --> RISK
    BKP --> RISK
    RISK --> OUT{Outcome}
    OUT -->|Frictionless| SUC([SUCCEEDED · Finalised Event]):::success
    OUT -->|Challenge| CHAL([Challenge Flow · Finalised Event]):::process
    OUT -->|Reject| REJ([REJECTED · Finalised Event]):::terminal

Card Link Response

The issuer's Card Link endpoint must return card details in the following structure.

💡

Returning cardProgramId in the response lets you dynamically route individual cards to different Card Programs. This is how you implement per-card accept, reject, or custom challenge behaviour without changing your BIN configuration.

Storage Modes

The Card Link Storage Mode controls how Apata handles card data retrieved during a lookup. Configure the storage mode on the Card Link settings for your Financial Institution.

Authentication Flows

Challenge Flow

Apata receives card details via Card Link, evaluates the Risk Profile, determines a challenge is required, and presents the Challenge Interface to the cardholder using the Challenge Profile configured on the Card Program.

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
    acs->>acs: Evaluate Risk Profile - challenge required
    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

Per-Card Override Flow

By returning a cardProgramId in the Card Link response, the issuer can dynamically assign a card to a specific Card Program. This is commonly used to always accept or always reject certain cards by associating them with a Card Program that has a Simple Rule configured accordingly.

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 (with cardProgramId)
    acs->>acs: Resolve Card Program by cardProgramId
    acs->>acs: Evaluate Risk Profile - accept or reject
    acs->>ds: ARes (transStatus Y or R)
    ds->>3ds: ARes
    opt Finalised Event
        acs->>issuer: Finalised Event notification
    end