> 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/api-reference/cards.md).

# Cards

## Create Card

Use this endpoint to create a user and issue a card without the Card Onboarding flow. It can only be used with card programs that have KYC/IDV bypass enabled (see [Bypass KYC/IDV](https://docs.zumrails.com/tokenization/how-it-works.md#bypass-kyc-idv)). It supports Prepaid Card and Secured Credit Card programs; the card type is determined by the `CardProgramId`.

`Method: POST`

`Endpoint: {{env}}/api/card/create`

{% tabs %}
{% tab title="Request" %}

```json
{
  "CardProgramId": "string",
  "UserId": "00000000-0000-0000-0000-000000000000",
  "FirstName": "string",
  "LastName": "string",
  "Email": "string",
  "PhoneNumber": "string",
  "DateOfBirth": "string",
  "ClientUserId": "string",
  "Language": "En",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "AddressCity": "string",
  "AddressState": "string",
  "AddressPostalCode": "string",
  "AddressCountry": "string"
}

```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "FirstName": "string",
        "LastName": "string",
        "Email": "string",
        "PhoneNumber": "string",
        "DateOfBirth": "string",
        "CustomerId": "00000000-0000-0000-0000-000000000000",
        "OnboardId": "00000000-0000-0000-0000-000000000000",
        "OnboardStatus": "string",
        "SessionId": "string",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "ClientUserId": "string",
        "UserCardId": "00000000-0000-0000-0000-000000000000",
        "CardType": "string",
        "AddressLine1": "string",
        "AddressLine2": "string",
        "AddressCity": "string",
        "AddressState": "string",
        "AddressPostalCode": "string",
        "AddressCountry": "string"
    }
}
```

{% endtab %}
{% endtabs %}

#### **Input Parameters**

| Parameter            | Type    | Mandatory                        | Description                                                                        |
| -------------------- | ------- | -------------------------------- | ---------------------------------------------------------------------------------- |
| CardProgramId        | String  | Yes                              | Card Program ID to issue the card under                                            |
| UserId               | Guid    | No                               | Existing user to issue the card to. When provided, profile fields are not required |
| FirstName            | String  | Yes, if `UserId` is not provided | First name                                                                         |
| LastName             | String  | Yes, if `UserId` is not provided | Last name                                                                          |
| Email                | String  | Yes, if `UserId` is not provided | Email address                                                                      |
| PhoneNumber          | String  | Yes, if `UserId` is not provided | Mobile phone number                                                                |
| DateOfBirth          | String  | Yes, if `UserId` is not provided | Date of birth, `MM/dd/yyyy`                                                        |
| Language             | String  | No                               | Cardholder language                                                                |
| ClientUserId         | String  | No                               | Your own identifier for the user                                                   |
| AddressLine1         | String  | Yes¹                             | Address line 1                                                                     |
| AddressLine2         | String  | No                               | Address line 2                                                                     |
| AddressCity          | String  | Yes¹                             | City                                                                               |
| AddressState         | String  | Yes¹                             | Province code                                                                      |
| AddressPostalCode    | String  | Yes¹                             | Postal code                                                                        |
| AddressCountry       | String  | Yes¹                             | Country                                                                            |
| CreditLimitRequested | Decimal | Yes, for Secured Credit Card     | Requested credit limit. Must be within the program's minimum and maximum           |

¹ Required for Secured Credit Card programs. For Prepaid Card programs, required unless your program is configured to not require an address.

#### **Response**

| Field               | Type   | Description                                                       |
| ------------------- | ------ | ----------------------------------------------------------------- |
| FirstName           | string | The legal first name of the profile holder.                       |
| LastName            | string | The legal last name of the profile holder.                        |
| Email               | string | The registered email address for the user profile.                |
| PhoneNumber         | string | The verified phone number for the profile.                        |
| DateOfBirth         | string | The user's date of birth as recorded in the system.               |
| CustomerId          | Guid   | The unique identifier for the customer record.                    |
| OnboardId           | Guid   | The unique identifier for the specific onboarding session.        |
| OnboardStatus       | string | The current state of the onboarding process.                      |
| SessionId           | string | The identifier for the active verification or onboarding session. |
| UserId              | Guid   | The unique identifier for the user in the BaaS platform.          |
| ClientUserId        | string | The external identifier provided by the client for the user.      |
| UserCardId          | Guid   | The unique identifier for the card associated with this user.     |
| CardType            | string | The category of the issued card (e.g., Prepaid, Secured).         |
| CardHolderPortalUrl | string | The URL where the cardholder can access their management portal.  |
| AddressLine1        | string | The primary line of the user's registered address.                |
| AddressLine2        | string | The secondary line of the user's address.                         |
| AddressCity         | string | The city of the user's address.                                   |
| AddressState        | string | The state or province of the user's address.                      |
| AddressPostalCode   | string | The postal or zip code of the user's address.                     |
| AddressCountry      | string | The country code of the user's address.                           |

#### **Errors**

Errors are returned with HTTP 400. Multiple missing fields are returned together, e.g. *"FirstName is required; Email is required"*.

| Message                                                                                                                  | Reason                                                   |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| Card program does not support bypass KYC onboarding.                                                                     | KYC/IDV bypass is not enabled on the card program        |
| Credit limit requested is required for secured card applications                                                         | `CreditLimitRequested` missing for a Secured Credit Card |
| Credit limit requested must be at least {min} / must not exceed {max}                                                    | `CreditLimitRequested` outside the program's range       |
| Error - Card Program Id {CardProgramId} does not exist for customer {CustomerId}.                                        | Card program not found on your account                   |
| User not found.                                                                                                          | `UserId` does not exist                                  |
| User already has a {card type} that is not closed (status: {status}). Close the existing card before creating a new one. | User already holds a non-closed card of this card type   |
| Invalid province selected for the card program.                                                                          | `AddressState` is not enabled for the card program       |

## Activate Card

Use this endpoint to set the users current prepaid card status to Activated.

`Method: POST`

`Endpoint: {{env}}/api/card/activate-card`

{% hint style="info" %}
For physical cards, set the cardholder's PIN with [Set PIN](#set-pin). Cardholders activating from the Cardholder Portal are asked to confirm the last 4 digits and expiry date of their physical card and to set a PIN.
{% endhint %}

{% tabs %}
{% tab title="Request" %}

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9bd31212b-...b926dc141397"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "ResponseDesc": "Operation is successful."
    }
}
```

{% endtab %}
{% endtabs %}

#### **Input Parameters**

