# How it Works

## Authentication

All API requests use the Bearer Token Authorization. See [Authentication](/api-reference/authentication.md) for details.

## Identity Verification

The Zūm Rails platform features an integrated identity verification engine designed to meet strict Canadian regulatory requirements (FINTRAC). Our automated system collects, parses, and validates applicant data in real time, ensuring a frictionless transition from applicant to cardholder.

The onboarding interface is delivered as a secure, Zūm-hosted web experience. Partners can deploy this via two primary methods:

1. Hosted URL: Redirect applicants to a unique, Zūm-hosted landing page.
2. Embedded SDK: Use the Zūm Connect SDK to iframe the verification journey directly into your existing web or mobile application for a seamless "in-app" feel.

Zūm Rails collects the required information from the cardholder, including personal details and verification documents such as a valid government-issued ID, proof of address, or other supporting documentation. 

See [Zum Connect](/tokenization-1/zum-connect.md) for integration details.

**Onboarding & KYC Journey**

1. Profile Setup & OTP: Applicants provide core contact details, including Legal Full Name, Email Address, and Phone Number. To ensure the authenticity of the contact data, Zūm Rails triggers a mandatory One-Time Password (OTP) verification via SMS or Email.
2. Comprehensive IDV & Occupation Declaration: Upon successful profile creation, the system initiates the Identity Verification (IDV) phase:
   1. Address Collection: The verified residential address is automatically synchronized as both the Shipping Address for plastic issuance and the Billing Address for card transactions.
   2. Government ID Upload: Collection of valid, non-expired government-issued identification.
   3. Biometric Facial Match: A live "selfie" comparison against the provided ID to prevent spoofing.

Here’s a preview of the form used in Zūm Rails’ sample integration:

<figure><img src="/files/hMyJ5YiJMVVmLOWSaOnM" alt=""><figcaption></figcaption></figure>

#### Your unique card onboarding URL/SDK

* Navigate to Settings → Integration Codes.
* For Hosted URL: Select the Embedded Codes tab. Locate the Card Onboarding banner to copy your production or sandbox URL.
  * "Enable Public URLs" checkbox needs to be checked for the hosted URL option to work
* For SDK Implementation: Select the JavaScript SDK tab. Locate the Card Onboarding section to find your specific `ConnectTokenType`: `CardOnboarding` configuration.

#### How to customize your card onboarding URL/SDK

* Navigate to Settings → Brand Customization.
* Visual Identity: Upload your brand logo and icon.

#### Available notifications and webhook

* After the card applicant completes the card onboarding flow, based on your configuration and level of integration, if applicable, the following will occur: real-time status updates, webhook notifications, and user synchronization.

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Customer</td><td>Notification of card application submitted, approved, under review, declined, and incomplete</td></tr><tr><td>Cardholder</td><td>Notification of card application submitted, approved, under review, declined, and incomplete</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

<table data-header-hidden><thead><tr><th width="232">Type</th><th>Event</th><th>Description</th></tr></thead><tbody><tr><td>PrepaidCardUser</td><td>OnboardIncomplete</td><td>Webhook call for user that has completed profile setup but not KYC/IDV step</td></tr><tr><td>PrepaidCardUser</td><td>OnboardInProgress</td><td>Webhook call for user submitted card application</td></tr><tr><td>PrepaidCardUser</td><td>OnboardApproval</td><td>Webhook call for user KYC card application is approved and pending card issuance</td></tr><tr><td>PrepaidCardUser</td><td>OnboardUnderReview</td><td>Webhook call for user card application is under review</td></tr><tr><td>PrepaidCardUser</td><td>OnboardDeclined</td><td>Webhook call for user card application is declined</td></tr><tr><td>SecuredCardUser</td><td>OnboardIncomplete</td><td>Webhook call for user that has completed profile setup but not KYC/IDV step</td></tr><tr><td>SecuredCardUser</td><td>OnboardInProgress</td><td>Webhook call for user submitted card application</td></tr><tr><td>SecuredCardUser</td><td>OnboardApproval</td><td>Webhook call for user KYC card application is approved and pending card issuance</td></tr><tr><td>SecuredCardUser</td><td>OnboardUnderReview</td><td>Webhook call for user card application is under review</td></tr><tr><td>SecuredCardUser</td><td>OnboardDeclined</td><td>Webhook call for user card application is declined</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Card Issuance

