Accounts

Overview

The Accounts module of the Customer API is a crucial component designed to provide a comprehensive view of a customer's financial activities within the system. This module features three primary API endpoints, each essential for a different aspect of account information retrieval:

  1. Create Asset Account: Allows users to set up new asset accounts for customers, defining the account's name and currency. This is often the first step in customer account management, necessary before any transactions or account customizations can take place. By default, a customer will not have an account for a most currencies until an asset account is created, or if they do an exchange into that currency.

  2. Get Asset Account by ID: By specifying an account ID, users can obtain detailed information about a particular customer account. This functionality allows users to quickly access specific account details as needed.

  3. Get Manager Account Balances - This endpoint allows customers to quickly obtain real-time information about the current state of their accounts, including the available balance and any pending transactions that might affect this balance.

  4. List Transactions - A historical record is vital for customers to track their spendings, earnings, and all other transaction activities. The 'List Transactions' endpoint serves this need by enabling customers to retrieve a list of all their transactions over a specified period. This function helps them review their financial movements comprehensively.

  5. Get Transaction Details - For a deeper dive into any particular transaction, this endpoint is critical. Customers can use it to fetch detailed information about a single transaction, allowing for an in-depth understanding of specific financial events, such as the parties involved, the transaction amount, date, status, and any associated fees.

  6. Withdraw Crypto from Customer Account to External Wallet - This operation allows users to initiate withdrawals from a customer's cryptocurrency account to an external wallet, effectively moving assets out of the customer's account.

  7. Get Deposit Address for a Crypto Asset Account - Enables users to retrieve the deposit address of a cryptocurrency wallet associated with a customer's asset account. By retrieving a deposit address, users can make an external deposit and see the transaction reflected in their account once it's been confirmed.


Create Asset Account

This API endpoint is used to create a new account for a customer. It requires the ID of the customer, the desired name for the account, and the account asset (currency).

When someone wants to create an account for a customer, they use a specific pathway on our system to set it up. They need to provide who it's for (the customer's ID), what they want to call it (name of the account), and what kind of currency it will use (like USD). Once they send this info, our system creates the account and sends back details like the account number and balances. It's like opening a bank account for someone else, making sure it's labeled and set up with the right details. A managed customer will have an account created for each account held by the manager.

  • Endpoint: /api/v2/customer/accounts/create

  • Method: POST

Request Parameters:

  • CustomersId (Integer): The ID of the customer.

  • Name (String): The name of the account.

  • Asset (String): The asset (currency) of the account, currently limited to USD and supported cryptocurrencies.

Request Example:

{
  "CustomersId": 1037,
  "Name": "Fiat account",
  "Asset": "USD"
}

Response Parameters:

  • id (Integer): This field is not used in the response.

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

  • details.customersReference (String): User-set customer reference.

  • details.accounts (Object Array): Contains details of the created accounts.

  • details.accounts.id (Integer): The ID of the newly created account.

  • details.accounts.name (String): The name of the account.

  • details.accounts.routingNumber (String): The routing number of the account.

  • details.accounts.accountNumber (String): The account number.

  • details.accounts.asset (String): The asset (currency) of the account.

  • details.accounts.totalBalance (Decimal): The total balance of the account.

  • details.accounts.availableBalance (Decimal): The available balance of the account.

  • details.accounts.pendingBalance (Decimal): The pending balance of the account.

  • details.accounts.bSuppressed (Bool): Indicates whether the account is suppressed.

Success Response Example:

{
    "id": 0,
    "details": {
        "customersId": 1728,
        "customersReference": "CST1728",
        "accounts": [
            {
                "id": 3770,
                "name": "Fiat account",
                "routingNumber": "999999999",
                "accountNumber": "123456789",
                "swiftCode": null,
                "reference": "REF3770",
                "asset": "USD",
                "totalBalance": 0.0,
                "availableBalance": 0.0,
                "pendingBalance": 0.0,
                "bSuppressed": false
            }
        ]
    },
    "status": "1",
    "errors": []
}

Possible Error Messages

Error Message CodeDescription

Required

Named field is missing or zero

Invalid

Value given for named field is invalid

Documents_Not_Verified

Cannot perform this action for this customer due to the KYC state


Get Asset Account by ID

