Customer Portal

Cards

Overview

The Cards module in the customer API provides essential functionalities related to the financial cards of the customers. It offers two primary endpoints that facilitate the retrieval of card balances and transaction histories.

Here is an overview of the endpoints available within the Cards module:

1. Create Customer Card: Enables users to create a new card for a customer. This is usually the first step in providing a customer with transactional capabilities.

2. Get Customer Cards: Retrieves a list of all cards issued under the customer's account, offering a consolidated view of the card inventory.

3. Get Card Balances - This GET endpoint allows users to retrieve a list of all the cards available on the customer's account, providing details such as card ID, currency, total balance, available balance, and the status of any pending transactions. Users can also obtain information on whether a card is currently enabled or disabled.

4. Get Card Transactions - A GET request where users can access a detailed list of transactions for a specific card over a defined time period. This endpoint supplies information like transaction ID, card ID, amount, currency, description, transaction date and time, as well as the pending status of the transaction. It is crucial for customers who need to track their spending or review their transaction history for accounting or budgeting purposes.

Together, these endpoints empower customers with the ability to track their financial card activities closely, ensuring they stay informed about their balances and transactions at all times. The module's focus is on giving users full transparency into their financial status, thereby enabling better money management and financial planning.

Create Customer Card

The Create Card endpoint is used to issue a new card to a customer's account. The user must specify the customer's account ID, the currency for the card, and various compliance-related fields such as customer subtype, business activity, occupation, and source of funds. With this information, a new card can be created and linked to the customer's account. Once the card is issued, it's initially suppressed (deactivated) until it's activated by the customer or manager.

  • Endpoint: /api/v1/customer/cards/create

  • Method: POST

  • Request Format: application/json

Request Body Parameters:

  • customersID (Integer): The customer's ID for which the new card will be issued—required.

  • currency (String): The currency to use on the card, e.g., "USD"—required.

  • cardReferenceId (String, Optional): Reference Id of the card that is to be assigned to a customer, required for batch card distribution mode.

  • customerSubtype (String): Defined under Customer Subtypes in Enumerations Codes and Definitions—required.

  • businessActivityType (String): Defined under Business Activity Types in Enumerations Codes and Definitions—required.

  • occupationType (String): Defined under Occupation Types in Enumerations Codes and Definitions—required.

  • sourceOfFundsType (String): Defined under Source of Funds Types in terminology—required.

Request Example:

{
  "customersId": 11079,
  "currency": "USD",
  "cardReferenceId": "123456",
  "customerSubtype": "0",
  "businessActivityType": "800",
  "occupationType": "50",
  "sourceOfFundsType": "1900"
}

Response Body Parameters:

  • id (Integer): Not used.

  • details (Object):

    • customersId (Integer): The ID of the customer card owner.

    • customersReference (String): The reference given when creating the customer.

    • card (Object):

      • id (Integer): The ID of the new customer card.

      • currency (String): The currency of the customer card.

      • cardNumber (String): Masked card number.

      • totalBalance (Decimal): The total balance on the card.

      • availableBalance (Decimal): The available balance on the card.

      • pendingBalance (Decimal): The sum of all pending transaction amounts.

      • bSuppressed (Boolean): True if the card is deactivated.

  • status (String): The status of the API call.

  • errors (Array): Any error messages.

Success Response Example:

{
  "id": 0,
  "details": {
    "customersId": 11057,
    "customersReference": "34233rqcpomrkvqd",
    "card": {
      "id": 1005,
      "currency": "USD",
      "cardNumber": "XXXX XXXX XXXX 6451",
      "totalBalance": 0.00,
      "availableBalance": 0.00,
      "pendingBalance": 0.00,
      "bSuppressed": true
    }
  },
  "status": "1",
  "errors": []
}

Get Customer Cards

Retrieves a list of card details for a given customer.

The "Get Customer Cards" feature is a way for users to view all the cards and card details associated with their customers. This list provides essential information such as the card's balance, pending transactions, and whether the card is currently active or disabled. This is particularly helpful for keeping an overview of all customer activity and ensuring that their cards are properly managed.

  • Endpoint: /api/v1/customer/cards/byuser

  • Method: GET

Query Parameters:

  • customersId(Integer, Optional): The customer's ID for which the card details will be retrieved.

Request Example:

To request the list of managed cards using pagination:

GET /api/v1/customer/cards/byuser?customersId=11057

Response Body Parameters:

  • id (Integer): Not used.

  • details (Array of Objects):

    • customersId (Integer): ID of the customer.

    • customersReference (String): The customer reference used when creating the customer.

    • cards (Array of Objects):

      • id (Integer): ID of the customer's card.

      • currency (String): Currency of the card.

      • totalBalance (Decimal): Total balance on the card.

      • availableBalance (Decimal): The available balance on the card.

      • pendingBalance (Decimal): Sum of all pending transaction amounts.

      • bSuppressed (Boolean): True if use of this card is disabled.