<table><thead><tr><th width="208.625">Parameter</th><th width="140.25">Type</th><th width="108.8828125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>UserId</td><td>Guid</td><td>Yes</td><td>User Id</td></tr><tr><td>UserCardID</td><td>Guid</td><td>Yes</td><td>Id of the specific card type issued (e.g. Prepaid Card User Id)</td></tr></tbody></table>

#### Response

| Parameter    | Type   | Description                 |
| ------------ | ------ | --------------------------- |
| ResponseDesc | String | Description of the response |

## Update Card Program

Use this endpoint to update the card program of the current card attached to the user.

`Method: POST`

`Endpoint: {{env}}/api/card/update-card-program`

{% tabs %}
{% tab title="Request" %}

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9bd31212b-...b926dc141397",
    "NewProgramId": "Customer_Card_Program"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "CardReferenceId": "110195650197284",
        "NewProgramId": "Zumrail_test_prog",
        "ResponseDesc": "Operation is successful."
    }
}
```

{% endtab %}
{% endtabs %}

#### **Input Parameters**

<table><thead><tr><th width="176.23046875">Parameter</th><th width="122.19140625">Type</th><th width="110.76171875">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>UserId</td><td>Guid</td><td>Yes</td><td>User Id</td></tr><tr><td>UserCardId</td><td>Guid</td><td>Yes</td><td>Id of the specific card type issued (e.g. Prepaid Card User Id)</td></tr><tr><td>NewProgramId</td><td>String</td><td>Yes</td><td>New Card Program Id (Case Sensitive)</td></tr></tbody></table>

#### Response

| Parameter       | Type   | Description          |
| --------------- | ------ | -------------------- |
| CardReferenceId | String | Card Reference Id    |
| NewProgramId    | String | New Card Program Id  |
| ResponseDesc    | String | Response description |

## Get Cards

Use this endpoint to gather all the cards attached to the user.

`Method: GET`

`Endpoint: {{env}}/api/card/get-cards/{{userId}}`

{% tabs %}
{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": [
        {
            "Id": "ba2d7ae1-65e8-4e90-8064-91f65f76a9d5",
            "CardBrand": "Unknown",
            "CardType": "SecuredCreditCard",
            "CardApplicationStatus": "Approved",
            "OnboardStatus": "Approved",
            "CardNumber": "************1619",
            "ExpireMonth": "07",
            "ExpireYear": "28",
            "CardStatus": "IssuedInactive",
            "CardReferenceId": "599000386149",
            "CardRegistrationStatus": "NotRegistered",
            "CardProgramId": "SECURE_TEST",
            "CardholderId": "599000000000003861",
            "AvailableBalance": -10.0,
            "LedgerBalance": -10.0,
            "CustomerId": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f",
            "OnboardId": "a30803aa-3dff-4dc6-9940-d74d5f9d8a1a",
            "CreatedAt": "0001-01-01T05:00:00Z",
            "VirtualCard": "N",
            "PhysicalCard": "N",
            "FulfillmentStatus": null,
            "FulfillmentType": null,
            "IDVVerification": "Not Bypassed",
            "PendingAmount": 0,
            "CreditLimitRequested": 500,
            "CreditLimit": 500.0,
            "SecurityDepositAmount": 500.0,
            "SecurityDepositCardNumber": "************4463",
            "SecurityDepositCardReferenceId": "599000386049",
            "LastPaymentAmount": 0,
            "MinimumPaymentAmount": 0,
            "StatementDate": "2026-07-27",
            "StatementAmount": 0,
            "IsPrimaryCard": true,
            "SharedBalanceGroupId": "5b1e7c2a-...-0f3d9a6b1c44",
            "SiblingCards": [],
            "WalletProvisionings": []
        },
        {
            "Id": "c08e177c-be4c-4f36-8539-83689fb95ae0",
            "CardBrand": "Unknown",
            "CardType": "PrepaidCard",
            "CardApplicationStatus": "Approved",
            "OnboardStatus": "Approved",
            "CardNumber": "************3481",
            "ExpireMonth": "07",
            "ExpireYear": "2029",
            "CardStatus": "IssuedInactive",
            "CardReferenceId": "599000385610",
            "CardRegistrationStatus": "NotRegistered",
            "CardProgramId": "Zumrail_ProdT",
            "CardholderId": "599000000000003833",
            "AvailableBalance": 99.99,
            "LedgerBalance": 99.99,
            "CustomerId": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f",
            "OnboardId": "e57e7797-fb41-492b-8606-b91314ae15bd",
            "CreatedAt": "2026-07-21T00:14:20.341661Z"
        },
        {
            "Id": "c9680dfc-cbc3-41f0-bf9d-29f9ab36f66f",
            "CardBrand": "Unknown",
            "CardType": "PrepaidCard",
            "CardApplicationStatus": "Approved",
            "OnboardStatus": "Approved",
            "CardNumber": "************1996",
            "ExpireMonth": "07",
            "ExpireYear": "29",
            "CardStatus": "Closed",
            "CardReferenceId": "599000383331",
            "CardRegistrationStatus": "NotRegistered",
            "CardProgramId": "Zumrail_ProdT",
            "CardholderId": "599000000000003833",
            "AvailableBalance": 0.0,
            "LedgerBalance": 0.0,
            "CustomerId": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f",
            "OnboardId": "e57e7797-fb41-492b-8606-b91314ae15bd",
            "CreatedAt": "2026-07-18T00:26:52.844958Z",
            "CardActivatedAt": "2026-07-18T00:40:42.760871Z",
            "CardClosedAt": "2026-07-21T00:14:19.617416Z",
            "VirtualCard": "N",
            "PhysicalCard": "N",
            "FulfillmentStatus": null,
            "FulfillmentType": null,
            "IDVVerification": "Not Bypassed"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

**Input Parameters**

| Parameter | Type | Mandatory | Description |
| --------- | ---- | --------- | ----------- |
| UserId    | Guid | Yes       | User Id     |

**Response**

| Id                             | Guid     | The unique identifier for the User Card                                                           |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------- |
| CardBrand                      | string   | The brand of the card (e.g., Visa, Mastercard).                                                   |
| CardType                       | string   | The functional type of the card (Prepaid or Secured).                                             |
| CardApplicationStatus          | string   | The current status of the card application.                                                       |
| OnboardStatus                  | string   | The status of the user onboarding process for this card.                                          |
| CardNumber                     | string   | The masked or truncated card number.                                                              |
| ExpireMonth                    | string   | The two-digit expiration month of the card.                                                       |
| ExpireYear                     | string   | The expiration year of the card.                                                                  |
| CardStatus                     | string   | The operational status of the card (e.g., Active, Blocked, Closed).                               |
| CardOnboardingStatus           | string   | Specific onboarding step reached for the card.                                                    |
| CardReferenceId                | string   | The external reference identifier from the card processor.                                        |
| CardRegistrationStatus         | string   | Indicates if the card has been registered by the user.                                            |
| CardholderUserId               | string   | The identifier of the user who holds the card.                                                    |
| CardProgramId                  | string   | The identifier of the card program this card belongs to.                                          |
| CardholderId                   | string   | The processor-specific cardholder identifier.                                                     |
| AvailableBalance               | decimal  | The amount of funds currently available for spending.                                             |
| LedgerBalance                  | decimal  | The total balance including pending transactions.                                                 |
| CustomerId                     | string   | The unique identifier for the customer (tenant).                                                  |
| OnboardId                      | string   | The identifier for the specific onboarding session.                                               |
| CreatedAt                      | DateTime | The timestamp when the card record was created.                                                   |
| CardActivatedAt                | DateTime | The timestamp when the card was activated.                                                        |
| CardClosedAt                   | DateTime | The timestamp when the card was closed.                                                           |
| VirtualCard                    | string   | `Y` if the card is a virtual card, otherwise `N`.                                                 |
| PhysicalCard                   | string   | `Y` if the card is a physical card, otherwise `N`.                                                |
| FulfillmentStatus              | string   | Physical card fulfillment status: `Ordered`, `Shipped`, `Delivered`. Null for virtual cards.      |
| FulfillmentType                | string   | Physical card shipping type: `Standard`, `Expedited`. Null for virtual cards.                     |
| IDVVerification                | string   | How identity verification was completed: `Bypassed`, `Not Bypassed`, `KYC Completed by Customer`. |
| PendingAmount                  | decimal  | The sum of all transactions currently in a pending state.                                         |
| CreditLimitRequested           | decimal  | The credit limit amount requested by the applicant.                                               |
| CreditLimit                    | decimal  | The total approved credit limit for the card.                                                     |
| SecurityDepositAmount          | decimal  | The amount held as a security deposit for secured cards.                                          |
| SecurityDepositCardNumber      | string   | The card number associated with the security deposit.                                             |
| SecurityDepositCardReferenceId | string   | The reference ID for the security deposit card.                                                   |
| LastPaymentDate                | string   | The date of the last payment made on the account.                                                 |
| LastPaymentAmount              | decimal  | The amount of the most recent payment.                                                            |
| MinimumPaymentAmount           | decimal  | The minimum amount required for the next payment.                                                 |
| MinimumPaymentDueDate          | string   | The deadline for making the minimum payment.                                                      |
| StatementDate                  | string   | The date when the most recent statement was generated.                                            |
| StatementAmount                | decimal  | The total balance due on the last statement.                                                      |
| IsPrimaryCard                  | Boolean  | Whether the card is the Primary card for the card type.                                           |
| SharedBalanceGroupId           | Guid     | Identifier shared by all cards that share the same balance or credit line.                        |
| SiblingCards                   | Array    | Other cards in the same shared-balance group, excluding the current card. See below.              |
| WalletProvisionings            | Array    | Digital wallets the card has been added to. See below.                                            |

**SiblingCards**

| Parameter       | Type    | Description                                               |
| --------------- | ------- | --------------------------------------------------------- |
| Id              | Guid    | The unique identifier for the sibling User Card           |
| CardReferenceId | String  | The external reference identifier from the card processor |
| IsPrimaryCard   | Boolean | Whether the sibling card is the Primary card of the group |
| CardStatus      | String  | The operational status of the sibling card                |
| PhysicalCard    | Boolean | Whether the sibling card is a physical card               |
| Last4Digits     | String  | Last 4 digits of the sibling card number                  |

**WalletProvisionings**

| Parameter        | Type     | Description                                                                                                     |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| Id               | Guid     | The unique identifier for the wallet provisioning                                                               |
| DeviceName       | String   | Name of the device the card was added to                                                                        |
| WalletType       | String   | `ApplePay`, `GooglePay`, `SamsungPay`, `Unknown`                                                                |
| Status           | String   | `Added`, `Suspended`, `Resumed`, `PendingStepUp`, `Unknown`. Removed and declined wallet tokens are not listed. |
| TokenRequesterId | String   | Identifier of the wallet provider                                                                               |
| EventDate        | DateTime | Date and time of the latest wallet event                                                                        |

## Update Card Status

Use this endpoint to set the card status of the user’s current card.

`Method: POST`

`Endpoint: {{env}}/api/card/update-card-status`

{% tabs %}
{% tab title="Request" %}

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9bd31212b-...b926dc141397",
    "CardStatus": "FraudBlock"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "CardStatus": "FraudBlock",
        "ResponseDesc": "Operation is successful."
    }
}
```