This API endpoint retrieves the details of a single account by its unique identifier (ID). This gives you the ability to look up a specific account's details using its unique number. It shows you everything you need to know about this account, including what type of currency it has and its current balance.

  • Endpoint: /api/v1/customer/accounts/account

  • Method: GET

  • Query Parameter:

    • Id (Integer): The unique Account ID.

Response Body Parameters and Types:

  • id (Integer): A reference ID for the operation; typically the requested Account ID.

  • details (Object): Contains the detailed information of the account.

    • id (Integer): The account’s unique ID.

    • customersId (Integer): The customer’s ID related to this account.

    • name (String): The name of the account.

    • routingNumber (String): The routing number associated with the account.

    • accountNumber (String): The account number.

    • asset (String): The account's currency code.

    • totalBalance (Decimal): The total balance available in the account.

    • availableBalance (Decimal): The balance readily available for transactions.

    • pendingBalance (Decimal): The balance currently in processing (not yet cleared).

    • bSuppressed (Boolean): Indicates whether the account is suppressed or active.

    • dateAdded (String): The date and time when the account was added.

  • status (String): The status of the request.

  • errors (Array): Any error messages, if present.

Success Response Example:

{
  "id": 1025,
  "details": {
    "id": 1055,
    "customersId": 1004,
    "name": "Account Name",
    "routingNumber": "021214891",
    "accountNumber": "357901009807",
    "asset": "USD",
    "totalBalance": 100.0,
    "availableBalance": 0.0,
    "pendingBalance": 100.0,
    "bSuppressed": false,
    "dateAdded": "2022-07-07T16:33:08.413+00:00"
  },
  "pageSize": 10,
  "pageNumber": 1,
  "numberOfPages": 1,
  "status": "1",
  "errors": []
}

The response returns an object containing detailed information about the customer's account, including the name, routing and account numbers, asset (currency), balances, suppress status, and the date the account was added.


Get Manager Account Balances

Fetches a list of the manager's asset accounts along with the current balances, including total, available, and pending balances. This endpoint is essential for users to obtain a clear overview of their financial status within the system. If you would like to get balances of a managee, use the Get List of Accounts for a Managee by ID endpoint.

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

  • Method: GET

Query Parameters:

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

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

If pageNumber and pageSize are not supplied, then an unpaginated list will be returned.

Request Example:

To request the first page with ten results:

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

Response Body Parameters:

  • id (Integer): Not used in the example.

  • details (Array of Objects): Each object contains the details of an asset account balance.

    • id (Integer): The ID of the asset account.

    • asset (String): The type of asset the account holds.

    • totalBalance (Decimal): The total balance in the account.

    • availableBalance (Decimal): The available balance that is ready for use.

    • pendingBalance (Decimal): The balance that is currently in pending transactions and not yet cleared.

    • bSuppressed (Boolean): Indicates whether the use of this account is currently disabled.

Success Response Example:

{
  "id": 0,
  "details": [
    {
      "id": 1000,
      "asset": "USDC",
      "totalBalance": 100.00,
      "availableBalance": 98.00,
      "pendingBalance": 2.00,
      "bSuppressed": false
    }
  ],
  "pageSize": 10,
  "pageNumber": 1,
  "status": "1",
  "errors": []
}

List Account Transactions

Retrieve a comprehensive list of transactions for a user's asset account, which may include deposits, withdrawals, and other types of transactions. It helps users track their deposits, withdrawals, and other transactions across accounts, providing transparency into their financial movements and the status of each transaction

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

  • Method: GET

Query Parameters:

  • AccountsId (Integer): The ID of the user's asset account for which transactions are to be listed—optional.

  • FromDate (ISO 8601 date): The start date to filter transactions—optional.

  • ToDate (ISO 8601 date): The end date to filter transactions—optional.

  • PageNumber (Integer): The page of results to return, with 1 as the default—optional.

  • PageSize (Integer): The number of records per page, with 10 as the default—optional.

Request Example:

To request a list of transactions for a specific account:

GET /api/v1/customer/accounts/transactions?AccountsId=1056&FromDate=2022-07-01&ToDate=2022-07-31

