Integration

To integrate the Card Enrollment SDK into your web application, follow these steps:

1. Loading the JS file

Begin by loading the JavaScript file provided by us. You can find it at the following URL:

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

2. Launching the SDK

Once you have added the script to your website, it will register a global variable named CardEnrollmentSdk. This variable provides the following methods:

• CardEnrollmentSdk.openForm(config): launches the Card Enrollment SDK, used for enrolling cards, and initiates the verification process of the card.
• CardEnrollmentSdk.closeForm(): closes the Card Enrollment SDK.
• CardEnrollmentSdk.setStyle(style): applies your brand theme to the SDK (see Visual Customization).

See the next section to learn about the different configurations supported when calling the openForm method.

Configuration

In this section, you will learn how to configure the parameters when calling the CardEnrollmentSdk.openForm(config)method. The following config parameters are supported:

CardEnrollmentSdk.openForm({
  companyName: "Your company name",
  subaccountId: "67bc3887-4e25-49cf-bea7-326d808acb5f",
  getAccessToken: async () => 'valid-json-web-token',
  getAccessTokenTimeoutMs: 5000, // optional, raise if your token exchange is slow (default 5000)
  onConnect: () => console.log("The SDK connected to the page."),
  onSuccess: (data) => console.log(data),
  onError: (data) => console.log(data),
  onCancel: () => console.log("The user abandoned the enrollment flow."),
  terms: {
  	text: "By checking this box, you are indicating that you agree to the [terms](https://yourcompany.com/terms) and [policy](https://yourcompany.com/policy)."
	}
   // Add more configuration parameters here if needed
  ...
});

TypeScript types

Astrada publishes official TypeScript types for the SDK, @astrada.co/card-enrollment-sdk. The package contains type declarations only, with no runtime code, so install it as a dev dependency; it adds nothing to your bundle, and the SDK still loads from the hosted script above. Importing it also declares the CardEnrollmentSdk global, so you don't hand-write a .d.ts:

npm install --save-dev @astrada.co/card-enrollment-sdk

import type {
  CardEnrollmentSdkConfig,
  EnrollmentSuccess, // the onSuccess payload
  OnErrorPayload,    // the onError payload
  SdkStyle,          // the setStyle argument
} from "@astrada.co/card-enrollment-sdk";

The types are generated from the SDK source and checked against it in CI, so they match what the runtime sends.

Authentication

The Card Enrollment SDK uses a separate set of credentials from the main API. During onboarding, you'll receive dedicated SDK credentials (client_id + client_secret) scoped specifically for card enrollment operations.

The getAccessToken passed to the openForm must be an asynchronous function responsible for returning an Access Token (JWT). Your backend should use the SDK credentials to obtain this token from Astrada's OAuth endpoint, then return it to the frontend. This function must resolve within the configured timeout, 5 seconds by default. If your token exchange is slower, raise the limit with the getAccessTokenTimeoutMs option (in milliseconds). Otherwise, it will timeout and return an error, resulting in a failed enrollment.

The Access Token is fetched at two different points in time:

1. When the SDK is launched.
2. When the Access Token being used expires.

📘

See the Authentication Guide for full details on credential types, the token exchange flow, and security best practices.

🚧

Never use any client_id or client_secret directly in browser code. Your backend must exchange the SDK credentials for a token and pass only the resulting JWT to the frontend via getAccessToken.

Callbacks

Callbacks provide information about events that occur during the card enrollment process.

No payload.

Example Payload:

{
  "subscriptionId": "1c6db37a-333a-4379-8ac5-0f819f2c0bf7",
  "cardId": "8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4",
  "enrollmentGuidance": {
    "availableEnrollmentMethods": [
      "cardholder-single"
    ]
  },
  "authenticationFlow": "frictionless"
}

onSuccess also returns the enrolled cardId and the 3DS authenticationFlow (challenge, frictionless, or null). To retrieve card details as well as the latest subscription status, you can use the subscriptionId to call the GET Card Subscription endpoint.

Example Payload (Server Error):

{
    "type": "server",
    "error": {
      "detail": "Card verification step with id=d397da41-95ac-4bb0-82da-cd78d10d06ff for card verification with id=ed146b4a-8e48-4c7f-b284-62eb64dca7bb can not be completed at this state",
      "title": "Bad Request"
    },
    "verificationId": "ed146b4a-8e48-4c7f-b284-62eb64dca7bb",
    "cardId": "8309b5f8-d5d8-49bb-9001-38bf1bb0f1e4",
    "subscriptionId": "1c6db37a-333a-4379-8ac5-0f819f2c0bf7"
}