{% endtab %}
{% endtabs %}

#### **Request Parameters**

<table><thead><tr><th width="165.55859375">Parameter</th><th width="128.15234375">Type</th><th width="118.47265625">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>UserId</td><td>Guid</td><td>Yes</td><td>User Id</td></tr><tr><td>UserCardId</td><td>Guid</td><td>Yes</td><td>Id of the specific card type issued (e.g. Prepaid Card User Id)</td></tr><tr><td>CardStatus</td><td>String</td><td>Yes</td><td>New Card Status. Allowed values: <code>Activated</code>, <code>Inactive</code>, <code>FraudBlock</code>, <code>Closed</code></td></tr></tbody></table>

#### **Response**

| Parameter    | Type   | Description          |
| ------------ | ------ | -------------------- |
| CardStatus   | String | Card Status          |
| ResponseDesc | String | Response description |

#### **Card Status**

These are the available card status updates.

| Card Status      | Description                                                                         |
| ---------------- | ----------------------------------------------------------------------------------- |
| Issued\&inactive | Card is issued and not activated yet (default card status on new and reissued card) |
| Activated        | Card is active and ready for use.                                                   |
| Closed           | Card account is closed.                                                             |
| Inactive         | Card is temporarily inactive.                                                       |
| FraudBlock       | Card is blocked due to suspected fraud.                                             |

{% hint style="info" %}
**Secured Credit Card:** when a card with a remaining Security Deposit is closed, the full Security Deposit is automatically unloaded to your Zūm Wallet before the card is closed. A card with an outstanding balance cannot be closed.

