Card Enrolment
Card Link allows Apata to fetch card details from the issuer's system in real time when a transaction is received, rather than requiring cards to be pre-enrolled. When a transaction arrives, Apata calls the issuer's Card Link endpoint with the PAN and the issuer responds with the card details needed to process authentication.
Card Link Types
The standard integration type. The issuer implements the Card Link endpoint according to the Apata API specification.
Extends STANDARD_V1 to allow the issuer to include risk engine results directly in the card details response.
A bespoke integration built by Apata. Read-only in the Portal; managed by the Apata Customer Success team.
The standard type for all issuers that do not require a custom integration. The issuer implements the Card Link endpoint according to the Apata API specification and returns card details in the standard format.
An extension of STANDARD_V1 that allows the issuer to include risk engine results directly in the card details response, removing the need for a separate risk evaluation call.
| Field | Values | Behaviour |
|---|---|---|
riskAction | ACCEPT, CHALLENGE, REJECT | Takes precedence over all Risk Profile rules. Defaults to EVALUATE if omitted. |
riskScoreCategory | LOW, MEDIUM, HIGH | Feeds into Conditional Rules as the "Risk Score" field. |
riskScore | -100 to 100 | Numeric score for additional granularity. |
exemption | LOW_RISK, DATA_SHARE, ACQUIRER_EXEMPTION, and others | Reported to the payment scheme when riskAction is ACCEPT. Defaults to LOW_RISK. |
A fully custom integration built by Apata for a specific issuer. Custom integrations cannot be created or modified via the Portal and must be managed by the Apata Customer Success team. They can be viewed in the Portal in a read-only state.
PAN Formatting
The PAN is sent as received from the payment scheme, with no transformation applied.
The PAN is hashed before sending.
- Supported algorithm: SHA-256
- Supported encodings: Base64, HEX
The PAN is encrypted using a pre-shared secret.
- Supported algorithm: AES-256-GCM
- Supported encodings: Base64, HEX
Storage Modes
Permanently stores card details. Card Link is not called again for future transactions.
Stores card details for the current transaction only. Card Link is called on every transaction.
Stores card details temporarily with a 90-day backup. Falls back to backup if Card Link fails.
Apata enrolls the card details permanently, in the same way as the CreateCard endpoint. Future transactions use the stored details and Card Link is not called again. To update the card, the issuer must use the UpdateCard endpoint.
Apata stores the card details only for the duration of that transaction. A new Card Link request is made for every transaction.
Similar to Temp, but Apata also maintains a backup of the most recently received card details for up to 90 days. If a Card Link request fails, Apata falls back to the backup details and proceeds with the transaction. Error responses such as card disabled or card not enrolled do not count as failures.
The card_lookup_method field on the transaction indicates how the card was resolved:
| Value | Meaning |
|---|---|
| CARD_LINK | Card details were fetched from the issuer. |
| CARD_LINK_BACKUP | The issuer did not respond; backup details were used. |
| SYSTEM_STORE | The card was already enrolled and Card Link was not used. |
| UNKNOWN | The lookup method could not be determined. |
Card Link Responses
Successful Response
The issuer must return at minimum:
| Field | Description |
|---|---|
financialInstitutionId | Identifies which Financial Institution the card belongs to. Required because multiple Financial Institutions can share the same BIN. |
externalId | An external reference meaningful to the issuer, used for filtering and querying. |
language | The preferred language for any cardholder-facing interfaces or messages. |
Optional fields include phone numbers and email addresses for OTP delivery, a cardProgramId to dynamically assign the card to a specific Card Program, a challengeProfileId to override the profile inferred from the Card Program, and KBA questions and answers if the KBA challenge method is in use.
Unsuccessful Response
| Code | Meaning |
|---|---|
| CARD_NOT_ENROLLED | The card exists but is not enrolled in the 3DS service. |
| CARD_DOES_NOT_EXIST | No card with the specified PAN exists. |
| CARD_DISABLED | The card is currently disabled. |
When returning CARD_NOT_ENROLLED, Mastercard may invoke a stand-in service which can incur charges for the issuer. If the card does not exist at all, return CARD_DOES_NOT_EXIST instead.
Enabling Card Link
Card Link can be enabled at the Organisation level, applying to all transactions across the organisation, or at the BIN and Card Range level for more targeted activation. The configuration is the same in both cases - only the point at which it is applied differs.
Updated 7 months ago