> 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/recipes/physical-secured-credit-card-issuance-with-multiple-cards.md).

# Physical Secured Credit Card issuance with multiple cards

This is a step by step tutorial on how you can use Zūm Rails to set up a physical Secured Credit Card program that issues multiple cards per cardholder.

## Guide

This recipe walks you through onboarding a cardholder, securing their Security Deposit, issuing their Secured Credit Card, ordering a physical card, and issuing additional cards that share the same credit line. To start, the Credit Card Issuance payment method, physical card issuance, and multiple card issuance need to be enabled. Speak to our sales or support team on how to get [Cards](https://docs.zumrails.com/tokenization/introduction.md) enabled.

{% stepper %}
{% step %}

### Prerequisite

* [ ] Get the Credit Card Issuance payment method enabled on the Zūm Portal. Our Zūm Rails team will get your account ready for testing
* [ ] Get physical card issuance enabled: a virtual card program linked to a physical card program, with your shipping types (Standard and/or Expedited). See [Physical Card Issuance](https://docs.zumrails.com/tokenization/how-it-works.md#physical-card-issuance)
* [ ] Get multiple card issuance enabled, with your maximum number of physical and virtual cards per cardholder. See [Issue multiple cards to a user](https://docs.zumrails.com/tokenization/how-it-works.md#issue-multiple-cards-to-a-user)
* [ ] Get PIN Management enabled and your encryption key configured, if you will set PINs through the API. See [PIN Management](https://docs.zumrails.com/api-reference/cards.md#pin-management)
* [ ] Make sure you have a sandbox account for testing and read the developer quick start as [described here](https://docs.zumrails.com/getting-started/quickstart.md)
* [ ] Get the API username and password in the sandbox portal as [described here](https://docs.zumrails.com/getting-started/your-zum-rails-account.md#get-access-to-api-credentials) for API access
* [ ] Get your funding source ID. You can find this information in your portal under settings/funding source page or via API, as [described here](https://docs.zumrails.com/api-reference/funding-source.md)
* [ ] Get your wallet ID. You can find this information in your portal under the wallet page or via API, as [described here](https://docs.zumrails.com/api-reference/wallets.md)
  {% endstep %}

{% step %}

### Authenticate with Zūm APIs

Authenticate with the Zūm Rails API as indicated below, or view more details [here](https://docs.zumrails.com/api-reference/authentication.md)

```
Endpoint: /api/authenticate
Method: POST
```

```json
{
  "Username": "abc...123",
  "Password": "xyz...321"
}
```

{% endstep %}

{% step %}

### Cardholder Onboarding (IDV and KYC)

Zūm Rails requires Identity Verification (IDV) to meet KYC standards before a card can be issued. Only cardholders who pass identity verification can be issued multiple cards.

* To onboard via public URL: In the Zūm Portal, you can access your Card Onboarding URL to send directly to your prospect cardholders in the Settings --> Integration Codes page
* To onboard via [Card Onboarding](https://docs.zumrails.com/tokenization-1/zum-connect.md#card-onboarding) Hosted Link/SDK (Integrated):
  1. Create a Connect Token: Call `POST /api/connect/createtoken` and set the `ConnectTokenType` to `"CardOnboarding"`.
  2. Initialize the SDK: Embed the Zūm Connect iFrame or SDK into your application using this token.

{% hint style="info" %}
You can pre-fill the cardholder's residential address, shipping address, and occupation through the [optional parameters](https://docs.zumrails.com/tokenization-1/zum-connect.md#pre-filling-the-form). Use `shippingSameAsHomeAddress` when the physical card should be shipped to the residential address.
{% endhint %}

The prospect cardholder completes the Card Onboarding flow:

* Province/Territory selection: only the provinces and territories enabled for the card program are listed
* Profile Setup: full name (optional middle name), email, date of birth, phone number, language preference, occupation, residential address (must match the government-issued ID), shipping address, and consent to the Cardholder Agreement and electronic delivery
* One-Time Passcode: sent by SMS or email to verify their contact details
* ID Verification on their phone: Government ID upload and a selfie
* Security Deposit (if enabled on your card program)

The cardholder is informed that their full name will be printed on the physical card.

Once the prospect cardholder has completed the onboarding flow, a [User](https://docs.zumrails.com/api-reference/users.md) will be created at Zūm Rails. You have to store the Zūm Rails UserID, received in the response of the API call or [event listener](https://docs.zumrails.com/tokenization-1/zum-connect.md#event-listener-2). In addition, you can enable [email notifications](https://docs.zumrails.com/tokenization/how-it-works.md#email-notifications) and [card webhook](https://docs.zumrails.com/api-reference/webhooks.md#card-webhook) to keep you updated on the IDV status.

{% hint style="warning" %}
Cardholders created with [Bypass KYC/IDV](https://docs.zumrails.com/tokenization/how-it-works.md#bypass-kyc-idv) cannot be issued multiple cards.
{% endhint %}
{% endstep %}

{% step %}

### Security Deposit

Before approving the issuance of the Secured Credit Card for the User, the Security Deposit must be in your **Zūm Wallet.** The Security Deposit secures the credit line shared by all of the cardholder's cards.

If the [Security Deposit Step](https://docs.zumrails.com/tokenization/how-it-works.md#security-deposit-step) is enabled on your card program, the cardholder funds the Security Deposit by Interac e-Transfer or selects the Loan option at the end of Card Onboarding. Otherwise, fund your Zūm Wallet from your funding source:

```
Endpoint: /api/transaction
Method: POST
```

```json
{
  "ZumRailsType": "FundWallet",
  "TransactionMethod": "Eft",
  "Amount": 123.45,
  "Memo": "Fund 01",
  "Comment": "Funding Zum Wallet for security deposits",
  "FundingSourceId": "<your-funding-source-id>",
  "WalletId": "<your-wallet-id>"
}
```

{% endstep %}

{% step %}

### Card Issuance

Once the user has completed the onboarding flow, passed the identity check, and the Security Deposit is in your Zūm Wallet, the card can be issued. This first card is the cardholder's **Primary** card.

* Zūm Portal: Navigate to the User page and search for the user in the portal. If the card KYC is "Approved", you will see an option under the 3 Dots menu to approve and issue the card manually. You will be asked to provide the Credit Limit Amount which is the Security Deposit that will be pulled from the Zūm Wallet.
* Zūm API: Call the [Approve Card](https://docs.zumrails.com/api-reference/users.md#approve-a-card) endpoint in the User API. If the response is successful, it verifies that the KYC is complete, the Security Deposit was successfully pulled, and a card was issued to the User

Store the `UserCardId` of the Primary card returned by [Get Cards](https://docs.zumrails.com/api-reference/cards.md#get-cards). You will use it to order the physical card and to add more cards.
{% endstep %}

{% step %}

### Order the physical card

The cardholder's card is reissued onto your linked physical card program and shipped to the cardholder. The physical card has a new card number and replaces the virtual card.

* Cardholder Portal: The cardholder selects **Order Physical Card**, confirms the shipping address, and chooses a shipping type.
* Zūm Portal: Navigate to the User --> Card --> Manage Cards --> Physical Card, then confirm the shipping address and shipping type.
* Zūm API: Call the [Order Physical Card](https://docs.zumrails.com/api-reference/cards.md#order-physical-card) endpoint.

```
Endpoint: /api/card/order-physical-card
Method: POST
```

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9bd31212b-...b926dc141397",
    "CardShipmentType": "Standard",
    "ShippingAddress": {
        "AddressLine1": "123 Main St",
        "AddressLine2": "",
        "AddressCity": "Toronto",
        "AddressState": "ON",
        "AddressPostalCode": "A1A1A1",
        "AddressCountry": "CA"
    }
}
```

You can follow the order with the `FulfillmentStatus` field in [Get Cards](https://docs.zumrails.com/api-reference/cards.md#get-cards) and the [Physical Card Lifecycle](https://docs.zumrails.com/api-reference/webhooks.md) webhooks.
{% endstep %}

{% step %}

### Card Activation

The physical card arrives in an `IssuedInactive` status and must be activated with a PIN.

* Cardholder Portal (recommended): The cardholder enters the last 4 digits and expiry date printed on the card, then sets a 4-digit PIN.
* Zūm API: Set the PIN with the [Set PIN](https://docs.zumrails.com/api-reference/cards.md#set-pin) endpoint (the PIN must be encrypted), then call the [Activate Card](https://docs.zumrails.com/api-reference/cards.md#activate-card) endpoint.

{% hint style="info" %}
**Sandbox:** in the Cardholder Portal, last 4 digits `9999`, expiry month `99` and expiry year `99` always activate successfully.
{% endhint %}

You can verify the status at any time on the Zūm Portal by navigating to the User --> Manage Cards --> see Card Status or by calling [Get Cards](https://docs.zumrails.com/api-reference/cards.md#get-cards).
{% endstep %}

{% step %}

### Issue additional cards

Once the Primary card has been activated, you or the cardholder can add more virtual or physical cards, up to your configured limits. A card cannot be added if the Primary card is closed or has never been activated. Additional cards share the Primary card's credit line and Security Deposit, and all purchases appear on one monthly statement.

* Cardholder Portal: When **Add a Card** is enabled under Program Management --> Cardholder Portal, the cardholder selects **+ Add a card**, chooses a virtual or physical card, and can give it a nickname.
* Zūm Portal: Navigate to the User --> Card --> Manage Cards.
* Zūm API: Call the [Add Secondary Card](https://docs.zumrails.com/api-reference/cards.md#add-secondary-card) endpoint with the Primary card's `UserCardId`. You can set an optional `Nickname`. For a physical card, set `IsPhysical` to `true` and include a `CardShipmentType` and, optionally, a `ShippingAddress`.

```
Endpoint: /api/card/add-secondary-card
Method: POST
```

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9bd31212b-...b926dc141397",
    "IsPhysical": false,
    "Nickname": "Online shopping"
}
```

New virtual cards start in an `IssuedInactive` status and must be activated with the [Activate Card](https://docs.zumrails.com/api-reference/cards.md#activate-card) endpoint or from the Zūm Portal. New physical cards are shipped and activated like the first physical card.

{% hint style="warning" %}
If the shared balance goes over the credit limit, all of the cardholder's cards are placed in Fraud Block until a payment is received.
{% endhint %}
{% endstep %}

{% step %}

### Receive card updates

The recommended way to receive card updates is through webhooks.

You can configure your webhook URL and which events you might want to receive in the Zūm Rails portal, under settings/webhook and api settings.

We recommend setting up all available Secured Credit Card events, including:

* **Secured Credit Card User Events:** onboarding, Security Deposit, card status, `CardOverlimit`, `CardStatement`, PIN, `CardAddedToGroup`, `CardRemovedFromGroup` and `GroupClosed`
* **Secured Credit Card Physical Lifecycle Events:** `CardPhysicalOrdered`, `CardPhysicalShipped` and `CardPhysicalDelivered`
* **Secured Credit Card Transaction Events**

Card webhooks include `IsPrimaryCard` and `SharedBalanceGroupId` so you can link each card to the cardholder's card group, as [described here](https://docs.zumrails.com/api-reference/webhooks.md)
{% endstep %}

{% step %}

### Close a card and return the Security Deposit

* To remove a secondary card, set its status to `Closed` with [Update Card Status](https://docs.zumrails.com/api-reference/cards.md#update-card-status). The credit line and other cards are not affected.
* Closing the Primary card closes all of the cardholder's cards. Zūm Rails automatically unloads the remaining Security Deposit to your Zūm Wallet before closing the cards. A card with an outstanding balance cannot be closed. See [Closing a Secured Credit Card](https://docs.zumrails.com/tokenization/how-it-works.md#closing-a-secured-credit-card-with-a-security-deposit).
  {% endstep %}
  {% endstepper %}


---

# 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/recipes/physical-secured-credit-card-issuance-with-multiple-cards.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.