**Sandbox:** set `SimulationEvent` to `UnloadFailing` to simulate a failed Security Deposit unload.
{% endhint %}

These are the available card statuses that can be returned.

| Card Status         | Description                             |
| ------------------- | --------------------------------------- |
| PendingCardIssuance | Card is not issued yet                  |
| Issued\&inactive    | Card is issued and not activated yet    |
| Activated           | Card is active and ready for use.       |
| Closed              | Card account is closed.                 |
| Inactive            | Card is temporarily inactive.           |
| FraudBlock          | Card is blocked due to suspected fraud. |

These are the available card application statuses when the User is in the process of applying for the card and the card is not yet issued.

| Card Status     | Description                                                                                   |
| --------------- | --------------------------------------------------------------------------------------------- |
| PendingApproval | Card application has passed KYC/IDV and not yet approved for card issuance                    |
| UnderReview     | Card application is under review                                                              |
| Rejected        | Card application is declined                                                                  |
| Approved        | Card application is approved for card issuance                                                |
| InProgress      | Card application KYC/IDV verification is submitted and process is in progress                 |
| Incomplete      | Card application has completed the card profile setup and KYC/IDV step has not been completed |

#### **Errors**

| Message                                                                               |
| ------------------------------------------------------------------------------------- |
| Card cannot be closed when there is an outstanding balance.                           |
| Unload failed while attempting to close card, view transaction details for more info. |

## Reissue Card

Use this endpoint to reissue an existing non-closed card and close the existing card attached to the user. The reissued card will have a new card number, new expire date, and new CVC.

`Method: POST`

`Endpoint: {{env}}/api/card/reissue-card`

{% hint style="info" %}
Reissue Card does not convert a virtual card to a physical card. Use [Order Physical Card](#order-physical-card).
{% endhint %}

{% tabs %}
{% tab title="Request" %}

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9ebd932b-...b92633e14297"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "NewCardReferenceId": "110195650225284",
        "ResponseDesc": "Operation is successful.",
        "UserId": "8cdbcf63-7fd1-445c-ac34-4d20bef30c82",
        "Last4Digits": "1956",
        "ExpireMonth": "04",
        "ExpireYear": "27",
        "AvailableBalance": 4.35,
        "LedgerBalance": 4.35,
        "FirstName": "Julies",
        "LastName": "Test",
        "CardStatus": "IssuedInactive",
        "CardProgramId": "Zumrail_Test",        
        "Email": "john.doe@zumrails.com"
    }
}

```

{% endtab %}
{% endtabs %}

#### **Request Parameters**

| Parameter        | Type    | Required | Description                                                                 |
| ---------------- | ------- | -------- | --------------------------------------------------------------------------- |
| UserId           | guid    | yes      | User Id                                                                     |
| UserCardId       | guid    | yes      | Id of the specific card type issued (e.g. Prepaid Card User Id)             |
| IsLostOrStolen   | Boolean | No       | Set to `true` when the card is being replaced because it was lost or stolen |
| CardShipmentType | String  | No       | Physical cards only. `Standard` or `Expedited`                              |
| ShippingAddress  | Object  | No       | Physical cards only. Updates the shipping address for the replacement card  |

#### **Response**

| Parameter          | Field  | Description                                      |
| ------------------ | ------ | ------------------------------------------------ |
| NewCardReferenceId | String | New Card Reference Id                            |
| ResponseDesc       | String | Response description                             |
| UserId             | Guid   | User Id of the prepaid card user                 |
| Last4Digits        | Number | Last 4 digits of the prepaid card number         |
| ExpireMonth        | String | Expiry month of the prepaid card number          |
| ExpireYear         | String | Expiry year of the prepaid card number           |
| Available balance  | Number | Available balance of the prepaid card number     |
| Ledger Balance     | Number | Ledger balance of the prepaid card number        |
| FirstName          | String | First name of the prepaid card user              |
| LastName           | String | Last name of the prepaid card user               |
| CardStatus         | String | Card status of the reissued card                 |
| CardProgramId      | String | Card program the reissued card is assigned under |
| Email              | String | Email address of the prepaid card user           |

## Order Physical Card

Use this endpoint to order a physical card for a user's current virtual card. The card is reissued onto the linked physical card program with a new card number.

`Method: POST`

`Endpoint: {{env}}/api/card/order-physical-card`

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}
{% endtabs %}

#### **Input Parameters**

| Parameter        | Type   | Mandatory | Description                                                                                                                                        |
| ---------------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| UserId           | Guid   | Yes       | User Id                                                                                                                                            |
| UserCardId       | Guid   | Yes       | Id of the user's current card                                                                                                                      |
| CardShipmentType | String | No        | `Standard` or `Expedited`. Must be enabled for the card program                                                                                    |
| ShippingAddress  | Object | Yes       | Shipping address (`AddressLine1`, `AddressLine2`, `AddressCity`, `AddressState`, `AddressPostalCode`, `AddressCountry`). PO Boxes are not accepted |

## Add Secondary Card

Use this endpoint to issue an additional card of the same card type to a user. The new card shares the balance (Prepaid Card) or credit line (Secured Credit Card) of the user's Primary card. Multiple card issuance must be enabled on your account.

`Method: POST`

`Endpoint: {{env}}/api/card/add-secondary-card`

{% tabs %}
{% tab title="Request" %}

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

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "Id": "3f6c2d1e-8a4b-4c7d-9e2f-1a2b3c4d5e6f",
        "CardBrand": "Unknown",
        "CardType": "PrepaidCard",
        "CardApplicationStatus": "Approved",
        "OnboardStatus": "Approved",
        "CardNumber": "************5678",
        "ExpireMonth": "07",
        "ExpireYear": "29",
        "CardStatus": "IssuedInactive",
        "CardReferenceId": "599000386250",
        "CardRegistrationStatus": "NotRegistered",
        "CardProgramId": "Zumrail_ProdT",
        "CardholderId": "599000000000003833",
        "AvailableBalance": 99.99,
        "LedgerBalance": 99.99,
        "CustomerId": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f",
        "OnboardId": "e57e7797-fb41-492b-8606-b91314ae15bd",
        "CreatedAt": "2026-07-22T15:02:11.512304Z",
        "VirtualCard": "Y",
        "PhysicalCard": "N",
        "FulfillmentStatus": null,
        "FulfillmentType": null,
        "IDVVerification": "Not Bypassed",
        "SharedBalanceGroupId": "5b1e7c2a-...-0f3d9a6b1c44",
        "IsPrimaryCard": false,
        "SiblingCards": [
            {
                "Id": "c08e177c-be4c-4f36-8539-83689fb95ae0",
                "CardReferenceId": "599000385610",
                "IsPrimaryCard": true,
                "CardStatus": "Activated",
                "PhysicalCard": false,
                "Last4Digits": "3481"
            }
        ],
        "WalletProvisionings": []
    }
}
```

