Cards

PreviousBusiness Onboarding NextCrypto Exchanges

Last updated 9 months ago

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. : Enables users to create a new card for a customer. This is usually the first step in providing a customer with transactional capabilities.

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

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

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):
- - Label (string) The descriptive name of the value
  - Value (string) The value that represents this option
- - Label (string) The descriptive name of the value
  - Value (string) The value that represents this option
- - Label (string) The descriptive name of the value
  - Value (string) The value that represents this option
- - 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 Onboarding NextCrypto Exchanges

Last updated 9 months ago

POST /api/v1/customer/cards/create HTTP/1.1 Host: public-api.ibanera.com Authorization: YOUR_API_KEY otp: text Content-Type: application/json-patch+json Accept: */* Content-Length: 152 { "customersId": 1, "currency": "text", "cardReferenceId": "text", "customerSubtype": 1, "businessActivityType": 878, "occupationType": 11, "sourceOfFundsType": 1936 }

{ "status": "text", "errors": [ { "fieldName": "text", "messageCode": "text" } ], "id": 1, "details": { "status": "text", "errors": [ { "fieldName": "text", "messageCode": "text" } ], "id": 1, "details": { "customersId": 1, "customersReference": "text", "card": { "id": 1, "currency": "text", "cardNumber": "text", "totalBalance": 1, "availableBalance": 1, "pendingBalance": 1, "bSuppressed": true }, "notificationData": { "customerAssetAccountsId": 1, "topUpCardsId": 1, "siteUsersDetails": [ { "siteUsersId": 1, "customerAssetAccounts": [ { "customerAssetAccountsId": 1, "assetClass": 0, "treatAsAccount": true, "assetAccountType": 0, "elementType": 0, "customerAssetAccountsTransactionsId": 1, "amount": 1, "bPending": true, "bReserved": true, "bFrozen": true, "bVoid": true, "guid": "text", "topUpCardsId": 1, "moneyFlowDirection": 0, "bNewTransaction": true, "bAmountUpdated": true, "bPendingUpdated": true, "bPriceUpdated": true, "bFrozenUpdated": true, "bFeeUpdated": true, "bNewAssetAccount": true, "bDeposit": true, "bNewlyVoided": true, "bAccessElementsUpdated": true, "bBuyExchangeCompleted": true, "bSellExchangeCompleted": true, "assetCode": "text", "accountName": "text", "bExchangeCompleted": true, "exchangePrice": 1, "exchangeAmount": 1, "exchangeAssetCode": "text", "exchangePairedAssetCode": "text", "exchangeAssetClass": 0, "exchangePairedAssetClass": 0 } ], "notifications": [ "text" ], "firstName": "text", "emailAddress": "text", "phoneNumber": "text", "cultureInfo": "text", "domain": "text" } ] }, "setNotificationData": { "customerAssetAccountsId": 1, "topUpCardsId": 1, "siteUsersDetails": [ { "siteUsersId": 1, "customerAssetAccounts": [ { "customerAssetAccountsId": 1, "assetClass": 0, "treatAsAccount": true, "assetAccountType": 0, "elementType": 0, "customerAssetAccountsTransactionsId": 1, "amount": 1, "bPending": true, "bReserved": true, "bFrozen": true, "bVoid": true, "guid": "text", "topUpCardsId": 1, "moneyFlowDirection": 0, "bNewTransaction": true, "bAmountUpdated": true, "bPendingUpdated": true, "bPriceUpdated": true, "bFrozenUpdated": true, "bFeeUpdated": true, "bNewAssetAccount": true, "bDeposit": true, "bNewlyVoided": true, "bAccessElementsUpdated": true, "bBuyExchangeCompleted": true, "bSellExchangeCompleted": true, "assetCode": "text", "accountName": "text", "bExchangeCompleted": true, "exchangePrice": 1, "exchangeAmount": 1, "exchangeAssetCode": "text", "exchangePairedAssetCode": "text", "exchangeAssetClass": 0, "exchangePairedAssetClass": 0 } ], "notifications": [ "text" ], "firstName": "text", "emailAddress": "text", "phoneNumber": "text", "cultureInfo": "text", "domain": "text" } ] }, "newCardCallbackDbDetails": [ { "customerApiPrincipalUsersId": 1, "webhookCallbackUrl": "text", "hashSecret": "text" } ] } } }

{ "status": "text", "errors": [ { "errorType": "text", "fieldName": "text", "messageCode": "text" } ], "id": 1, "details": { "customersId": 1, "customerReference": "text", "card": { "id": 1, "cardNumber": "text", "currency": "text", "totalBalance": 1, "availableBalance": 1, "pendingBalance": 1, "bSuppressed": true }, "notificationDetails": { "siteUsersDetails": [ { "siteUsersId": 1, "customerAssetAccounts": [ { "customerAssetAccountsId": 1, "assetClass": 0, "treatAsAccount": true, "assetAccountType": 0, "elementType": 0, "customerAssetAccountsTransactionsId": 1, "amount": 1, "bPending": true, "bReserved": true, "bFrozen": true, "bVoid": true, "guid": "text", "topUpCardsId": 1, "moneyFlowDirection": 0, "bNewTransaction": true, "bAmountUpdated": true, "bPendingUpdated": true, "bPriceUpdated": true, "bFrozenUpdated": true, "bFeeUpdated": true, "bNewAssetAccount": true, "bDeposit": true, "bNewlyVoided": true, "bAccessElementsUpdated": true, "bBuyExchangeCompleted": true, "bSellExchangeCompleted": true, "assetCode": "text", "accountName": "text", "bExchangeCompleted": true, "exchangePrice": 1, "exchangeAmount": 1, "exchangeAssetCode": "text", "exchangePairedAssetCode": "text", "exchangeAssetClass": 0, "exchangePairedAssetClass": 0 } ], "notifications": [ "text" ], "firstName": "text", "emailAddress": "text", "phoneNumber": "text", "cultureInfo": "text", "domain": "text" } ] }, "setNotificationDetails": { "siteUsersDetails": [ { "siteUsersId": 1, "customerAssetAccounts": [ { "customerAssetAccountsId": 1, "assetClass": 0, "treatAsAccount": true, "assetAccountType": 0, "elementType": 0, "customerAssetAccountsTransactionsId": 1, "amount": 1, "bPending": true, "bReserved": true, "bFrozen": true, "bVoid": true, "guid": "text", "topUpCardsId": 1, "moneyFlowDirection": 0, "bNewTransaction": true, "bAmountUpdated": true, "bPendingUpdated": true, "bPriceUpdated": true, "bFrozenUpdated": true, "bFeeUpdated": true, "bNewAssetAccount": true, "bDeposit": true, "bNewlyVoided": true, "bAccessElementsUpdated": true, "bBuyExchangeCompleted": true, "bSellExchangeCompleted": true, "assetCode": "text", "accountName": "text", "bExchangeCompleted": true, "exchangePrice": 1, "exchangeAmount": 1, "exchangeAssetCode": "text", "exchangePairedAssetCode": "text", "exchangeAssetClass": 0, "exchangePairedAssetClass": 0 } ], "notifications": [ "text" ], "firstName": "text", "emailAddress": "text", "phoneNumber": "text", "cultureInfo": "text", "domain": "text" } ] } } }

Overview

Create Customer Card

Get Customer Cards

Get Card Balances

Get Card Transactions

Activate Card

Example JSON Request

Deactivate Card

Example JSON Request

Get Customer Cards

Move Funds to Card

Example Request Body

List Requested Cards

Query Parameters:

Get Compliance Fields

Overview

Create Customer Card

Get Customer Cards

Get Card Balances

Get Card Transactions

Activate Card

Example JSON Request

Deactivate Card

Example JSON Request

Get Customer Cards

Move Funds to Card

Example Request Body

List Requested Cards

Query Parameters:

Get Compliance Fields

Get cards balances

List of manager card transactions

Get single customer

Get all customers

List of requested cards

Get lists of available compliance fields and their associated id codes

Create a top up card for customer

Activate card

Deactivate card

Move funds to and from managee's card