# Cards

## Activate Card

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

`Method: POST`

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

{% 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 Balance Inquiry

Use this endpoint to get the balance on the current card attached to the user.

`Method: GET`

`Endpoint: {{env}}/api/card/balance-inquiry/{{userId}}`

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

```json
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": {
        "ResponseDesc": "Operation is successful.",
        "AvailableBalance": 100,
        "LedgerBalance": 0.0
    }
}
```

{% endtab %}
{% endtabs %}

#### Response

| Parameter        | Type    | Description                 |
| ---------------- | ------- | --------------------------- |
| ResponseDesc     | String  | Response description        |
| AvailableBalance | Decimal | Current balance of the card |
| LedgerBalance    | Decimal | Ledger balance of the card  |

## Get Cards

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

`Method: GET`

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

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

```json
{
    "statusCode": 200,
    "message": "GET Request successful.",
    "isError": false,
    "result": {
        "ResponseDesc": "Operation is successful.",
        "AvailableBalance": 0.0,
        "LastDepositAmount": 0.0,
        "LedgerBalance": 0.0,
        "Cards": [
            {
                "CardNumber": "************2208",
                "IsRegistered": "N",
                "CardReferenceId": "110195650227752",
                "CardProgramId": "Zumrail_test_prog",
                "Status": "Activated",
                "CustomerId": "110000001956502277"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

**Input Parameters**

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

**Response**

| Parameter         | Type       | Description                                 |
| ----------------- | ---------- | ------------------------------------------- |
| ResponseDesc      | String     | Response description                        |
| AvailableBalance  | Decimal    | Current balance of the card                 |
| LastDepositAmount | Decimal    | Amount of last deposit                      |
| LedgerBalance     | Decimal    | Ledger balance of the card                  |
| **Cards**         |            |                                             |
| CardNumber        | String     | Card number                                 |
| IsRegistered      | Char (Y/N) | Card Registration Status                    |
| CardReferenceId   | String     | Card Reference Id                           |
| CardProgramId     | String     | Card Program Id                             |
| Status            | String     | Card Status                                 |
| CustomerId        | String     | Unique card Id assigned to the card profile |

## 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</td></tr></tbody></table>

#### **Response**&#x20;

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

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 |

## 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`

{% 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) |

#### **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           |

## 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:**&#x20;

| 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:**&#x20;

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

**CardTransactionType:**&#x20;

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


---

# Agent Instructions: Querying This Documentation

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

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

```
GET https://docs.zumrails.com/api-reference/cards.md?ask=<question>
```

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

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