{% endtab %}
{% endtabs %}

#### **Input Parameters**

| Parameter        | Type    | Mandatory          | Description                                                                                                                                  |
| ---------------- | ------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| UserId           | Guid    | Yes                | User Id                                                                                                                                      |
| UserCardId       | Guid    | Yes                | Id of the user's Primary card                                                                                                                |
| IsPhysical       | Boolean | Yes                | `true` to issue a physical card, `false` for virtual                                                                                         |
| CardShipmentType | String  | Yes, physical only | `Standard` or `Expedited`                                                                                                                    |
| ShippingAddress  | Object  | No                 | Physical cards only. Shipping address (`AddressLine1`, `AddressLine2`, `AddressCity`, `AddressState`, `AddressPostalCode`, `AddressCountry`) |
| Nickname         | String  | No                 | Nickname for the new card                                                                                                                    |

Requires permission to update user card details.

#### **Response**

Returns the new card in the same format as a card in [Get Cards](#get-cards), including `SiblingCards`.

#### **Errors**

All errors return HTTP 400.

| Message                                                                                                                     | Cause                                                                          |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| UserId and UserCardId are required.                                                                                         | `UserId` or `UserCardId` is missing                                            |
| Card with id {id} not found.                                                                                                | The card was not found                                                         |
| Card with id {id} is not a primary card. A secondary card can only be linked against the primary of a shared-balance group. | `UserCardId` is not the Primary card                                           |
| Card with id {id} is closed or has never been activated. A secondary card cannot be linked.                                 | The Primary card is closed or was never activated                              |
| BaasUser {id} has not passed KYC/IDV verification and is not eligible to hold multiple cards.                               | The user is not KYC/IDV verified (including users created with Bypass KYC/IDV) |
| Customer {id} does not have multi-card issuance enabled for {CardType}.                                                     | Multiple card issuance is not enabled for the card type                        |
| Shipment type is required to issue a physical secondary card.                                                               | `CardShipmentType` is missing for a physical card                              |
| You've reached the maximum number of physical cards for your account.                                                       | Physical card limit reached                                                    |
| You've reached the maximum number of virtual cards for your account.                                                        | Virtual card limit reached                                                     |

To remove a secondary card, set its status to `Closed` with [Update Card Status](#update-card-status). Closing the Primary card closes all cards in the group.

## Get Card Transactions

Use this endpoint for transaction history from a users prepaid card.

`Method: POST`

`Endpoint: {{env}}/api/user/get-card-transactions`

{% tabs %}
{% tab title="Request" %}

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "CardReferenceId": "599000027458",
    "CreatedAtOperator": "isInTheLast",
    "CreatedAt": "2023-01-01 12:00:00.000",
    "Pagination": {
        "PageNumber": 1,
        "ItemsPerPage": 10
    }
}

```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 10,
        "TotalCount": 4,
        "Items": [
            {
                "Id": "6adae97f-1bf0-491a-b192-173d81cb9518",
                "CreatedAt": "2025-06-10T12:20:30Z",
                "SettlementDate": "2025-06-14",
                "TransactionId": "F333334",
                "Description": "Grocery Store Purchase",
                "Status": "Posted",
                "Debit": -3.99,
                "Credit": 0,
                "MerchantNameAndLocation": "Fake Retailer Inc. New York NY"
            },...
        ]
    }
}


```

{% endtab %}
{% endtabs %}

#### **Request Parameters**

| UserId                  | Guid            | Yes | User Id                                        |
| ----------------------- | --------------- | --- | ---------------------------------------------- |
| CardReferenceId         | String          | Yes | Card reference id                              |
| CardTransactionType     | String          | No  | Card issuer transaction type                   |
| CardTransactionStatuses | String          | No  | Card transaction statuses                      |
| TransactionZumRailsType | String          | No  | Transaction zum rails type                     |
| CardTransactionId       | String          | No  | Card issuer transaction id                     |
| GenericSearch           | String          | No  | Filter the search with this text               |
| AmountLowerLimit        | Number          | No  | Lower limit transaction amount                 |
| AmountUpperLimit        | Number          | No  | Upper limit transaction amount                 |
| CreatedAtOperator       | String          | No  | Date filter type for query                     |
| CreatedAtFrom           | Datetime        | No  | Start date for query                           |
| CreatedAtTo             | Datetime        | No  | End date for query                             |
| CreatedAt               | Datetime        | No  | Base date for query                            |
| Timezone                | Windows or IANA | No  | Timezone identifier                            |
| **Pagination**          | -               | Yes |                                                |
| PageNumber              | Number          | Yes | The respective page, starting at 1             |
| ItemsPerPage            | Number          | Yes | The amount of items per page between 0 and 100 |

#### **Response**

| Parameter               | Type        | Description                       |
| ----------------------- | ----------- | --------------------------------- |
| CurrentPage             | Number      | Current page of transaction list  |
| PageSize                | Number      | Number of items in page requested |
| TotalCount              | Number      | Number of total items queryable   |
| **Items**               | <p><br></p> | <p><br></p>                       |
| Id                      | Guid        | Zum Rails Transaction Id          |
| CreatedAt               | Datetime    | Created at date and time          |
| SettlementDate          | Date        | Date funds settled                |
| TransactionId           | String      | Card issuer transaction id        |
| Description             | String      | Description of transaction        |
| Status                  | String      | Status of transaction             |
| Debit                   | Decimal     | Amount Debited                    |
| Credit                  | Decimal     | Amount Credited                   |
| MerchantNameAndLocation | String      | Merchant name and location        |

**CreatedAtOperator:**

| Type           | Description                              |
| -------------- | ---------------------------------------- |
| IsInTheLast    | Between user creation date and now       |
| ExactlyMatches | Exactly matches CreatedAt                |
| IsBetween      | Is between CreatedAtFrom and CreatedAtTo |
| IsAfter        | Is after CreatedAt                       |
| IsOnOrAfter    | Is on or after CreatedAt                 |
| IsBefore       | Is before CreatedAt                      |
| IsBeforeOrOn   | Is before or on CreatedAt                |

**CardTransactionStatuses:**

| Type     | Description           |
| -------- | --------------------- |
| Posted   | Posted transactions   |
| Pending  | Pre Auth Transactions |
| Declined | Declined Transcations |

**CardTransactionType:**

| Type   | Description         |
| ------ | ------------------- |
| POS    | POS Purchase        |
| ATM    | Cash Withdrawal     |
| Debit  | Debit Transactions  |
| Credit | Credit Transactions |

## Cancel Transactions

Use this endpoint for reversing pre-auth POS transactions and fee transactions.

`Method: DELETE`

`Endpoint: {{env}}/api/card-transaction/{transactionId}`

{% tabs %}
{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "DELETE Request successful.",
    "isError": false,
    "result": "Request completed"
}
```

{% endtab %}
{% endtabs %}

## Get Statement List

Use this endpoint to retrieve a paginated list of card statements for a User.

`Method: POST`

`Endpoint: {{env}}/api/card/statements/filter`

{% tabs %}
{% tab title="Request" %}

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9bd31212b-...b926dc141397",
    "AddTransactionDetails": true,
    "dateFrom": "2026-05-01T00:00:00Z",
    "dateTo": "2026-12-31T23:59:59Z",
    "TransactionPageSize": 10,
    "Pagination": {
        "PageNumber": 1,
        "ItemsPerPage": 10
    }
}

```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 10,
        "TotalCount": 2,
        "Items": [
            {
                "Id": "a3986b76-c899-4be1-8999-29d4b3adab34",
                "UserCardId": "952ea6a5-5eee-4291-9d13-422df35fcd94",
                "PeriodStart": "05-01-2026",
                "PeriodEnd": "05-31-2026",
                "StatementDate": "05-01-2026",
                "PaymentDueDate": "2026-05-25T04:00:00Z",
                "CreatedAt": "2026-06-02T23:22:48.893546Z",
                "Last4Digits": "2945",
                "CardType": "SecuredCreditCard",
                "PreviousBalance": 146.65,
                "Payments": 0.0,
                "OtherCredits": 0.0,
                "Purchases": 0.0,
                "CashAdvance": 0.0,
                "InterestCharged": 0.7,
                "FeeCharged": 35.0,
                "NewBalance": 182.35,
                "MinimumPaymentDue": 10,
                "CreditLimit": 360.0,
                "AvailableCredit": 177.65,
                "DaysAccountPastDue": 0,
                "StatementGenerated": true,
                "Transactions": []
            }
        ]
    }
}


