Installation

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:

JavaScript

<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.

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:

Parameter	Type	Required	Description	Example
`companyName`	`string`	Yes	The name of the company using card linking	"Your company name"
`subaccountId`	`string`	Yes	A valid UUID of the Astrada subaccount where the card should be enrolled	"67bc3887-4e25-49cf-bea7-326d808acb5f"
`terms.text`	`string`	No	Markdown text for a customizable consent message	By checking this box, you are indicating that you agree to the terms and policy.
`terms.privacyUrl`	`string`	No	URL to privacy documentation	https://yourcompany.com/privacy
`terms.termsUrl`	`string`	No	URL to terms and conditions documentation	https://yourcompany.com/terms
`statusLabels.creatingSubscription`	`string`	No	Overrides the progress message shown while the card subscription is created	Securely connecting your card
`statusLabels.startingVerification`	`string`	No	Overrides the progress message shown while card verification starts	Contacting your bank
`statusLabels.verifying`	`string`	No	Overrides the progress message shown while the card is verified	Verifying with your bank
`statusLabels.finishing`	`string`	No	Overrides the progress message shown while enrollment is finalized	Finalizing your enrollment
`customerReferenceId`	`string`	No	A valid UUID used to correlate the card enrolment	"67bc3887-4e25-49cf-bea7-326d808acb5f"
`getAccessToken`	`function`	Yes	An asynchronous function that returns a valid Access Token to request Astrada's API
`getAccessTokenTimeoutMs`	`number`	No	Milliseconds to wait for `getAccessToken` to resolve before the token fetch times out. Defaults to `5000`.	5000
`onConnect`	`function`	No	Function to be triggered when the SDK connects to your page, before the enrollment form renders
`onSuccess`	`function`	No	Function to be triggered when the cardholder successfully enrolls a card
`onError`	`function`	No	Function to be triggered when an error occurs during the card enrollment (e.g. failure to create a card subscription, verify the card, etc)
`onCancel`	`function`	No	Function to be triggered when the cardholder abandons/cancels the enrollment flow
`container`	`HTMLElement`	No	The HTML element in which the SDK should be rendered.	document.querySelector("#container-div")

Config example

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
  ...
});

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.

Callbacks

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

Event	Description
`onConnect`	Triggered when the SDK connects to your page, before the enrollment form renders.
`onSuccess`	Triggered when the customer successfully enrolls a card and activates a card subscription.

Example Payload:

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

Event	Description
`onError`	Indicates an error during the card enrollment process, such as failure to create a card subscription or verify the card.

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"
}

Event	Description
`onCancel`	Indicates that the customer canceled the enrollment flow, typically by clicking on the exit button, outside the SDK's frame, or by pressing the ESC key on the keyboard.

Customization

Consent Message

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

Troubleshooting

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