Cards, Subscriptions, and Verifications
Introduction
Cards, Subscriptions, and Verifications are all pivotal components for providing you with access to transactional data. These resources are used to abstract the complexities of establishing data sharing with the multiple partners and integrations required for your seamless experience.
Cards contain the indelible facts relating to a card and is a specific reference to the physical or virtual card, as a unique combination of its attributes, including PAN, Expiry Date, and Country. This resource is used for providing you with the information you require about the physical or virtual card itself. Please note: The PAN will not be exposed via the Card resource and is only used to guarantee uniqueness.
Subscriptions contain the state of data sharing for a particular Card and enable you to understand when data sharing has been enabled and disabled over time. This resource is used for tracking the present and past state of data sharing on a specific card.
Verifications are used to track the current state of the process to verify the cardholder's identity.
In this page, we will provide you a deeper understanding of each resource and it's corresponding data model.
Cards
A Card in the service represents the physical or virtual payment card, encapsulating essential information that remains constant over its lifetime. This includes the card's country of issuance, expiry date, and other indelible facts.
Cards Entity
Field | Requirement | Type | Description | Format |
---|---|---|---|---|
id | REQUIRED | string | The unique identifier of the Card entity. | UUID |
subaccountId | REQUIRED | string | The unique identifier of the corresponding Subaccount | UUID |
network | REQUIRED | string | The card network | enum: VISA, MASTERCARD, UNKNOWN |
country | REQUIRED | string | Country of Issuance | ISO 3166 ALPHA-3 |
expiryMonth | REQUIRED | integer | Card expiry month | MM, i.e. "12" |
expiryYear | REQUIRED | integer | Card expiry year | YYYY, i.e. "2026" |
first6digits | REQUIRED | string | The first 6 digits of the Card Number (PAN) | |
last4digits | REQUIRED | string | The last 4 digits of the Card Number (PAN) | |
createdAt | REQUIRED | string | Entity creation date | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
updatedAt | REQUIRED | string | Entity last update date | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
Subscriptions
The Subscription resource is the pipeline through which transactional data is shared within the scope of a Subaccount.
It is used to model the state of data-sharing for a particular Card in a particular Subaccount. When the Subscription is active
then transactional data can be received for the corresponding card.
This pipeline abstracts all of the required data-sources to provide a single streamlined view over the transactional data records for a specific Card.
Subscriptions Entity
Field | Requirement | Type | Description | Format |
---|---|---|---|---|
id | REQUIRED | string | The unique identifier of the Subscription entity | UUID |
subaccountId | REQUIRED | string | The unique identifier of the corresponding Subaccount | UUID |
cardId | REQUIRED | string | The id of the associated card | UUID |
customerReferenceId | OPTIONAL | string | An optional id in UUID format passed by the customer to associate with the card subscription | UUID |
state | REQUIRED | string | Subscription status.reqSCA : Subscription requires the card holder to be verified.active : Subscription is active and ready to receive datafailed-to-create : It was not possible to create the subscription due to an internal error.expired : Subscription expired and no data is being shareddeactivated : Subscription was deactivated and no data is being shared | enum: reqSCA , active , failed-to-create , expired , deactivated |
effectiveDate | REQUIRED | string | The effective when the subscription was activated and start receiving data | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
expirationDate | REQUIRED | string | The date when the subscription will expire and stop receiving data | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
enrollmentType | REQUIRED | string | The flow that led to the creation of the card subscription. | enum: cardholder-single , network-bulk |
createdAt | REQUIRED | string | Entity creation date | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
updatedAt | REQUIRED | string | Entity last update date | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
Verifications
Verifications represent the processes required to transition a Subscription from an inactive state to an active state, ensuring that the Card is validated and authorized for data tracking.
The card verification process exists to ensure that the person providing the service with cardholder data for enrollment has the right to provide consent. It is a lightweight form of identity verification intended to suitably restrict and verify accesses to cardholder data to only authorised individuals.
In order to ensure the best security and compliance practices, in tandem with the best UX, our verification measures are based on the latest 3DS standards.
For cards participating in Single Card Enrollment, we look to employ frictionless and challenge authentication flows dictated by the 3DS protocol, to verify the cardholder, and validate the cardholder's access to their card issuer's services. These techniques look to collate and assess different data sources that collectively help ascertain the identity of a specific card holder.
Card holder verification is only required for cards participating in Single Card Enrollment, and the only available verification method is based on 3DS standards.
For cards participating in Corporate Card Bulk Enrollment, we employ implicit verification in partnership with the relevant bank issuer and the payment network. This abstracts individual card holders from having to individually verify corporate cards to their name.
Card Verification Steps
The card verification steps are a critical component of our security protocols, specifically designed to align with the 3DS protocol requirements for verifying a card. This process is structured to ensure a seamless and frictionless authentication experience for cardholders, and promote successful card enrollments.
Initially, our approach focuses on collecting background information about the cardholder to facilitate a verification process that doesn't require active participation from the user. By leveraging device fingerprinting (fingerprint
) technology, which utilizes data from the user's device, browser, and history of previous successful verifications, we aim to authenticate the cardholder's identity in the most non-intrusive way possible known widely as frictionless authentication. This fingerprint information is sent to the issuer's Access Control System (ACS) and verified against all the card holder information that it holds.
ACS decision factors
- Historical Data Comparison: The ACS compares the current device fingerprint with previously seen fingerprints associated with the cardholder. If the device has been used in past successful transactions, it is considered lower risk.
- Anomaly Detection: The ACS looks for anomalies or inconsistencies in the fingerprint data. For example, a sudden change in device characteristics (like a different IP address or unusual operating system) might indicate a higher risk.
- Geolocation and IP Analysis: The ACS assesses the geographical location and IP address of the device. Transactions originating from high-risk regions or using anonymizing services (like VPNs) may be flagged as higher risk.
- Behavioral Analysis: The ACS evaluates the user’s behavior patterns. Deviations from usual behavior, such as purchasing from a new device at an unusual time or buying atypical products, can increase the risk score.
- Reputation Checks: The ACS checks the device fingerprint against known blacklists or databases of fraudulent devices. If the device has been associated with previous fraud, it will be flagged as high risk.
- Device Consistency: The consistency of the device’s attributes over time is analyzed. Frequent changes in device characteristics can be a sign of fraud.
- Transaction Context: The ACS also considers contextual information about the transaction, such as the transaction amount, the type of goods or services being purchased, and the merchant's risk profile.
- Machine Learning Models: Advanced ACS systems use machine learning models to predict fraud. These models are trained on large datasets of both legitimate and fraudulent transactions and can identify complex patterns that signify risk.
In situations where the data obtained from device fingerprinting is insufficient for a successful verification with the ACS, the card issuer may initiate an additional verification step known as the challenge
. In this phase, cardholders who are subject to further verification will need to respond to a token-based challenge. This could involve authentication through an app (online banking or authentication), an SMS code, or a one-time password (OTP). This step is designed to ensure the integrity of the verification process while maintaining a high level of security and user convenience.
It's important to note that card holders have no control over which card verification steps are going to be required, nor if they will be able to be subject to a challenge - this is dependent on the issuer and their risk appreciation and appetite.
Card Verification State
A Card Verification has a defined lifecycle of possible states. These states can be transitioned for a number of reasons, including unsuccessful completion of required verification steps.
1. Validation: The validation process can fail whenever incorrect or ineligible card data is provided to the system. This is usually caused by a constraint to the network, country, or other property inherent to the Card.
2. In Progress: Only one verification may be in state in-progress
for a particular card subscription at any point in time.
A card verification will be in
in-progress
state until a maximum of 1 hour. After that, Astrada will mark this specific card verification asfailed
, and will allow the card holder to restart a new card verification.
2.1. Step expired: This is caused when a verification challenge
is not completed in the required time period.
- If the card holder verification step expires, certain issuers will allow users to proceed with the same verification challenge step until up to 1 hour since the previous attempt. After this hour, as explained in the previous point, if the card verification isn't completed successfully, Astrada will mark this specific card verification as
failed
, and will allow the card holder to restart a new card verification.- However, specifically on the SDK, if a card verification isn't successfully completed within 5 minutes, the card verification is set to
failed
, and the card holder is allowed to restart a new verification.- When building your own card enrollment UI using Astrada's endpoints, you can define this timeout period to your own preferences, as long as it respects the limits imposed by the specific card issuer.
2.2. Failed step: This is caused when a cardholder fails a step. Within 3DS type verifications this is most often seen due to a failed challenge step.
If a card verification attempt is unsuccessful, card holders are granted an unlimited number of opportunities to retry the verification process.
2.3. Successful verification: The cardholder has successfully completed all required steps and the verification has transitioned into the completed
state.
Verifications Entity
Field | Requirement | Type | Description | Format |
---|---|---|---|---|
id | REQUIRED | string | The unique identifier of the Verification entity | UUID |
subaccountId | REQUIRED | string | The unique identifier of the corresponding Subaccount | UUID |
cardId | REQUIRED | string | The id of the associated card | UUID |
type | REQUIRED | string | The verification type | enum: 3DS |
currentStepId | REQUIRED | string | The current Verification Step entity id | enum: fingerprint , challenge |
state | REQUIRED | string | Verification statusin-progress : Verification is in progress and requires all verification steps to be completedcompleted : Verification is complete and all associated verification steps are also completedfailed : A Verification Step failed to complete or the Verification expired the time to complete | enum: in-progress , completed , failed |
createdAt | REQUIRED | string | Entity creation date | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
updatedAt | REQUIRED | string | Entity last update date | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
Verifications Step Entity
Field | Requirement | Type | Description | Format |
---|---|---|---|---|
id | REQUIRED | string | The Verification Step identifier | enum: fingerprint , challenge |
subaccountId | REQUIRED | string | The unique identifier of the corresponding Subaccount | UUID |
verificationId | REQUIRED | string | The associated Verification unique identifier | UUID |
type | REQUIRED | string | The Verification Step type | enum: fingerprint , challenge |
state | REQUIRED | string | Verification Step statusin-progress : Verification Step is in progresscompleted : Verification Step is completedfailed : A Verification Step failed to complete or expired the time to complete | enum: in-progress , completed , failed |
outcome | OPTIONAL | string | The Fingerprint Verification Step outcomerequires-challenge : A challenge step is required to be performedauthenticated : It's a frictionless verification, challenge is required | enum: requires-challenge , authenticated |
data | OPTIONAL | JSON | Verification Step specific data required for the client to perform the step | JSON |
createdAt | REQUIRED | string | Entity creation date | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
updatedAt | REQUIRED | string | Entity last update date | ISO 8601 format, YYYY-MM-DDThh:mm:ss |
Updated 4 months ago