```

{% endtab %}

{% tab title="Response with Transactions" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 10,
        "TotalCount": 2,
        "Items": [
            {
            "Id": "a3986b76-c899-4be1-8999-29d4b3adab34",
            "UserCardId": "952ea6a5-5eee-4291-9d13-422df35fcd94",
            "PeriodStart": "05-01-2026",
            "PeriodEnd": "05-31-2026",
            "StatementDate": "05-01-2026",
            "PaymentDueDate": "2026-05-25T04:00:00Z",
            "CreatedAt": "2026-06-02T23:22:48.893546Z",
            "Last4Digits": "2945",
            "CardType": "SecuredCreditCard",
            "PreviousBalance": 146.65,
            "Payments": 0.0,
            "OtherCredits": 0.0,
            "Purchases": 0.0,
            "CashAdvance": 0.0,
            "InterestCharged": 0.7,
            "FeeCharged": 35.0,
            "NewBalance": 182.35,
            "MinimumPaymentDue": 10,
            "CreditLimit": 360.0,
            "AvailableCredit": 177.65,
            "DaysAccountPastDue": 0,
            "StatementGenerated": true,
            "Transactions": [
                    {
                        "Id": "08994cab-b3d9-466b-be58-4d3227997d37",
                        "StatementId": "a3986b76-c899-4be1-8999-29d4b3adab34",
                        "Type": "Fee",
                        "Description": "Fee - Card Activation",
                        "TransactionDate": "2026-05-28T04:00:00Z",
                        "TransactionPostedDate": "2026-05-28T04:00:00Z",
                        "Amount": 0.01,
                        "CreatedAt": "2026-06-02T23:22:48.892975Z",
                        "TransactionId": "123456",
                        "TransactionType": "40",
                        "MessageType": "0200"
                    }
                ]
            }
        ]
    }
}


```

{% endtab %}
{% endtabs %}

#### **Request Parameters**

<table><thead><tr><th width="205.25390625">Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>UserId</td><td>Guid</td><td>Yes</td><td>User Id</td></tr><tr><td>UserCardId</td><td>Guid</td><td>No</td><td>Id of the specific card type issued (e.g. Secured Credit Card User Id)</td></tr><tr><td>AddTransactionDetails</td><td>Bool</td><td>No</td><td><p>Whether to include transactions in each statement.</p><p>Set to true or false.</p><p>Default: false</p></td></tr><tr><td>DateFrom</td><td>Datetime</td><td>No</td><td>Start date for query</td></tr><tr><td>DateTo</td><td>Datetime</td><td>No</td><td>End date for query</td></tr><tr><td>Pagination</td><td></td><td>No</td><td></td></tr><tr><td>PageNumber</td><td>Number</td><td>No</td><td>The respective page, starting at 1</td></tr><tr><td>ItemsPerPage</td><td>Number</td><td>No</td><td>The amount of items per page between 0 and 100</td></tr></tbody></table>

#### **Response**