Success Response Example:

{
  "id": 0,
  "details": [
    {
      "customersId": 0,
      "customersReference": "string",
      "cards": [
        {
          "id": 0,
          "currency": "usd",
          "totalBalance": 0,
          "availableBalance": 0,
          "pendingBalance": 0,
          "bSuppressed": true
        }
      ]
    }
  ],
  "pageSize": 10,
  "pageNumber": 1,
  "status": "1",
  "errors": []
}

Get Card Balances

Allows customers to retrieve a summary of their card balances, which can be useful for managing and topping up cards associated with the customer’s account. This feature helps customers see what funds they have available, what is pending, and if any cards are not in use. It's beneficial for keeping track of finances and planning for top-ups or other card management actions.

  • Endpoint: /api/v1/customer/cards/balances

  • Method: GET

Query Parameters:

  • pageNumber (Integer): Specifies the page number of the results.

  • pageSize (Integer): Specifies the number of results per page.

Request Example:

GET /api/v1/customer/cards/balances?pageNumber=1&pageSize=10

Response Body Parameters:

  • id (Integer): A placeholder ID not actively used in the response.

  • details (Array):

    • id (Integer): The unique identifier for the card.

    • cardNumber (String): The masked number of the card.

    • currency (String): The currency code for the balance on the card.

    • totalBalance (Decimal): The total balance amount on the card.

    • availableBalance (Decimal): The available balance amount for use.

    • pendingBalance (Decimal): The total amount of pending transactions that are yet to be finalized.

    • bSuppressed (Boolean): Indicates whether the card is currently active or suppressed (deactivated).

Success Response Example:

{
  "id": 0,
  "details": [
    {
      "id": 1016,
      "cardNumber": "XXXX XXXX XXXX 9467",
      "currency": "USD",
      "totalBalance": 91.57,
      "availableBalance": 91.57,
      "pendingBalance": 0.00,
      "bSuppressed": false
    }
  ],
  "pageSize": 10,
  "pageNumber": 1,
  "status": "1",
  "errors": []
}

Get Card Transactions

The Get Transactions function is a convenient tool for customers to retrieve a detailed list of transactions associated with a particular manager card. They can see a history of when and how much was spent or deposited, including pending transactions that haven't yet cleared. This helps customers track their spending and manage their finances more effectively.

  • Endpoint: /api/v1/customer/cards/transactions

  • Method: GET

Query Parameters:

  • cardsId (Integer, Optional): The ID of the manager card to filter transactions by.

  • fromDate (ISO 8601 UTC date, Optional): The start date for transaction filtering.

  • toDate (ISO 8601 UTC date, Optional): The end date for transaction filtering.

  • pageNumber (Integer, Optional): The page of results to return.

  • pageSize (Integer, Optional): The maximum number of results to return per page.

Request Example:

To request transactions for a specific card between two dates:

GET /api/v1/customer/cards/transactions?cardsId=1000&fromDate=2022-01-01&toDate=2022-01-31&pageNumber=1&pageSize=10

Response Body Parameters:

  • id (Integer): A placeholder ID not actively used in the response.

  • details (Array of Objects): Details of each transaction.

    • id (Integer): Transaction ID.

    • cardsId (Integer): Associated manager card ID.

    • amount (Decimal): Transaction amount.

    • currency (String): Transaction currency.

    • description (String): Transaction description.

    • dateTime (ISO 8601 date): The date and time of the transaction.

    • bPending (Boolean): Indicates whether the transaction is still pending.

  • pageSize (Integer): The page size of the result set.

  • pageNumber (Integer): The current page number of the result set.

  • numberOfPages (Integer): The total number of available pages.

  • status (String): Status of the API call.

  • errors (Array): Any error messages.

Success Response Example:

{
  "id": 1000,
  "details": [
    {
      "id": 1000,
      "cardsId": 1000,
      "amount": 3.00,
      "currency": "USD",
      "description": "Transaction description",
      "dateTime": "2022-01-01T01:02:03.000+00:00",
      "bPending": false
    },
    {
      "id": 1001,
      "cardsId": 1000,
      "amount": 100.00,
      "currency": "USD",
      "description": "Transaction description",
      "dateTime": "2022-01-01T01:02:03.000+00:00",
      "bPending": false
    }
  ],
  "pageSize": 2,
  "pageNumber": 1,
  "numberOfPages": 5,
  "status": "1",
  "errors": []
}
PreviousBusinessNextExchanges

Last updated