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.

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',
  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 getAccessToken passed to the openForm must be an asynchronous function responsible for returning an Access Token (JWT) to request Astrada's API. This function must resolve within 5 seconds. Otherwise, it will timeout and return an error, resulting in failing 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 Authentication for more details on how to get the Access Token.

🚧

We strongly advise against using any client ID and Secret directly through the browser. Consider adding a dedicated interface to your backend, responsible to authenticate with Astrada's API and returning the Access Token to be used.

Callbacks

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

Example Payload:

{  
  "subscriptionId": "1c6db37a-333a-4379-8ac5-0f819f2c0bf7"
}

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

Example Payload (Client Error):

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

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 just insert your company's Privacy Policy and Terms & Conditions, follow the example below:

<CardEnrollmentSdk.openForm({  
  companyName: "",  
  subaccountId: "",  
  accessToken: "",  
  terms: {  
    privacyUrl: "YOUR_PRIVACY_URL_HERE",  
    termsUrl: "YOUR_TERMS_URL_HERE",  
  }  
});

Customize customer consent language

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

CardEnrollmentSdk.openForm({  
  companyName: "",  
  subaccountId: "",  
  accessToken: "",  
  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: "",  
  accessToken: "",
  container: document.querySelector("#container-div")
});

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

Troubleshooting

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