Response Body Parameters:

  • id (Integer): Not actively used in the example.

  • details (Array of Objects): Each object contains detailed transaction information.

    • id (Integer): The transaction ID.

    • accountsId (Integer): The account ID from which the transaction originated or was directed to.

    • fromTransactionsId (Integer, Nullable): The ID of the source transaction, if applicable.

    • fromAccountsId (Integer, Nullable): The ID of the source account, if applicable.

    • toTransactionsId (Integer, Nullable): The ID of the destination transaction, if applicable.

    • toAccountsId (Integer): The ID of the destination account.

    • amount (Decimal): The amount involved in the transaction.

    • description (String): Description of the transaction.

    • dateTime (ISO 8601 date): The timestamp when the transaction occurred.

    • bPending (Boolean): A flag indicating whether the transaction is pending.

Success Response Example:

{
  "id": 1025,
  "details": [
    {
      "id": 1864,
      "accountsId": 1056,
      "fromTransactionsId": null,
      "fromAccountsId": null,
      "toTransactionsId": 1006,
      "toAccountsId": 1001,
      "amount": 100.00,
      "description": "USD deposit",
      "dateTime": "2022-07-08T16:57:12.127+00:00",
      "bPending": false
    }
  ],
  "pageSize": 1,
  "pageNumber": 1,
  "numberOfPages": 26,
  "status": "1",
  "errors": []
}

Get Transaction Details

Obtain details for a specific transaction within the user's account. This includes all available data points from the amount and type of asset traded to when the transaction took place and its current processing status. It is essential for users to track and reconcile individual transactions against their account records.

  • Endpoint: /api/v1/customer/accounts/transactions/get

  • Method: GET

Query Parameters:

  • Id (Integer): The unique identifier of the account transaction to get details for—required.

Request Example:

GET /api/v1/customer/accounts/transactions/get?Id=1089

Response Body Parameters:

  • id (Integer): A reference value not actively used in the response.

  • details (Object): An encapsulation of the transaction details.

    • transactionId (Integer): The identifier of the specific transaction.

    • customerId (Integer): The customer ID associated with the transaction.

    • assetAccountId (Integer): The account ID where the asset transaction took place.

    • assetClass (String): The category of the asset, e.g., "Cryptocurrency".

    • asset (String): The specific asset involved in the transaction, e.g., "BTC".

    • amount (Decimal): The quantity of the asset transferred in the transaction.

    • description (String): A narrative describing the transaction.

    • timestamp (ISO 8601 date): The exact moment the transaction was recorded.

    • transactionStatus (String): The current processing status of the transaction, e.g., "Pending".

    • feeTransactionId (Integer, Nullable): The transaction ID for any fees, if applicable.

    • rollbackTransactionId (Integer, Nullable): The transaction ID for a rollback, if that occurred.

    • bookTransferDetails (Object, Nullable): Details if the transaction involved a book transfer.

    • achTransferDetails (Object, Nullable): Details if the transaction was an ACH transfer.

    • wireTransferDetails (Object, Nullable): Details if the transaction was a wire transfer.

    • internalTransferDetails (Object, Nullable): Details if the transaction was an internal transfer.

    • walletTransferDetails (Object, Nullable): Details if the transaction involved a wallet transfer.

    • assetExchangeTransferDetails (Object, Nullable): Details specifically for asset exchange transactions.

      • assetExchangeId (Integer): The ID of the asset exchange, if applicable.

      • assetExchangeType (String): The type of exchange, e.g., "Buy".

      • customerId (Integer): The ID of the customer engaged in the exchange.

      • assetExchangeStatus (String): The status of the asset exchange, e.g., "Pending".

      • fromTransactionsId (Integer, Nullable): The originating transaction ID for the exchange.

      • toTransactionsId (Integer): The receiving transaction ID for the exchange.

      • fromAsset (String): The asset being exchanged from.

      • toAsset (String): The asset being exchanged to.

      • fromAssetClass (String): The asset class for the originating asset.

      • toAssetClass (String): The asset class for the receiving asset.

      • requestAmount (Decimal): The amount requested for the exchange.

      • requestPrice (Decimal): The price requested for the exchange.

      • executedAmount (Decimal, Nullable): The amount actually executed in the exchange.

      • executedPrice (Decimal, Nullable): The price at which the exchange was executed.

      • commissionFee (Decimal): The commission fee for the exchange.

      • payeesId (Integer, Nullable): The payee ID, if another party is involved.

      • fromCustomerAssetAccountId (Integer, Nullable): The customer's originating asset account ID.

      • toCustomerAssetAccountId (Integer): The customer's destination asset account ID for the asset received.