Upon receiving card application has passed the identify verification, a Partner and Customer can approve the card on the Zūm Rails portal on the Users page or with the [Approve Card](/api-reference/users.md#approve-card) endpoint in the [Users API](/api-reference/users.md). This endpoint is used when the identity verification process has been completed and the card applicant has passed verification.

#### Available notifications and webhooks

If you have the configuration, the following emails will be sent.

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Customer</td><td>Notification of card is issued successfully</td></tr><tr><td>Cardholder</td><td>Notification of card is issued successfully</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type            | Event      | Description                                         |
| --------------- | ---------- | --------------------------------------------------- |
| PrepaidCardUser | CardIssued | Webhook call for user’s card is issued successfully |
| SecuredCardUser | CardIssued | Webhook call for user’s card is issued successfully |
| {% endtab %}    |            |                                                     |
| {% endtabs %}   |            |                                                     |

## Card Management

### Display full card details

You can use our [View Card Information](/tokenization-1/zum-connect.md#view-prepaid-card-details) SDK to display the sensitive data of your issued cards on your application.

Go to Settings → Integration Codes → JavaScript SDK to locate the View Card Information banner to find the `ConnectTokenType`: `ViewCardInformation` configuration.

### Activate the users current card

Once your card has been approved or you created a new card, you need to activate the card to perform other card management activities. You can use the [Activate Card](/api-reference/cards.md#activate-card) endpoint in the [Cards API](/api-reference/cards.md) to activate your user's card.

#### Available notifications and webhooks

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Cardholder</td><td>Notification of card being activated</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type            | Event         | Description                                |
| --------------- | ------------- | ------------------------------------------ |
| PrepaidCardUser | CardActivated | Notification of users card being activated |
| SecuredCardUser | CardActivated | Notification of users card being activated |
| {% endtab %}    |               |                                            |
| {% endtabs %}   |               |                                            |

### Change the card program of a user's current card

Each card is assigned a card program ID which sets the overall transaction limitations, card artwork, and other program configurations. To change the card program attached to a user's card, call the [Change Card Program](/api-reference/cards.md#change-card-program) endpoint in the [Cards API](/api-reference/cards.md). The card program ID you input must be an existing card program id listed under your Customer profile.

You can also do this on our portal through the user detail page.

#### Available notifications and webhooks

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Cardholder</td><td>Notification that the users card has changed card programs</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type            | Event              | Description                                       |
| --------------- | ------------------ | ------------------------------------------------- |
| PrepaidCardUser | CardProgramChange  | Webhook call for user updating their card program |
| SecuredCardUser | CardProgramChanged | Webhook call for user updating their card program |
| {% endtab %}    |                    |                                                   |
| {% endtabs %}   |                    |                                                   |

### Get the balance on a user's current card

You can view a user's current card balance through the [Get Balance Inquiry](/api-reference/cards.md#get-balance-inquiry) endpoint in the [Cards API](/api-reference/cards.md).&#x20;

### Get all cards attached to a user

You can view a user's cards through the [Get Card](/api-reference/cards.md#get-cards) endpoint in the [Cards API](/api-reference/cards.md).&#x20;

### Update the status on a user's current card

You can update the user’s current card status through our [Set Card Status](/api-reference/cards.md#set-card-status) endpoint in the [Cards API](/api-reference/cards.md).&#x20;

You can also do this through our portal on the View User Details page.

#### Available notifications and webhooks

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Cardholder</td><td>Notification of what the card status is changed to</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type            | Event             | Description                                                                                          |
| --------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
| PrepaidCardUser | CardStatusChanged | Webhook call for user’s new [card status](https://docs.zumrails.com/api-reference/cards#card-status) |
| SecuredCardUser | CardStatusChanged | Webhook call for user’s new [card status](https://docs.zumrails.com/api-reference/cards#card-status) |

{% endtab %}
{% endtabs %}

### Update card profile

There are 3 different endpoints we have to update the card profile.

* &#x20;[Update User Profile Information endpoint in User API](/api-reference/users.md#update-a-user)
* [ Update Address Information endpoint in User API](/api-reference/users.md#update-a-card-information)

You can also do this through our portal on the users edit detail page.

**Available notifications and webhooks**

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Cardholder</td><td>Notification of card profile updates (name, address, date of birth, occupation, phone number)</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type            | Event         | Description                                                                                    |
| --------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| PrepaidCardUser | ProfileUpdate | Webhook call for user profile updates (name, address, date of birth, occupation, phone number) |
| SecuredCardUser | ProfileUpdate | Webhook call for user profile updates (name, address, date of birth, occupation, phone number) |
| {% endtab %}    |               |                                                                                                |
| {% endtabs %}   |               |                                                                                                |

### Reissue card

If your user has an existing card and wants a new card, you can use the [Reissue Card](/api-reference/cards.md#reissue-card) endpoint in the [Card API](/api-reference/cards.md) to create a new card and attach it to your user. The old card will be detached from our database but you can still access the information via [Get Card](/api-reference/cards.md#get-cards) endpoint in the [Cards API](/api-reference/cards.md).

You can also do this through our portal on the users edit detail page.

#### Available notifications

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Cardholder</td><td>Notification of new card being added</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type            | Event       | Description                             |
| --------------- | ----------- | --------------------------------------- |
| PrepaidCardUser | CardReissue | Webhook call for user’s card reissuance |
| SecuredCardUser | CardReissue | Webhook call for user’s card reissuance |
| {% endtab %}    |             |                                         |
| {% endtabs %}   |             |                                         |

### Funding

For Prepaid Cards, you can add funds to the card from your Zūm Wallet via the Zūm Rails portal and [Transaction API](/api-reference/transactions.md#creating-a-new-transaction), or the cardholder can load funds through an applicable Zūm Rails payment method via the [Card Funding Checkout](/tokenization-1/zum-connect.md#card-funding-checkout) SDK. You can unload funds back to your Zūm Wallet through the Zūm Rails portal.&#x20;

**Available notifications**

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Cardholder</td><td>Notification for transactions (Approved, Pending, Declined)</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Security Deposit

For Secured Credit Card, you can add funds to the card from your Zūm Wallet via the Zūm Rails portal and [Transaction API](/api-reference/transactions.md#creating-a-new-transaction), or the cardholder can load funds through an applicable Zūm Rails payment method via the [Card Funding Checkout](/tokenization-1/zum-connect.md#card-funding-checkout) SDK. You can unload funds back to your Zūm Wallet through the Zūm Rails portal.&#x20;

**Available notifications**

Funding

For Prepaid Cards, you can add funds to the card from your Zūm Wallet via the Zūm Rails portal and [Transaction API](/api-reference/transactions.md#creating-a-new-transaction), or the cardholder can load funds through an applicable Zūm Rails payment method via the [Card Funding Checkout](/tokenization-1/zum-connect.md#card-funding-checkout) SDK. You can unload funds back to your Zūm Wallet through the Zūm Rails portal.&#x20;

**Available notifications**

{% tabs %}
{% tab title="Emails from Zum Rails" %}

<table><thead><tr><th width="179.4000244140625">Email(s) To</th><th>Reason for Email(s)</th></tr></thead><tbody><tr><td>Cardholder</td><td>Notification for transactions (Approved, Pending, Declined)</td></tr></tbody></table>
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zumrails.com/tokenization/how-it-works.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.