Introduction

In the Astrada ecosystem, three core resources manage the lifecycle of card enrollment and data sharing: Cards, Card Subscriptions, and Verifications.

A Card represents the physical or virtual payment card identity. A Card Subscription models the data-sharing relationship between a Card and a Subaccount — it is the active link that determines whether transaction data is captured. A Verification ensures the card is validated before data begins to flow.

Together, these resources form the enrollment layer that sits between Subaccounts and Transaction data.

Card

The Card 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, network, and the first and last digits of the PAN (Primary Account Number). A Card is created during the enrollment process and belongs to a specific Subaccount.

Card Resource

Example Card

{
  "_links": {
    "self": { "href": "/cards/f744b691-bf05-4f2a-ab89-bb1afe4eb840" }
  },
  "id": "f744b691-bf05-4f2a-ab89-bb1afe4eb840",
  "subaccountId": "da6649a8-f0ea-4af0-b342-c0b5c3e024dd",
  "first6digits": 434343,
  "last4digits": 4343,
  "network": "mastercard",
  "country": "USA",
  "expiryMonth": 11,
  "expiryYear": 2028,
  "createdAt": "2024-02-04T18:41:16.142Z",
  "updatedAt": "2024-02-04T18:41:16.142Z"
}

Astrada stores only the first 6 and last 4 digits of the PAN. The full card number is never stored or returned by the API.

Cardholder

The Cardholder is an optional sub-resource available via GET /cards/{cardId}/cardholder. It contains personal and corporate information associated with the card — including firstName, lastName, email, and a nested corporate object with corporate.id, corporate.employeeId, and corporate.alternativeEmployeeId. Cardholder data is primarily populated for cards enrolled through network bulk enrollment.

Card Subscription

The Card Subscription models the state of the continuous flow of transactional data for a specific Card within a specific Subaccount. It is the active link that determines whether transaction data is captured for a given card. When a Card Subscription is active, Astrada will deliver transaction data for that card to the associated Subaccount.

Card Subscription Resource

Subscription state

Example Card Subscription

{
  "_links": {
    "self": { "href": "/card-subscriptions/a1b2c3d4-5678-90ab-cdef-1234567890ab" },
    "card": { "href": "/cards/f744b691-bf05-4f2a-ab89-bb1afe4eb840" }
  },
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "subaccountId": "da6649a8-f0ea-4af0-b342-c0b5c3e024dd",
  "cardId": "f744b691-bf05-4f2a-ab89-bb1afe4eb840",
  "enrollmentType": "cardholder-single",
  "state": "active",
  "effectiveDate": "2024-02-04T18:53:32.000Z",
  "expirationDate": "2025-02-04T18:53:32.000Z",
  "createdAt": "2024-02-04T18:53:32.000Z",
  "updatedAt": "2024-02-04T18:53:32.000Z"
}

Only cardholder-single subscriptions can be updated or deactivated via PATCH /card-subscriptions/{id}. Attempting to update a network-bulk subscription returns 422.

Deactivation is final and cannot be undone.

Enrollment Types

• Cardholder Individual Enrollment (cardholder-single): Enrolled via the SDK or API on a per-card basis. See Enrolling Cards.
• Network Bulk Enrollment (network-bulk): Enrolled via the API for corporate card portfolios. See Enrolling Cards.

Webhook Events

Learn more about Webhooks.

Verification

Verifications ensure a Card is validated and authorized before data tracking begins. When a Card Subscription is created via cardholder individual enrollment, it enters the reqSCA state. A Verification must be completed to transition the subscription to active.

For individual enrollment, the verification process uses 3D Secure (3DS):

1. Device Fingerprint — Browser and device data is collected via a hidden iframe to assess risk.
2. 3DS Challenge (conditional) — If the issuer requires it, a challenge is presented via the issuer's Access Control Server (ACS). The form of the challenge (OTP, biometric, in-app notification, etc.) is determined by the card issuer.

Once the verification completes successfully, the Card Subscription transitions to active and transaction data begins flowing.

For a detailed walkthrough of the enrollment and verification flow, see Cardholder Individual Enrollment.

API

See our API reference for the full set of Card and Card Subscription endpoints.