Success Response Example:

{
  "id": 0,
  "details": {
    "transactionId": 1089,
    "customerId": 1061,
    "assetAccountId": 1040,
    "assetClass": "Cryptocurrency",
    "asset": "BTC",
    "amount": 0.001,
    "description": "Bitcoin Purchase",
    "timestamp": "2023-06-09T15:03:40.183",
    "transactionStatus": "Pending",
    "feeTransactionId": null,
    "feeTransactionAmount": null,
    "rollbackTransactionId": null,
    "bookTransferDetails": null,
    "achTransferDetails": null,
    "wireTransferDetails": null,
    "internalTransferDetails": null,
    "walletTransferDetails": null,
    "assetExchangeTransferDetails": {
      "assetExchangeId": 1108,
      "assetExchangeType": "Buy",
      "customerId": 1061,
      "assetExchangeStatus": "Pending",
      "fromTransactionsId": null,
      "toTransactionsId": 1089,
      "fromAsset": "USD",
      "toAsset": "BTC",
      "fromAssetClass": "Currency",
      "toAssetClass": "Cryptocurrency",
      "requestAmount": 0.001,
      "requestPrice": 32.92,
      "executedAmount": null,
      "executedPrice": null,
      "commissionFee": 5.00,
      "payeesId": null,
      "fromCustomerAssetAccountId": null,
      "toCustomerAssetAccountId": 1040
    }
  },
  "status": 1,
  "errors": []
}

Withdraw Crypto from Customer Account to External Wallet

Allows a user to withdraw cryptocurrency from a customer account to an external blockchain wallet. Users have the capability to send cryptocurrency from an customer's account to another digital wallet that they specify. To do this, they provide the account ID from which the money will come, how much they want to send, and the address of the digital wallet to receive the funds. Once the request is made, the system processes it and either confirms the transaction has taken place or gives an error if something went wrong during the process.

  • Endpoint: /api/v1/customer/accounts/crypto/withdraw

  • Method: POST

  • Request Body Parameters:

    • accountsId (Integer): The ID of the customer account from which the withdrawal is to be made.

    • amount (Decimal): The amount of cryptocurrency to be withdrawn.

    • destinationAddress (String): The blockchain wallet address to which the funds will be withdrawn.

Request Example:

{
  "accountsId": 1004,
  "amount": 0.005,
  "destinationAddress": "mxcMwdmLsyQGRNhvHSBuxomxhL1"
}

Response Body Parameters:

  • id (Integer): A reference ID for the transaction; not used in the example.

  • details.id (Integer): The ID of the withdrawal transaction.

  • details.accountsId (Integer): The ID of the customer account.

  • details.amount (Decimal): The amount withdrawn.

  • details.description (String): A description of the transaction.

  • details.dateTime (String): Timestamp of when the transaction took place.

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

Success Response Example:

{
  "id": 1025,
  "details": {
    "id": 1864,
    "accountsId": 1056,
    "amount": 0.0001,
    "description": "BTC withdrawal",
    "dateTime": "2022-07-08T16:57:12.127+00:00",
    "bPending": false
  },
  "status": "1",
  "errors": []
}

Error Codes:

  • If the withdrawal request fails due to screening, a BadRequest error with a Transaction_Blocked messageCode can be returned in the response.

  • errorType: The type of error encountered during the request processing.

  • fieldName: The field that caused the error.

  • messageCode: A code that designates the specific error, for example, "Transaction_Blocked."

Error Response Example:

{
  "id": 0,
  "details": null,
  "status": "0",
  "errors": [
    {
      "errorType": "BadRequest",
      "fieldName": "Screening",
      "messageCode": "Transaction_Blocked"
    }
  ]
}

Get Deposit Address for a Crypto Asset Account

Enables users to retrieve the deposit address of a cryptocurrency wallet associated with a customer's asset account. By retrieving a deposit address, users can make an external deposit and see the transaction reflected in their account once it's been confirmed.

  • Endpoint: /api/v1/customer/accounts/crypto/depositaddress

  • Method: POST

  • Request Body Parameters:

    • accountsId (Integer): The ID of the customer account to retrieve a deposit address for.

Last updated