# Cards

## Activate Card

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

`Method: PATCH`

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

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

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "CardProgramId": "Customer_Card_Program"
}
```

{% endtab %}

{% tab title="Response" %}

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

{% endtab %}
{% endtabs %}

#### **Input Parameters**

| Parameter     | Type   | Mandatory | Description                      |
| ------------- | ------ | --------- | -------------------------------- |
| UserId        | Guid   | Yes       | User Id                          |
| CardProgramId | String | Yes       | Card Program Id (Case Sensitive) |

#### Response

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

## Change Card Program

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

`Method: PATCH`

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

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

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "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**

| Parameter    | Type   | Mandatory | Description                          |
| ------------ | ------ | --------- | ------------------------------------ |
| UserId       | Guid   | Yes       | User Id                              |
| NewProgramId | String | Yes       | New Card Program Id (Case Sensitive) |

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

| Parameter  | Type   | Mandatory | Description     |
| ---------- | ------ | --------- | --------------- |
| UserId     | Guid   | Yes       | User Id         |
| CardStatus | String | Yes       | New Card Status |

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

`Method: POST`

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

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

```json
{
    "UserId": "8ebd932b-...b92633e14297",
    "cardReferenceId": "110195650252149"
}
```

{% 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           |
| cardReferenceId | String | Yes      | Card Reference 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 |