| Parameter             | Type     | Description                                                                                          |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| CurrentPage           | Number   | Current page of results                                                                              |
| PageSize              | Number   | Number of items in page requested                                                                    |
| TotalCount            | Number   | Total number of items queryable                                                                      |
| Items                 |          |                                                                                                      |
| Id                    | Guid     | Statement Id                                                                                         |
| UserCardId            | Guid     | Id of the Secured Credit Card associated with the statement                                          |
| PeriodStart           | DateOnly | Start date of the statement period                                                                   |
| PeriodEnd             | DateOnly | End date of the statement period                                                                     |
| StatementDate         | DateOnly | Date the statement was generated                                                                     |
| PaymentDueDate        | Datetime | Payment due date                                                                                     |
| CreatedAt             | Datetime | Record creation timestamp                                                                            |
| Last4Digits           | String   | Last 4 digits of the card number                                                                     |
| CardType              | String   | Card type (e.g. SecuredCredit)                                                                       |
| PreviousBalance       | Decimal  | Balance carried over from prior statement                                                            |
| Payments              | Decimal  | Total payments received                                                                              |
| OtherCredits          | Decimal  | Other credits applied                                                                                |
| Purchases             | Decimal  | Total purchases made                                                                                 |
| CashAdvance           | Decimal  | Total cash advances                                                                                  |
| InterestCharged       | Decimal  | Interest charged this period                                                                         |
| FeeCharged            | Decimal  | Fees charged this period                                                                             |
| NewBalance            | Decimal  | Closing balance of the statement                                                                     |
| MinimumPaymentDue     | Decimal  | Minimum payment required                                                                             |
| CreditLimit           | Decimal  | Credit limit of the card                                                                             |
| AvailableCredit       | Decimal  | Available credit remaining                                                                           |
| DaysAccountPastDue    | Int      | Number of days the account is past due                                                               |
| StatementGenerated    | Bool     | Whether the statement has been generated                                                             |
| Transactions          | List     | Transactions included if AddTransactionDetails is true                                               |
| Transactions          |          |                                                                                                      |
| Id                    | Guid     | Internal Id assigned to the transaction                                                              |
| StatementId           | Guid     | Corresponding StatementId of the transaction                                                         |
| Last4Digits           | Number   | Last 4 digits of the card                                                                            |
| CardStatus            | String   | Status of the card at the time of the transaction                                                    |
| Type                  | String   | Transaction type                                                                                     |
| Description           | String   | Description of the transaction                                                                       |
| TransactionDate       | Datetime | Date and time the transaction occured                                                                |
| TransactionPostedDate | Datetime | Date and time the transaction was posted                                                             |
| Amount                | Decimal  | Transaction amount. Negative amount is a debit.                                                      |
| CreatedAt             | Datetime | Record creation timestamp                                                                            |
| TransactionId         | String   | Trace audit number of the statement transaction, used to reconcile statement lines with your records |
| TransactionType       | String   | Card processor transaction type code (e.g. `LF`, `FC`, `40`)                                         |
| MessageType           | String   | ISO 8583 message type (e.g. `0200`, `0720`, `0722`)                                                  |

## Get Statement Transactions

Use this endpoint to retrieve a paginated list of card statement transactions for a User.

Returns a `404` if a `StatementId` is provided but not found for the user.

`Method: POST`

`Endpoint: {{env}}/api/card/statements-transactions/filter`

{% tabs %}
{% tab title="Request" %}

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9bd31212b-...b926dc141397",
    "StatementId": "a1b2c3d4-...e5f6",
    "Date": "2025-05-01T00:00:00Z",
    "DateOperator": "IsAfter",
    "Pagination": {
        "PageNumber": 1,
        "ItemsPerPage": 10
    }
}

```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": {
        "CurrentPage": 1,
        "PageSize": 10,
        "TotalCount": 67,
        "Items": [
            {
                "Id": "41747dff-93b8-4d09-a014-c36e13bf834b",
                "StatementId": "a07e344c-775c-45f8-8b20-2511c0c271ba",
                "Type": "Purchase",
                "Description": "Maintenance fee charged",
                "TransactionDate": "2026-05-07T04:00:00Z",
                "TransactionPostedDate": "2026-05-07T04:00:00Z",
                "Amount": 2,
                "CreatedAt": "2026-05-29T22:08:16.754873Z",
                "TransactionId": "123456",
                "TransactionType": "40",
                "MessageType": "0200"
            },
            {
                "Id": "9127fe5a-71b1-44b4-b70f-38e47baa90d7",
                "StatementId": "a07e344c-775c-45f8-8b20-2511c0c271ba",
                "Type": "Credit",
                "Description": "Payment",
                "TransactionDate": "2026-05-07T04:00:00Z",
                "TransactionPostedDate": "2026-05-07T04:00:00Z",
                "Amount": -22.0,
                "CreatedAt": "2026-05-29T22:08:16.754875Z",
                "TransactionId": "123457",
                "TransactionType": "40",
                "MessageType": "0200"
            }
        ]
    }
}


```

{% endtab %}
{% endtabs %}

#### **Request Parameters**

| Parameter    | Type         | Mandatory | Description                                                     |
| ------------ | ------------ | --------- | --------------------------------------------------------------- |
| UserId       | Guid         | Yes       | User Id                                                         |
| UserCardId   | Guid         | Yes       | Filter by specific card. Id of the specific card type issued    |
| StatementId  | Guid         | No        | Filter by specific statement. Returns 404 if not found for user |
| Date         | DateTime     | No        | Base date for query (used with DateOperator)                    |
| DateOperator | DateOperator | No        | Date filter type for query                                      |
| DateFrom     | DateTime     | No        | Start date for range query                                      |
| DateTo       | DateTime     | No        | End date for range query                                        |
| Pagination   |              | No        |                                                                 |
| PageNumber   | Number       | No        | The respective page, starting at 1                              |
| ItemsPerPage | Number       | No        | The amount of items per page between 0 and 100                  |

#### **Response**

| Parameter             | Type     | Description                                                                                          |
| --------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| CurrentPage           | Number   | Current page of results                                                                              |
| PageSize              | Number   | Number of items in page requested                                                                    |
| TotalCount            | Number   | Total number of items queryable                                                                      |
| Items                 |          |                                                                                                      |
| Id                    | Guid     | Transaction Id                                                                                       |
| Last4Digits           | String   | Last 4 digits of the card number                                                                     |
| UserCardId            | Guid     | Id of the card associated with the transaction                                                       |
| CardStatus            | String   | Status of the card at time of transaction                                                            |
| Type                  | String   | Transaction type                                                                                     |
| Description           | String   | Description of the transaction                                                                       |
| TransactionDate       | DateTime | Date and time the transaction occurred                                                               |
| TransactionPostedDate | DateTime | Date and time the transaction was posted                                                             |
| Amount                | Decimal  | Transaction amount (negative = debit)                                                                |
| CreatedAt             | DateTime | Record creation timestamp                                                                            |
| TransactionId         | String   | Trace audit number of the statement transaction, used to reconcile statement lines with your records |
| TransactionType       | String   | Card processor transaction type code (e.g. `LF`, `FC`, `40`)                                         |
| MessageType           | String   | ISO 8583 message type (e.g. `0200`, `0720`, `0722`)                                                  |

**DateOperator:**

