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:

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": []
}

Activate Card

Activate a card to enable it for transactions. This endpoint can be called at any time but for physical cards is intended to be called after receipt of the physical card. A card can subsequently be deactivated, but must be active to participate in transactions.

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

  • Method: POST

Example JSON Request

{
  "cardsId": 1001
}

Deactivate Card

Deactivate a card that was previously activated. A deactivated card can no longer participate in transactions. Deactivating a card will void pending transactions against it. The card may subsequently be activated.

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

  • Method: POST

Example JSON Request

{
  "cardsId": 1001
}

Get Customer Cards

List cards for all managed customers

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

  • Method: GET

Query Parameters:

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

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

Move Funds to Card

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

  • Method: POST

Example Request Body

{
  "fromCardsId": 1001,
  "toCardsId": 1002,
  "amount": 10
}

More information coming soon..

List Requested Cards

Get a list of cards requested by managed users requiring approval

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

  • Method: GET

Query Parameters:

  • CustomerId: filter requested cards by CustomerId

  • FromDate: filter requested cards by creation date

  • ToDate: filter requested cards by creation date

  • PageNumber: list page number (default = 1)

  • PageSize: list page size (default = 10)

Get Compliance Fields

Get enumeration values that are required under some card programs to create a card. If the returned arrays are empty, then the field is not required for the customer's card program.

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

  • Method: GET

Query Parameters:

  • None

Response Body Parameters:

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

  • details (Object):

    • customerSubtypes (Array of Objects): Description of the employment situation of the card holder. Otherwise defined by Customer Subtypes.

      • Label (string) The descriptive name of the value

      • Value (string) The value that represents this option

    • businessActivities(Array of Objects): The primary trade or other activity of the card holder's employer, or otherwise the entity requesting the card. Otherwise defined by Business Activity Types.

      • Label (string) The descriptive name of the value

      • Value (string) The value that represents this option

    • occupations(Array of Objects): The card holder's occupation. Otherwise defined by Occupation Types.

      • Label (string) The descriptive name of the value

      • Value (string) The value that represents this option

    • sourcesOfFunds (Array of Objects): The source of funds that will be used to top up the card. Otherwise defined by Source Of Funds Types.

      • Label (string) The descriptive name of the value

      • Value (string) The value that represents this option

Success Response Example:

{
  "id": 1000,
  "details": {
    "customerSubtypes" : [
      {
        "label" : "Business owner",
        "value" : "1"
      },
      {
        "label" : "Employee with fixed salary",
        "value" : "6"
      },
      {
        "label" : "Unemployed",
        "value" : "10"
      }
    ],
    "businessActivities" : [
      {
        "label" : "Custom computer programming services",
        "value" : "1119"
      },
      {
        "label" : "Miscellaneous financial investment activities",
        "value" : "1422"
      },
      {
        "label" : "Others",
        "value" : "878"
      }
    ],
    "occupations" : [
      {
        "label" : "Accountants and auditors",
        "value" : "70"
      },
      {
        "label" : "Software developers",
        "value" : "95"
      },
      {
        "label" : "Others",
        "value" : "11"
      }
    ],
    "sourcesOfFunds " : [
      {
        "label" : "Business earnings",
        "value" : "70"
      },
      {
        "label" : "Employment salaried",
        "value" : "1950"
      },
      {
        "label" : "Others",
        "value" : "1946"
      }
    ] 
  }
    
}
PreviousBusiness OnboardingNextCrypto Exchanges

Last updated