Example Payload (Client Error):

{
    "type": "client",
    "error": {
      "detail": "Card subscription data is undefined."
    }
}

When the failure happens after the card subscription and verification exist, onError also includes the discrete verificationId, cardId, and subscriptionId fields (all optional, omitted for pre-create rejections such as an invalid CVC or an ineligible card). Pass verificationId to GET Card Verification to read the verification's failureReason.

No payload.

Customization

Consent Message

Approved Consent Language:

It is mandatory to collect two separate consents: (1) Network Consent and; (2) Astrada & Customer Consent. The Network Consent language will always be shown and isn't customizable, whereas the Astrada & Customer Consent language is.

Network Consent: By submitting your card information and checking this box, you authorize your [Card Network] to access, monitor, and share transaction data (e.g., amount, time, date, and merchant name) with Astrada (our service provider) for the purposes of identifying relevant transactions and carrying out related spend management services. You also affirm that the card being monitored is used primarily for business purposes.

Astrada & Customer Consent: By submitting your card information and checking this box, you affirm your consent so that Astrada may process said data in accordance with [(Customer Name)’s Terms and Conditions], [(Customer Name)’s Privacy Policy], and Astrada’s Privacy Policy. You also acknowledge and agree that relevant transaction details may be shared with involved third parties to enable spend management processes, in accordance with Astrada's Privacy Policy. You may opt out of transaction monitoring on the payment card you entered at any time by going to your account settings.

Rely on the default consent language

If the terms object is not passed to the openForm, the default language will be shown, without customizable terms.

Customize links within the Customer default consent language

If you want to rely on both consent languages, network-specific and customer, you can proceed with the default consent message and insert your company's Privacy Policy and Terms & Conditions, follow the example below:

CardEnrollmentSdk.openForm({
  companyName: "",
  subaccountId: "",
  getAccessToken: async () => "<access token>",
  terms: {
    privacyUrl: "YOUR_PRIVACY_URL_HERE",
    termsUrl: "YOUR_TERMS_URL_HERE",
  }
});

Customize customer consent language

To set up a fully customizable consent message, use the following code snippet::

CardEnrollmentSdk.openForm({
  companyName: "",
  subaccountId: "",
  getAccessToken: async () => "<access token>",
  terms: {
    text: "By checking this box, you are indicating that you agree to the [terms](https://yourcompany.com/terms) and [policy](https://yourcompany.com/policy).",
  }
});

To proceed with the default consent message and insert your company's Privacy Policy and Terms & Conditions, follow the example below:

Customize where the SDK should be rendered

To customize where the SDK is rendered on your page, follow the example below:

CardEnrollmentSdk.openForm({
  companyName: "",
  subaccountId: "",
  getAccessToken: async () => "<access token>",
  container: document.querySelector("#container-div")
});

The SDK will render at full-page scale if the HTML element is absent.

Handling specific errors and closing the SDK

In some scenarios, it may be necessary to close the SDK when a specific error occurs to allow the client to proceed with an alternative flow. For example, if a cardholder attempts to enroll a network-bulk eligible card, the operation will fail with this error.

In such cases, the client can intercept the onError callback, close the SDK, and allow you to proceed with your own custom logic.

The following example demonstrates how to handle this use case:

CardEnrollmentSdk.openForm({
  ...
  onSuccess: (data) => console.log(data),
  onError: (data) => {
    const networkBulkError = "card_subscription.card_must_be_network_bulk_enrolled";
  	const { errorCode } = data.error;
  	if (errorCode == networkBulkError) {
  		CardEnrollmentSdk.closeForm();
  	}
  },
  onCancel: onCancel,
  ...
});

Progress Messages

Creating the card subscription and verifying the card can take some time. To make the wait easier to follow, the SDK shows a short progress checklist that advances through the enrollment: Securely connecting your card → Contacting your bank → Verifying with your bank → Finalizing your enrollment.

Rely on the default progress messages

If statusLabels is not passed to openForm, the built-in messages above are shown.

Customize the progress messages

Pass statusLabels to override any subset of the stage messages; omitted stages keep the built-in copy. Each key maps to a stage of the enrollment:

CardEnrollmentSdk.openForm({
  companyName: "",
  subaccountId: "",
  getAccessToken: async () => "<access token>",
  statusLabels: {
    creatingSubscription: "Securely connecting your card",
    startingVerification: "Contacting your bank",
    verifying: "Talking to your card issuer",
    finishing: "Finalizing your enrollment",
  },
});

Troubleshooting

Having issues integrating with the SDK? See our Troubleshooting Guide.