| Type           | Description                              |
| -------------- | ---------------------------------------- |
| IsInTheLast    | Between user creation date and now       |
| ExactlyMatches | Exactly matches CreatedAt                |
| IsBetween      | Is between CreatedAtFrom and CreatedAtTo |
| IsAfter        | Is after CreatedAt                       |
| IsOnOrAfter    | Is on or after CreatedAt                 |
| IsBefore       | Is before CreatedAt                      |
| IsBeforeOrOn   | Is before or on CreatedAt                |

## PIN Management

{% hint style="warning" %}
PIN Management is available for physical card programs only. All PIN values must be encrypted with the Zūm Rails public key. See [Encryption](https://docs.zumrails.com/api-reference/encryption.md).
{% endhint %}

### Get PIN encryption public key

Returns the RSA public key used to encrypt PIN values. Your account must be configured with an encryption key by the Zūm Rails team. Contact support to securely share the key.

`Method: GET`

`Endpoint: {{env}}/api/customer/kms-public-key`

### Set PIN

Use this endpoint to set the PIN on a card for the first time.

`Method: POST`

`Endpoint: {{env}}/api/card/pin/set`

{% tabs %}
{% tab title="Request" %}

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "UserCardId": "9bd31212b-...b926dc141397",
    "EncryptedPin": "<encrypted-pin>"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "statusCode": 200,
    "message": "POST Request successful.",
    "isError": false,
    "result": ""
}
```

{% endtab %}
{% endtabs %}

#### **Input Parameters**

<table><thead><tr><th width="208.625">Parameter</th><th width="140.25">Type</th><th width="108.8828125">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>UserId</td><td>Guid</td><td>Yes</td><td>User Id</td></tr><tr><td>UserCardId</td><td>Guid</td><td>Yes</td><td>Id of the card</td></tr><tr><td>EncryptedPin</td><td>String</td><td>Yes</td><td>4-digit PIN encrypted with the Zūm Rails public key</td></tr></tbody></table>

### Change PIN

Use this endpoint to change the PIN on a card.

`Method: POST`

`Endpoint: {{env}}/api/card/pin/change`

#### **Input Parameters**

| Parameter           | Type   | Mandatory | Description            |
| ------------------- | ------ | --------- | ---------------------- |
| UserId              | Guid   | Yes       | User Id                |
| UserCardId          | Guid   | Yes       | Id of the card         |
| EncryptedCurrentPin | String | Yes       | Current PIN, encrypted |
| EncryptedNewPin     | String | Yes       | New PIN, encrypted     |

### Send PIN OTP

Sends a one-time passcode to the cardholder's email. Required before Reset PIN or Unblock PIN.

`Method: POST`

`Endpoint: {{env}}/api/card/pin/otp/send`

#### **Input Parameters**

| Parameter  | Type   | Mandatory | Description                  |
| ---------- | ------ | --------- | ---------------------------- |
| UserId     | Guid   | Yes       | User Id                      |
| UserCardId | Guid   | Yes       | Id of the card               |
| Purpose    | String | Yes       | `Set`, `Reset`, or `Unblock` |

### Verify PIN OTP

Use this endpoint to verify the one-time passcode received by the cardholder.

`Method: POST`

`Endpoint: {{env}}/api/card/pin/otp/verify`

#### **Input Parameters**

| Parameter  | Type   | Mandatory | Description                     |
| ---------- | ------ | --------- | ------------------------------- |
| UserId     | Guid   | Yes       | User Id                         |
| UserCardId | Guid   | Yes       | Id of the card                  |
| OtpCode    | String | Yes       | Code received by the cardholder |
| Purpose    | String | Yes       | `Set`, `Reset`, or `Unblock`    |

### Reset PIN

Use this endpoint to reset the PIN on a card. Requires a verified `Reset` OTP (valid for 10 minutes).

`Method: POST`

`Endpoint: {{env}}/api/card/pin/reset`

#### **Input Parameters**

| Parameter       | Type   | Mandatory | Description        |
| --------------- | ------ | --------- | ------------------ |
| UserId          | Guid   | Yes       | User Id            |
| UserCardId      | Guid   | Yes       | Id of the card     |
| EncryptedNewPin | String | Yes       | New PIN, encrypted |

### Unblock PIN

Use this endpoint to unblock a card's PIN.

`Method: POST`

`Endpoint: {{env}}/api/card/pin/unblock`

#### **Input Parameters**

| Parameter     | Type    | Mandatory | Description                                                         |
| ------------- | ------- | --------- | ------------------------------------------------------------------- |
| UserId        | Guid    | Yes       | User Id                                                             |
| UserCardId    | Guid    | Yes       | Id of the card                                                      |
| BypassOtpCode | Boolean | No        | Default `false`. When `false`, a verified `Unblock` OTP is required |

### PIN errors

| Message                                                                                                    |
| ---------------------------------------------------------------------------------------------------------- |
| Invalid request: PIN must be encrypted using the public key provided by Zum Rails.                         |
| Invalid request: decrypted PIN must be exactly 4 digits.                                                   |
| PIN management is only available on physical card programs.                                                |
| Card with id {id} has set pin before, please call change pin api.                                          |
| Card with id {id} cannot change its PIN to the same value.                                                 |
| Card with id {id} PIN was changed less than 24 hours ago.                                                  |
| Card with id {id} has its PIN blocked and must be unblocked before its PIN can be set or changed.          |
| Card with id {id} does not have pin blocked.                                                               |
| Card with id {id} has not completed OTP verification for a PIN {purpose}, or the verification has expired. |
| Invalid OTP Code.                                                                                          |

## Get Recipients

Use this endpoint to list the Interac e-Transfer recipients a Prepaid cardholder has saved in the Cardholder Portal.

`Method: POST`

`Endpoint: {{env}}/api/card/recipients/filter`

#### **Input Parameters**

| Parameter       | Type   | Mandatory | Description                                                         |
| --------------- | ------ | --------- | ------------------------------------------------------------------- |
| UserId          | Guid   | Yes       | User Id                                                             |
| RecipientStatus | String | No        | `Deleted` to return removed recipients; otherwise active recipients |

#### **Response**

| Parameter | Type     | Description                    |
| --------- | -------- | ------------------------------ |
| Id        | Guid     | Recipient Id                   |
| FirstName | String   | Recipient first name           |
| LastName  | String   | Recipient last name            |
| Email     | String   | Recipient email                |
| Status    | String   | `Active` or `Deleted`          |
| CreatedAt | DateTime | Date the recipient was added   |
| UpdatedAt | DateTime | Date the recipient was updated |
| DeletedAt | DateTime | Date the recipient was removed |


---

# 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/api-reference/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.
