> For the complete documentation index, see [llms.txt](https://docs.zumrails.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zumrails.com/tokenization/how-it-works.md).

# How it Works

## Authentication

All API requests use the Bearer Token Authorization. See [Authentication](https://docs.zumrails.com/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](https://docs.zumrails.com/tokenization-1/zum-connect.md) for integration details.

**Onboarding & KYC Journey**

1. **Province/Territory Selection:** Applicants first select their province or territory of residence. Only the provinces and territories enabled for the card program are listed. See [Card Program Regions](#card-program-regions).
   * If no `CardProgramId` is passed in the URL/SDK, the applicant is routed to the first active card program for the card type whose Region matches the selected province.
   * If a `CardProgramId` is passed and its Region matches the selected province, onboarding continues.
   * If the Region does **not** match, the applicant cannot continue.
   * Applicants resuming an existing application skip this step.
2. **Profile Setup & OTP:** Applicants provide their personal and residential details:

   * Legal Full Name (with an optional Middle Name), Date of Birth, Email Address, Phone Number, and Language Preference.
   * **Occupation**.
   * **Residential address** — the address must match the government-issued ID the applicant will upload. Address autocomplete is available for Canadian addresses.
   * For physical card programs, the applicant can select **Shipping address same as above** or enter a separate shipping address.
   * Acceptance of the Cardholder Agreement and Disclosures, and separate consent to electronic delivery of documents.

   To ensure the authenticity of the contact data, Zūm Rails triggers a mandatory One-Time Password (OTP) verification via SMS or Email.
3. **Identity Verification (IDV):** Applicants scan a QR code to continue on their phone, then:

   1. Government ID Upload: Collection of valid, non-expired government-issued identification.
   2. Biometric Facial Match: A live "selfie" comparison against the provided ID to prevent spoofing.

   The application status page updates automatically once verification is complete.
4. **Security Deposit (Secured Credit Card only, optional):** If the Security Deposit step is enabled for your card program, applicants who pass KYC are taken to the Security Deposit step. See [Security Deposit Step](#security-deposit-step).

{% hint style="info" %}
For physical card programs, applicants are informed that their full name will be printed on the card. Due to character length limitations, Zūm Rails will attempt to print the name in this order: full name with middle name, first and last name, or first name and partial last name.
{% endhint %}

{% hint style="info" %}
You can pre-fill the residential address, shipping address, and occupation through the Card Onboarding URL or SDK. See [Pre-filling the form](https://docs.zumrails.com/tokenization-1/zum-connect.md#card-onboarding).
{% endhint %}

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

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FuYdJTripoS2GKee7yB0z%2FZum-ID%20Upload.png?alt=media&amp;token=4bcd0203-30b3-4a58-adbc-e786cf64635d" alt=""><figcaption></figcaption></figure>

#### Address validation

To reduce unnecessary manual reviews, the following address inputs are accepted automatically:

* Province short codes in any letter case (e.g. `qc`, `QC`).
* Postal codes in the format `X1X1X1` or `X1X 1X1`, in any letter case, with leading or trailing spaces.
* A PO Box in **Address Line 2** when Address Line 1 contains a street number and street name.

Any other PO Box placement or postal code format will send the application to Under Review.

#### Card Program Regions

Each Card Program ID has a **Region** and a list of allowed **provinces and territories** that determine which applicants it can onboard.

| Card Type           | Region  | Provinces and territories                                               |
| ------------------- | ------- | ----------------------------------------------------------------------- |
| Secured Credit Card | `QC`    | Québec                                                                  |
| Secured Credit Card | `NonQC` | Any provinces and territories enabled for the program, excluding Québec |
| Prepaid Card        | `All`   | Any provinces and territories enabled for the program                   |

You can view the Region and allowed provinces and territories for each card program in the Zūm Portal under **Program Management → Card Program → Card Regions**. Contact support to change them.

* The Card Onboarding province list only shows the provinces and territories enabled for the card program.
* If a pre-filled province is not enabled for the card program, the applicant sees *"Invalid province selected."* and must choose an allowed province.
* Cards created with the [Create Card](https://docs.zumrails.com/api-reference/cards.md#create-card) endpoint are validated against the same list.
* The restriction applies to the residential address at onboarding only. Shipping addresses, and address updates after the card is issued, are not restricted.

{% hint style="warning" %}
If the applicant's selected province does not match the Region of the Card Program ID passed in the URL/SDK, the applicant will see: *"Something unexpected happened and your card application cannot be processed. Please contact cardholder support."* The applicant's ID address is also validated against the card program's Region during identity verification.
{% endhint %}

#### Security Deposit Step

For Secured Credit Card programs, Zūm Rails provides an optional Security Deposit step in the Card Onboarding flow. Once the applicant passes identity verification, they are asked how they would like to fund their Security Deposit:

* **Personal Funds via Interac e-Transfer:** The applicant sends their Security Deposit via Interac e-Transfer. If the transfer fails, the applicant can retry or switch to the Loan option.
* **Get a Loan:** For Customers handling the Security Deposit on behalf of the cardholder (e.g. a credit-builder loan). The application is placed in **Pending Security Deposit – Loan** until you approve and issue the card.

If the applicant leaves the flow before completing the deposit, they can return using their onboarding link and resume at the Security Deposit step. Applications approved after manual review also resume at this step; the cardholder receives an email with a link to continue, and the `OnboardDepositNotStarted` webhook includes the same link in `CardOnboardingSession`.

The Security Deposit step is enabled per card program by the Zūm Rails team. Contact support to enable it.

| Onboarding Status           | Description                                                                 |
| --------------------------- | --------------------------------------------------------------------------- |
| SuccessfulDepositNotStarted | Applicant passed KYC and has not started the Security Deposit step          |
| SuccessfulDepositPending    | Applicant initiated an Interac e-Transfer deposit; awaiting funds           |
| SuccessfulDepositFailed     | The Interac e-Transfer deposit failed                                       |
| LoanDepositPending          | Applicant selected the Loan option; pending your approval and card issuance |
| UnderReviewDepositPending   | Application is under review and the Security Deposit has not been completed |

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

| Type                  | Event                     | Description                                                                                              |
| --------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| PrepaidCardUser       | OnboardIncomplete         | Webhook call for user that has completed profile setup but not KYC/IDV step                              |
| PrepaidCardUser       | OnboardInProgress         | Webhook call for user submitted card application                                                         |
| PrepaidCardUser       | OnboardApproval           | Webhook call for user KYC card application is approved and pending card issuance                         |
| PrepaidCardUser       | OnboardUnderReview        | Webhook call for user card application is under review                                                   |
| PrepaidCardUser       | OnboardDeclined           | Webhook call for user card application is declined                                                       |
| PrepaidCardUser       | OnboardSessionExpired     | Webhook call for user card onboarding session expired                                                    |
| SecuredCreditCardUser | OnboardIncomplete         | Webhook call for user that has completed profile setup but not KYC/IDV step                              |
| SecuredCreditCardUser | OnboardInProgress         | Webhook call for user submitted card application                                                         |
| SecuredCreditCardUser | OnboardApproval           | Webhook call for user KYC card application is approved and pending card issuance                         |
| SecuredCreditCardUser | OnboardUnderReview        | Webhook call for user card application is under review                                                   |
| SecuredCreditCardUser | OnboardDeclined           | Webhook call for user card application is declined                                                       |
| SecuredCreditCardUser | OnboardSessionExpired     | Webhook call for user card onboarding session expired                                                    |
| SecuredCreditCardUser | OnboardDepositNotStarted  | Webhook call for user passed KYC but has not started the Security Deposit step. Includes the resume link |
| SecuredCreditCardUser | OnboardDepositPending     | Webhook call for user initiated an Interac e-Transfer Security Deposit                                   |
| SecuredCreditCardUser | OnboardDepositFailed      | Webhook call for user's Interac e-Transfer Security Deposit failed                                       |
| SecuredCreditCardUser | OnboardLoanDepositPending | Webhook call for user selected the Loan option for the Security Deposit                                  |
| {% endtab %}          |                           |                                                                                                          |
| {% endtabs %}         |                           |                                                                                                          |

### Bypass KYC/IDV

If your business performs its own identity verification, Zūm Rails can enable KYC/IDV bypass on your card program. This setting is configured per card program by the Zūm Rails team and is disabled by default. Contact support to enable it.

| Card Type           | Setting (Program Management)          | Behaviour                                                                                                          |
| ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Prepaid Card        | Bypass KYC/IDV during Card Onboarding | Applicants onboarding through the Card Onboarding URL/SDK skip the KYC/IDV step. Cards can also be created via API |
| Secured Credit Card | Bypass KYC/IDV Via API                | Cards can be created via API without KYC/IDV. Applicants using the Card Onboarding URL/SDK still complete KYC/IDV  |

#### Creating cards via API

Use the [Create Card](https://docs.zumrails.com/api-reference/cards.md#create-card) endpoint in the [Cards API](https://docs.zumrails.com/api-reference/cards.md) to create the cardholder and their card in one call.

* By creating a card via API on a bypass-enabled program, your business attests that it has completed KYC on the cardholder.
* For Secured Credit Card programs, `CreditLimitRequested` and the full address are required.
* To issue a card to an existing user, pass their `UserId` instead of the profile fields.
* A user can only hold one non-closed card per card type.

When the card is created via API, the card history shows **Onboard Incomplete → Onboard KYC Completed By Customer → Onboard Approval**, and the card's `IDVVerification` value is **KYC Completed by Customer**. The card is placed in Pending Approval until it is approved, unless Automatic Card Issuance is enabled on your account. The existing onboarding webhooks (`OnboardApproval`, `CardIssued`, …) are sent as usual.

### Testing card onboarding in sandbox

In the sandbox environment, you can simulate different identity verification outcomes for Prepaid and Secured Credit Card onboarding. Complete the Card Onboarding flow as normal (Hosted URL or SDK) and enter one of the values below in the applicant's **Last Name** field. The resulting status, warnings, emails and webhooks behave as they would in production.

Values are not case-sensitive. Any other last name will result in an **Approved** KYC status.

| Last Name                         | KYC Result   | Reason Displayed                                                 |
| --------------------------------- | ------------ | ---------------------------------------------------------------- |
| *(any other value)*               | Approved     | —                                                                |
| `SimulatePostalCode`              | Under Review | Zip/Postal Code is not the correct format                        |
| `SimulateSuppliedNameMismatch`    | Under Review | Mismatch between supplied user name and extracted/looked up name |
| `SimulateIdNameMismatch`          | Under Review | Entered first name and/or last name does not match ID            |
| `SimulateIdAddressMismatch`       | Under Review | Address on ID does not match inputted address                    |
| `SimulateSuppliedAddressMismatch` | Under Review | Address on ID does not match inputted address                    |
| `SimulateDOB`                     | Under Review | Entered DOB does not match ID                                    |
| `SimulateBlurryImage`             | Declined     | The document image is blurry.                                    |
| `SimulateSelfie`                  | Declined     | Selfie photo is not live                                         |
| `SimulateMissingExpiryDate`       | Declined     | Document expiry date is missing or cannot be read.               |
| `SimulateIdExpired`               | Declined     | Document is expired.                                             |

{% hint style="info" %}
To test [Card Program Regions](#card-program-regions), include `Quebec` in the Last Name — the simulated ID will have a Québec address.

Only one simulation value can be used per onboarding attempt. Simulation values have no effect in production.
{% endhint %}

## 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](https://docs.zumrails.com/api-reference/users.md#approve-card) endpoint in the [Users API](https://docs.zumrails.com/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 |
| SecuredCreditCardUser | CardIssued | Webhook call for user’s card is issued successfully |
| {% endtab %}          |            |                                                     |
| {% endtabs %}         |            |                                                     |

## Email Notifications

Email notifications are configured **per card program**, so each of your Prepaid and Secured Credit Card programs can have its own notification preferences.

In the Zūm Portal, navigate to **Program Management → select your Card Program → Email Notifications**. Contact support to make changes.

Notifications are organized into groups. Each group has a master toggle and individual toggles for each email:

* Turning a group **off** disables every email in that group. Individual settings are kept and re-applied when the group is turned back on.
* An email is sent only when both the group toggle and the individual toggle are **on**.

| Group                           | Emails                                                                                                                                                                                                                                        |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OTP                             | 3DS OTP, Mobile wallet OTP, Card onboarding OTP, PIN reset OTP¹, PIN unblock OTP¹                                                                                                                                                             |
| Non-financial                   | Card status update, Profile update, Card reissue, Physical card order status², Apple Pay token events, Wallet token events (Google Pay, Samsung Pay, etc.), New statement generated³, Low balance alert, Recipient added, updated or removed⁴ |
| Financial                       | Pre-auth, Posted, Reversal, Fee                                                                                                                                                                                                               |
| Card onboarding — to cardholder | Application submitted, Application under review, Application under review and deposit not started³, Verification declined, Verification approved, Card issued, Credit limit request³                                                          |
| Card onboarding — to you        | Application submitted, Application under review, Verification declined, Verification approved, Card issued, Credit limit request³                                                                                                             |
| PIN management¹                 | PIN set, PIN changed, PIN reset, PIN unblocked, PIN blocked                                                                                                                                                                                   |

¹ Physical card programs with PIN Management enabled. ² Physical card programs. ³ Secured Credit Card programs. ⁴ Prepaid Card programs.

**Apple Pay token events** and **Wallet token events** are independent. Wallet token events cover all other wallets (e.g. Google Pay, Samsung Pay) and are enabled by default.

{% hint style="info" %}
The Cardholder Portal login OTP email is configured separately at the account level.
{% endhint %}

#### Statement notifications (Secured Credit Card)

When a monthly statement is generated, Zūm Rails can email the cardholder that their statement is ready. The email includes the masked card number, statement period, total amount due, minimum payment, payment due date, and a link to the Cardholder Portal. This email is independent of the [`CardStatement` webhook](https://docs.zumrails.com/api-reference/webhooks.md#card-statement-webhook).

{% hint style="info" %}
To send statement emails to your cardholders, make sure **Non-financial → New statement generated** is enabled for your card program.
{% endhint %}

#### Low balance notifications

The **Low balance alert** email is sent when the card's balance (Prepaid) or available credit (Secured Credit Card) falls below the threshold configured in the card program's **Low Balance Rule** (**Program Management → Rules**).

## Physical Card Issuance

Zūm Rails supports physical (plastic) card issuance for Prepaid Card and Secured Credit Card programs. Cardholders start with a virtual card and can order a physical card from the Cardholder Portal, or you can order one on their behalf from the Zūm Portal or the [Order Physical Card](https://docs.zumrails.com/api-reference/cards.md#order-physical-card) API.

#### How it works

* Each virtual card program is linked to a corresponding **physical card program** of the same card type.
* When a physical card is ordered, the cardholder's card is **reissued** onto the linked physical card program. The physical card has a **new card number**, and the previous virtual card is replaced.
* The cardholder's name is printed on the card, using the Middle Name where it fits.

#### Configuration

Physical card issuance is configured by the Zūm Rails team. Contact support to enable it. Once enabled, you can review the configuration in the Zūm Portal:

| Setting                             | Location                                                 | Description                                                               |
| ----------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------- |
| Card Format                         | Program Management → Card Programs                       | `Virtual` or `Physical`, and the physical program linked to a virtual one |
| Fulfillment Type                    | Program Management → Physical Card Fulfillment           | `OnDemand`                                                                |
| Shipping Type                       | Program Management → Physical Card Fulfillment           | `Standard`, `Expedited`, or both                                          |
| Allow user to order a physical card | Program Management → Cardholder Portal                   | Shows the "Order Physical Card" option in the Cardholder Portal           |
| Physical card order status          | Program Management → Email Notifications → Non-financial | Physical card order/shipping emails                                       |

#### Ordering a physical card

* **Cardholder Portal:** the cardholder selects **Order Physical Card**, confirms or edits the shipping address, and chooses a shipping type from the options enabled for the program.
* **Zūm Portal:** navigate to **Users → User → Card → Manage Cards → Physical Card**, then confirm the shipping address and shipping type.
* **API:** call the [Order Physical Card](https://docs.zumrails.com/api-reference/cards.md#order-physical-card) endpoint.

The shipping address is pre-filled from the cardholder's profile. PO Boxes are not accepted.

{% hint style="info" %}
Expedited shipping fees will be charged to the cardholder.
{% endhint %}

#### Fulfillment status

| Fulfillment Status | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| Ordered            | The physical card order has been accepted by the card processor |
| Shipped            | The card has been handed over to Canada Post                    |
| Delivered          | The card has been delivered (Expedited shipping only)           |

{% hint style="info" %}
Shipped and Delivered updates are coming soon. In sandbox, you can test them under **Users → User → Card → Manage Cards → Simulate: Mark as Shipped / Delivered**.
{% endhint %}

#### Activating a physical card

Physical cards are issued in an inactive state. To activate it from the Cardholder Portal, the cardholder:

1. Follow the prompt to activate the physical card.
2. Set a 4-digit PIN in the same activation flow.

Card details are hidden in the Cardholder Portal until the physical card is activated.

#### Lost or stolen physical cards

When a physical card is reported Lost or Stolen, it is reissued with a new card number. The cardholder must set a new PIN when activating the replacement 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 that the physical card has been ordered, shipped, or delivered</td></tr><tr><td>Cardholder</td><td>Unlock code after too many failed activation attempts</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type                               | Event                 | Description                              |
| ---------------------------------- | --------------------- | ---------------------------------------- |
| PrepaidCardPhysicalLifecycle       | CardPhysicalOrdered   | Webhook call for physical card ordered   |
| PrepaidCardPhysicalLifecycle       | CardPhysicalShipped   | Webhook call for physical card shipped   |
| PrepaidCardPhysicalLifecycle       | CardPhysicalDelivered | Webhook call for physical card delivered |
| SecuredCreditCardPhysicalLifecycle | CardPhysicalOrdered   | Webhook call for physical card ordered   |
| SecuredCreditCardPhysicalLifecycle | CardPhysicalShipped   | Webhook call for physical card shipped   |
| SecuredCreditCardPhysicalLifecycle | CardPhysicalDelivered | Webhook call for physical card delivered |
| {% endtab %}                       |                       |                                          |
| {% endtabs %}                      |                       |                                          |

## Card Management

### Display full card details

You can use our [View Card Information](https://docs.zumrails.com/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](https://docs.zumrails.com/api-reference/cards.md#activate-card) endpoint in the [Cards API](https://docs.zumrails.com/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 |
| SecuredCreditCardUser | 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](https://docs.zumrails.com/api-reference/cards.md#change-card-program) endpoint in the [Cards API](https://docs.zumrails.com/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       | CardProgramChanged | Webhook call for user updating their card program |
| SecuredCreditCardUser | 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](https://docs.zumrails.com/api-reference/cards.md#get-balance-inquiry) endpoint in the [Cards API](https://docs.zumrails.com/api-reference/cards.md).

### Get all cards attached to a user

You can view a user's cards through the [Get Card](https://docs.zumrails.com/api-reference/cards.md#get-cards) endpoint in the [Cards API](https://docs.zumrails.com/api-reference/cards.md).

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

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

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

* [Update User Profile Information endpoint in User API](https://docs.zumrails.com/api-reference/users.md#update-a-user)
* [Update Address Information endpoint in User API](https://docs.zumrails.com/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) |
| SecuredCreditCardUser | 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](https://docs.zumrails.com/api-reference/cards.md#reissue-card) endpoint in the [Card API](https://docs.zumrails.com/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](https://docs.zumrails.com/api-reference/cards.md#get-cards) endpoint in the [Cards API](https://docs.zumrails.com/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 |
| SecuredCreditCardUser | CardReissue | Webhook call for user’s card reissuance |
| {% endtab %}          |             |                                         |
| {% endtabs %}         |             |                                         |

### Issue multiple cards to a user

Cardholders who have passed identity verification can hold more than one card of the same card type, for example a physical card for everyday use and a virtual card for online purchases. All cards of the same card type share **one balance** (Prepaid Card) or **one credit line and Security Deposit** (Secured Credit Card).

* The first card issued for a card type is the **Primary** card. Additional cards are **secondary** cards.
* Prepaid Cards and Secured Credit Cards are never combined.
* Cardholders created with [Bypass KYC/IDV](#bypass-kyc-idv) cannot be issued additional cards.
* A purchase on any card reduces the shared balance or available credit.

#### Configuration

Multiple card issuance is enabled by the Zūm Rails team. Contact support to enable it.

| Setting                            | Location                                                     | Description                                                                                     |
| ---------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Allow multi-card issuance          | Payment Methods → Prepaid Card / Credit Card (CA) – Issuance | Enables multiple cards per card type for your account                                           |
| Max Physical Cards                 | Payment Methods → Prepaid Card / Credit Card (CA) – Issuance | Maximum physical cards per cardholder per card type, including the Primary card. Default: **1** |
| Max Virtual Cards                  | Payment Methods → Prepaid Card / Credit Card (CA) – Issuance | Maximum virtual cards per cardholder per card type, including the Primary card. Default: **2**  |
| Max Cards Per Shared Balance Group | Program Management → Card Program                            | Optional lower limit for a specific card program                                                |
| Add a Card                         | Program Management → Cardholder Portal                       | Lets cardholders add and remove cards from the Cardholder Portal                                |

Reissued cards do not count toward these limits.

#### Adding a card

* **Cardholder Portal:** the cardholder selects **+ Add a card** from the card menu, chooses a virtual or physical card, and can give it a nickname. Physical cards also require a shipping address and shipping type. See [Cardholder Portal](https://docs.zumrails.com/tokenization/cardholder-portal.md#multiple-cards).
* **Zūm Portal:** navigate to **Users → User → Card → Manage Cards**.
* **API:** use the [Add Secondary Card](https://docs.zumrails.com/api-reference/cards.md#add-secondary-card) endpoint in the [Cards API](https://docs.zumrails.com/api-reference/cards.md) with the Primary card's `UserCardId`. You can also set a nickname with the optional `Nickname` field. Physical cards require a `CardShipmentType` and can take an optional `ShippingAddress`.

A card can be added only when the Primary card is active. A card cannot be added when the Primary card is Closed or has never been activated, or when the cardholder has reached the card limit.

#### How multiple cards behave

| Action                                         | Result                                                                                                       |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Close a secondary card                         | Only that card is closed. The shared balance and other cards are not affected                                |
| Close the Primary card                         | All cards of that card type are closed                                                                       |
| Freeze a card                                  | Only that card is frozen                                                                                     |
| Reissue a card                                 | The replacement card stays in the same group and keeps its nickname. A reissued Primary card remains Primary |
| Secured Credit Card goes over the credit limit | All cards of that card type are placed in Fraud Block until a payment is received                            |
| Statements (Secured Credit Card)               | One statement per cardholder, including transactions from all cards, each attributed to the card used        |
| Credit reporting (Secured Credit Card)         | One trade line per cardholder, reported under the Primary card                                               |

{% hint style="info" %}
In the Zūm Portal, closing a Primary card shows a **Card Closure Warning** confirming that all cards sharing the balance will be closed.
{% endhint %}

#### 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 a new card being issued (Card issued email)</td></tr><tr><td>Cardholder</td><td>Notification of a card being removed (Card status update email)</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type                  | Event                | Description                                                   |
| --------------------- | -------------------- | ------------------------------------------------------------- |
| PrepaidCardUser       | CardAddedToGroup     | Webhook call for a card added to the user's card group        |
| PrepaidCardUser       | CardRemovedFromGroup | Webhook call for a secondary card removed from the card group |
| PrepaidCardUser       | GroupClosed          | Webhook call for all cards in the group closed                |
| SecuredCreditCardUser | CardAddedToGroup     | Webhook call for a card added to the user's card group        |
| SecuredCreditCardUser | CardRemovedFromGroup | Webhook call for a secondary card removed from the card group |
| SecuredCreditCardUser | GroupClosed          | Webhook call for all cards in the group closed                |
| {% endtab %}          |                      |                                                               |
| {% endtabs %}         |                      |                                                               |

### View a card's digital wallets

When a cardholder adds their card to a mobile wallet such as Apple Pay, Google Pay or Samsung Pay, Zūm Rails records a **digital wallet token** for each wallet and device. You can see each card's digital wallets and their status through the API, webhooks, the Zūm Portal and the Cardholder Portal.

| Status        | Description                                      |
| ------------- | ------------------------------------------------ |
| Added         | The card was added to the wallet                 |
| Suspended     | The wallet token is suspended and cannot be used |
| Resumed       | The wallet token was resumed after a suspension  |
| Removed       | The card was removed from the wallet             |
| Declined      | Provisioning the card to the wallet was declined |
| PendingStepUp | Additional cardholder verification is required   |
| Unknown       | The wallet token status could not be determined  |

* **API:** each card in the [Get Cards](https://docs.zumrails.com/api-reference/cards.md#get-cards) response includes its digital wallets in the `WalletProvisionings` field. Each entry has an `Id`, `DeviceName`, `WalletType` (`ApplePay`, `GooglePay`, `SamsungPay` or `Unknown`), `Status`, `TokenRequesterId` and `EventDate`.
* **Zūm Portal:** navigate to **Users → ⋮ → Digital Wallets** to see each card's wallets, with the Wallet Type, Device Name, Wallet Provisioning Status and Token ID. The Token ID is the Token Unique Reference (TUR) used to look up the tokenized card with Mastercard.
* **Cardholder Portal:** cardholders can see the wallets their card has been added to under **Digital Wallets**.

Removed and declined wallets are not listed in API responses or card webhooks; they are only reported in the wallet token event webhook. Digital wallet tokens are managed by the cardholder in their wallet app; they cannot be suspended or removed from the Zūm Portal.

{% hint style="info" %}
**Sandbox:** you can simulate wallet token events from the **Digital Wallets** page in the Zūm Portal.
{% endhint %}

#### 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 card was added to, suspended in, resumed in, or removed from a digital wallet</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type                  | Event                           | Description                                                                  |
| --------------------- | ------------------------------- | ---------------------------------------------------------------------------- |
| PrepaidCardUser       | WalletTokenAdded                | Webhook call for card added to a digital wallet                              |
| PrepaidCardUser       | WalletTokenSuspended            | Webhook call for digital wallet token suspended                              |
| PrepaidCardUser       | WalletTokenResumed              | Webhook call for digital wallet token resumed                                |
| PrepaidCardUser       | WalletTokenRemoved              | Webhook call for card removed from a digital wallet                          |
| PrepaidCardUser       | WalletTokenProvisioningDeclined | Webhook call for card provisioning to a digital wallet declined              |
| PrepaidCardUser       | WalletTokenStepUpRequired       | Webhook call for digital wallet requiring additional cardholder verification |
| PrepaidCardUser       | WalletTokenUnknown              | Webhook call for an unrecognized wallet token event                          |
| SecuredCreditCardUser | WalletTokenAdded                | Webhook call for card added to a digital wallet                              |
| SecuredCreditCardUser | WalletTokenSuspended            | Webhook call for digital wallet token suspended                              |
| SecuredCreditCardUser | WalletTokenResumed              | Webhook call for digital wallet token resumed                                |
| SecuredCreditCardUser | WalletTokenRemoved              | Webhook call for card removed from a digital wallet                          |
| SecuredCreditCardUser | WalletTokenProvisioningDeclined | Webhook call for card provisioning to a digital wallet declined              |
| SecuredCreditCardUser | WalletTokenStepUpRequired       | Webhook call for digital wallet requiring additional cardholder verification |
| SecuredCreditCardUser | WalletTokenUnknown              | Webhook call for an unrecognized wallet token event                          |
| {% endtab %}          |                                 |                                                                              |
| {% endtabs %}         |                                 |                                                                              |

Each wallet token event includes the card payload and a `WalletProvisioning` object for the wallet token that changed.

Enable these webhooks in **Settings → Webhook & API Settings → Card User Events → Wallet Token Events**.

### Manage the PIN on a user's physical card

PIN management is available for **physical card programs**. Zūm Rails supports the following PIN actions:

| Action  | Description                                                                 | Cardholder Portal | Zūm Portal | API |
| ------- | --------------------------------------------------------------------------- | :---------------: | :--------: | :-: |
| Set     | Set the PIN for the first time                                              |         ✓         |            |  ✓  |
| Change  | Change an existing PIN using the current PIN                                |         ✓         |            |  ✓  |
| Reset   | Set a new PIN without the current PIN (requires OTP verification)           |         ✓         |      ✓     |  ✓  |
| Unblock | Unblock a PIN after too many incorrect attempts (requires OTP verification) |         ✓         |      ✓     |  ✓  |

PIN Management is enabled by the Zūm Rails team. Set and Change are enabled by default; Reset and Unblock can be configured per card program under **Program Management → PIN Management**. Contact support to make adjustments.

#### PIN rules

* PINs must be exactly **4 digits**.
* Repeated digits (e.g. `1111`), ascending sequences (e.g. `1234`) and descending sequences (e.g. `4321`) are not allowed.
* A new PIN cannot be the same as the current PIN.
* The PIN can only be changed once every **24 hours**. PIN resets performed by your team in the Zūm Portal are not subject to this limit but subject to cardholder verification.
* The PIN is blocked after **3** incorrect attempts.
* PIN OTP codes expire after **10 minutes**.

{% hint style="warning" %}
PINs must be encrypted before being sent to the API. See [Encryption](https://docs.zumrails.com/api-reference/encryption.md) and the [PIN Management](https://docs.zumrails.com/api-reference/cards.md#pin-management) endpoints in the [Cards API](https://docs.zumrails.com/api-reference/cards.md). PIN values are never included in webhooks or emails.
{% endhint %}

**Cardholder Portal:** the cardholder uses the **Manage PIN** menu on their card. Set is shown when no PIN exists; Change and Reset when a PIN is set; Unblock when the PIN is blocked. The menu is hidden for Closed and Issued Inactive cards.

**Zūm Portal:** navigate to **Users → User → Card → Manage Cards → Manage PIN** to Reset or Unblock a PIN. The card's **PIN Status** (`Not Set`, `Active`, `Blocked`) is shown on the same 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 PIN has been set, changed, reset, unblocked, or blocked</td></tr><tr><td>Cardholder</td><td>OTP for PIN reset or PIN unblock</td></tr></tbody></table>
{% endtab %}

{% tab title="Webhooks" %}

| Type                                    | Event           | Description                                                         |
| --------------------------------------- | --------------- | ------------------------------------------------------------------- |
| PrepaidCardUser / SecuredCreditCardUser | PinSet          | Webhook call for PIN set                                            |
| PrepaidCardUser / SecuredCreditCardUser | PinChanged      | Webhook call for PIN changed                                        |
| PrepaidCardUser / SecuredCreditCardUser | PinReset        | Webhook call for PIN reset                                          |
| PrepaidCardUser / SecuredCreditCardUser | PinUnblock      | Webhook call for PIN unblocked                                      |
| PrepaidCardUser / SecuredCreditCardUser | PinBlocked      | Webhook call for PIN blocked after too many incorrect attempts      |
| PrepaidCardUser / SecuredCreditCardUser | OfflinePinBlock | Webhook call for PIN blocked from an offline (terminal) transaction |
| PrepaidCardOTP / SecuredCreditCardOTP   | PinSetOtp       | Webhook call for PIN set OTP sent                                   |
| PrepaidCardOTP / SecuredCreditCardOTP   | PinResetOtp     | Webhook call for PIN reset OTP sent                                 |
| PrepaidCardOTP / SecuredCreditCardOTP   | PinUnblockOtp   | Webhook call for PIN unblock OTP sent                               |
| {% 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](https://docs.zumrails.com/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](https://docs.zumrails.com/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.

**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 %}

#### First Load Fee (Prepaid Card)

You can charge cardholders a one-time fee when their Prepaid Card receives its first load.

* The fee is configured per card program under **Program Management → Card Program → Rules → First Load Fee**. Contact support to enable it, as the fee must also be set up with the card processor.
* The fee is charged once per cardholder, on the first successful load of the card. It is not charged on later loads or on reissued or replacement cards.
* Cards that were already loaded before the rule was enabled are not charged.
* The first load must be equal to or greater than the fee amount. Smaller loads are rejected from the Cardholder Portal, the Zūm Portal and the API.
* In the Cardholder Portal, the cardholder sees *"On your first load, a fee of {amount} will be deducted after your load is successful."* when adding money for the first time.
* The fee appears as a separate card transaction, **Fee - First Load**, and can be reversed from the Zūm Portal like other card fees.

{% hint style="info" %}
A first load below the fee amount is rejected with: *"Load an amount equal or greater than the applicable card fee."*
{% endhint %}

**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 the First Load Fee (Financial → Fee email)</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

### Security Deposit

For Secured Credit Card, you can add funds to the Security Deposit from your Zūm Wallet via the Zūm Rails portal and [Transaction API](https://docs.zumrails.com/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](https://docs.zumrails.com/tokenization-1/zum-connect.md#card-funding-checkout) SDK or the Cardholder Portal (**Top Up Deposit**).

You can unload part of the Security Deposit back to your Zūm Wallet through the Zūm Rails portal or the Transaction API. Cardholders can also unload part of it from the Cardholder Portal (**Unload Security Deposit**).

{% hint style="warning" %}
The Security Deposit cannot be unloaded to **$0** while the card is open. To return the full Security Deposit, close the card instead.
{% endhint %}

#### Closing a Secured Credit Card with a Security Deposit

When a Secured Credit Card with a remaining Security Deposit is closed, Zūm Rails automatically unloads the full Security Deposit to your Zūm Wallet and then closes the card. This applies when the card is closed from the Zūm Portal, the Cardholder Portal, or the [Update Card Status](https://docs.zumrails.com/api-reference/cards.md#update-card-status) endpoint.

* The card cannot be closed while it has an outstanding balance.
* In the Zūm Portal, the close confirmation shows the Security Deposit amount that will be unloaded.
* If the deposit is unloaded but the card cannot be closed, the card remains open with a $0 Security Deposit. Retry closing the card.

A successful close appears as an **Unload** transaction followed by a **Card Status Changed** event; the existing `CardStatusChanged` webhook and email are sent.

{% hint style="info" %}
A user cannot be deleted while they have a Secured Credit Card with a non-zero Security Deposit.
{% endhint %}

**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><tr><td>Cardholder</td><td>Notification of card status changed (Closed)</td></tr></tbody></table>
{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
