Introduction

This is the fastest path to enrolling a card with Astrada end to end: authenticate, point a card at a subaccount, verify the cardholder with 3DS, and activate. Each step links to the detailed guide so you can go as deep as you need.

📘

New here?

If you only read one page, read this one — it maps the whole journey and links out. Astrada's Card Enrollment SDK handles the verification UI and the Stripe steps for you; for the field-by-field contract see Single Card Enrollment — API Reference.

Get the SDK

Astrada provides the Card Enrollment SDK — a hosted JavaScript bundle (no npm install). Add the script to your page:

<script
  type="text/javascript"
  src="https://sdk.astrada.co/v1/cardEnrollmentSdk.js"
  data-id="card-enrollment-sdk"
></script>

It registers a global CardEnrollmentSdk. Open the enrollment form for a cardholder's subaccount, passing a token provider and result handlers:

CardEnrollmentSdk.openForm({
  companyName: "Your company",
  subaccountId: "<subaccountId>",
  getAccessToken: async () => "<access token>", // must resolve within 5s
  onSuccess: (data) => { /* card enrolled */ },
  onError: (data) => { /* show an error */ },
  onCancel: () => { /* cardholder abandoned the flow */ },
});

The SDK renders the entire verification UI for you — the card form below, the 3DS challenge, and the HIGHEST two-hold confirmation:

Full setup and options: Installation; theming and branding: Visual Customization.

The flow at a glance

sequenceDiagram
    autonumber
    participant CH as Cardholder
    participant You as Your app (via the SDK)
    participant Astrada as Astrada API
    participant Issuer
    You->>Astrada: Create card subscription (card + subaccount)
    Astrada-->>You: Subscription created — verification required
    You->>Astrada: Start 3DS verification
    Astrada->>Issuer: Authenticate cardholder (per the subaccount's risk tier)
    Issuer-->>Astrada: Frictionless or challenge result
    Astrada-->>You: completed (or a follow-up step)
    Note over You,Astrada: On success the subscription activates

Your configuration

How a card is verified is controlled by the subaccount's verification policy plus its enrollment controls. This is the whole picture in one place.

What am I enabled on? Inspect the subaccount with GET /subaccounts/{subaccountId}:

{
  "verificationPolicy": { "stripeValidationLevel": "MEDIUM", "sandbox": false },
  "configurations": { "...": "allowed countries / card types / funding" }
}

New subaccounts default to tier MEDIUM with sandbox off. With no tier set, verification runs the default path (TokenEx/IXOPAY for Visa, TNS for Mastercard).

What does each setting do, and what's its flow?

How do I change a setting? PATCH /subaccounts/{subaccountId} (Update Subaccount) — send only the field(s) you want to change; it takes effect on the next verification.

Raise the tier:

PATCH /subaccounts/{subaccountId}

{ "verificationPolicy": { "stripeValidationLevel": "HIGH" } }

Turn on sandbox test routing:

PATCH /subaccounts/{subaccountId}

{ "verificationPolicy": { "sandbox": true } }

Requesting LOW returns 403 (internal-only). Test your settings → Test Cards & Sandbox Testing. Use them → the Steps below.

Steps

1. Authenticate

Get an access token for the Astrada API. See Authentication.

2. Choose a subaccount and set its verification policy

Cards are enrolled under a subaccount, and its verification policy decides how strict verification is and whether sandbox routing is on. New subaccounts default to MEDIUM; set the tier (and sandbox for testing) before you enroll. The decision guide below helps you pick a tier — see Your configuration for inspecting and changing settings.

Which tier should I pick?

flowchart TD
    A[Pick a tier] --> B{Need the strongest proof of ownership?}
    B -- yes --> H[HIGHEST: 3DS + two-hold confirmation]
    B -- no --> C{Want an authorization-hold + fraud signals?}
    C -- yes --> G[HIGH]
    C -- no --> D{Standard verification for most onboarding?}
    D -- yes --> M[MEDIUM - default]
    D -- "want issuer-side soft signals tolerated" --> L[LOW - internal-only, ask Astrada]

3. Create the card subscription

Create the subscription that ties the card to the subaccount — this is the enrollment entry point. The SDK does this for you. Full request/response: Single Card Enrollment — API Reference.

4. Verify the cardholder (3DS)

Verification runs automatically based on the tier. The cardholder either passes frictionlessly or completes a 3DS challenge; at HIGHEST a frictionless result adds a two-hold confirmation. The SDK renders all of this for you. For how the tier shapes what the cardholder sees, see Verification Risk Tiers.

5. Activation

On a successful verification the subscription activates and the card is enrolled. From here you'll receive transactions for the card — see Webhooks and Cards, Subscriptions, and Verifications.

Test before you go live

Enable sandbox on a dedicated subaccount (verificationPolicy.sandbox: true) and use the test-card matrix to drive success, challenge, decline, and HIGHEST flows deterministically — no real money moves. See Sandbox Testing & Test Cards.

When something goes wrong

Every failure returns a structured error (errorCode / category / retryable) and maps to a specific cardholder screen. The full catalog of rejection states, causes, and remediation is in Error States & Remediation.

Next steps

• Verification Risk Tiers — choose and configure the tier.
• HIGHEST Verification — the strictest tier's two-hold flow.
• Sandbox Testing & Test Cards — test every path before production.
• Error States & Remediation — handle every failure.
• Single Card Enrollment — API Reference — the full API contract.