# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://customer-api-docs.ibanera.com/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

---

# Overview

The Customer API is an integral component of the banking platform, designed primarily to extend the platform's functionalities to users who require enhanced control and automation capabilities. It's particularly useful for users or organizations with substantial operational needs, such as managing a large number of accounts or performing high-frequency financial activities.

Here's a high-level overview of what the Customer API facilitates:

* **Streamlined Operations:** Users can make actions on accounts, optimizing operational efficiency for themselves or the people they manage.
* **Data Accessibility:** The API provides access to account information in a standardized and easily exchangeable data format, namely JSON, which is advantageous for integrating with other systems or applications.

The API encompasses a range of modules, each tailored to a specific function within the financial ecosystem:

* **Account Transactions:** Offers an interface to manage exchanges and asset transfers, augmenting the banking experience with advanced transactional capabilities.
* **Payee Management:** Enables users to efficiently manage payees, enhancing the ease of setting up and executing payments.
* **Card Management:** Streamlines the process of issuing and overseeing top-up cards for organizations, simplifying expense management and payment distribution.
* **Managee Management**: Operate banking accounts for clients, facilitate transfers, exchanges, create payment cards, and more.

To encapsulate, the Customer API not only augments the banking platform with additional layers of functionality but also delivers a more adaptable and efficient banking experience for those who manage multiple accounts or engage in frequent financial operations. It stands as a testament to the adaptability and the forward-leaning nature of the banking platform, seeking to cater to the evolving needs of modern businesses and organizations.


# Terminology


# Exchanges of Assets

### **Buy Exchange**

* Users can *buy* a digital asset (like Bitcoin) by using a paired asset (like US dollars) or another digital asset they own.
* The paired asset is deducted from the customer's balance and used to acquire the chosen crypto asset.

### **Sell Exchange**

* In a sell exchange, the customer can *sell* a digital asset they own to get regular money or another digital asset in exchange.
* The customer receives a fiat currency or another crypto asset in return, depending on the paired asset selected.
* If a customer sells crypto in exchange for fiat, the resulting fiat will be transferred to the customer’s fiat account and finally out to a chosen payee. On the other hand, if the customer is selling one cryptocurrency for another, then the resulting paired crypto asset funds will be credited to the customer’s wallet.

**It is explicitly noted that fiat currency (government-issued currency) can only serve as a paired asset.**

* Customers cannot use fiat to buy other fiat assets or sell fiat to receive crypto assets. Fiat is strictly used to purchase crypto assets or received from selling crypto assets.

### Allowed Exchange Types

<table><thead><tr><th width="110">Type</th><th>Asset Being Exchanged</th><th>Paired Asset for Exchange</th><th>Exchange Allowed?</th></tr></thead><tbody><tr><td>Buy</td><td>Crypto (e.g., Bitcoin)</td><td>Fiat (e.g., US Dollars)</td><td><mark style="color:green;"><strong>Yes</strong></mark></td></tr><tr><td>Buy</td><td>Crypto (e.g., Ethereum)</td><td>Crypto (e.g., Bitcoin)</td><td><mark style="color:green;"><strong>Yes</strong></mark></td></tr><tr><td>Buy</td><td>Fiat (e.g., US Dollars)</td><td>Crypto (e.g., Bitcoin)</td><td><mark style="color:red;"><strong>No</strong></mark></td></tr><tr><td>Buy</td><td>Fiat (e.g., Euros)</td><td>Fiat (e.g., US Dollars)</td><td><mark style="color:red;"><strong>No</strong></mark></td></tr><tr><td>Sell</td><td>Crypto (e.g., Bitcoin)</td><td>Fiat (e.g., US Dollars)</td><td><mark style="color:green;"><strong>Yes</strong></mark></td></tr><tr><td>Sell</td><td>Crypto (e.g., Ethereum)</td><td>Crypto (e.g., Bitcoin)</td><td><mark style="color:green;"><strong>Yes</strong></mark></td></tr><tr><td>Sell</td><td>Fiat (e.g., US Dollars)</td><td>Crypto (e.g., Bitcoin)</td><td><mark style="color:red;"><strong>No</strong></mark></td></tr><tr><td>Sell</td><td>Fiat (e.g., Euros)</td><td>Fiat (e.g., US Dollars)</td><td><mark style="color:red;"><strong>No</strong></mark></td></tr></tbody></table>

The rules outlined ensure that an asset exchange process remains consistent, clear, and adheres to the financial regulations set by the platform


# Payees

In the realm of finance and banking, payees are essential components that facilitate transactions. On the Ibanera banking platform, the concept of payees is built into the system, allowing customer users to designate and enroll trustworthy bank accounts—either individual accounts or pool accounts—to work alongside their subledger accounts. Here are some key aspects of managing payees on the platform:

1. **Payee Registration**: Customers can register payees in a couple of ways—either via Plaid, which links to an external bank account, or through Visa Direct, connecting to a debit card account. For business customers, there's also the provision to add payees by submitting a form with the bank account details.
2. **Funds Transfer**: Once a payee account is registered and associated with a customer’s subledger account, the customer is positioned to transfer funds out to the payee account.
3. **Asset Exchange**: Customers can nominate registered payees for use during a crypto to fiat sell exchange, streamlining the process where fiat cannot be held in subledger accounts indefinitely. This is critical for asset exchanges: once such a trade reaches the payee transfer stage, the resulting fiat is transferred out to the selected payee.
4. **Funds Pull**: If a payee account is added through Plaid, customers have the ability to initiate ACH pull transfers. This means they can draw funds from the payee account into their Ibanera subledger account.

Through these mechanisms, the platform ensures that customer subledger accounts remain primarily for asset management and not for the long-term storage of fiat funds, maintaining clear lines between different types of transactions and accounts


# Personal Customers

## **Asset Management**

Personal customers on the Ibanera platform are individuals tasked with overseeing their assets independently. This group is equipped to manage a variety of crypto asset wallets and maintain a fiat balance via a top-up card. It is important to note that direct storage of fiat funds on the Ibanera platform is not possible for personal customers. Any fiat deposits into a personal customer's subledger account are primarily for the purpose of replenishing a top-up card balance or acquiring crypto assets.

### **Account Setup and Features**

Upon successful completion of registration and KYC procedures, personal customers receive a dedicated subledger USD account. This account primarily serves the funding needs for a crypto asset wallet, with USDC being the default crypto asset linked to this account. The customer portal offers an intuitive interface for customers to track transactions related to this subledger. Additionally, it provides essential account details, enabling customers to facilitate bank transfers between their subledger and external bank accounts. The portal also allows for the management of a roster of trusted payees.

### **Trusted Payees and Crypto Wallets**

Trusted payees are integral for receiving funds from asset exchanges that cannot be housed in the subledger account. When a payee is added via Plaid, customers can transfer funds from the payee account to bolster their subledger account. The creation of crypto wallets is contingent upon necessity, such as when depositing funds into the funding account. Customers have the visibility to monitor all transactions involving each of their crypto wallets and can transfer funds from these wallets to external crypto wallets outside the Ibanera ecosystem.

### **Top-Up Card Program**

Enrollment in the Ibanera top-up card program entails the creation of a separate funding subledger account for each top-up card owned by the customer. Deposits into this account trigger a top-up process, whereby the deposited funds are transferred out of the funding account and added to the top-up card's balance. These cards are versatile, allowing purchases of goods and services beyond the Ibanera platform.

### **Customer Portal Services**

The customer portal extends access to the OTC desk for buying and selling crypto assets and depositing crypto assets from external wallets into the Ibanera account. Furthermore, customers can acquire crypto assets directly through the portal using credit or debit cards. This process involves specifying the desired cryptocurrency and amount, followed by a card payment within an iframe. Successful payments initiate an asset exchange, converting the fiat funds from the card’s account into the chosen crypto asset.


# Business Customers

## **Overview**

Ibanera business accounts are intended for customers that wish to manage their funds as an organisation. Each business registered with Ibanera has a main account holder, who is responsible for managing other customer users within their organisation, and providing business documents for KYB verification.

The main account holder has full privileges to:

* View the business’s asset accounts
* Manage the business’s top-up cards
* Use the crypto OTC desk
* Buy crypto using credit/debit cards

Other customers within the business that are not the main account holder will have a subset of these privileges, as determined when they are added by the main account holder.

## **Asset Management**

Business customers, akin to [personal customers](/terminology/personal-customers), can operate a funding subledger account on the Ibanera platform. Funds deposited in these accounts are primarily designated for conversion into crypto funds, rather than being stored as fiat.

### **FBO Account Option**

A distinct feature for business customers is the option to maintain a pooled subledger account, commonly known as an FBO (For Benefit Of) account. This account represents a segment of a unified subledger account within Ibanera. The funds within an FBO account are internally distributed among the various businesses on the platform, each identified by a unique reference for their specific partition.

### **Utilization of FBO Accounts**

Businesses can leverage the funds in their FBO accounts for purchasing crypto assets via the OTC desk or executing payments to trusted payees. Essential details of the FBO account, including the reference for the business's pooled account, are accessible to business customers. This reference is critical for accurate allocation of funds to the respective business during bank transfers between the FBO account and external bank accounts.

### **Top-Up Cards and OTC Desk Access**

Subject to certain privileges, business customer users can add top-up cards to their business account, generating a funding subledger account for each card. Furthermore, these users, if authorized, can engage with the OTC desk for buying, selling, or depositing crypto assets into the business's Ibanera wallets.

### **Crypto Wallet Management and Purchases**

With the appropriate permissions, business customer users can view and manage each crypto wallet associated with the business, including the ability to initiate withdrawals to external wallets. Additionally, there is a provision for these users to purchase crypto assets directly using credit or debit card payments, provided they have the necessary authorization from the main account holder.


# Managees

Terminology is critical in understanding and using the Customer API effectively. This terminology page serves to define the key terms used throughout the API documentation and interaction:

* **Manager**: This term refers to the individual or entity that holds a personal or business account within the banking platform and has been granted API access. Managers have the capability to oversee and manage other customer accounts through the API.
  * Example: John Doe, who operates a small business, is a manager on the banking platform and supervises his employees' financial transactions.
* **Manager Card**: A top-up card associated with the manager's account is known as a manager card. It is a financial tool that the manager can use for various transactions.
  * Example: John Doe has a manager card that he uses to load funds for operational expenses.
* **Managee**: A managee is a customer user that is created and overseen by a manager. This relationship allows for structured financial governance within an organization.
  * Example: Mary Jane, an employee at John Doe's business, is a managee with an account on the banking platform.
* **Managee Card**: This is a top-up card linked to the managee's account on the banking platform. It can be used by the managee for authorized expenses or to receive payments from the manager.
  * Example: Each of John Doe's employees, including Mary Jane, has a managee card for business-related expenditures.

When the terms customer or user are mentioned without the manager-managee context, they generally refer to any account holder who is accessing or interacting with the API.

These terms create a framework for understanding the hierarchical structure and roles within the Customer API, simplifying the interaction with the banking platform's various features and services.


# Enumerations, Codes and Definitions


# Source of Funds Types

Specifies the source of funds that will be used to top up the card.

<table><thead><tr><th width="100">Value</th><th>Description</th></tr></thead><tbody><tr><td>1939</td><td>Business Earnings</td></tr><tr><td>1940</td><td>Business Owner</td></tr><tr><td>1948</td><td>Divorce Settlement</td></tr><tr><td>1941</td><td>Earnings (Sale of Business)</td></tr><tr><td>1942</td><td>Earnings (Sale of Investments)</td></tr><tr><td>1943</td><td>Earnings (Sale of Property)</td></tr><tr><td>1949</td><td>Employment (Retirement Income)</td></tr><tr><td>1950</td><td>Employment (Salaried)</td></tr><tr><td>1951</td><td>Employment (Self-employed / Professional Fees)</td></tr><tr><td>1936</td><td>Inheritance / Family Gift</td></tr><tr><td>1944</td><td>Insurance Proceeds / Settlement</td></tr><tr><td>1945</td><td>Investment Income / Returns</td></tr><tr><td>1946</td><td>Others, specify:</td></tr><tr><td>1947</td><td>Rental Property Income</td></tr><tr><td>1937</td><td>Winnings (Government Lottery)</td></tr><tr><td>1938</td><td>Winnings (Non-Government Lottery)</td></tr></tbody></table>


# Transfer Purpose Codes Reference

### Overview

Purpose codes are utilized to categorize external transfers from Ibanera. If you are unsure which purpose code to use for your transfer, you should obtain a list of applicable [purpose codes via API](https://github.com/gradam26/Phoenix-Documentation/blob/main/customer-api/api-endpoints/transfers/transfers.md#get-purpose-codes). The table below outlines all possible purpose codes along with their respective description.

### Purpose Code Table

| Code     | Description                                                                                            |
| -------- | ------------------------------------------------------------------------------------------------------ |
| PUC001   | Transfer to own account                                                                                |
| PUC002   | Family Maintenance                                                                                     |
| PUC003   | Education-related student expenses                                                                     |
| PUC004   | Medical Treatment                                                                                      |
| PUC005   | Hotel Accommodation                                                                                    |
| PUC006   | Travel                                                                                                 |
| PUC007   | Utility Bills                                                                                          |
| PUC008   | Repayment of Loans                                                                                     |
| PUC009   | Tax Payment                                                                                            |
| PUC010   | Purchase of Residential Property                                                                       |
| PUC011   | Payment of Property Rental                                                                             |
| PUC012   | Insurance Premium                                                                                      |
| PUC013   | Life Insurance                                                                                         |
| PUC014   | Insurance Claims Payment                                                                               |
| PUC015   | Mutual Fund Investment                                                                                 |
| PUC016   | Investment in Shares                                                                                   |
| PUC01801 | Information Service Charges                                                                            |
| PUC01802 | Advertising & Public relations-related expenses                                                        |
| PUC01803 | Royalty fees, trademark fees, patent fees, and copyright fees                                          |
| PUC01804 | Fees for brokers, front end fee, commitment fee, guarantee fee and custodian fee                       |
| PUC01805 | Fees for advisors, technical assistance and academic knowledge, including remuneration for specialists |
| PUC01806 | Representative office expenses                                                                         |
| PUC01807 | Construction costs/expenses                                                                            |
| PUC01808 | Transportation fees for goods                                                                          |
| PUC01809 | For payment of exported goods                                                                          |
| PUC01810 | Delivery fees for goods                                                                                |
| PUC01811 | General Goods Trades - Offline trade                                                                   |
| PUC020   | Salary                                                                                                 |
| PUC1001  | Business Expenses                                                                                      |
| PUC1002  | Bonus Payment                                                                                          |
| PUC1003  | Cable TV Bill                                                                                          |
| PUC1004  | Credit Card Payment                                                                                    |
| PUC1005  | Charity Payment                                                                                        |
| PUC1006  | Collection Payment                                                                                     |
| PUC1007  | Commission                                                                                             |
| PUC1008  | Carpark Charges                                                                                        |
| PUC1009  | Cash Disbursement                                                                                      |
| PUC1010  | Debit Card Payment                                                                                     |
| PUC1011  | Dividend                                                                                               |
| PUC1012  | Payment of Fees & Charges                                                                              |
| PUC1013  | Foreign Worker Levy                                                                                    |
| PUC1014  | Government Insurance                                                                                   |
| PUC1015  | Goods & Services Tax                                                                                   |
| PUC1016  | Hospital Care                                                                                          |
| PUC1017  | Instalment Hire Purchase Agreement                                                                     |
| PUC1018  | Interest                                                                                               |
| PUC1019  | Invoice Payment                                                                                        |
| PUC1020  | Net Income Tax                                                                                         |
| PUC1021  | Telephone Bill                                                                                         |
| PUC1022  | Property Tax                                                                                           |
| PUC1023  | Road Tax                                                                                               |
| PUC1024  | Rebate                                                                                                 |
| PUC1025  | Refund                                                                                                 |
| PUC1026  | Supplier Payment                                                                                       |
| PUC1027  | Telco Bill                                                                                             |
| PUC1028  | Town Council Service Charges                                                                           |
| PUC1029  | Trade Services                                                                                         |
| PUC1030  | Treasury Payment                                                                                       |
| PUC1031  | Transport                                                                                              |
| PUC1032  | With Holding                                                                                           |
| PUC1033  | Other                                                                                                  |


# Getting Started

## Welcome to the Ibanera API Getting Started Guide!

This guide is designed to introduce you to the basic functionalities of the Ibanera API, equipping you with the necessary knowledge to begin utilizing its features effectively. By the end of this guide, you'll have a clear understanding of the key operations and will be capable of executing a successful login, setting a strong foundation for further exploration and integration.

### Objectives

Through this guide, you will:

1. **Understand the API User**: Learn about the fundamental principals of a user of the Ibanera API.
2. **Set Up Your Environment**: Get instructions on preparing your environment for API interaction.
3. **Authenticate Effectively**: Master the process of authentication to ensure secure access.
4. **Achieve a Successful Login**: Gain the ability to log in using the API, marking the start of your journey with Ibanera's services.
5. **Make Your First API Call**: Put your knowledge into practice by making a basic API request.

### Step-by-Step Process

1. **Familiarization with API Endpoints**: Begin by understanding the various endpoints provided by the Ibanera API, including asset management, customer or business details, and transaction processes.
2. **Environment Setup**:
   * **API Credentials**: Ensure you have the necessary API credentials (username, password, shared secret) provided by Ibanera.
   * **Development Tools**: Set up your preferred development environment and tools, such as Postman for API testing or relevant IDEs for coding in Python, Node.js, Go, etc.
3. **Authentication**:
   * [Learn the process of using your API credentials to authenticate](/getting-started/authentication-and-authorization).
   * [Understand the generation and use of TOTPs for enhanced security.](/getting-started/authentication-and-authorization/generating-a-time-based-one-time-password-totp-with-a-shared-secret)
4. **Executing Your First API Request**:
   * [Start with a simple API call, such as retrieving your account balances.](/getting-started/first-api-call)
   * Learn to interpret the API responses and handle possible errors.
5. **Next Steps**:
   * Explore further functionalities such as creating additional users, managing assets, or initiating transactions.

### Conclusion

By the end of this guide, you'll have a fundamental understanding of the Ibanera API, capable of performing a successful login and ready to explore more advanced features and functionalities. This journey marks the beginning of leveraging Ibanera's robust platform for your asset management and financial operations.


# Access the API

### Domains

To access the customer API, use the following domains which host the API in their respective environments:

| Enviroment | Endpoint                             |
| ---------- | ------------------------------------ |
| Sandbox    | <https://public-api-uat.ibanera.com> |
| Production | <https://public-api.ibanera.com>     |


# API Principal Account

### **Introduction**

The Ibanera platform categorizes certain business customers as Customer API Principal users. These users are distinguished by additional privileges that grant them access to the customer management API. This specialized API is a tool for Customer API Principal users to create and administer additional customer users, often referred to as managed customers or managees.

***

### **Eligibility and Access Process**

To qualify as a Customer API Principal user, a personal or business customer must first complete the KYC (Know Your Customer) or KYB (Know Your Business) verification process. Following this, they can reach out to the Ibanera support team to apply for an elevation to Customer API Principal status.

### **Functionality of the Customer Management API**

The primary function of the customer management API is to offer a streamlined and scalable solution for organizations to effectively handle accounts, cards, and funds distribution among their members, such as employees within a business. As of now, the management of these features is facilitated exclusively through the API, as there is no user interface available for customer management. The API is designed as a collection of RESTful endpoints, secured through bearer token authentication.

***

## **API Credentials and Security**

Upon gaining API access, a user is provided with specific API credentials, which include:

* Username
* Password
* Shared Secret

The Shared Secret plays a crucial role in the security infrastructure of the account. It is utilized to generate two-factor authentication codes, a mandatory requirement for API interactions. This additional layer of security is instrumental in safeguarding the account holder's information and operations within the API.

[Refer to our guide on Generating a Time-Based One-Time Password (TOTP) with a Shared Secret.](/getting-started/authentication-and-authorization/generating-a-time-based-one-time-password-totp-with-a-shared-secret)


# Common Response Format

#### Most responses from the Customer API use a common format, with slight differences depending on whether the data returned is a JSON object or an array.

## Response Body Parameters

Refer to the following table for parameters produced in response to the Customer API.

| Body Parameter     | Type            | Description                                                                                               |
| ------------------ | --------------- | --------------------------------------------------------------------------------------------------------- |
| id                 | Integer         | Identity of entity modified, or 0 if unused.                                                              |
| details            | Object or Array | Detailed response, or null if response is not success.                                                    |
| pageSize           | Integer         | Requested number of detail entries per page (fewer than pageSize items may be returned on the last page). |
| pageNumber         | Integer         | Requested page of data, if details is an array. Default is 1.                                             |
| errors             | Array           | Details of errors that occurred.                                                                          |
| errors.fieldName   | String          | Request item or step in handling the request that caused of the error.                                    |
| errors.messageCode | String          | Code identifying the error.                                                                               |
| status             | String          | <p>• “1” indicates success</p><p>• “0” indicates an error</p>                                             |

## Example Responses

### Successful Response for an Object

```json
{
    "id": 0,
    "details": {
        ... object content ...
    },
    "status": "1",
    "errors": []
}
```

### Successful Response for an Array

```json
{
    "id": 0,
    "details": [
        ... array content ...
    ],
    "pageSize": 10,
    "pageNumber": 1,
    "status": "1",
    "errors": []
}
```

### Error Response

```json
{
    "id": 0,
    "details": null,
    "status": "0",
    "errors": [
        {
            "fieldName": "...",
            "messageCode": "..."
        }
    ]
}
```


# First API Call

## Getting Started: [**`Get Balances`**](/api-endpoints/accounts#get-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.

This API endpoint is a GET request, which makes it a great endpoint for inital testing as it's configuration is relatively simple and straightforward. [Remember to configure your request's header with both `Authorization` and `otp` fields.](/getting-started/authentication-and-authorization#authorization)

***

## Get Account Balances

Fetches a list of the user’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.

* **Endpoint:** `/api/v1/customer/accounts/balances`
* **Method:** `GET`

{% openapi src="/files/jJ7E6wWPcyFuZH6ofuNu" path="/api/v1/customer/accounts/balances" method="get" expanded="false" fullWidth="true" %}
[Customer API - Customer v5.0.7.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-1018aaf3121ec8a24cd8dd89c9a572d034369d99%2FCustomer%20API%20-%20Customer%20v5.0.7.json?alt=media)
{% endopenapi %}

**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:

```json
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:**

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

###


# Authentication & Authorization

## Authentication

In order to login using the API, you must submit your API credentials supplied to you by Ibanera, in addition to a one time password (`otp`). The login endpoint authenticates a user by validating their credentials and TOTP code, providing an access token for subsequent API requests.

[Refer to our guide on Generating a Time-Based One-Time Password (TOTP) with a Shared Secret.](/getting-started/authentication-and-authorization/generating-a-time-based-one-time-password-totp-with-a-shared-secret)

* **Endpoint:** `/api/v1/public/auth/login`
* **Method:** `POST`

{% openapi src="/files/FvdwoJS3Dil80FZGCCyt" path="/api/v1/public/auth/login" method="post" expanded="true" %}
[Customer API - Public.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-6face27c0a15b254555d05b77ca4cd8e06609f27%2FCustomer%20API%20-%20Public.json?alt=media)
{% endopenapi %}

**Request Body Parameters:**

* `username` (String): The username of the user attempting to log in—required.
* `password` (String): The password associated with the username—required.
* `otp` (String): A time-based one-time password (TOTP) generated from the user's shared secret—required.

**Request Example:**

```json
{
  "username": "exampleUser",
  "password": "examplePass",
  "otp": "123456"
}
```

**Response Body Parameters:**

* `id` (Integer): A numerical identifier of the response, often representing the authenticated user’s ID.
* `details` (Object):
  * `accessToken` (String): The bearer token provided upon successful authentication.
  * `expiresIn` (Integer): The number of seconds until the token expires.

**Success Response Example:**

```json
{
  "id": 0,
  "details": {
    "accessToken": "eyJhbGciOiJIUzI1Ni...",
    "expiresIn": 3600
  },
  "status": "1",
  "errors": []
}
```

***

## Authorization

API requests are authorized if the headers contains both the `Authorization` and `otp` fields.

<table><thead><tr><th>Header Key</th><th width="272">Expected Value</th><th>Example</th></tr></thead><tbody><tr><td>Authorization</td><td>Bearer {{accessToken}}</td><td>Bearer eyJhbGciOiJIUzI1Ni...</td></tr><tr><td>otp</td><td><p>TOTP using:</p><ul><li>SHA-1 hash</li><li>6 digit output</li><li>30 second interval<br>based on the user’s shared secret.</li></ul></td><td>679008</td></tr></tbody></table>


# Generating a Time-Based One-Time Password (TOTP) with a Shared Secret

### Introduction

In the realm of digital security, Time-Based One-Time Passwords (TOTPs) play a pivotal role, particularly in two-factor authentication systems. A TOTP is a unique passcode that is valid for only a short period of time, enhancing security by adding a dynamic layer to the authentication process. These passwords are generated by combining a shared secret key with the current time, processed through a cryptographic hash function.

The use of TOTPs is widespread in various security protocols due to their effectiveness in safeguarding against common threats like replay attacks. In this guide, we will delve into how to generate a TOTP using:

* SHA-1 hash algorithm,
* producing a 6-digit output,
* with a 30-second validity interval.

The process hinges on the user's shared secret, which is a critical element in ensuring that the generated TOTP is both secure and unique to each user.

This guide provides an initial step towards integrating TOTP generation into your authentication systems, using Python and Node.js. The methods outlined here are straightforward and can be easily incorporated into a variety of security frameworks.

***

### Generating TOTP in Python

#### Requirements

* Python library: `pyotp`

#### Installation

```bash
pip install pyotp
```

#### Code Example

```python
import pyotp

def generate_totp(shared_secret):
    totp = pyotp.TOTP(shared_secret, interval=30, digits=6)
    return totp.now()

# Example Usage
shared_secret = 'YOUR_SHARED_SECRET_HERE'
print(generate_totp(shared_secret))
```

***

### Generating TOTP in Node.js

#### Requirements

* Node.js library: `otplib`

#### Installation

```bash
npm install otplib
```

#### Code Example

```javascript
const { totp } = require('otplib');

function generateTOTP(sharedSecret) {
    totp.options = { digits: 6, algorithm: 'SHA1', step: 30 };
    return totp.generate(sharedSecret);
}

// Example Usage
const sharedSecret = 'YOUR_SHARED_SECRET_HERE';
console.log(generateTOTP(sharedSecret));
```


# API Endpoints


# 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 are essential for a different aspect of account information retrieval:

1. [**Create Asset Account**](#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**](#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**](#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 Asset Accounts for Customer**](#list-asset-accounts-for-customer) - This endpoint allows customers to quickly obtain real-time information about the current state of either the manager or a managee accounts. This endpoint differs from [**Get Manager Account Balances**](#get-manager-account-balances) as you can specify a **CustomersID** to retrieve account information for, where as the prior endpoint will only retrieve account details for the manager.
5. [**List Transactions**](#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.
6. [**Get Transaction Details** ](#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.

***

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

{% openapi src="/files/L62FqnFPYYLdXHL4Oqm4" path="/api/v2/customer/accounts/create" method="post" %}
[public-api-customer-role (3).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-d62c60559c95747edfde0cf6e1f491168054ab32%2Fpublic-api-customer-role%20\(3\).json?alt=media)
{% endopenapi %}

**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**:

```json
{
  "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**:

```json
{
    "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 Code       | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| 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.

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/accounts/account" method="get" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

**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**:

```json
{
  "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**](/api-endpoints/managees#get-list-of-accounts-for-a-managee-by-id) **endpoint.**

* **Endpoint:** `/api/v1/customer/accounts/balances`
* **Method:** `GET`

{% openapi src="/files/jJ7E6wWPcyFuZH6ofuNu" path="/api/v1/customer/accounts/balances" method="get" expanded="false" %}
[Customer API - Customer v5.0.7.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-1018aaf3121ec8a24cd8dd89c9a572d034369d99%2FCustomer%20API%20-%20Customer%20v5.0.7.json?alt=media)
{% endopenapi %}

**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:

```json
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:**

```json
{
  "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 Asset Accounts for Customer

Fetches a list of asset accounts along with the current balances for a **CustomersID**, including total, available, and pending balances. This endpoint is essential for users to obtain a clear overview of their financial status within the system.

* **Endpoint**: `/api/v1/customer/accounts/list-accounts`
* **Method**: `GET`

## Get a list of accounts

> Request query:
> \
> &#x20;\- CustomersId: Customer's Id filter
> \
> &#x20;\- Asset: Asset filter
> \
> &#x20;\- PageNumber: List page number (optional, default = 1)
> \
> &#x20;\- PageSize: List page size (optional, default = 10)
> \
> &#x20;
> \
> Response:
> \
> &#x20;\- array of&#x20;
> \
> &#x20;  \- Id: Account Id
> \
> &#x20;  \- Name: Name of the account
> \
> &#x20;  \- RoutingNumber: Account routing number
> \
> &#x20;  \- AccountNumber: Account number
> \
> &#x20;  \- Asset: Account asset
> \
> &#x20;  \- TotalBalance: Account total balance
> \
> &#x20;  \- AvailableBalance: Account available balance
> \
> &#x20;  \- PendingBalance: Account pending balance
> \
> &#x20;  \- bSuppressed: true if account is suppressed
> \
> &#x20;  \- DateAdded: date account was added

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"AccountsModule"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"Results.PaginatedObjectResultDto_System.Collections.Generic.IEnumerable_CustomerRole.AccountsModule.CustomerAccountDto":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"details":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.AccountsModule.CustomerAccountDto"},"nullable":true,"readOnly":true},"pageSize":{"type":"integer","format":"int32","nullable":true},"pageNumber":{"type":"integer","format":"int32","nullable":true},"numberOfPages":{"type":"integer","format":"int32","nullable":true},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.AccountsModule.CustomerAccountDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"customersId":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true},"routingNumber":{"type":"string","nullable":true},"accountNumber":{"type":"string","nullable":true},"swiftCode":{"type":"string","nullable":true},"virtualAccountNumber":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"asset":{"type":"string","nullable":true},"assetDisplayName":{"type":"string","nullable":true},"totalBalance":{"type":"number","format":"double"},"availableBalance":{"type":"number","format":"double"},"pendingBalance":{"type":"number","format":"double"},"bSuppressed":{"type":"boolean"},"dateAdded":{"type":"string","format":"date-time"}},"additionalProperties":false},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false},"Results.ResultDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false}}},"paths":{"/api/v1/customer/accounts/list-accounts":{"get":{"tags":["AccountsModule"],"summary":"Get a list of accounts","description":"Request query:\r\n - CustomersId: Customer's Id filter\r\n - Asset: Asset filter\r\n - PageNumber: List page number (optional, default = 1)\r\n - PageSize: List page size (optional, default = 10)\r\n \r\nResponse:\r\n - array of \r\n   - Id: Account Id\r\n   - Name: Name of the account\r\n   - RoutingNumber: Account routing number\r\n   - AccountNumber: Account number\r\n   - Asset: Account asset\r\n   - TotalBalance: Account total balance\r\n   - AvailableBalance: Account available balance\r\n   - PendingBalance: Account pending balance\r\n   - bSuppressed: true if account is suppressed\r\n   - DateAdded: date account was added","operationId":"GET-api-v1-customer-accounts-list-accounts","parameters":[{"name":"customersId","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"asset","in":"query","schema":{"type":"string"}},{"name":"pageNumber","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"pageSize","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.PaginatedObjectResultDto_System.Collections.Generic.IEnumerable_CustomerRole.AccountsModule.CustomerAccountDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ResultDto"}}}}}}}}}
```

#### Success Response Example:

```json
{
    "id": 14631,
    "details": [
        {
            "id": 4646,
            "customersId": 14391,
            "name": "dUSD Account",
            "routingNumber": null,
            "accountNumber": null,
            "swiftCode": null,
            "virtualAccountNumber": null,
            "reference": null,
            "asset": "dUSD",
            "assetDisplayName": "dUSD",
            "totalBalance": 0.000000000000000000,
            "availableBalance": 0.000000000000000000,
            "pendingBalance": 0.000000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-09-10T03:58:40.1066667+00:00",
            "bDDAAccount": true, // can be true or false
        },
        {
            "id": 4681,
            "customersId": 14391,
            "name": "USD Account (Domestic)",
            "routingNumber": "999999999",
            "accountNumber": "336674726730",
            "swiftCode": null,
            "virtualAccountNumber": null,
            "reference": "REF4681",
            "asset": "USD",
            "assetDisplayName": "United States Dollar",
            "totalBalance": 999935.160000000000000000,
            "availableBalance": 999934.160000000000000000,
            "pendingBalance": -50.000000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-09-11T18:29:10.4833333+00:00",
            "bDDAAccount": true, // can be true or false
        },
        {
            "id": 6306,
            "customersId": 14391,
            "name": "AED Account",
            "routingNumber": null,
            "accountNumber": "11020048859",
            "swiftCode": "GLDTSGSG",
            "virtualAccountNumber": null,
            "reference": "REF6306",
            "asset": "AED ",
            "assetDisplayName": "Arab Emirates Dirham",
            "totalBalance": 1000000.000000000000000000,
            "availableBalance": 1000000.000000000000000000,
            "pendingBalance": 0.000000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-11-20T05:18:41.4566667+00:00",
            "bDDAAccount": true, // can be true or false
        },
        {
            "id": 6307,
            "customersId": 14391,
            "name": "AUD Account",
            "routingNumber": null,
            "accountNumber": "11020048859",
            "swiftCode": "GLDTSGSG",
            "virtualAccountNumber": null,
            "reference": "REF6307",
            "asset": "AUD",
            "assetDisplayName": "Australian Dollar",
            "totalBalance": 999985.000000000000000000,
            "availableBalance": 999985.000000000000000000,
            "pendingBalance": -15.000000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-11-20T05:18:41.4566667+00:00",
            "bDDAAccount": true, // can be true or false
        },
        {
            "id": 6308,
            "customersId": 14391,
            "name": "CNH Account",
            "routingNumber": null,
            "accountNumber": "11020048859",
            "swiftCode": "GLDTSGSG",
            "virtualAccountNumber": null,
            "reference": "REF6308",
            "asset": "CNH",
            "assetDisplayName": "Chinese Yuan Renminbi",
            "totalBalance": 999892.930000000000000000,
            "availableBalance": 999892.930000000000000000,
            "pendingBalance": -107.070000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-11-20T05:18:41.4566667+00:00",
            "bDDAAccount": true, // can be true or false
        },
        {
            "id": 6309,
            "customersId": 14391,
            "name": "EUR Account",
            "routingNumber": null,
            "accountNumber": "11020048859",
            "swiftCode": "GLDTSGSG",
            "virtualAccountNumber": null,
            "reference": "REF6309",
            "asset": "EUR",
            "assetDisplayName": "Euro",
            "totalBalance": 999985.870000000000000000,
            "availableBalance": 999985.870000000000000000,
            "pendingBalance": -14.130000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-11-20T05:18:41.4566667+00:00",
            "bDDAAccount": false, // can be true or false
        },
        {
            "id": 6310,
            "customersId": 14391,
            "name": "GBP Account",
            "routingNumber": null,
            "accountNumber": "11020048859",
            "swiftCode": "GLDTSGSG",
            "virtualAccountNumber": null,
            "reference": "REF6310",
            "asset": "GBP",
            "assetDisplayName": "Pound Sterling",
            "totalBalance": 999988.330000000000000000,
            "availableBalance": 999988.330000000000000000,
            "pendingBalance": -11.670000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-11-20T05:18:41.4566667+00:00",
            "bDDAAccount": false, // can be true or false
        },
        {
            "id": 6311,
            "customersId": 14391,
            "name": "HKD Account",
            "routingNumber": null,
            "accountNumber": "11020048859",
            "swiftCode": "GLDTSGSG",
            "virtualAccountNumber": null,
            "reference": "REF6311",
            "asset": "HKD",
            "assetDisplayName": "Hong Kong Dollar",
            "totalBalance": 999883.990000000000000000,
            "availableBalance": 999883.990000000000000000,
            "pendingBalance": -116.010000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-11-20T05:18:41.4566667+00:00",
            "bDDAAccount": false, // can be true or false
        },
        {
            "id": 6312,
            "customersId": 14391,
            "name": "SGD Account",
            "routingNumber": null,
            "accountNumber": "11020048859",
            "swiftCode": "GLDTSGSG",
            "virtualAccountNumber": null,
            "reference": "REF6312",
            "asset": "SGD",
            "assetDisplayName": "Singapore Dollar",
            "totalBalance": 999979.960000000000000000,
            "availableBalance": 999979.960000000000000000,
            "pendingBalance": -20.040000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-11-20T05:18:41.4566667+00:00",
            "bDDAAccount": false, // can be true or false
        },
        {
            "id": 6313,
            "customersId": 14391,
            "name": "USD Account",
            "routingNumber": null,
            "accountNumber": "11020048859",
            "swiftCode": "GLDTSGSG",
            "virtualAccountNumber": null,
            "reference": "REF6313",
            "asset": "USD",
            "assetDisplayName": "United States Dollar",
            "totalBalance": 999985.000000000000000000,
            "availableBalance": 999985.000000000000000000,
            "pendingBalance": -15.000000000000000000,
            "bSuppressed": false,
            "dateAdded": "2024-11-20T05:18:41.4566667+00:00",
            "bDDAAccount": false, // can be true or false
        }
    ],
    "pageSize": 25,
    "pageNumber": 1,
    "numberOfPages": 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`

{% openapi src="/files/RgbXckfTMuZnDyDpnAqY" path="/api/v1/customer/accounts/transactions" method="get" %}
[public-api-openapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-902a887a41e4525d2b6f614fc425695fd9d9c525%2Fpublic-api-openapi.json?alt=media)
{% endopenapi %}

**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:

```json
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.
  * `bCancellable` (Boolean): A flag indicating whether the transaction might be cancelled. For a more accurate and real-time check on whether or not a transaction may be cancelled, users are encouraged to use [this endpoint.](/api-endpoints/transaction-cancellation#get-transaction-cancellation-eligibility)

**Success Response Example:**

```json
{
  "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,
      "bCancellable": 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/v2/customer/accounts/transactions/get`
* **Method:** `GET`

**Query Parameters:**

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

**Request Example:**

```json
GET /api/v2/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.
  * `bEligibleForReversal` (Boolean): A flag indicating whether the transaction can be reversed.
  * `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:**

```json
{
  "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,
    "bEligibleForReversal": false,
    "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": []
}
```

***


# Business Onboarding

## Overview

The Business module within the Customer API offers a suite of endpoints tailored to streamline the business creation and verification processes, alongside managing business-related documents efficiently. Here's a brief overview of what each endpoint aims to achieve:

* [**Get Business Creation Parameters V2**](#get-business-creation-parameters-v2): This endpoint provides a list of required parameters and prerequisites needed to initiate the business creation process. It's a preparatory step that ensures businesses have gathered necessary information before submission.
* [**Create Business V2**](#create-business-v2) : Allows for the creation of a new business entity on the Ibanera platform. This endpoint is the starting point for registering a business and requires submission of detailed information such as business name, type, and identifying information.
* [**Get Parameters for Business Verification V2**](#get-parameters-for-business-verification-v2): Once a business is created, this endpoint is used to retrieve a detailed list of parameters and documents required for verification purposes. Its role is to guide businesses through assembling the necessary documentation and data for verification.
* [**Upload Business Document**](#upload-business-document): Facilitates the upload of business-related documents to the platform. This endpoint is pivotal in submitting the documents necessary for business verification, such as proof of address, incorporation certificates, and more.
* [**Delete Business Document**](#delete-business-document): Offers functionality to remove previously uploaded documents. This endpoint is useful in case of submission errors or when a document update is necessary, thereby maintaining the accuracy and relevancy of submitted documents.
* [**Submit Business Verification**](#submit-business-verification)**:** Central to the verification process, this endpoint allows businesses to submit their complete set of verification data along with necessary documents. It's the culmination of the business verification preparation, where all collated information and documentation are officially submitted for review.
* [**Get Verification Status**](#get-business-verification-status): Provides businesses with the ability to check the status of their verification process. It gives real-time feedback on the review progress, including approved, pending, or required additional information, ensuring businesses are informed about their verification journey.

Each of these endpoints collectively supports businesses in their journey from creation to verification on the Ibanera platform, ensuring a structured and efficient process in becoming a recognized and verified business entity.

***

### Get Business Creation Parameters V2

This endpoint is designed to retrieve the necessary parameters required for the **Create Business** endpoint, which is used to register a new business account. This endpoint provides essential data for countries, states, and entity types that are required for the creation of a business account.

* **Endpoint**: `/api/v2/customer/business/createparameters`
* **Method**: `GET`

## GET /api/v2/customer/business/createparameters

> Get details for the create endpoint

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"BusinessV2Module"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"Results.ObjectResultDto_CustomerRole.BusinessV2Module.CreateDetailsDto":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"details":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.CreateDetailsDto"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.CreateDetailsDto":{"type":"object","properties":{"countries":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.CreateDetailsDto.CountryDto"},"nullable":true},"states":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.CreateDetailsDto.StateDto"},"nullable":true},"productServices":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.CreateDetailsDto.ProductServicesDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.CreateDetailsDto.CountryDto":{"type":"object","properties":{"name":{"type":"string","nullable":true},"isoCode":{"type":"string","nullable":true},"id":{"type":"integer","format":"int32"}},"additionalProperties":false},"CustomerRole.BusinessV2Module.CreateDetailsDto.StateDto":{"type":"object","properties":{"countriesID":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true},"ansiCode":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.CreateDetailsDto.ProductServicesDto":{"type":"object","properties":{"name":{"type":"string","nullable":true},"id":{"type":"integer","format":"int32"}},"additionalProperties":false},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false},"Results.Base.BaseResultDto":{"type":"object","properties":{"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false}}},"paths":{"/api/v2/customer/business/createparameters":{"get":{"tags":["BusinessV2Module"],"summary":"Get details for the create endpoint","operationId":"GET-api-v2-customer-business-createparameters","parameters":[{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ObjectResultDto_CustomerRole.BusinessV2Module.CreateDetailsDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.Base.BaseResultDto"}}}}}}}}}
```

**Response Body Types:**

The response is structured in JSON format and contains the following main elements within the `details` object:

* **countries**: An array of country objects with:
  * `id` (integer): Id of country, to be matched with `CountriesID` for States
  * `name` (string): Country Name
  * `isoCode` (String): Country ISO Code, 3 letters - ISO 3166-1 alpha-3
* **states**: An array of state objects including
  * `countriesID` (Integer): Id of state’s country
  * `name` (String): Name of state
  * `ansiCode` (String): ANSI Code for US states
* **productServices**: An array of products and service type objects with
  * `id` (Integer): Id of product or service type
  * `name` (String): Name of product or service type

**Example of a Successful Response:**

```json
{
    "id": 0,
    "details": {
        "countries": [
            {
                "name": "United States",
                "isoCode": "USA",
                "id": 1001
            }
        ],
        "states": [
            {
                "countriesID": 1001,
                "name": "Alabama",
                "ansiCode": "AL"
            }
        ],
        "productServices": [
            {
                "name": "Bank Transfers",
                "id": 1000
            }
        ]
    },
    "status": "1",
    "errors": []
}
```

**Possible Error Message Codes:**

In cases of failure or invalid requests, the response might return `"status": "0"` with a list of errors each containing:

* **fieldName**: Indicates the request item or step that caused the error.
* **messageCode**: A code identifying the specific error.

***

### Create Business V2

The **Create Business** endpoint is designed to register a new business account. This POST request requires comprehensive information about both personal and business details, terms and conditions agreements, and an optional invitation send flag.

* **Endpoint**: `/api/v2/customer/business/create`
* **Method**: `POST`

## Create managed business customer

> Request body parameters:
> \
> \- PersonalDetails.FirstName: Customer's first given name
> \
> \- PersonalDetails.MiddleNames: Customer's middle names
> \
> \- PersonalDetails.LastName: Customer's surname
> \
> \- PersonalDetails.Reference: Reference for the managed customer
> \
> \- PersonalDetails.CurrencyCode: Customer's currency code
> \
> \- PersonalDetails.EmailAddress: Customer's personal email
> \
> \- PersonalDetails.PhoneNumber: Customer's personal phone number
> \
> \- RegisteredCountryCode: Country of business registration
> \
> \- bConductsThirdPartyPayments: Flag to determine whether customer will be conducting third party payments
> \
> \- RequestedProducts: A list of products and services that the account will be used for
> \
> \- SendInvite: Set true to send welcome email to customer
> \
> Response:
> \
> \- Id: Customer's Id
> \
> &#x20;&#x20;
> \
> Possible validation errors:
> \
> \- Forbidden - no access
> \
> \- Required - field missing
> \
> \- Username\_Not\_Available - email address is already in use
> \
> \- Invalid\_PhoneNumber: Phone number in incorrect format
> \
> \- Invalid\_CurrencyCode: Currency code invalid or not available
> \
> \- Invalid\_CountryISOCode: Country not found
> \
> \- Invalid\_RequestedProducts: Product not recognized

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"BusinessV2Module"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"CustomerRole.BusinessV2Module.CreateDto":{"required":["bConductsThirdPartyPayments","personalDetails","registeredCountryCode","requestedProducts","sendInvite"],"type":"object","properties":{"personalDetails":{"description":"Required. Details of the primary user created for the business — used to set up their login and, when sendInvite is true, to send the welcome invite email.","allOf":[{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.BusinessRegistrationPersonalDto"}]},"registeredCountryCode":{"minLength":1,"type":"string"},"bConductsThirdPartyPayments":{"type":"boolean"},"requestedProducts":{"type":"array","items":{"type":"integer","format":"int32"}},"sendInvite":{"type":"boolean"}},"additionalProperties":false},"CustomerRole.BusinessV2Module.BusinessRegistrationPersonalDto":{"required":["currencyCode","emailAddress","firstName","lastName","phoneNumber","reference"],"type":"object","properties":{"firstName":{"minLength":1,"type":"string"},"middleNames":{"type":"string","nullable":true},"lastName":{"minLength":1,"type":"string"},"reference":{"minLength":1,"type":"string","description":"Their reference for the customer"},"currencyCode":{"minLength":1,"type":"string"},"emailAddress":{"minLength":1,"type":"string","format":"email"},"phoneNumber":{"minLength":1,"pattern":"^(\\+?\\d+)?\\s?(\\(\\d+\\))?\\s?(\\d+-\\d+)?$","type":"string","format":"tel"}},"additionalProperties":false},"Results.ResultDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/api/v2/customer/business/create":{"post":{"tags":["BusinessV2Module"],"summary":"Create managed business customer","description":"Request body parameters:\r\n- PersonalDetails.FirstName: Customer's first given name\r\n- PersonalDetails.MiddleNames: Customer's middle names\r\n- PersonalDetails.LastName: Customer's surname\r\n- PersonalDetails.Reference: Reference for the managed customer\r\n- PersonalDetails.CurrencyCode: Customer's currency code\r\n- PersonalDetails.EmailAddress: Customer's personal email\r\n- PersonalDetails.PhoneNumber: Customer's personal phone number\r\n- RegisteredCountryCode: Country of business registration\r\n- bConductsThirdPartyPayments: Flag to determine whether customer will be conducting third party payments\r\n- RequestedProducts: A list of products and services that the account will be used for\r\n- SendInvite: Set true to send welcome email to customer\r\nResponse:\r\n- Id: Customer's Id\r\n  \r\nPossible validation errors:\r\n- Forbidden - no access\r\n- Required - field missing\r\n- Username_Not_Available - email address is already in use\r\n- Invalid_PhoneNumber: Phone number in incorrect format\r\n- Invalid_CurrencyCode: Currency code invalid or not available\r\n- Invalid_CountryISOCode: Country not found\r\n- Invalid_RequestedProducts: Product not recognized","operationId":"POST-api-v2-customer-business-create","parameters":[{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.CreateDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.CreateDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.CreateDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.CreateDto"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ResultDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ResultDto"}}}}}}}}}
```

**Request Body Parameters:**

* **`personalDetails`** (JSON Object, Required): Container for personal information.
  * **`firstName`** (String, Required): First Name.
  * **`middleNames`** (String, Not Required, Nullable): Middle Names.
  * **`lastName`** (String, Required): Last Name.
  * **`emailAddress`** (String, Required): Email Address.
  * **`phoneNumber`** (String, Required): Phone Number, should include country code.
  * **`reference`** (String, Not Required): External reference for the customer.
  * **`currencyCode`**(String, Required): Currency code.
* **`registeredCountryCode`**(String, Required): Country code where business is registered.
* **`bConductsThirdPartyPayments`** (Boolean, Required): Flag to determine whether customer will be conducting third party payments.
* **`requestedProducts`**(Integer array, Required): A list of products and services that the account will be used for.
* **`sendInvite`** (Boolean, Required): Flag to send an email invite to the user to login via the User Interface. Set to `false` by default.

**Request Body Example JSON:**

```json
{
    "personalDetails": {
        "firstName": "John",
	    "middleNames": null,
	    "lastName": "Smith",
        "reference": "User_6685",
        "currencyCode": "USD",
        "emailAddress": "user@example.com",
        "phoneNumber": "+1234567890"
    },
    "RegisteredCountryCode": "USA",
    "bConductsThirdPartyPayments": false,
    "RequestedProducts": [1000,1001],
    "sendInvite": true
}
```

**Response Body Types:**

On successful creation, the response will contain:

* **`id`** (Integer): A numeric ID representing the operation.
* **`details`** (JSON Object): Includes `customersId` and `customerUsersCustomersID`, identifying the created business and the user associated with it.
* **`status`** (String): "1" indicates a successful operation.
* **`errors`** (JSON Array): Empty for successful operations.

**Example of a Successful Response:**

```json
{
  "id": 13984,
  "details": {
    "customersId": 13833,
    "customerUsersCustomersID": 14087
  },
  "status": "1",
  "errors": []
}
```

**Possible Error Message Codes:**

Similar to other endpoints, in case of failure, an error object will be included with:

* **fieldName**: Field related to the error.
* **messageCode**: Specific error code.

| Error Message Code         | Description                                                                                                                                                                            |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Required                   | Named field missing, null or empty                                                                                                                                                     |
| Username\_Not\_Available   | Email address is already in use                                                                                                                                                        |
| Invalid\_PhoneNumber       | <p>Minimum length is six digits. Invalid format. Example supported formats:</p><p>+12345678910</p><p>12345678910</p><p>+1(234)567-8910</p><p>+1 (234) 567-8910</p><p>+1 2345678910</p> |
| Invalid\_RequestedProducts | Product not recognized                                                                                                                                                                 |
| Invalid\_CurrencyCode      | Currency Code not found/available                                                                                                                                                      |
| Invalid\_CountryISOCode    | Country not found                                                                                                                                                                      |

***

### Get Parameters for Business Verification V2

This endpoint is designed to assist in collecting the necessary parameters for submitting business verification data through the Submit Verification endpoint. By making a GET request to this endpoint, developers and users can retrieve lists of countries, states, document types, and other essential verification-related parameters.

* **Endpoint**: `/api/v2/customer/business/verificationparameters`
* **Method**: `GET`

## Get managed verification form data, and details of customer's document upload status

> Query Parameters:
> \
> \- CustomersId - Id of managed customer
> \\
>
> \
> Response:
> \
> \- countries: list of available countries
> \
> \- states: list of available states
> \
> \- mainActivityTypes: list of main activity types
> \
> \- sourceFundTypes: list of source fund types
> \
> \- transactionVolumes: list of transaction volume types
> \
> \- monthlyUsdEquivalents: list of monthly USD equivalents types
> \
> \- uBOReportingExemptions: list of UBO reporting exemptions
> \
> \- regionsOfOperation: list of regions of operations
> \
> \- entityTypes: list of business entity types
> \
> \- documents: Details about customer's document upload status
> \
> \- additionalDocuments: Details about customer's additional supporting document upload status
> \
> Possible validation errors:
> \
> \- Required
> \
> \- Unauthorized - Managed customer must be managed by user

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"BusinessV2Module"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"CustomerRole.BusinessV2Module.FormDataDto":{"type":"object","properties":{"countries":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.Country"},"nullable":true},"states":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.State"},"nullable":true},"mainActivityTypes":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.MainActivityType"},"nullable":true},"sourceFundTypes":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.SourceFundType"},"nullable":true},"documents":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.Document"},"nullable":true},"additionalDocuments":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.Document"},"nullable":true},"transactionVolumes":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.TransactionVolumeType"},"nullable":true},"monthlyUsdEquivalents":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.MonthlyUsdEquivalentType"},"nullable":true},"uboReportingExemptions":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.UBOReportingExemptionType"},"nullable":true},"regionsOfOperation":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.RegionOfOperationType"},"nullable":true},"entityTypes":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.EntityTypesDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.Country":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"countryName":{"type":"string","nullable":true},"isoCode":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.State":{"type":"object","properties":{"countriesID":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true},"ansiCode":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.MainActivityType":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.SourceFundType":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.Document":{"type":"object","properties":{"bRequired":{"type":"boolean"},"documentTypesId":{"type":"integer","format":"int32"},"documentNotes":{"type":"string","nullable":true},"documentStatus":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"fileName":{"type":"string","nullable":true},"bSingleUploadOnly":{"type":"boolean"}},"additionalProperties":false},"CustomerRole.BusinessV2Module.TransactionVolumeType":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.MonthlyUsdEquivalentType":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.UBOReportingExemptionType":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.RegionOfOperationType":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV2Module.EntityTypesDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"name":{"type":"string","nullable":true}},"additionalProperties":false},"Results.Base.BaseResultDto":{"type":"object","properties":{"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/api/v2/customer/business/verificationparameters":{"get":{"tags":["BusinessV2Module"],"summary":"Get managed verification form data, and details of customer's document upload status","description":"Query Parameters:\r\n- CustomersId - Id of managed customer\r\n\r\nResponse:\r\n- countries: list of available countries\r\n- states: list of available states\r\n- mainActivityTypes: list of main activity types\r\n- sourceFundTypes: list of source fund types\r\n- transactionVolumes: list of transaction volume types\r\n- monthlyUsdEquivalents: list of monthly USD equivalents types\r\n- uBOReportingExemptions: list of UBO reporting exemptions\r\n- regionsOfOperation: list of regions of operations\r\n- entityTypes: list of business entity types\r\n- documents: Details about customer's document upload status\r\n- additionalDocuments: Details about customer's additional supporting document upload status\r\nPossible validation errors:\r\n- Required\r\n- Unauthorized - Managed customer must be managed by user","operationId":"GET-api-v2-customer-business-verificationparameters","parameters":[{"name":"customersId","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV2Module.FormDataDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.Base.BaseResultDto"}}}}}}}}}
```

**Request Parameters**

* **`customersId`** (Integer, Required): The ID of the customer whose verification parameters are to be retrieved.

**Response Body Types**

The response consists of several arrays that include:

* **`countries`** (JSON Array): Contains objects with necessary details for countries, including:
  * **`id`** (Integer): ID of the country.
  * **`countryName`** (String): Name of the country.
  * **`isoCode`** (ISO 3166-1 alpha-3 String): 3-letter country ISO code.
* **`states`** (JSON Array): Contains objects with state-specific information:
  * **`countriesID`** (Integer): ID of the state’s country.
  * **`name`** (String): Name of the state.
  * **`ansiCode`** (String): ANSI code for US states and equivalent for others.
* **`mainActivityTypes`**, **`sourceFundTypes`**, **`transactionVolumes`**, **`monthlyUsdEquivalents`**, **`uboReportingExemptions`**, **`regionsOfOperation`** , **`entityTypes`** (JSON Arrays): Lists main business activity, source fund, transaction volume, monthly USD equivalents, UBO reporting exemptions, regions of operation and business entity types required for verification.
  * **`id`** (Integer): Identifier for the type.
  * **`name`** (String): Name of the type.
* **`documents`** (JSON Array): Contains objects with necessary details for document upload, including:
  * **`bRequired`** (Bool): True if required for verification
  * **`DocumentTypesId`** (Integer): Id of Document Type
  * **`DocumentNotes`** (String): Description of document type
  * **`DocumentStatus`** (String): Status of Customer's document:
    * Not Submitted
    * Checking
    * Approved
    * Expired
    * Rejected
  * **`Filename`** (String): Filename of uploaded document
  * **`Name`** (String): Name of document type
* **`AdditionalDocuments`** (JSON Array): Contains objects with additional supporting documents for document upload, including:
  * **`bRequired`** (Bool): True if required for verification
  * **`DocumentTypesId`** (Integer): Id of Document Type
  * **`DocumentNotes`** (String): Description of document type
  * **`DocumentStatus`** (String): Status of Customer's document:
    * Not Submitted
    * Checking
    * Approved
    * Expired
    * Rejected
  * **`Filename`** (String): Filename of uploaded document
  * **`Name`** (String): Name of document type

**Example of a Successful Response:**

```json
{
    "id": 10030,
    "details": {
        "countries": [
            {
                "id": 1001,
                "countryName": "United States",
                "isoCode": "USA"
            }
        ],
        "states": [
            {
                "countriesID": 1001,
                "name": "Alabama",
                "ansiCode": "AL"
            }
        ],
        "mainActivityTypes": [
            {
                "id": 1009,
                "name": "Accommodation and Food Services"
            }
        ],
        "sourceFundTypes": [
            {
                "id": 1006,
                "name": "Business Income"
            }
        ],
        "documents": [
            {
                "bRequired": true,
                "documentTypesId": 1001,
                "documentNotes": "Any utility bill, bank statement or similar proof of address within the last 3 months",
                "documentStatus": "0",
                "name": "Proof of Address",
                "fileName": null,
                "bSingleUploadOnly": true
            }
        ],
        "additionalDocuments": [
            {
                "bRequired": true,
                "documentTypesId": 1003,
                "documentNotes": "Any utility bill, bank statement or similar proof of address within the last 3 months",
                "documentStatus": "Not Submitted",
                "name": "Significant Parties Proof of Address",
                "fileName": null,
                "bSingleUploadOnly": false
            }
        ],
        "transactionVolumes": [
            {
                "id": 1000,
                "name": "Less than 10"
            }
        ],
        "monthlyUsdEquivalents": [
            {
                "id": 1000,
                "name": "1 to 100,000"
            }
        ],
        "uboReportingExemptions": [
            {
                "id": 1000,
                "name": "Securities reporting issuer"
            }
        ],
        "regionsOfOperation": [
            {
                "id": 1000,
                "name": "North America"
            }
        ],
        "entityTypes": [
            {
                "id": 1003,
                "name": "Corporation"
            }
        ]
    },
    "status": "1",
    "errors": []
}
```

***

### Upload Business Document

The **Upload Business Document** endpoint allows businesses to upload documents that are necessary for the verification process of the business account. This endpoint plays a crucial role in fulfilling the document submission requirements for account verification, including proofs of address, identity, operational licenses, and other significant documentation.

* **Endpoint**: `/api/v1/customer/business/uploaddocument`
* **Method**: `POST`
* **Content-Type:** `multipart/form-data`
  * This endpoint requires the 'Content-Type' to be set to 'multipart/form-data' due to the file upload requirement.

## POST /api/v1/customer/business/uploaddocument

>

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"BusinessModule"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"Results.ResultDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false},"Results.Base.BaseResultDto":{"type":"object","properties":{"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false}}},"paths":{"/api/v1/customer/business/uploaddocument":{"post":{"tags":["BusinessModule"],"operationId":"POST-api-v1-customer-business-uploaddocument","parameters":[{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"documentId":{"type":"integer","format":"int32"},"bAdditionalDocument":{"type":"boolean"},"customersId":{"type":"integer","format":"int32"},"note":{"type":"string"},"file":{"type":"string","description":"Base 64 encoded JPEG or PNG data\r\nMax 10MB","format":"binary"}}},"encoding":{"documentId":{"style":"form"},"bAdditionalDocument":{"style":"form"},"customersId":{"style":"form"},"note":{"style":"form"},"file":{"style":"form"}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ResultDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.Base.BaseResultDto"}}}}}}}}}
```

#### **Form Parameters**

* **`customersId`** (Integer): The ID of the business customer for whom the document is being uploaded. This identifier ensures that the document is associated with the correct account.
* **`bAdditionalDocument`** (Boolean): A flag to indicate if the document being uploaded is an additional document not explicitly required but submitted to aid in the verification process. This can be useful for providing extra evidence to expedite verification.
* **`documentId`** (Integer): The ID referencing the type of document being uploaded, as defined by the verification parameters provided by the [`/verificationparameters`](#get-parameters-for-business-verification) endpoint.
* **`file`** (File): The document file to be uploaded. The request should use multipart file upload to include the actual document file.
* **`note`** (String, Optional): Any additional notes or comments that should accompany the document being uploaded. This can provide context or additional information relevant to the document.

**Response Format**

* **application/json**: The response data is provided in JSON format.

**Success Response Example**

```json
{
  "id": 12413,
  "status": "1",
  "errors": []
}
```

This response indicates that the document upload was successful, with `"status": "1"` denoting a successful operation and an empty `"errors"` array signifying no errors occurred during the process.

| Error Message Code       | Description                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| Required                 | Named field missing, null or empty                                                                                              |
| Unauthorized             | User is not permitted to edit Customer’s files                                                                                  |
| Invalid\_FileName        | File not found                                                                                                                  |
| Invalid\_DocumentTypesID | Valid document types available at [/api/v1/customer/business/verificationparameters](#get-parameters-for-business-verification) |

***

### Get Business Verification Status

The **Get Business Verification Status** endpoint of the Customer API retrieves the current verification status of a business customer.

**Endpoint Description**

* **Endpoint**: `/api/v1/customer/businesses/getverificationstatus`
* **Method**: `GET`
* **Query Parameters**:
  * `customersId` (Integer): Identifier of the managed business customer. This parameter is required.

## Get managed customer's business verification status

> Query Parameters:
> \
> \- CustomersId - Id of managed customer
> \\
>
> \
> Response:
> \
> \- businessVerificationStep -- NotStarted, InProgress, Submitted or Verified
> \
> \- documents - verification document statuses
> \
> \- additionalDocuments - additional supporting document statuses
> \
> Possible validation errors:
> \
> \- Required
> \
> \- Unauthorized - Managed customer must be managed by user

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"BusinessModule"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"Results.ObjectResultDto_CustomerRole.BusinessModule.VerificationStatusDto":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"details":{"$ref":"#/components/schemas/CustomerRole.BusinessModule.VerificationStatusDto"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.BusinessModule.VerificationStatusDto":{"type":"object","properties":{"businessVerificationStep":{"$ref":"#/components/schemas/BusinessVerificationStepTypes"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessModule.BusinessDocumentDto"},"nullable":true},"additionalDocuments":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessModule.BusinessFormDocumentDto"},"nullable":true}},"additionalProperties":false},"BusinessVerificationStepTypes":{"enum":["NotStarted","InProgress","Submitted","Verified"],"type":"string"},"CustomerRole.BusinessModule.BusinessDocumentDto":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"bUploaded":{"type":"boolean"},"bRejected":{"type":"boolean"},"bVerified":{"type":"boolean"},"documentStatus":{"type":"string","nullable":true},"uploadNotes":{"type":"string","nullable":true},"documentId":{"type":"integer","format":"int32"},"rejectionReason":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessModule.BusinessFormDocumentDto":{"type":"object","properties":{"filename":{"type":"string","nullable":true},"bUploaded":{"type":"boolean"},"bRejected":{"type":"boolean"},"bVerified":{"type":"boolean"},"documentStatus":{"type":"string","nullable":true},"uploadNotes":{"type":"string","nullable":true},"documentId":{"type":"integer","format":"int32"},"rejectionReason":{"type":"string","nullable":true}},"additionalProperties":false},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false},"Results.Base.BaseResultDto":{"type":"object","properties":{"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false}}},"paths":{"/api/v1/customer/business/getverificationstatus":{"get":{"tags":["BusinessModule"],"summary":"Get managed customer's business verification status","description":"Query Parameters:\r\n- CustomersId - Id of managed customer\r\n\r\nResponse:\r\n- businessVerificationStep -- NotStarted, InProgress, Submitted or Verified\r\n- documents - verification document statuses\r\n- additionalDocuments - additional supporting document statuses\r\nPossible validation errors:\r\n- Required\r\n- Unauthorized - Managed customer must be managed by user","operationId":"GET-api-v1-customer-business-getverificationstatus","parameters":[{"name":"customersId","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ObjectResultDto_CustomerRole.BusinessModule.VerificationStatusDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.Base.BaseResultDto"}}}}}}}}}
```

**Response Body Types**

* **status** (Integer): Indicates the operation's success (`1`) or failure (`0`).
* **errors** (String array): List of errors if the operation fails.
* **details** (Object):
  * **businessVerificationStep** (String): The current verification step such as `Not Started`, `In Progress`, `Submitted`, `Verified`.
  * **documents** (Array): Details about documents uploaded.
    * **fileName** (String): Name of the file.
    * **bUploaded** (Bool): True if the document is uploaded.
    * **bRejected** (Bool): True if the document is rejected.
    * **bVerified** (Bool): True if the document is verified.
    * **documentStatus** (String): Status of the document e.g., `Not Submitted`, `Checking`, `Approved`.
    * **uploadNotes** (String): Notes associated with the document upload.
    * **documentId** (Integer): Identifier of the Document Type.
    * **rejectionReason** (String): Reason for document rejection, if any.
* **additionalDocuments** (Array): Similar structure to `documents` for additional documents submitted.

**Example of a Successful Response**

```json
{
  "id": 13830,
  "details": {
    "businessVerificationStep": "InProgress",
    "documents": [
      {
        "fileName": null,
        "bUploaded": false,
        "bRejected": false,
        "bVerified": false,
        "documentStatus": "Not Submitted",
        "uploadNotes": null,
        "documentId": 1000,
        "rejectionReason": null
      }
    ],
    "additionalDocuments": [
      {
        "fileName": "examplepdf.pdf",
        "bUploaded": true,
        "bRejected": false,
        "bVerified": false,
        "documentStatus": "Checking",
        "uploadNotes": null,
        "documentId": 1000,
        "rejectionReason": null
      }
    ]
  },
  "status": "1",
  "errors": []
}
```

**Possible Error Message Codes**

* **Unauthorized**: The user is not permitted to use the endpoint.
* **Required**: Named field missing, null or empty
* **Invalid\_CustomersId**: The `customersId` parameter is invalid.
* **Business\_Account\_Not\_Found**: No business account found for the given `customersId`.

***

### Delete Business Document

This section documents the `Delete Business Document` endpoint of the Customer API, used for removing a verification document associated with a business customer.

**Endpoint Description**

* **Endpoint**: `/api/v1/customer/business/deletedocument`
* **Method**: `POST`
* **Content-Type**: `application/json`

## POST /api/v1/customer/business/deletedocument

>

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"BusinessModule"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"CustomerRole.BusinessModule.DeleteDocumentDto":{"required":["bAdditionalDocument","customersId","documentId","filename"],"type":"object","properties":{"documentId":{"type":"integer","format":"int32"},"bAdditionalDocument":{"type":"boolean"},"customersId":{"type":"integer","format":"int32"},"filename":{"minLength":1,"type":"string"}},"additionalProperties":false},"Results.ResultDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false},"Results.Base.BaseResultDto":{"type":"object","properties":{"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false}}},"paths":{"/api/v1/customer/business/deletedocument":{"post":{"tags":["BusinessModule"],"operationId":"POST-api-v1-customer-business-deletedocument","parameters":[{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessModule.DeleteDocumentDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessModule.DeleteDocumentDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessModule.DeleteDocumentDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessModule.DeleteDocumentDto"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ResultDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.Base.BaseResultDto"}}}}}}}}}
```

**Request Body Parameters**

* **customersId** (Integer): Identifier of the managed business customer. This parameter is required.
* **documentId** (Integer): Identifier of the document to be deleted. This parameter is required.
* **filename** (String): Name of the file to delete. This parameter is required.
* **bAdditionalDocument** (Bool): Indicates whether the document is listed in the additional documents list in `verificationparameters` response. This parameter is required.

**Request Body Example**

```json
{
  "bAdditionalDocument": false,
  "customersId": 13830,
  "documentId": 1000,
  "filename": "examplepdf.pdf"
}
```

**Success Response Body Types**

* **status** (Integer): Indicates the operation's success (`1`) or failure (`0`).
* **errors** (String array): List of errors if the operation fails.
* **details** (Object):
  * **bSuccess** (Bool): True if the document was successfully deleted.

**Example of a Successful Response**

```json
{
  "id": 1,
  "details": {
    "bSuccess": true,
    "details": null,
    "errors": []
  },
  "status": "1",
  "errors": []
}
```

**Possible Error Message Codes**

* **Unauthorized**: The user is not permitted to use the endpoint.
* **Required**: Named field missing, null or empty
* **Invalid\_FileName**: Indicated an issue with the file name provided.
* **Invalid\_DocumentTypesID**: The `documentId` provided is not valid.
* **Invalid\_FileSize**: The file size exceeds the maximum limit allowed.

***

### Submit Business Verification

The **Submit Business Verification** endpoint is designed for submitting the comprehensive verification details of a business customer. This involves critical information relating to the company's ownership structure, main business activities, capital, investments, and anticipated activity, among others. This information is crucial for the completion of the business verification process.

* **Endpoint**: `/api/v3/customer/business/submitverification`
* **Method**: `POST`

## POST /api/v3/customer/business/submitverification

>

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"BusinessV3Module"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"CustomerRole.BusinessV3Module.VerificationFormDto":{"required":["customersID","terms"],"type":"object","properties":{"customersID":{"type":"integer","format":"int32"},"registrationInformation":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.RegistrationInformationDto"},"operationsInformation":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.OperationsInformationDto"},"ownerInformation":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.OwnerInformationDto"},"terms":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.TermsDto"},"documentsUpload":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.DocumentsUploadDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV3Module.RegistrationInformationDto":{"required":["addressCity","addressCountry","addressNumber","addressPostCode","addressState","addressStreet","doingBusinessAs","entityName","entityTypesID","registrationDate","registrationNumber","taxNumber"],"type":"object","properties":{"entityName":{"minLength":1,"type":"string"},"entityTypesID":{"type":"integer","format":"int32"},"entityTypesOther":{"description":"Required when the selected entity type is \"Other\".","type":"string","nullable":true},"registrationDate":{"type":"string","format":"date-time"},"registrationNumber":{"minLength":1,"type":"string"},"taxNumber":{"minLength":1,"type":"string"},"doingBusinessAs":{"minLength":1,"type":"string"},"addressStreet":{"minLength":1,"type":"string"},"addressNumber":{"minLength":1,"type":"string"},"addressPostCode":{"minLength":1,"type":"string"},"addressCity":{"minLength":1,"type":"string"},"addressState":{"minLength":1,"type":"string"},"addressCountry":{"minLength":1,"type":"string"},"operatingAddressStreet":{"description":"Part of the operating (trading) address. Optional individually, but if any operating-address field is supplied then the full operating address (street, number, post code, city, state, country) becomes required.","type":"string","nullable":true},"operatingAddressNumber":{"description":"Part of the operating (trading) address. Optional individually, but if any operating-address field is supplied then the full operating address (street, number, post code, city, state, country) becomes required.","type":"string","nullable":true},"operatingAddressPostCode":{"description":"Part of the operating (trading) address. Optional individually, but if any operating-address field is supplied then the full operating address (street, number, post code, city, state, country) becomes required.","type":"string","nullable":true},"operatingAddressCity":{"description":"Part of the operating (trading) address. Optional individually, but if any operating-address field is supplied then the full operating address (street, number, post code, city, state, country) becomes required.","type":"string","nullable":true},"operatingAddressState":{"description":"Part of the operating (trading) address. Optional individually, but if any operating-address field is supplied then the full operating address (street, number, post code, city, state, country) becomes required.","type":"string","nullable":true},"operatingAddressCountry":{"description":"Part of the operating (trading) address. Optional individually, but if any operating-address field is supplied then the full operating address (street, number, post code, city, state, country) becomes required.","type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV3Module.OperationsInformationDto":{"required":["activeBanks","bLicenseRequired","bPubliclyListed","businessActivityIds","monthlyUsdValueId","operationRegionIds","sourceOfFundsIds","yearlyTransactionsId"],"type":"object","properties":{"webAddress":{"maxLength":100,"type":"string","nullable":true},"phoneNumber":{"pattern":"^(\\+?\\d+)?\\s?(\\(\\d+\\))?\\s?(\\d+-\\d+)?$","type":"string","format":"tel","nullable":true},"supportEmail":{"maxLength":100,"type":"string","nullable":true},"bPubliclyListed":{"minLength":1,"type":"string"},"ticker":{"description":"Required when bPubliclyListed is \"Yes\" (publicly listed businesses).","type":"string","nullable":true},"exchanges":{"description":"Required when bPubliclyListed is \"Yes\" (publicly listed businesses).","type":"string","nullable":true},"operationRegionIds":{"type":"array","minItems":1,"items":{"type":"integer","format":"int32"}},"bLicenseRequired":{"minLength":1,"type":"string"},"additionalLicensingInfo":{"type":"string","nullable":true},"primaryRegulator":{"type":"string","nullable":true},"licenseNumber":{"type":"string","nullable":true},"financialInstitutionFormFileName":{"type":"string","nullable":true},"businessActivityIds":{"type":"array","minItems":1,"items":{"type":"integer","format":"int32"}},"web3ChainsAndAddresses":{"type":"string","nullable":true},"sourceOfFundsIds":{"type":"array","minItems":1,"items":{"type":"integer","format":"int32"}},"sourceOfFundsOther":{"description":"Required when an \"Other\" option is selected in sourceOfFundsIds.","type":"string","nullable":true},"activeBanks":{"minLength":1,"type":"string"},"yearlyTransactionsId":{"type":"integer","format":"int32"},"monthlyUsdValueId":{"type":"integer","format":"int32"}},"additionalProperties":false},"CustomerRole.BusinessV3Module.OwnerInformationDto":{"required":["authorizedSigner"],"type":"object","properties":{"exemptionId":{"description":"Optional UBO reporting exemption. When set (an exemption is claimed) beneficial owners must NOT be supplied; when null, beneficial owners are required.","type":"integer","format":"int32","nullable":true},"businessBeneficialOwners":{"description":"Required when no UBO exemption is claimed (exemptionId is null); must be omitted when exemptionId is set. For each entry these are required: number, guid, entityName, entityTypesID (plus entityTypesOther when the type is \"Other\"), registrationDate, registrationNumber, taxNumber, doingBusinessAs, and the full registered address (operating address required when it differs).","type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.BusinessBeneficialOwnersDto"},"nullable":true},"individualBeneficialOwners":{"description":"Required when no UBO exemption is claimed (exemptionId is null); must be omitted when exemptionId is set. For each entry these are required: number, guid, firstName, lastName, title, dateOfBirth, nationality, email, phoneNumber, country, ssn, stateProvince, city, addressLine1, postcode, percentageSharesOwned, position, bControllingParty, proofOfAddressFilename.","type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.IndividualBeneficialOwnersDto"},"nullable":true},"beneficialOwnersStructure":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.OwnershipTreeDto"},"nullable":true},"authorizedSigner":{"minLength":1,"type":"string"},"bConfirmAboveTen":{"type":"boolean","nullable":true},"metadata":{"nullable":true,"readOnly":true}},"additionalProperties":false},"CustomerRole.BusinessV3Module.BusinessBeneficialOwnersDto":{"type":"object","properties":{"number":{"type":"integer","format":"int32","nullable":true},"guid":{"type":"string","nullable":true},"entityName":{"type":"string","nullable":true},"entityTypesID":{"type":"integer","format":"int32","nullable":true},"entityTypesOther":{"type":"string","nullable":true},"registrationDate":{"type":"string","format":"date-time","nullable":true},"registrationNumber":{"type":"string","nullable":true},"taxNumber":{"type":"string","nullable":true},"doingBusinessAs":{"type":"string","nullable":true},"addressStreet":{"type":"string","nullable":true},"addressNumber":{"type":"string","nullable":true},"addressPostCode":{"type":"string","nullable":true},"addressCity":{"type":"string","nullable":true},"addressState":{"type":"string","nullable":true},"addressCountry":{"type":"string","nullable":true},"operatingAddressStreet":{"type":"string","nullable":true},"operatingAddressNumber":{"type":"string","nullable":true},"operatingAddressPostCode":{"type":"string","nullable":true},"operatingAddressCity":{"type":"string","nullable":true},"operatingAddressState":{"type":"string","nullable":true},"operatingAddressCountry":{"type":"string","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV3Module.IndividualBeneficialOwnersDto":{"type":"object","properties":{"number":{"type":"integer","format":"int32","nullable":true},"guid":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"dateOfBirth":{"type":"string","format":"date-time","nullable":true},"nationality":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phoneNumber":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"ssn":{"type":"string","nullable":true},"stateProvince":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"postcode":{"type":"string","nullable":true},"proofOfAddressFilename":{"type":"string","description":"Max 10MB","nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV3Module.OwnershipTreeDto":{"type":"object","properties":{"bIsBusiness":{"type":"boolean","nullable":true},"ownersGuid":{"type":"string","nullable":true},"percentageOwned":{"type":"number","format":"double"},"bControllingParty":{"type":"boolean","nullable":true},"positionAtCompany":{"type":"string","nullable":true},"children":{"type":"array","items":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.OwnershipTreeDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.BusinessV3Module.TermsDto":{"required":["bAcceptTerms","bConfirmTrueAndCorrect","bFatcaAcknowledgement","bTaxAcknowledgement"],"type":"object","properties":{"bTaxAcknowledgement":{"type":"boolean"},"bFatcaAcknowledgement":{"type":"boolean"},"bConfirmTrueAndCorrect":{"type":"boolean"},"bAcceptTerms":{"type":"boolean"}},"additionalProperties":false},"CustomerRole.BusinessV3Module.DocumentsUploadDto":{"type":"object","properties":{"documentTypesID":{"type":"integer","format":"int32","nullable":true},"fileName":{"type":"string","nullable":true},"metadata":{"nullable":true,"readOnly":true}},"additionalProperties":false},"CustomerRole.BusinessV3Module.SubmitFormResponseDto":{"type":"object","properties":{"customersId":{"type":"integer","format":"int32"},"businessVerificationStep":{"type":"string","nullable":true}},"additionalProperties":false},"Results.Base.BaseResultDto":{"type":"object","properties":{"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false}}},"paths":{"/api/v3/customer/business/submitverification":{"post":{"tags":["BusinessV3Module"],"summary":"","operationId":"POST-api-v3-customer-business-submitverification","parameters":[{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.VerificationFormDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.VerificationFormDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.VerificationFormDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.VerificationFormDto"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.BusinessV3Module.SubmitFormResponseDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.Base.BaseResultDto"}}}}}}}}}
```

**Request Body Parameters:**

* **`customersID`** (Integer): Id of the managed business account
* **`registrationInformation`** (JSON Object): Contains registration details for the business
  * **`entityName`** (String, Required): Legal name of entity
  * **`entityTypesID`** (Integer, Required): Type of business entity
  * **`entityTypeOther`** (String): Type of business entity if the type 'Other' is specified in as entityTypesID
  * **`registrationDate`** (Datetime, Required): Date of business registration
  * **`registrationNumber`** (String, Required): Official registration number
  * **`taxNumber`** (String, Required): Tax ID number
  * **`doingBusinessAs`** (String, Required): List of all business names
  * **`addressStreet`** (String, Required): Registered address street
  * **`addressNumber`** (String, Required): Registered address unit number
  * **`addressPostCode`** (String, Required): Registered address zip/postal code
  * **`addressCity`** (String, Required): Registered address city
  * **`addressState`** (String, Required): Registered address state/county/province as applicable
  * **`addressCountry`** (String, Required): Registered address country code
  * **`operatingAddressStreet`** (String): Operating address street. Required if any other operating address field is entered
  * **`operatingAddressNumber`** (String): Operating address unit number. Required if any other operating address field is entered
  * **`operatingAddressPostCode`** (String): Operating address zip/postal code. Required if any other operating address field is entered
  * **`operatingAddressCity`** (String): Operating address city. Required if any other operating address field is entered
  * **`operatingAddressState`** (String): Operating address state/county/province as applicable. Required if any other operating address field is entered
  * **`operatingAddressCountry`** (String): Operating address country code. Required if any other operating address field is entered
* **`operationsInformation`** (JSON Object): Contains operations details for the entity
  * **`webAddress`** (String): Website address of entity
  * **`phoneNumber`** (String): Business phone number
  * **`supportEmail`** (String): Business support email
  * **`bPubliclyListed`** (String, Required): Is the business publicly listed. Value must be "Yes", "No" or "NA"
  * **`ticker`** (String): Trading symbol of the listed company. Required if publicly listed
  * **`exhcanges`** (String): Exchange(s) where company is listed
  * **`operationRegionIds`** (Integer Array, Required): Regions of business operations
  * **`bLicenseRequired`** (String, Required): Does the business require a license. Value must be "Yes", "No" or "NA"
  * **`additionalLicensingInfo`** (String): Additional licensing information
  * **`financialInstitutionFormFileName`** (String): File name of financial institution form
  * **`businessActivityIds`** (Integer Array, Required): Main business activity types
  * **`web3ChainsAndAddresses`** (String): If the entity uses Web3 for transactions, any blockchain and blockchain addresses
  * **`sourceOfFundsIds`** (Integer Array, Required): Source of funds types
  * **`sourceOfFundsOther`** (String): Other source of fund type. Required if 'Other' source fund type is chosen.
  * **`activeBanks`** (String, Required): Name of bank(s) for which the business currently holds an active account
  * **`yearlyTransactionsId`** (Integer, Required): Anticipated yearly number of transactions type
  * **`monthlyUsdValueId`** (Integer, Required): Anticipated monthly US dollar equivalent
* **`ownerInformation`** (JSON Object): Contains information about beneficial owners of the business
  * exemptionId (Integer): UBO Exemption type, if applicable.
  * authorizedSigner (String, Required): An individual that is an authorized signer for the organisation
  * bConfirmAboveTen (Boolean): Confirmation that applicant has included all beneficial owners with 10% or more ownership.
  * **`individualBeneficialOwners`** (JSON Object, all elements are required. At least one controlling party is required, unless the entity has a UBO exemption): Contains objects with necessary details for Significant Parties - all beneficial owners and/or control persons
    * **`number`** (Integer): Individual beneficial owner number. Should be numbered 1 to N, where N is the number of individual beneficial owners in total
    * **`guid`**(String): Individual beneficial owner guid. Used to identify individual beneficial owner in beneficialOwnersStructure object.
    * **`firstName`** (String): First name
    * **`lastName`** (String): Last name
    * **`title`** (String): Title of individual
    * **`dateOfBirth`** (Date): Date of Birth in format ‘yyyy-mm-dd’.
    * **`nationality`** (String, Country ISO Code, 3 letters - ISO 3166-1 alpha-3): Nationality country
    * **`email`** (String): Individual's email address
    * **`phoneNumber`** (String): Phone number, must include country code
    * **`country`** (String, Country ISO Code, 3 letters - ISO 3166-1 alpha-3): Country of individual's current citizenship
    * **`ssn`** (String): SSN/ Tax Id Number
    * **`stateProvince`** (String, For USA, use ISO 3166-2:US code. E.g. US-FL): State or Province
    * **`city`** (String)
    * **`addressLine1`** (String): Address Line 1
    * **`addressLine2`** (String, Optional): Address Line 2
    * **`postcode`** (String): Postcode or ZIP code
    * **`proofOfAddressFileName`** (String): Proof of address filename. File should be uploaded via [uploaddocument](#upload-business-document), using documentId matching ‘Significant Parties Proof of Address’.
  * **`businessBeneficialOwners`** (JSON Object): Contains objects with necessary details for all entities which are beneficial owners
    * **`number`** (Integer): Business beneficial owner number. Should be numbered 1 to N, where N is the number of business beneficial owners in total
    * **`guid`**(String): Business beneficial owner guid. Used to identify business beneficial owner in beneficialOwnersStructure object.
    * **`entityName`** (String, Required): Legal name of entity
    * **`entityTypesID`** (Integer, Required): Type of business entity
    * **`registrationDate`** (Datetime, Required): Date of business registration
    * **`registrationNumber`** (String, Required): Official registration number
    * **`taxNumber`** (String, Required): Tax ID number
    * **`doingBusinessAs`** (String, Required): List of all business names
    * **`addressStreet`** (String, Required): Registered address street
    * **`addressNumber`** (String, Required): Registered address unit number
    * **`addressPostCode`** (String, Required): Registered address zip/postal code
    * **`addressCity`** (String, Required): Registered address city
    * **`addressState`** (String, Required): Registered address state/county/province as applicable
    * **`addressCountry`** (String, Required): Registered address country code
    * **`operatingAddressStreet`** (String): Operating address street. Required if any other operating address field is entered
    * **`operatingAddressNumber`** (String): Operating address unit number. Required if any other operating address field is entered
    * **`operatingAddressPostCode`** (String): Operating address zip/postal code. Required if any other operating address field is entered
    * **`operatingAddressCity`** (String): Operating address city. Required if any other operating address field is entered
    * **`operatingAddressState`** (String): Operating address state/county/province as applicable. Required if any other operating address field is entered
    * **`operatingAddressCountry`** (String): Operating address country code. Required if any other operating address field is entered
  * **`beneficialOwnersStructure`** (JSON Array): A list of objects of type [OwnershipTreeDto](#ownershiptreedto), representing the direct beneficial owners of the onboarding business. Required unless a UBO Exemption is given.
* **`documentsUpload`** (JSON Array): Document Upload
  * **`DocumentTypesID`** (Integer, Required)
  * **`FileName`** (String, Required): Name of file
* **`terms`** (JSON Object): Customer's confirmation
  * **bTaxAcknowledgement** (Boolean, Required): Indicates whether customer agrees to "I confirm that the entity applying for the account is up to date and compliant with all applicable tax laws and regulations for which the entity would be responsible"
  * **bFatcaAcknowledgement** (Boolean, Required): Indicates whether customer agrees to "I do confirm that I am in full compliance with the Foreign Account Tax Compliance Act (FATCA)"
  * **bConfirmTrueAndCorrect** (Boolean, Required): Indicates whether customer agrees to "I confirm that the information provided is true and correct. I will notify, in writing, any changes to the information provided. I am aware that all or part of the information provided in this questionnaire may be transferred to the tax administrator or to any other institution in accordance with international treaties or agreements, as well as the United States regarding automated exchange of information on financial accounts"
  * **bAcceptTerms** (Boolean, Required): Indicates whether customer agrees to "I agree to use the services of Ibanera LLC only for legitimate purposes. I acknowledge that false or incorrect information provided could require reports to regulators or law enforcement resulting in termionation of business relations"

#### OwnershipTreeDto

* **`bIsBusiness`**(Boolean, Required) True if owner is a business/entity, false if owner is an individual.
* **`ownersGuid`** (String, Required) Must match a guid from businessBeneficialOwners or individualBeneficialOwners according whether bIsBusiness is true or false.
* **`percentageOwned`** (Decimal, Required): Percentage Shares Owned
* **`position`** (String): Individual's position in the company. Required if owner is an individual, must be null otherwise.
* **`bControllingParty`** (Boolean): True if the individual is the controlling party. Required if owner is an individual, must be null otherwise.
* **`children`**(JSON Array): A list of objects of type [OwnershipTreeDto](#ownershiptreedto), representing the direct beneficial owners of the owner business. Must be null if the owner is an individual

**Beneficial Owners Structure Validation**

Validation errors pertaining to an object in Benefical Owners Structure will be referenced by a path of the form BeneficialOwnersStructure\[i].Children\[j].**...**.Children\[k] using zero-indexing to identify the specific object in BeneficialOwnersStructure.

<table><thead><tr><th>FieldName</th><th width="249">Message Code</th><th>Description</th></tr></thead><tbody><tr><td>OwnerInformation.BeneficialOwnersStructure</td><td>GUIDs must be distinct</td><td>GUIDs of the top level objects in beneficialOwnersStructure must be distinct</td></tr><tr><td>OwnerInformation.[[Path]].Children</td><td>GUIDs must be distinct</td><td>GUIDs of the top level objects in children must be distinct</td></tr><tr><td>OwnerInformation.[[Path]].bIsBusiness</td><td>Required</td><td>bIsBusiness must be true or false</td></tr><tr><td>OwnerInformation.[[Path]].OwnersGuid</td><td>Not Found</td><td>OwnersGuid not found on list of business/individual owners</td></tr><tr><td>OwnerInformation.[[Path]].OwnersGuid</td><td>Invalid</td><td>Every beneficial business owner should occur at least once in the ownership tree with Children not null</td></tr><tr><td>OwnerInformation.[[Path]].OwnersGuid</td><td>Repeated Children</td><td>Every beneficial business owner should occur at most once in the ownership tree with Children not null</td></tr><tr><td>OwnerInformation.[[Path]].OwnersGuid</td><td>Business cannot be direct owner of itself</td><td>A business cannot appear in BeneficialOwnersStructure as a direct child of itself</td></tr><tr><td>OwnerInformation.[[Path]].PercentageOwned</td><td>PercentageOwned must be between 0 and 100</td><td>PercentageOwned must be between 0 and 100</td></tr><tr><td>OwnerInformation.[[Path]].bControllingParty</td><td>Required</td><td>bControllingParty is required for individual owners</td></tr><tr><td>OwnerInformation.[[Path]].bControllingParty</td><td>Invalid</td><td>bControllingParty must be null for business owners</td></tr><tr><td>OwnerInformation.[[Path]].PositionAtCompany</td><td>Required</td><td>PositionAtCompany is required for individual owners</td></tr><tr><td>OwnerInformation.[[Path]].PositionAtCompany</td><td>Invalid</td><td>PositionAtCompany must be null for business owners</td></tr><tr><td>OwnerInformation.[[Path]].Children</td><td>Invalid</td><td>Children must be null for individual owners</td></tr><tr><td>OwnerInformation.[[Path]].Children</td><td>A controlling party is required</td><td>At least one object in Children should be have bControllingParty as true</td></tr></tbody></table>

#### Submit Business Verification Request Body JSON Example

{% code fullWidth="true" %}

```json
{
   "customersID": 14347,
  "registrationInformation": {
    "entityName": "Solid State Account Company",
    "entityTypesID": 1003,
    "entityTypeOther": null,
    "registrationDate": "2000-01-01",
    "registrationNumber": "123456789",
    "taxNumber": "123456789",
    "doingBusinessAs": "Auxiliary Wireless Company",
    "addressStreet": "747 Prosacco Stravenue",
    "addressNumber": "up House",
    "addressPostCode": "12345",
    "addressCity": "La Mesa",
    "addressState": "NY",
    "addressCountry": "USA",
    "operatingAddressStreet": null,
    "operatingAddressNumber": null,
    "operatingAddressPostCode": null,
    "operatingAddressCity": null,
    "operatingAddressState": null,
    "operatingAddressCountry": null
  },
  "operationsInformation": {
    "webAddress": "www.mycompany.com",
    "phoneNumber": "123456789",
    "supportEmail": "support@email.com",
    "bPubliclyListed": "NA",
    "ticker": null,
    "exchanges": null,
    "operationRegionIds": [
      1000
    ],
    "bLicenseRequired": "NA",
    "additionalLicensingInfo": null,
    "primaryRegulator": null,
    "licenseNumber": null,
    "financialInstitutionFormFileName": null,
    "businessActivityIds": [
      1009
    ],
    "web3ChainsAndAddresses": "293583498y5fr",
    "sourceOfFundsIds": [
      1006
    ],
    "sourceOfFundsOther": null,
    "activeBanks": "My Bank",
    "yearlyTransactionsId": 1000,
    "monthlyUsdValueId": 1000
  },
  "ownerInformation": {
    "exemptionId": null,
    "businessBeneficialOwners": [
      {
        "number": 1,
        "guid":"0553a3dc-4615-4fa6-bb4f-e51ac3893e61",
        "entityName": "Neural Keyboard Company",
        "entityTypesID": 1003,
        "entityTypesOther": null,
        "registrationDate": "2000-01-01",
        "registrationNumber": "123456789",
        "taxNumber": "123456789",
        "doingBusinessAs": "Online Ball Company",
        "addressStreet": "547 Haag Rest",
        "addressNumber": "Indiana Block",
        "addressPostCode": "12345",
        "addressCity": "Justynfurt",
        "addressState": "NY",
        "addressCountry": "USA",
        "operatingAddressStreet": null,
        "operatingAddressNumber": null,
        "operatingAddressPostCode": null,
        "operatingAddressCity": null,
        "operatingAddressState": null,
        "operatingAddressCountry": null
      }
    ],
    "individualBeneficialOwners": [
      {
        "number": 1,
        "guid":"f82de508-37b9-4cc8-901a-11498e1d0603",
        "firstName": "Alan",
        "lastName": "Von",
        "title": "Mr",
        "dateOfBirth": "1988-04-21",
        "nationality": "GBR",
        "email": "email1@example.co.uk",
        "phoneNumber": "123456789",
        "country": "GBR",
        "ssn": "123456789",
        "stateProvince": "Yorkshire",
        "city": "Schimmelfurt",
        "addressLine1": "9907 Alexa Ways",
        "addressLine2": "No. 1",
        "postcode": "HU5 8EZ",
        "proofOfAddressFilename": "sgp1.pdf"
      },
      {
        "number": 2,
        "guid":"9d597eca-ecd2-4580-8376-98ddf6ef3825",
        "firstName": "Ned",
        "lastName": "Mills",
        "title": "Mr",
        "dateOfBirth": "1988-04-21",
        "nationality": "GBR",
        "email": "email2@example.co.uk",
        "phoneNumber": "123456789",
        "country": "GBR",
        "ssn": "123456789",
        "stateProvince": "Yorkshire",
        "city": "Fargo",
        "addressLine1": "93513 Grady Manors",
        "addressLine2": "No. 1",
        "postcode": "HU5 8EZ",
        "proofOfAddressFilename": "sgp2.pdf"
      }
    ],
    "beneficialOwnersStructure": [
      {
        "bIsBusiness": true,
        "ownersGuid": "0553a3dc-4615-4fa6-bb4f-e51ac3893e61",
        "percentageOwned": 44,
        "bControllingParty": null,
        "positionAtCompany": null,
        "children": [{
            "bIsBusiness": false,
            "ownersGuid": "9d597eca-ecd2-4580-8376-98ddf6ef3825",
            "percentageOwned": 13,
            "bControllingParty": true,
            "positionAtCompany": "Boss",
            "children": null
        }]
      },
      {
        "bIsBusiness": false,
        "ownersGuid": "f82de508-37b9-4cc8-901a-11498e1d0603",
        "percentageOwned": 12,
        "bControllingParty": true,
        "positionAtCompany": "CEO",
        "children": null
      }],
    "authorizedSigner": "Jay Ell",
    "bConfirmAboveTen":true
  },
  "terms": {
    "bTaxAcknowledgement": true,
    "bFatcaAcknowledgement": true,
    "bConfirmTrueAndCorrect": true,
    "bAcceptTerms": true
  },
  "documentsUpload": [
    {
      "documentTypesID": 1001,
      "fileName": "file1001.pdf"
    },
    {
      "documentTypesID": 1002,
      "fileName": "file1002.pdf"
    },
    {
      "documentTypesID": 1003,
      "fileName": "file1003.pdf"
    },
    {
      "documentTypesID": 1007,
      "fileName": "file1007.pdf"
    }
  ]
}
```

{% endcode %}

#### Response Body Parameters

* **`status`** (Integer): 1 if success, 0 if failure
* **`errors`** (Array): List of errors (if present)
* **`details`** (JSON Object)
  * **`customersId`** (Integer): Customer Id of the new business
  * **`businessVerificationStep`** (String): State of business verification: Not Started, In Progress, Submitted, Verified

#### Response Body JSON Example

<pre class="language-json"><code class="lang-json">{
    "id": 13830,
    "details": {
<strong>        "customersId": 13830,
</strong>        "businessVerificationStep": "Submitted"
    },
    "status": "1",
    "errors": []
}
</code></pre>

#### Potential Error Codes

<table><thead><tr><th width="454">Error Code Message</th><th>Description</th></tr></thead><tbody><tr><td>Required</td><td>Required field not provided</td></tr><tr><td>Invalid_RegistrationInformation_EntityTypesID</td><td>Entity type not found</td></tr><tr><td>Invalid_RegistrationInformation_AddressCountry</td><td>Country not found</td></tr><tr><td>Invalid_RegistrationInformation_AddressState</td><td>State not found</td></tr><tr><td>Invalid_RegistrationInformation_OperatingAddressCountry</td><td>Country not found</td></tr><tr><td>Invalid_RegistrationInformation_OperatingAddressState</td><td>State not found</td></tr><tr><td>Invalid_OperationsInformation_bPubliclyListed</td><td>Value must be "Yes", "No" or "NA"</td></tr><tr><td>Invalid_OperationsInformation_OperationRegionIds</td><td>Id not found</td></tr><tr><td>Duplicated_OperationsInformation_OperationRegionIds</td><td>Ids must not be duplicated</td></tr><tr><td>Invalid_OperationsInformation_bLicenseRequired</td><td>Value must be "Yes", "No" or "NA"</td></tr><tr><td>Invalid_OperationsInformation_BusinessActivityIds</td><td>Id not found</td></tr><tr><td>Duplicated_OperationsInformation_BusinessActivityIds</td><td>Ids must not be duplicated</td></tr><tr><td>Invalid_OperationsInformation_SourceOfFundsIds</td><td>Id not found</td></tr><tr><td>Duplicated_OperationsInformation_SourceOfFundsIds</td><td>Ids must not be duplicated</td></tr><tr><td>Invalid_OperationsInformation_YearlyTransactionsId</td><td>Id not found</td></tr><tr><td>Invalid_OperationsInformation_MonthlyUsdValueId</td><td>Id not found</td></tr><tr><td>Invalid_OwnerInformation_ExemptionId</td><td>Id not found</td></tr><tr><td>Invalid_OwnerInformation_BusinessBeneficialOwners</td><td>Should be null if business exempt</td></tr><tr><td>Invalid_OwnerInformation_IndividualBeneficialOwners</td><td>Should be null if business exempt</td></tr><tr><td>Invalid_OwnerInformation_BusinessBeneficialOwners_Number</td><td>Numbers should be distinct and consecutive starting at 1</td></tr><tr><td>Invalid_OwnerInformation_BusinessBeneficialOwners_EntityTypesID_[[Number]]</td><td>Entity type Id not found for beneficial business owner number [[Number]]</td></tr><tr><td>Invalid_OwnerInformation_BusinessBeneficialOwners_AddressCountry_[[Number]]</td><td>Country not found for beneficial business owner number [[Number]]</td></tr><tr><td>Invalid_OwnerInformation_BusinessBeneficialOwners_AddressState_[[Number]]</td><td>State not found for beneficial business owner number [[Number]]</td></tr><tr><td>Invalid_OwnerInformation_BusinessBeneficialOwners_OperatingAddressCountry_[[Number]]</td><td>Country not found for beneficial business owner number [[Number]]</td></tr><tr><td>Invalid_OwnerInformation_BusinessBeneficialOwners_OperatingAddressState_[[Number]]</td><td>State not found for beneficial business owner number [[Number]]</td></tr><tr><td>Invalid_OwnerInformation_IndividualBeneficialOwners_Number</td><td>Numbers should be distinct and consecutive starting at 1</td></tr><tr><td>Invalid_OwnerInformation_IndividualBeneficialOwners_Email</td><td>Emails of individual beneficial owners must be distinct</td></tr><tr><td>Invalid_OwnerInformation_IndividualBeneficialOwners_Country_[[Number]]</td><td>Country not found for individual beneficial owner [[Number]]</td></tr><tr><td>Invalid_OwnerInformation_IndividualBeneficialOwners_Nationality_[[Number]]</td><td>Nationality not found for individual beneficial owner [[Number]]</td></tr><tr><td>Invalid_OwnerInformation_IndividualBeneficialOwners_StateProvince_[[Number]]</td><td>State not found for individual beneficial owner [[Number]]</td></tr><tr><td>Invalid_OwnerInformation.bConfirmAboveTen</td><td>bConfirmAboveTen must be true unless business has UBO exemption</td></tr><tr><td>Invalid_DocumentUpload_DocumentTypesID</td><td>Only one file per document type is allowed</td></tr><tr><td>Invalid_DocumentUpload_FileNames</td><td>Files must be distinct</td></tr><tr><td>Invalid_DocumentUpload_DocumentTypesID_[[DocumentTypesID]]</td><td>Type not found</td></tr><tr><td>Invalid_DocumentUpload_FileName_[[DocumentTypesID]]</td><td>File with document type [[DocumentTypesID]] not found</td></tr></tbody></table>


# 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:

#### **Card Creation**

1. [**Review Customer Details for Card Creation**](/api-endpoints/cards/review-customer-details): Customers / managees that are **older than 6 months** are required to review and confirm that certain details are up to date. This endpoint will provide details for relevant endpoints
2. [**Upload Document**](/api-endpoints/cards/review-customer-details#upload-missing-document): This endpoint is used when clients need to upload missing documents in order to create a card.
3. [**Create Customer Card**](/api-endpoints/cards/create-card#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.

#### **Card Management**

1. [**Activate Card**](/api-endpoints/cards/activation-deactivation#post-api-v1-customer-cards-activate): Used to activate a card for use, this endpoint should only be used once the physical / virtual card is intended to be used.
2. [**Deactivate Card**](/api-endpoints/cards/activation-deactivation#post-api-v1-customer-cards-deactivate): Used to deactivate a card, in cases where a card is lost or stolen. Cards may be reactivated at a later date.
3. [**Change Card PIN**](/api-endpoints/cards/change-card-pin) **-** A `POST` request where users can change the pin of an existing card

**Card Analytics**

1. [**Get Customer Cards By Customer:**](/api-endpoints/cards/get-customer-cards#get-cards-by-customer) Retrieves a list of all cards issued under the customer's account, offering a consolidated view of the card inventory.
2. [**Get Card Details by ID**](/api-endpoints/cards/get-card-details-by-id#get-card-details-by-id): Retrieves details of a single card, including relevant account details.
3. [**Get Sensitive Card Details by ID**](/api-endpoints/cards/get-card-details-by-id#get-sensitive-card-details-by-id): Retrieves sensitive card details of a single card by its ID.
4. [**Get Card Balances**](/api-endpoints/cards/list-card-balances-and-transactions#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.
5. [**Get Card Transactions**](/api-endpoints/cards/list-card-balances-and-transactions#get-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.

#### **Money Movement**

1. [**Add Funds to a Card**](/api-endpoints/cards/card-transfers#card-transfer-funds): Facilitates moving of funds between a customer asset account and a card.
2. [**Move Funds Between Cards**](/api-endpoints/cards/card-transfers#card-to-card-transfer): Facilitates movement of funds between two different cards.


# Review Create Card

This endpoint allows you to review the details of a card creation request. The review ensures that all required details have been updated and that the customer is eligible for card creation.

* **Endpoint URL:** `/api/v1/customer/cards/reviewcreatecard?customersId={customerId}`
* **Method:** `GET`
* **Parameters**
  * `customersId`: **required** - Unique identifier for the customer. Replace with the actual customer ID.
* **Header Parameter**
  * ot&#x70;**: required**

**Example Request**

```http
GET /api/v1/customer/cards/reviewcreatecard?customersId=12345
```

**Example Response**

<pre class="language-json"><code class="lang-json">{
    "id": 0,
    "details": {
        "personalReviewDetails": {
            "sourceOfFunds": "Salary",
            "estimatedGrossAnnualIncome": 10000.00,
            "estimatedNetWorth": 200000.00,
            "activelyEmployed": true,
            "employedCompanyName": "ABC Technologies",
            "employedJobTitle": "Software Engineer"
        },
        "requiredDocuments": [],
        "PersonalSourceFundTypes":[
                "Salary",
<strong>                "Savings",
</strong>                "Self Employed",
                "Loans/Borrowed Funds"
            ]
    },
    "status": "1",
    "errors": []
}
</code></pre>


# Create Card

## 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. \
This endpoint supports customers both **with and without trade wallets**. It can create **physical or virtual cards** for customers with an existing **DDA (Demand Deposit Account)**. If a DDA does not exist for the card, the endpoint will automatically create one as part of the card issuance process.

* **Endpoint:** `/api/v1/customer/cards/create`
* **Method:** `POST`
* **Request Format:** application/json
* **Header Parameter**
  * otp : **required**

#### Request Body

```json
{
  "customersId": 14387,                     // required, number, e.g., 1001, 14387
  "currency": "USD",                        // required, string, possible: "USD"
  "cardReferenceId": "CARD-REF-001",       // required, string, can be any identifier
  "shippingMethod": "Standard",             // required, string, possible: "Standard", "Express"
  "cardProgramID": 1002,                    // required, number, must match an existing program ID
  "cardType": "Physical",                  //Physical OR Virtual
  "shippingAddress": {
    "shippingAddressLine1": "Suite 500",    // required, string, street or suite number
    "shippingAddressCity": "New York",      // required, string, valid city name
    "shippingAddressState": "Texas",        // required, string, state name or abbreviation
    "shippingAddressPostcode": "55050",     // required, string, postal/ZIP code
    "shippingAddressCountry": "USA"         // required, string, ISO country code or name
  },
  "businessReviewDetails": {
    "legalEntityName": "Acme Corporation",              // required, string
    "doingBusinessAs": "Acme Co",                       // required, string
    "entityType": "LLC",                                // required, string, possible: "LLC", "Corporation", "Partnership", "Sole Proprietor"
    "registeredAddressStreet": "123 Main St",           // required, string
    "registeredAddressNumber": "10",                    // optional, string
    "registeredAddressCity": "Austin",                  // required, string
    "registeredAddressState": "TX",                     // required, string
    "registeredAddressPostcode": "73301",               // required, string
    "registeredAddressCountry": "USA",                  // required, string
    "operatingAddressStreet": "500 Market St",          // optional*, string, required if any operating field provided
    "operatingAddressNumber": "Suite 2",                // optional, string
    "operatingAddressCity": "Dallas",                   // optional*, string
    "operatingAddressState": "TX",                      // optional*, string
    "operatingAddressPostcode": "75001",                // optional*, string
    "operatingAddressCountry": "USA",                   // optional*, string
    "businessActivities": ["Retail", "E-commerce"],    // required, array of strings, at least one
    "regionOfOperations": ["USA", "EU"],               // required, array of strings, at least one
    "fundsReceivedFromUSA": true,                       // required, boolean, true/false
    "fundsSentToUSA": false,                            // required, boolean, true/false
    "hasOwnershipStructureChangedSinceOnboarding": false,                                                        // required, boolean, cannot be TRUE
    "sourceOfFunds": ["Business Revenue", "Investments"],  // required, array of strings, at least one
    "authorizedCapital": 100000,                        // required, number, must be > 0
    "comingYearTurnOverPlanned": 500000                 // required, number, must be > 0
  },
  "personalReviewDetails": {
    "sourceOfFunds": ["Salary", "Investments"],       // required, array of strings, at least one
    "estimatedGrossAnnualIncome": 90000,              // required, number, must be > 0
    "estimatedNetWorth": 250000,                      // required, number, must be > 0
    "activelyEmployed": true,                          // required, boolean
    "employedCompanyName": "Global Tech Inc",        // required, string
    "employedJobTitle": "Software Engineer"          // required, string
  }
}


```

#### Response Body

```json
{
  "id": 1359,
  "details": {
    "customersId": 14387,
    "customersReference": "card-ref-1",
    "card": {
      "id": 1359,
      "currency": "USD",
      "cardNumber":"9aUb61b4b0EDk92pD7SCOg==",
      "totalBalance": 0,
      "availableBalance": 0,
      "pendingBalance": 0,
      "bDeactivated": true
    }
  },
  "status": "1",
  "errors": []
}
```


# Activation / Deactivation

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

#### Request Body Example

```json
{
    "cardsId": 1877,
    "pin": "1234"
}
```

#### Success Response Example

```json
{
    "id": 1877,
    "details": {
        "customersId": 14257,
        "customerReference": "112233",
        "card": {
            "id": 1877,
            "cardNumber": "XXXX XXXX XXXX 3632",
            "currency": "USD",
            "totalBalance": 0.00,
            "availableBalance": 0.00,
            "pendingBalance": 0.00,
            "bSuppressed": false,
            "bDeactivated": false
        }
    },
    "status": "1",
    "errors": []
}
```

***

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

#### Request Body Example

```json
{
  "cardsId": 1877
}
```

#### Success Response Example

```json
{
    "id": 1877,
    "details": {
        "customersId": 14257,
        "customerReference": "112233",
        "card": {
            "id": 1877,
            "cardNumber": "XXXX XXXX XXXX 3632",
            "currency": "USD",
            "totalBalance": 9.00,
            "availableBalance": 9.00,
            "pendingBalance": 0.00,
            "bSuppressed": false,
            "bDeactivated": true
        }
    },
    "status": "1",
    "errors": []
}
```


# Change Card PIN

Allows customers to update their card's PIN, which is used when a client authorizes a transaction

* **Endpoint:** `/api/v1/customer/cards/changecardpin`
* **Method:** POST

**Request Body Example:**

```json
{
    "TopUpCardsId": 1234,
    "OldPin": "1234",
    "NewPin": "5678"
}
```

**Success Response Example:**

```json
{
  "id": 0,
  "details": {
    "topUpCardsId": 1234
  },
  "status": "1",
   "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```


# Get Customer Cards

## Get Customer Cards

List cards for all managed customers

* **Endpoint:** `/api/v1/customer/cards/byuser/list`
* **Method:** GET

{% openapi src="/files/jy1U2qiRUqspQuQBhZGz" path="/api/v1/customer/cards/byuser/list" method="get" %}
[public-api-customer-role (4).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-1d89ce851f17d792a1fd40d557b07a1ec5acd080%2Fpublic-api-customer-role%20\(4\).json?alt=media)
{% endopenapi %}

**Query Parameters:**

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

***

## Get Cards By 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`

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/cards/byuser" method="get" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

**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:

```json
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:**

```json
{
  "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 Details By ID

## Get Card Details By ID

**Description**: This endpoint allows you to retrieve detailed information about a specific card using its unique identifier. It's particularly useful for accessing card attributes such as balance, expiry date, and associated account details.

**Endpoint:** `/api/v1/customer/cards/carddetails`  &#x20;

**Request Method**: Get

**Headers**:

* `Content-Type: application/json`
* `Authorization: Bearer <token>`
* `otp: 1234`

**Request Query Parameters**:

* `CardId` (integer, required): The unique identifier for the top-up card whose details are being requested.

#### **Response Body Example (200 OK)**:

* ```json
  {
      "id": 0,
      "details": {
          "customersID": 0,
          "customersReference": "string",
          "cardHolderName": "string",
          "cardLast4": "string",
          "currency": "string",
          "totalBalance": 0,
          "availableBalance": 0,
          "status": "string"
      },
      "status": "1",
      "errors": []
  }
  ```

  **Errors**:

  * `404 Not Found`: Returned if the card ID does not exist.
  * `401 Unauthorized`: If the request does not include valid authentication.

***

## **Get Sensitive Card Details By ID**

**Description**: This endpoint allows you to retrieve sensitive information about a specific card using its unique identifier. It's particularly useful for accessing card attributes such as card number, bank details, and cvc.

**Endpoint:** `/api/v1/customer/cards/sensitive-details`

**Request Method**: Get

**Headers**:

* `Content-Type: application/json`
* `Authorization: Bearer <token>`
* `otp: 1234`

**Request Query Parameters**:

* `CardId` (integer, required): The unique identifier for the top-up card whose details are being requested.

**Response Body Example (200 OK)**:

* ```json
  {
    "id": 0,
    "details": {
      "cardHolderName": "string",
      "expiryDate": "2025-12-05T18:28:08.228Z",
      "cardNumber": "string",
      "cvc": "string",
      "currency": "string",
      "totalBalance": 0,
      "availableBalance": 0,
      "status": "string",
      "orderStatus": "string",
      "processorCardStatus": "string",
      "pin": "string",
      "accounts": [
        {
          "id": 0,
          "accountNumber": "string",
          "routingNumber": "string",
          "bankName": "string",
          "bankAddress": "string",
          "accountHolderName": "string",
          "accountHolderAddress": "string"
        }
      ]
    },
    "status": "string",
    "errors": [
      {
        "fieldName": "string",
        "messageCode": "string"
      }
    ]
  }
  ```

  **Errors**:

  * `404 Not Found`: Returned if the card ID does not exist.
  * `401 Unauthorized`: If the request does not include valid authentication.


# List Card Balances & Transactions

## Get Card Balances

Retrieve the balances for all customer-associated cards. This endpoint provides detailed balance information for each card related to the customer, ensuring a full overview of available and spent credit limits.

* **HTTP Method:** GET
* **Endpoint:** `/api/v1/customer/cards/balances`

**Request Parameters**

* **PageSize** (optional, default = 10): Number of records to be returned
* **PageNumber** (Optional, default = 1): Index of page to be returned
* **CustomersID** (Optional): Filter to return cards belonging to a specific CustomersID

**Header Parameter**

* otp: **required**

#### **Response**

**Example Response (Status Code**: 200 OK)

```json
{
  "id": 0,
  "details": [
    {
      "id": 0,
      "customersReference": "string",
      "cardHolderName": "string",
      "cardLast4": "string",
      "customersID": "string",
      "currency": "string",
      "totalBalance": 0,
      "availableBalance": 0,
      "pendingBalance": 0,
      "status": "string"
    }
  ],
  "pageSize": 0,
  "pageNumber": 0,
  "numberOfPages": 0,
  "status": "string",
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

**Notes**

* The balances returned are up-to-date at the time of request and may vary based on pending transactions.

***

## Get Transactions

Retrieves a list of card transactions, with the ability to filter by `CardsId` and include a date range.

* **Method**: `GET`
* **Endpoint**: `/api/v1/customer/cards/transactions`

**Request Query Parameters**:

* `CardsId`: Use this parameter to filter transactions by the specific Card ID.
* `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`: Indicate the page number to retrieve; defaults to 1 if not specified.
* `PageSize`: Define the number of transactions per page; defaults to 10 if not specified.

**Example Response (Status Code**: 200 OK)

```json
{
  "id": 0,
  "details": [
    {
      "id": 0,
      "cardsId": 0,
      "amount": 0,
      "currency": "string",
      "description": "string",
      "dateTime": "2025-12-05T18:30:19.218Z",
      "bPending": true,
      "refundTransactionsID": "string"
    }
  ],
  "pageSize": 0,
  "pageNumber": 0,
  "numberOfPages": 0,
  "status": "string",
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

**Note**

* The transactions returned are reflective of all activity within the specified time frame and account for all completed, pending, and approved transactions.


# Review Transfer Funds

This endpoint allows you to review the details of a transfer. The review ensures that the card is active and calculates the applicable fee and total due amount after the fee is applied.

* **Endpoint:** `/api/v1/customer/cards/reviewtransferfunds`
* **Method:** POST

#### Note: Clients may use dUSD or USD accounts interchangably. For subledger customers, the `CustomerAssetAccountId` of the dUSD Account should be used. For other account types, you should use a USD Account.

**For Card-to-Card transfers, the currency type will always be USD.**

#### Request Body Example

```json
//Case-1 TopUpCard
{
  "amount": 10,
  "reference": "Test",
  "transferTypes": "TopUpCard",
  "currencyType": "USD", //"dUSD"
  "DestinationCardId": 1749,
  "CustomersId": "16221",
  "CustomerAssetAccountId": 8204
}
//Case-2 TopUpAccount
{
  "amount": 10,
  "reference": "Test",
  "transferTypes": "TopUpAccount",
  "currencyType": "USD",//"dUSD"
  "SourceCardId": 1249,
  "CustomersId": "16221",
  "CustomerAssetAccountId": 8204
}
//Case-3 CardToCard
{
  "amount": 10,
  "reference": "Test",
  "transferTypes": "CardToCard",
  "currencyType": "USD",
  "SourceCardId": 1249,
  "CustomersId": "16221",
  "DestinationCardId": 1749
}
```

#### Success Response Example

```json
{
    "id": 0,
    "details": {
        "fee": 0.00,
        "totalDue": 4.00
    },
    "status": "1",
    "errors": []
}
```


# Transfer Funds

## Transfer Funds

This endpoint enables clients to transfer funds to and from a card.

Move funds from a Customer Account to a card by calling the following endpoint. The `customerAssetAccountsId` must be either a USD (excluding subledger) or dUSD account.

* **Endpoint:** `/api/v1/customer/cards/transferfunds`
* **Method:** POST

#### Note: Clients may use dUSD or USD accounts interchangably. For subledger customers, the `CustomerAssetAccountId` of the dUSD Account should be used. For other account types, you should use a USD Account.

**For Card-to-Card transfers, the currency type will always be USD.**

#### Request Body Example

```json
//Case-1 TopUpCard
{
  "amount": 10,
  "reference": "Test",
  "transferTypes": "TopUpCard",
  "currencyType": "USD", //"dUSD"
  "DestinationCardId": 1749,
  "CustomersId": "16221",
  "CustomerAssetAccountId": 8204
}
//Case-2 TopUpAccount
{
  "amount": 10,
  "reference": "Test",
  "transferTypes": "TopUpAccount",
  "currencyType": "USD",//"dUSD"
  "SourceCardId": 1249,
  "CustomersId": "16221",
  "CustomerAssetAccountId": 8204
}
//Case-3 CardToCard
{
  "amount": 10,
  "reference": "Test",
  "transferTypes": "CardToCard",
  "currencyType": "USD",
  "SourceCardId": 1249,
  "CustomersId": "16221",
  "DestinationCardId": 1749
}
```

#### Success Response Example

```json
{
    "id": 30939,
    "details": {
        "FromTransactionId": 30939,
        "ToTransactionId": 30941,
        "FeeTransactionId": 30940,
        "amount": 10,
        "feeAmount": 0,
        "description": "Card transfer - Top Up Funds",
        "bPending": true
    },
    "status": "1",
    "errors": []
}
```


# Review Replace Card

## Review Card Replacement

The Review Replace Card endpoint previews a card replacement before it is carried out. It validates that the card is eligible for replacement and returns the replacement fee together with the account the fee will be charged from. No card is replaced and no funds are moved by this endpoint. Once reviewed, call Replace Card to perform the replacement.\
The optional **`shippingAddress`** may be supplied on the review request for consistency with the replace request. It is not required to preview the replacement.

* **Endpoint:** `/api/v1/customer/cards/reviewreplace`
* **Method:** `POST`
* **Request Format:** application/json
* **Header Parameter**
  * otp : **required**

#### Request Body

```json
{
  "cardsId": 1359,               // required, number, ID of the card to be replaced
  "replaceReason": "Damaged",    // required, string, one of: "Damaged", "Lost", "FraudCompromised", "Returned", "Expired", "Stolen"
  "shippingMethod": "Standard",  // optional, string, one of: "Standard" (default), "Express"
  "shippingAddress": {           // optional. Supply to ship the replacement card to a new address
    "shippingAddressLine1": "1 Roshar Ave",  // required when shippingAddress is supplied, string, max 60 characters
    "shippingAddressLine2": null,            // optional, string, max 60 characters
    "shippingAddressCity": "New York",       // required when shippingAddress is supplied, string, max 60 characters
    "shippingAddressState": "NY",            // required when shippingAddress is supplied, string, letters only, max 30 characters
    "shippingAddressPostcode": "10001",      // required when shippingAddress is supplied, string, digits only, max 10 characters
    "shippingAddressCountry": "US"           // required when shippingAddress is supplied, string, letters only
  }
}
```

#### Response Body

```json
{
  "id": 0,
  "details": {
    "cardsId": 1359,
    "nameOnCard": "John Smith",
    "fee": 15.00,
    "currency": "USD",
    "feesCustomerAssetAccountsId": 8204
  },
  "status": "1",
  "errors": []
}
```

#### Error Responses

Errors are returned using the standard envelope, with `status` set to `"0"` and one or more entries in the `errors` array, each containing a `fieldName` and a `messageCode`.

| messageCode                           | Meaning                                                                                  |
| ------------------------------------- | ---------------------------------------------------------------------------------------- |
| `Required`                            | A required field (`cardsId` or `replaceReason`) was not provided.                        |
| `Invalid`                             | `replaceReason` or `shippingMethod` is not one of the accepted values.                   |
| `Card_Provider_Not_Supported`         | Card replacement is not supported for this card.                                         |
| `Card_Already_Replaced`               | The card has already been replaced.                                                      |
| `Card_Account_Not_Found`              | The funding account for the card could not be found.                                     |
| `Card_Replacement_Fee_Not_Configured` | No card replacement fee is configured for the customer.                                  |
| `Insufficient_Funds`                  | The funding account does not have enough available balance to cover the replacement fee. |

```json
{
  "id": 0,
  "details": null,
  "status": "0",
  "errors": [
    {
      "fieldName": "CardsId",
      "messageCode": "Card_Replacement_Fee_Not_Configured"
    }
  ]
}
```


# Replace Card

## Replace Customer Card

The Replace Card endpoint issues a replacement for an existing card, for example when the card is damaged, lost, stolen, expired, returned, or compromised. The replacement is issued as a **new card with its own new `cardsId`**; the previous card's ID is not reused. It is created against the same funding account as the original, so the balance is retained, and the response returns `previousCardsId` (the ID of the card it replaced) for reconciliation. When the replacement reason is **Lost** or **Stolen**, the original card is closed. A replacement fee may apply and is reserved from the customer's card funding account once the replacement has succeeded. Use the Review Replace Card endpoint first to preview the fee and the paying account.\
Optionally, supply a **`shippingAddress`** to have the replacement card delivered to a different address than the original. When it is omitted, the original card's shipping address is used.

* **Endpoint:** `/api/v1/customer/cards/replace`
* **Method:** `POST`
* **Request Format:** application/json
* **Header Parameter**
  * otp : **required**

#### Request Body

```json
{
  "cardsId": 1359,               // required, number, ID of the card to replace
  "replaceReason": "Damaged",    // required, string, one of: "Damaged", "Lost", "FraudCompromised", "Returned", "Expired", "Stolen"
  "shippingMethod": "Standard",  // optional, string, one of: "Standard" (default), "Express"
  "shippingAddress": {           // optional. Supply to ship the replacement card to a new address
    "shippingAddressLine1": "1 Roshar Ave",  // required when shippingAddress is supplied, string, max 60 characters
    "shippingAddressLine2": null,            // optional, string, max 60 characters
    "shippingAddressCity": "New York",       // required when shippingAddress is supplied, string, max 60 characters
    "shippingAddressState": "NY",            // required when shippingAddress is supplied, string, letters only, max 30 characters
    "shippingAddressPostcode": "10001",      // required when shippingAddress is supplied, string, digits only, max 10 characters
    "shippingAddressCountry": "US"           // required when shippingAddress is supplied, string, letters only
  }
}
```

#### Response Body

```json
{
  "id": 1402,
  "details": {
    "cardsId": 1402,
    "cardsCode": "TUC-1402",
    "nameOnCard": "John Smith",
    "cardLastFour": "4821",
    "expiryDate": "09/29",
    "status": "Active",
    "shippingMethod": "Standard",
    "previousCardsId": 1359
  },
  "status": "1",
  "errors": []
}
```

#### Error Responses

Errors are returned using the standard envelope, with `status` set to `"0"` and one or more entries in the `errors` array, each containing a `fieldName` and a `messageCode`.

| messageCode                           | Meaning                                                                                     |
| ------------------------------------- | ------------------------------------------------------------------------------------------- |
| `Required`                            | A required field (`cardsId` or `replaceReason`) was not provided.                           |
| `Invalid`                             | `replaceReason` or `shippingMethod` is not one of the accepted values.                      |
| `Card_Provider_Not_Supported`         | Card replacement is not supported for this card.                                            |
| `Card_Already_Replaced`               | The card has already been replaced.                                                         |
| `Card_Account_Not_Found`              | The funding account for the card could not be found.                                        |
| `Card_Replacement_Fee_Not_Configured` | No card replacement fee is configured for the customer.                                     |
| `Insufficient_Funds`                  | The funding account does not have enough available balance to cover the replacement fee.    |
| `Card_Provider_Error`                 | The card could not be replaced due to an error while processing the replacement (HTTP 500). |

```json
{
  "id": 0,
  "details": null,
  "status": "0",
  "errors": [
    {
      "fieldName": "CardsId",
      "messageCode": "Insufficient_Funds"
    }
  ]
}
```


# Crypto Exchanges

## Overview

The Exchange module provides the infrastructure to carry out asset exchanges on behalf of customers —a particularly important feature for platforms that accommodate multiple asset types and currencies. This module includes a series of endpoints tailored to the needs of users looking to perform, monitor, and manage asset exchanges for their customers.

Offering functions from quoting to execution, along with detailed tracking mechanisms, the Exchange module endpoints include:

1. [**Get Available Asset Pairs**](#get-available-asset-pairs): Provides a full list of asset pairs enabled for the API user. The response will also include information on limits and minimums associated with each asset pair for exchanges.
2. [**Get Quote for Exchange**](#get-quote-for-exchange)**:** Provides an estimate for an exchange, detailing the price and amount before the actual exchange is executed, ensuring that the customer is informed about the potential transaction.
3. [**Sell Exchange**](#sell-exchange)**:** Enables a customer to sell an asset, converting it into another asset or currency as specified in the trade.
4. [**Buy Exchange**](#buy-exchange)**:** Allows a customer to purchase an asset, facilitating the exchange through a defined asset pair and desired quantity.
5. [**List Exchanges**](#list-exchanges): Provides a generated list of asset exchanges, with the ability to filter by customer, order type, and more.
6. [**Review Quote**](#review-quote): If the price of the asset changes between the time of initiating the exchange, and when it is approved, this endpoint allows a customer to review a price change for an exchange following approval by the transaction compliance team.
7. [**Confirm Sell Exchange**](#confirm-sell-exchange): Once an updated price is retrieved from Review Quote, this endpoint will allow a customer to confirm the price change and initiate the exchange.
8. [**Cancel Exchange**](#cancel-exchange): This endpoint will allow a customer to cancel an exchange that has been recently approved by transaction compliance, in scenarios where the price changes from when the exchange was initially requested.

Overall, the Exchange module is designed to offer a seamless and secure experience for handling the exchange requirements of customers, ensuring that users can manage these operations effectively with great precision and control.

***

## Get Available Asset Pairs

Provides a full list of asset pairs enabled for the API user. The response will also include information on limits and minimums associated with each asset pair for exchanges.

* **Endpoint:** `/api/v1/customer/crypto-exchanges/availablepairs`
* **Method:** `GET`

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/crypto-exchanges/availablepairs" method="get" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

***

## Get Quote for Exchange

This endpoint provides a quoted market price for a proposed asset exchange for a particular customer, detailing the amount and price for either a "Buy" or "Sell" exchange type. By specifying details of the desired trade, a customer can see the cost or proceeds they might expect from completing a transaction, including any applicable fees. This helps customers decide whether to proceed with an exchange based on real-time financial data. **Sell exchanges generally refer to converting a cryptocurrency into a fiat currency.**

* **Endpoint:** `/api/v2/customer/crypto-exchanges/quote`
* **Method:** POST

**Request Body Parameters:**

* `customersId` (Integer): ID of the customer making the exchange—required.
* `payeesId` (Integer, Nullable): Id of receiving payee, if receiving account is a passthrough account.
* `assetPair` (String): The pair of assets to be exchanged, such as "BTC/USDC"—required.
* `quantityType` (String): Defines if the exchange is based on "Price" or "Amount"—required.
* `exchangeType` (String): Either "Buy" or "Sell"—required.
* `transferType` (String): The transfer type, such as "Wire"—required.
  * `transferType` is only required for sell exchanges where the “payeesId” is not null.
* `price` (Decimal, Nullable): Desired price for a "Price"-based exchange, null for "Amount"-based.
* `amount` (Decimal, Nullable): Desired amount for an "Amount"-based exchange, null for "Price"-based.
* `bRequireBalanceValues`(boolean): When set to `true`, the response will include the customer's balance-based trade limits

**Request Example:**

```json
{
  "customersId": 1004,
  "assetPair": "BTC/USDC",
  "quantityType": "Price",
  "exchangeType": "Buy",
  "transferType": "Wire",
  "price": 10,
  "amount": null,
  "bRequireBalanceValues":false
}
```

**Response Body Parameters:**

* `id` (Integer): Not used.
* `details` (Object): Contains the quote details.
  * `customersId` (Integer): ID of the customer.
  * `payeesId` (Integer): The payee's ID to where the asset's sale proceeds will be credited. Required if receiving account is a passthrough account.
  * `quantityType` (String): Indicates whether "Amount" or "Price" is fixed for the exchange exchange.
  * `assetPair` (String): Asset pair involved in the exchange.
  * `amount` (Decimal): Amount of asset to be exchanged.
  * `netPrice` (Decimal): Exchange effective net price accounting for commission and network fees.
  * `networkFee` (Decimal): Estimated exchange network fee.
  * `commissionFee` (Decimal): The commission fee for the exchange.
  * `price` (Decimal): Total quoted price for the exchange.
  * `fxRateId` (Integer): FX rate ID that's to be used to for [sell exchanges](#sell-exchange).
  * `fxRateExpiryDate` (ISO 8601): Expire date for given `fxRateId`. Once the current time is greater than the expire time, you must generate a new quote.
  * `maxBalanceAmount`\
    Maximum asset quantity the customer can trade given their current paired-asset balance (gross, before fees).
  * `maxBalanceNetAmount`\
    Maximum asset quantity the customer can receive given their current balance, after fees are deducted.
  * `maxBalancePrice`\
    Maximum gross price (in paired asset) the customer can spend given their current balance (gross, before fees).
  * `maxBalanceNetPrice`\
    Maximum net price (in paired asset) the customer can spend given their current balance, after fees are deducted.
  * `minAmount`\
    Minimum asset quantity allowed for this trade, as configured in the fee/product rules.
  * `maxAmount`\
    Maximum asset quantity allowed for this trade, as configured in the fee/product rules.
  * `minPrice`\
    Minimum gross price (in paired asset) allowed for this trade, as configured in the fee/product rules.
  * `maxPrice`\
    Maximum gross price (in paired asset) allowed for this trade, as configured in the fee/product rules.
  * `minPriceAllowed`\
    Minimum gross price (in paired asset) the user may submit; always >= MinPrice and sufficient to purchase at least MinAmount of the asset after fees.
  * `minAmountAllowed`\
    Minimum asset quantity the user may submit; satisfies both the MinAmount constraint and the quantity implied by the MinPrice limit.
  * `maxAmountAllowed`\
    Maximum asset quantity the user may submit for this trade.
  * `maxPriceAllowed`\
    Maximum gross price (in paired asset) the user may submit for this trade.
  * `minFee`\
    Minimum flat fee applied when the percentage-based fee falls below this floor.
  * `fixedAdditionalFee`\
    Fixed fee added to every order regardless of size or fee percentage.

**Success Response Example:**

```json
{
  "id": 5261,
  "details": {
    "customersId": 1004,
    "payeesId": null,
    "quantityType": "Price",
    "assetPair": "BTC/USD",
    "amount": 0.00040068,
    "netPrice": 23.86,
    "networkFee": 0.08,
    "commissionFee": 0.18,
    "price": 24.12,
    "maxBalanceAmount": 0.34259933,
    "maxBalanceNetAmount": 0.34256933,
    "maxBalancePrice": 20581.11,
    "maxBalanceNetPrice": 20426.11,
    "fxRateId": null,
    "fxRateExpiryDate": null,
    "minAmount": 0.0004,
    "maxAmount": 10000000,
    "minPrice": 10,
    "maxPrice": 10000000000000,
    "minPriceAllowed": 24.11,
    "minAmountAllowed": 0.0004,
    "maxAmountAllowed": 10000000,
    "maxPriceAllowed": 600658656988.55,
    "minFee": 0,
    "fixedAdditionalFee": 0
  },
  "status": "1",
  "errors": [

  ]
}
```

#### Possible Error Codes

| Error Message Code         | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| Required                   | Named field 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 |
| Amount\_Must\_Be\_Positive | Invalid or missing amount                                         |

***

## Sell Exchange

This endpoint is designed to initiate a sell exchange, allowing a customer to sell an asset at a given price or for a specific amount.

* **Endpoint:** `/api/v3/customer/crypto-exchanges/sell`
* **Method:** `POST`

## Initiate a sell exchange

> Request Body:
> \
> &#x20;\- CustomersId: Customer's Id
> \
> &#x20;\- AssetPair: Asset pair to trade
> \
> &#x20;\- QuantityType: Quantity type indicating whether price or amount is fixed (possible values: Price, Amount)
> \
> &#x20;\- Amount: Amount to request to trade
> \
> &#x20;\- Price: Price to request to trade for
> \
> &#x20;\- PayeesId: If receiving account is a passthrough account, receiving payee's Id (optional)
> \
> &#x20;\- TransferType: If receiving account is a passthrough account, type of transfer from passthrough account to payee (optional) (possible values: Wire, ACH)
> \
> &#x20;\- FxRateId: Rate Id corresponding to the rate that's to be used for the sell exchange (FX only)
> \
> &#x20;\- PurposeCode: Reason code for the transfer to the payee (required for foreign exchanges). E.g. 'PUC001'
> \
> &#x20;\- Reference: A note or reference information about the asset exchange. E.g. 'Sell USDC'
> \\
>
> \
> Response:
> \
> &#x20;\- Id: Exhcange Id
> \
> &#x20;\- ExchangeType: Exchange type (possible values: Buy, Sell)
> \
> &#x20;\- Status: Exchange status (possible values: WaitingForApproval, Rejected, WaitingForConfirmation, AwaitingRfi, Pending, Completed, Failed)
> \
> &#x20;\- FromTransactionsId: Associated exchange transaction from debited managee asset account&#x20;
> \
> &#x20;\- ToTransactionsId: Associated exchange transaction to credited managee asset account&#x20;
> \
> &#x20;\- CustomersId: Customer's Id
> \
> &#x20;\- AssetPair: Asset pair
> \
> &#x20;\- RequestAmount: Amount requested
> \
> &#x20;\- RequestPrice: Price requested
> \
> &#x20;\- ExecutedAmount: Amount executed
> \
> &#x20;\- ExecutedPrice: Price executed
> \
> &#x20;\- CommissionFee: Commission fee
> \
> &#x20;\- PayeesId: If receiving account is a passthrough account, receiving payee's Id
> \
> &#x20;\- TransferType: If receiving account is a passthrough account, type of transfer from passthrough account to payee (possible values: Wire, ACH)
> \
> &#x20;\- bHasOpenRfi: Flag indicating if request for information is pending to be submitted (FX only)
> \\
>
> \
> Possible validation errors:
> \
> &#x20;\- Required
> \
> &#x20;\- Invalid
> \
> &#x20;\- Price\_Too\_Low (specified price lower than minimum allowed)
> \
> &#x20;\- Amount\_Too\_Low (specified amount lower than minimum allowed)
> \
> &#x20;\- Price\_Too\_High (specified price higher than maximum allowed)
> \
> &#x20;\- Amount\_Too\_High (specified amount highter than maximum allowed)
> \
> &#x20;\- Screening\_Failed (transfer to an external payee screening failed, exchange not permitted)&#x20;
> \
> &#x20;\- Insufficient\_Customer\_Balance (managee does not have sufficient balance for exchange)
> \
> &#x20;\- Price\_Updated (Asset price has updated, exchange cannot be executed at requested price)

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"CryptoExchangesModule"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"CustomerRole.V3.CryptoExchangesModule.SellExchangeRequestDto":{"type":"object","properties":{"bankFeeSplitType":{"type":"string","nullable":true},"customersId":{"type":"integer","format":"int32"},"payeesId":{"type":"integer","format":"int32","nullable":true},"assetPair":{"type":"string","nullable":true},"quantityType":{"$ref":"#/components/schemas/ExchangeQuantityTypes"},"amount":{"type":"number","format":"double","nullable":true},"price":{"type":"number","format":"double","nullable":true},"fxRateId":{"type":"integer","format":"int32","nullable":true},"transferType":{"$ref":"#/components/schemas/TransferTypes"},"purposeCode":{"type":"string","nullable":true},"purposeOther":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true}},"additionalProperties":false},"ExchangeQuantityTypes":{"enum":["Price","Amount"],"type":"string"},"TransferTypes":{"enum":["Wire","ACH","Internal","RTP","SWIFT"],"type":"string"},"Results.ObjectResultDto_CustomerRole.CryptoExchangesModule.AssetExchangeDto":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"details":{"$ref":"#/components/schemas/CustomerRole.CryptoExchangesModule.AssetExchangeDto"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.CryptoExchangesModule.AssetExchangeDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"exchangeType":{"$ref":"#/components/schemas/AssetExchangeTypes"},"status":{"$ref":"#/components/schemas/ExchangeStatus"},"fromTransactionsId":{"type":"integer","format":"int32"},"toTransactionsId":{"type":"integer","format":"int32","nullable":true},"customersId":{"type":"integer","format":"int32"},"assetPair":{"type":"string","nullable":true},"requestAmount":{"type":"number","format":"double"},"requestPrice":{"type":"number","format":"double"},"executedAmount":{"type":"number","format":"double","nullable":true},"executedPrice":{"type":"number","format":"double","nullable":true},"commissionFee":{"type":"number","format":"double"},"payeesId":{"type":"integer","format":"int32","nullable":true},"transferType":{"$ref":"#/components/schemas/TransferTypes"},"bHasOpenRfi":{"type":"boolean"}},"additionalProperties":false},"AssetExchangeTypes":{"enum":["Buy","Sell"],"type":"string"},"ExchangeStatus":{"enum":["WaitingForApproval","Rejected","WaitingForConfirmation","Pending","Completed","Failed","AwaitingRfi"],"type":"string"},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false},"Results.ResultDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false}}},"paths":{"/api/v3/customer/crypto-exchanges/sell":{"post":{"tags":["CryptoExchangesModule"],"summary":"Initiate a sell exchange","description":"Request Body:\r\n - CustomersId: Customer's Id\r\n - AssetPair: Asset pair to trade\r\n - QuantityType: Quantity type indicating whether price or amount is fixed (possible values: Price, Amount)\r\n - Amount: Amount to request to trade\r\n - Price: Price to request to trade for\r\n - PayeesId: If receiving account is a passthrough account, receiving payee's Id (optional)\r\n - TransferType: If receiving account is a passthrough account, type of transfer from passthrough account to payee (optional) (possible values: Wire, ACH)\r\n - FxRateId: Rate Id corresponding to the rate that's to be used for the sell exchange (FX only)\r\n - PurposeCode: Reason code for the transfer to the payee (required for foreign exchanges). E.g. 'PUC001'\r\n - Reference: A note or reference information about the asset exchange. E.g. 'Sell USDC'\r\n\r\nResponse:\r\n - Id: Exhcange Id\r\n - ExchangeType: Exchange type (possible values: Buy, Sell)\r\n - Status: Exchange status (possible values: WaitingForApproval, Rejected, WaitingForConfirmation, AwaitingRfi, Pending, Completed, Failed)\r\n - FromTransactionsId: Associated exchange transaction from debited managee asset account \r\n - ToTransactionsId: Associated exchange transaction to credited managee asset account \r\n - CustomersId: Customer's Id\r\n - AssetPair: Asset pair\r\n - RequestAmount: Amount requested\r\n - RequestPrice: Price requested\r\n - ExecutedAmount: Amount executed\r\n - ExecutedPrice: Price executed\r\n - CommissionFee: Commission fee\r\n - PayeesId: If receiving account is a passthrough account, receiving payee's Id\r\n - TransferType: If receiving account is a passthrough account, type of transfer from passthrough account to payee (possible values: Wire, ACH)\r\n - bHasOpenRfi: Flag indicating if request for information is pending to be submitted (FX only)\r\n\r\nPossible validation errors:\r\n - Required\r\n - Invalid\r\n - Price_Too_Low (specified price lower than minimum allowed)\r\n - Amount_Too_Low (specified amount lower than minimum allowed)\r\n - Price_Too_High (specified price higher than maximum allowed)\r\n - Amount_Too_High (specified amount highter than maximum allowed)\r\n - Screening_Failed (transfer to an external payee screening failed, exchange not permitted) \r\n - Insufficient_Customer_Balance (managee does not have sufficient balance for exchange)\r\n - Price_Updated (Asset price has updated, exchange cannot be executed at requested price)","operationId":"POST-api-v3-customer-crypto-exchanges-sell","parameters":[{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/CustomerRole.V3.CryptoExchangesModule.SellExchangeRequestDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.V3.CryptoExchangesModule.SellExchangeRequestDto"}},"text/json":{"schema":{"$ref":"#/components/schemas/CustomerRole.V3.CryptoExchangesModule.SellExchangeRequestDto"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/CustomerRole.V3.CryptoExchangesModule.SellExchangeRequestDto"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ObjectResultDto_CustomerRole.CryptoExchangesModule.AssetExchangeDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ResultDto"}}}}}}}}}
```

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

**Request Body Parameters:**

* `customersId` (Integer): The customer's ID who owns the asset to be sold—required.
* `assetPair` (String): The pair of assets involved in the exchange, such as "BTC/USD"—required.
* `TransferType` (String): The type of transfer to be used (e.g., "Wire")—required.
  * Possible Transfer Types

    **`Wire`** - FedWire, available to US accounts.

    **`ACH`** - Available to US accounts.

    **`RTP`** - Realtime Domestic US Payments, also known as FedNow. Available to US accounts.

    **`SWIFT`** - For international accounts.

    **`Internal`** - Internal Transfer to Ibanera Fiat acccount
* `fxRateId` (String, Nullable): The FX rate ID to be used for the sell exchange, if applicable.
* `QuantityType` (String): Specifies if the quote is for an "Amount" or "Price". **Required if fxRateId is not provided.**
* `amount` (Decimal): The amount of asset to be sold, if QuantityType is "Amount". **`Amount` or `Price` required if fxRateId is not provided - Required if `quantityType` is "Amount".**
* `price` (Decimal): The price at which the asset is to be sold, if QuantityType is "Price". **`Amount` or `Price` required if fxRateId is not provided - Required if `quantityType` is "Price".**
* `payeesId` (Integer): The payee's ID to where the asset's sale proceeds will be credited. Required if receiving account is a passthrough account.
* `purposeCode` (String, Nullable): A code that signifies the reason for the transaction, for regulatory or record-keeping purposes. **Required for FX sell orders.** A list of applicable purpose codes can be obtained by calling the [Purpose Codes](/api-endpoints/transfers/transfers#get-purpose-codes) endpoint.
* `purposeOther` (String, Nullable): If no purpose code is provided, then the purpose of the transaction should be provided here. This field is mandatory if the `purposeCode` corresponds to 'Other'.
* `reference` (String, Nullable): A note or reference information about the asset exchange. If the sell exchange involves a bank transfer, this reference will be sent to the beneficiary.

#### Request Body Example:

```json
{
    "CustomersId": 1004,
    "PayeesId": 1011,
    "FxRateId": null,
    "AssetPair": "BTC/USD",
    "QuantityType": "Price",
    "TransferType": "Wire",
    "Price": 100,
    "Amount": 0.004,
    "PurposeCode": null,
    "Reference": "Test Transfer #1234"
}
```

**Response Body Parameters:**

* `id` (Integer): Not used.
* `details` (Object):
  * `id` (Integer): A unique identifier for this sell exchange transaction.
  * `exchangeType` (String): Will show as "Sell" for most cases. .
  * `status` (String): The current status of the sell exchange (e.g., "Pending").
  * `fromTransactionsId` (Integer): Linked from transaction ID.
  * `toTransactionsId` (Integer, Nullable): Linked to transaction ID.
  * `customersId` (Integer): The customer's ID.
  * `assetPair` (String): The asset pair involved in the exchange.
  * `requestAmount` (Decimal): The amount requested to sell.
  * `requestPrice` (Decimal): The price requested for the sale.
  * `executedAmount` (Decimal, Nullable): The amount that was executed in the sale.
  * `executedPrice` (Decimal, Nullable): The price at which the sale was executed.
  * `commissionFee` (Decimal): The commission fee for the transaction.
  * `payeesId` (Integer): The ID of the payee's account where the proceeds will be credited.
  * `transferType` (String): The type of transfer from the asset account to the payee.
  * `bHasOpenRfi` (Boolean): Indicates whether there is an open request for information (relevant for FX only).

#### Success Response Example:

```json
{
        "id": 0,
        "details": {
            "id": 23304,
            "exchangeType": "Sell",
            "status": "WaitingForApproval",
            "fromTransactionsId": 3410,
            "toTransactionsId": 3409,
            "customersId": 1004,
            "assetPair": "BTC/USDC",
            "requestAmount": 0.004,
            "requestPrice": 100.0,
            "executedAmount": 0.00415,
            "executedPrice": 100.0,
            "commissionFee": 1.50,
            "payeesId": 1011,
            "transferType": "Wire",
            "bHasOpenRfi": false
        },
        "status": "1",
        "errors": []
}
```

#### Possible Error Codes

| Error Message Code       | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| Required                 | Named field 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 |

***

## Buy Exchange

This endpoint is intended for initiating a buy exchange, enabling a customer to purchase an asset at a specified price or quantity.

Using the Buy Asset feature, customers can securely order the purchase of digital assets such as Bitcoin using USDC, a stablecoin pegged to the US dollar. This order can be set at a specific price or amount, after which the system processes the order to buy at the most advantageous rates within set parameters, including applicable transaction fees.

* **Endpoint:** `/api/v1/customer/crypto-exchanges/buy`
* **Method:** `POST`

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/crypto-exchanges/buy" method="post" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

**Request Body Parameters:**

* `customersId` (Integer): The ID of the customer initiating the purchase—required.
* `assetPair` (String): The asset pair to be traded, such as "BTC/USDC"—required.
* `quantityType` (String): Specifies the fixed value type in the quote, either "`Price`" or "`Amount`"—required.
* `amount` (Decimal): The amount to be bought, used when the `quantityType` is "Amount"—required if `quantityType` is "Amount".
* `price` (Decimal): The price at which to buy, used when the `quantityType` is "Price"—required if `quantityType` is "Price".

**Request Example:**

```json
{
  "customersId": 1004,
  "assetPair": "BTC/USDC",
  "quantityType": "Price",
  "amount": 0.004,
  "price": 100
}
```

**Response Body Parameters:**

* `id` (Integer): Not used.
* `details` (Object):
  * `id` (Integer): The unique identifier for this buy exchange transaction.
  * `exchangeType` (String): Set to "Buy".
  * `status` (String): The status of the transaction, such as "Pending".
    * Possible values: `WaitingForApproval`, `Rejected`, `WaitingForConfirmation`, `Pending`, `Completed`, `Failed`
  * `fromTransactionsId` (Integer): The ID of the transaction debiting the payee.
  * `toTransactionsId` (Integer): The ID of the transaction crediting the customer.
  * `customersId` (Integer): The customer's ID.
  * `assetPair` (String): The asset pair for the exchange.
  * `requestAmount` (Decimal): The requested quantity to buy.
  * `requestPrice` (Decimal): The requested price for the buy.
  * `executedAmount` (Decimal): The actual quantity bought if the order is fulfilled.
  * `executedPrice` (Decimal): The price at which the order was executed.
  * `commissionFee` (Decimal): Fee charged for the transaction.
  * `payeesId` (Integer): Null for buy exchanges.
  * `transferType` (String): Null for buy exchanges.
  * `bHasOpenRfi` (Boolean): False for buy exchanges.

**Success Response Example:**

```json
{
  "id": 0,
  "details": {
    "id": 23304,
    "exchangeType": "Buy",
    "status": "Pending",
    "fromTransactionsId": 3412,
    "toTransactionsId": 3411,
    "customersId": 1004,
    "assetPair": "BTC/USDC",
    "requestAmount": 0.004,
    "requestPrice": 100.0,
    "executedAmount": 0.00399,
    "executedPrice": 100.0,
    "commissionFee": 1.50
  },
  "status": "1",
  "errors": []
}
```

#### Possible Error Codes

| Error Message Code       | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| Required                 | Named field 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 |

***

## List Exchanges

Provides a system generated list of crypto asset exchanges, with ability to filter by the type of exchange (Buy / Sell), the Status of the exchange, and CustomersID, asset pair.

* **Endpoint:** `/api/v1/customer/crypto-exchanges/buy`
* **Method:** `GET`

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/crypto-exchanges/list" method="get" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

#### Request Query

**Optional Request Query Parameters:**

* `customersId` (Integer): The ID of the customer initiating the purchase.
* `assetPair` (String): The asset pair to be filtered, such as "BTC/USDC".
* `exchangeType` (String): Specifies the type of exchanges to filter (possible values: Buy, Sell).
* `status` (String): Exchange status filter
  * **Possible values:**

    `WaitingForApproval` - Awaiting review by transaction compliance team

    `Rejected` - Rejected by transaction compliance team

    `WaitingForConfirmation` - Requires Customer to approve / cancel new price

    `Pending` - Exchange Processing

    `Completed` - Exchange Completed

    `Failed` - Exchange Failed / Voided
* `PageNumber` (Integer): List page number (default = 1)
* `PageSize` (Integer): List page size (default = 10)

#### Request Query Example

```url
{{endpoint}}/api/v1/customer/crypto-exchanges/list?CustomersId=1001
```

#### Response Body Example

```json
{
    "id": 1001,
    "details": [
        {
            "id": 1001,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 4030.340000000000000000,
            "requestPrice": 4007.800000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 20.140000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1002,
            "exchangeType": "Sell",
            "status": "Completed",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 5037.320000000000000000,
            "requestPrice": 5009.640000000000000000,
            "executedAmount": 5037.320301634090314320,
            "executedPrice": 5009.640000000000000000,
            "commissionFee": 25.170000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1003,
            "exchangeType": "Buy",
            "status": "Pending",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 48.430000000000000000,
            "requestPrice": 50.430000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 0.000000000000000000,
            "payeesId": null,
            "transferType": null,
            "bHasOpenRfi": false
        },
        {
            "id": 1004,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 25.500000000000000000,
            "requestPrice": 20.000000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 3.500000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1005,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 25.500000000000000000,
            "requestPrice": 20.000000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 3.500000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1006,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 67.000000000000000000,
            "requestPrice": 39.990000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 25.000000000000000000,
            "payeesId": 1001,
            "transferType": "Wire",
            "bHasOpenRfi": false
        },
        {
            "id": 1007,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "ETH/USD",
            "requestAmount": 0.021422500000000000,
            "requestPrice": 40.510000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 25.000000000000000000,
            "payeesId": 1001,
            "transferType": "Wire",
            "bHasOpenRfi": false
        },
        {
            "id": 1008,
            "exchangeType": "Sell",
            "status": "WaitingForConfirmation",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "ETH/USD",
            "requestAmount": 0.008122880000000000,
            "requestPrice": 20.030000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 3.500000000000000000,
            "payeesId": 1001,
            "transferType": "ACH",
            "bHasOpenRfi": false
        },
        {
            "id": 1009,
            "exchangeType": "Buy",
            "status": "Completed",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "USDC/USD",
            "requestAmount": 16.748325170000000000,
            "requestPrice": 22.250000000000000000,
            "executedAmount": 16.740000000000000000,
            "executedPrice": 22.250000000000000000,
            "commissionFee": 3.500000000000000000,
            "payeesId": null,
            "transferType": null,
            "bHasOpenRfi": false
        },
        {
            "id": 1010,
            "exchangeType": "Sell",
            "status": "Completed",
            "fromTransactionsId": 12345,
            "toTransactionsId": 12346,
            "customersId": 1001,
            "assetPair": "ETH/USD",
            "requestAmount": 0.013405240000000000,
            "requestPrice": 20.000000000000000000,
            "executedAmount": 0.013371975384448000,
            "executedPrice": 20.000000000000000000,
            "commissionFee": 25.000000000000000000,
            "payeesId": 1001,
            "transferType": "Wire",
            "bHasOpenRfi": false
        }
    ],
    "pageSize": 10,
    "pageNumber": 1,
    "numberOfPages": 2,
    "status": "1",
    "errors": []
}
```

***

## Review Quote

When an exchange is flagged for compliance review, exchange rates may fluctuate between the time that a request was made, and when the request is approved. This endpoint will allow you to retrieve new prices for an exchange that was approved by our compliance team, for scenarios where the price of the asset has changed.

* **Endpoint:** `/api/v1/customer/crypto-exchanges/reviewquote`
* **Method:** `POST`

Example Request Body

```json
{
    "ExchangesId": 5005
}
```

#### Response Parameters

* CustomersId: Customer's Id
* AssetPair: Asset pair to trade
* QuantityType: Quantity type indicating whether price or amount is fixed (possible values: Price, Amount)
* Amount: Amount to request to trade
* NetPrice: Exchange effective net price accounting for commission and network fees
* NetworkFee: Estimated exchange network fee
* CommissionFee: Exchange commission fee
* Price: Price to request to trade for
* PayeesId: If receiving account is a passthrough account, receiving payee's Id (optional)
* PreviousPrice: Previous exchange price before approval
* PreviousAmount: Previous exchange amount before approval

#### Example Response Body

```json
{
    "id": 5005,
    "details": {
        "previousPrice": 53.470000000000000000,
        "previousAmount": 58.983359712153660000,
        "customersId": 1000,
        "payeesId": 1001,
        "quantityType": "Amount",
        "assetPair": "USDC/USD",
        "amount": 58.983359712153660000,
        "netPrice": 58.970000000000000000,
        "networkFee": 2.00,
        "commissionFee": 0.710000000000000000,
        "price": 56.260000000000000000,
        "fxRateId": null,
        "fxRateExpiryDate": null
    },
    "status": "1",
    "errors": []
}
```

***

## Confirm Sell Exchange

When an exchange is flagged for compliance review, exchange rates may fluctuate between the time that a request was made, and when the request is approved. This endpoint will allow you to confirm a price change and trigger the exchange to proceed.

The Amount and Price submitted in the body are from the response of [Review Quote](#review-quote)

* **Endpoint:** `/api/v1/customer/crypto-exchanges/confirmsell`
* **Method:** `POST`

#### Example Request Body

```json
{
    "ExchangesId": 5005,
    "amount": 58.983359712153660000,
    "price": 56.260000000000000000
}
```

#### Example Response Body

```json
{
    "id": 5005,
    "details": {
        "id": 5005,
        "exchangeType": "Sell",
        "status": "WaitingForApproval",
        "fromTransactionsId": 123455,
        "toTransactionsId": 123456,
        "customersId": 1000,
        "assetPair": "USDT/USD",
        "requestAmount": 58.983359712153660000,
        "requestPrice": 56.260000000000000000,
        "executedPrice": 53.470000000000000000,
        "commissionFee": 3.500000000000000000,
        "commissionFee": 0.710000000000000000,
        "payeesId": 1001,
        "transferType": "ACH",
        "bHasOpenRfi": false
    },
    "status": "1",
    "errors": []
}
```

***

## Cancel Exchange

When an exchange is flagged for compliance review, exchange rates may fluctuate between the time that a request was made, and when the request is approved. This endpoint will allow you to cancel an exchange that was recently approved, when the price of an asset has changed.

* **Endpoint:** `/api/v1/customer/crypto-exchanges/cancel`
* **Method:** `POST`

Example Request Body

```json
{
    "ExchangesId": 5005
}
```

#### Example Response Body

```json
{
    "id": 0,
    "details": {
        "id": 5005,
        "exchangeType": "Sell",
        "status": "Failed",
        "fromTransactionsId": 123455,
        "toTransactionsId": 123456,
        "customersId": 1000,
        "assetPair": "USDC/USD",
        "requestAmount": 58.983359712153660000,
        "requestPrice": 53.470000000000000000,
        "executedAmount": 58.983359712153660000,
        "executedPrice": 53.470000000000000000,
        "commissionFee": 3.500000000000000000,
        "payeesId": 1001,
        "transferType": "ACH",
        "bHasOpenRfi": false
    },
    "status": "1",
    "errors": []
}

```


# Foreign Currency Exchange

## Overview

The Foreign Exchange module provides the infrastructure to carry out currency exchanges on behalf of customers —a particularly important feature for platforms that accommodate multiple currencies. This module includes a series of endpoints tailored to the needs of users looking to perform, monitor, and manage asset exchanges for their customers.

Offering functions from quoting to execution, along with detailed tracking mechanisms, the Foreign Exchange module endpoints include:

1. [**Get Available Currency Pairs**](#get-available-currency-pairs): Provides a full list of currency pairs available for exchange.
2. [**Get Account Details**](#get-account-details): This endpoint will return available source and destination accounts the customer can choose to do the exchange.
3. [**Get Quote for Exchange**](#get-quote-for-exchange)**:** Provides an estimate for an exchange, detailing the source and destination amount before the actual exchange is executed, ensuring that the customer is informed about the potential transaction.
4. [**Execute Exchange**](#execute-exchange)**:** Execute the quote exchange using the id received from the quote for exchange.

Overall, the Exchange module is designed to offer a seamless and secure experience for handling the exchange requirements of customers, ensuring that users can manage these operations effectively with great precision and control.

***

## Get Available Currency Pairs

Provides a full list of asset pairs enabled for the API user. The response will also include information on limits and minimums associated with each asset pair for exchanges.

* **Endpoint:** `/api/v1/customer/foreign-exchanges/pairs`
* **Method:** `GET`

{% openapi src="/files/LzwQu0gRokM1pqinJ26Q" path="/api/v1/customer/foreign-exchanges/pairs" method="get" %}
[publicapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-3f41179f70977055e3425370d7bea65077bb3152%2Fpublicapi.json?alt=media)
{% endopenapi %}

**Success Response Example:**

```json
{
    "id": 14107,
    "details": [
        {
            "baseAsset": "CNH",
            "exchangeAsset": "SGD"
        },        
        {
            "baseAsset": "EUR",
            "exchangeAsset": "CHF"
        },
        {
            "baseAsset": "GBP",
            "exchangeAsset": "SGD"
        },
        {
            "baseAsset": "USD",
            "exchangeAsset": "SGD"
        }
    ],
    "pageSize": 100,
    "pageNumber": 1,
    "numberOfPages": 1,
    "status": "1",
    "errors": []
}
```

## Get Account Details

Provides list of source and destination accounts based on the source and destination currency provided for the customer.

* **Endpoint:** `/api/v1/customer/foreign-exchanges/account-details`
* **Method:** `GET`

{% openapi src="/files/LzwQu0gRokM1pqinJ26Q" path="/api/v1/customer/foreign-exchanges/account-details" method="get" %}
[publicapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-3f41179f70977055e3425370d7bea65077bb3152%2Fpublicapi.json?alt=media)
{% endopenapi %}

**Success Response Example:**

```json
{
    "id": 14107,
    "details": {
        "sourceAsset": "GBP",
        "destinationAsset": "SGD",
        "fromAccounts": [
            {
                "accountID": "3140",
                "displayName": "GBP Account",
                "currencySymbol": "£",
                "balance": 5159.54
            }
        ],
        "toAccounts": [
            {
                "accountID": "3146",
                "displayName": "SGD Account",
                "currencySymbol": "S$",
                "balance": 2399.32
            }
        ]
    },
    "status": "1",
    "errors": []
}
```

## Get Quote for Exchange

This endpoint provides a quoted market price for a proposed asset exchange for a particular customer, detailing the source and destination amount for either a "Buy" or "Sell" exchange type. By specifying details of the desired trade, a customer can see the cost or proceeds they might expect from completing a transaction, including any applicable fees. This helps customers decide whether to proceed with an exchange based on real-time financial data.

* **Endpoint:** `/api/v1/customer/foreign-exchanges/quote`
* **Method:** POST

{% openapi src="/files/LzwQu0gRokM1pqinJ26Q" path="/api/v1/customer/foreign-exchanges/quote" method="post" %}
[publicapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-3f41179f70977055e3425370d7bea65077bb3152%2Fpublicapi.json?alt=media)
{% endopenapi %}

**Request Example:**

```json
{
    "SourceCurrency": "GBP",
    "DestinationCurrency": "SGD",
    "SourceAmount": "100",
    "SourceAccountId": 3140,
    "DestinationAccountId":3146
}
```

**Success Response Example:**

```json
{
    "id": 1,
    "details": {
        "sourceAmount": 100,
        "destinationAmount": null,
        "quoteSourceAmount": null,
        "quoteDestinationAmount": 167.89,
        "sourceAmountLessFees": 99.5,
        "comissionFees": 0.5,
        "totalFees": 0.5,
        "quotedFXRate": "1.687312",
        "quotedFXRateID": 1423,
        "quotedFxRateExpiry": "2024-08-19T14:13:22.6153953Z"
    },
    "status": "1",
    "errors": []
}
```

#### Possible Error Codes

<table><thead><tr><th width="268">Error Message Code</th><th>Description</th></tr></thead><tbody><tr><td>Required</td><td>Named field missing or zero</td></tr><tr><td>Invalid</td><td>Value given for named field is invalid</td></tr><tr><td>No_Account</td><td>No source account details found</td></tr><tr><td>Insufficient_Funds</td><td>Source account do not have enough funds to performa the exchange</td></tr></tbody></table>

***

## Execute Exchange

This endpoint is designed to initiate a sell exchange, allowing a customer to sell an asset at a given price or for a specific amount.

* **Endpoint:** `/api/v1/customer/foreign-exchanges/executeexchange`
* **Method:** `POST`

{% openapi src="/files/LzwQu0gRokM1pqinJ26Q" path="/api/v1/customer/foreign-exchanges/executeexchange" method="post" %}
[publicapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-3f41179f70977055e3425370d7bea65077bb3152%2Fpublicapi.json?alt=media)
{% endopenapi %}

#### Request Body Example:

```json
{
    "FxRateId": 1423,
    "PurposeCode": "test"
}
```

#### Success Response Example:

```json
{
    "id": 14589,
    "details": {},
    "status": "1",
    "errors": []
}
```

#### Possible Error Codes

| Error Message Code       | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| Required                 | Named field 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 |

***

```json
```


# Payees (Beneficiaries)

## Overview

The Payees module is an integral part of the customer API that allows users to manage their list of payees—people or organizations they need to send money to. It provides a suite of API endpoints that facilitate various operations required to maintain an up-to-date payee list for customers within the platform.

1. [**Create Payee**](#create-payee) **-** Allows users to add a new payee with details such as name, banking information, and address. This is essential for setting up new beneficiaries for transactions.
2. [**Edit Payee**](#edit-payee) **-** Users can update the details of an existing payee. This endpoint is useful for making corrections or changes to the payee information, such as their bank account details or address.
3. [**Get Payee by ID**](#get-payee-by-id) - Enables a user to retrieve information about a payee by submitting the ID of the payee.
4. [**List Payees**](#list-payees) - Retrieve a list of payees associated with a customer
5. [**Delete Payee**](#delete-payee) - Allows a user to delete a Payee, removing it from being an option for further transfer destinations
6. [**Create Card Payee**](#create-card-payee) - Allows a user to create a new payee for use with Visa Direct.
7. [**View Card Payee**](#view-card-payee) - Allows a user view details for a card payee.
8. [**List Card Payees**](#list-card-payees) - Retrieves a list of available card payees.
9. [**Initiate ACH Pull**](#initiate-ach-pull) **-** Allows a manager to initiate an ACH pull request from a customer's payee. If used with a card payee, will initiate a Visa Direct pull instead.

***

## Create Payee

This endpoint creates a new payee for a specific customer. A payee is essentially a destination that where one would send a payment to outside of the banking system, such as a bank account. A customer can use this feature to add a new person or company they need to send money to. The customer inputs necessary banking details and address information to set up the payee in their account

* **Endpoint:** `/api/v3/customer/payees/create`
* **Method:** `POST`

{% openapi src="/files/eODaclmiV5Dxiry7JC14" path="/api/v3/customer/payees/create" method="post" %}
[public-api-customer-role (1).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-694e446cdf6eb05828d1545398e8607aeb6ae7bd%2Fpublic-api-customer-role%20\(1\).json?alt=media)
{% endopenapi %}

**Request Body: `application/json`**

* `CustomersId` (Integer, Required): The identifier for the customer.
* `CustomerAssetAccountsId` (Integer, Required): Customer's account from which funds will be sent.
* `PayeeType` (String, Required): The type of payee, values can be `Personal` or `Company`.
* `RoutingNumber` (String, Optional, For domestic payees): The routing number of the payee's bank for domestic transactions.
* `AccountNumber` (String, Required): The bank account number of the payee.
* `BankName` (String, Optional): The bank's name. This will be looked up based on other information if not included.
* `Bic` (String, Optional, For international payees): The SWIFT/BIC code for international banking purposes.
* `IntermediaryBic` (String, Optional, For international payees): Bank intermediary SWIFT/BIC code.
* `Iban` (String, Optional, For international payees): The International Bank Account Number for international transactions.
* `PayeesReference` (String, Optional): A customer-defined reference for the payee.
* `Name` (String, Required): The full name of the payee.
* `AddressLine1` (String, Required): The primary address line for the payee.
* `AddressLine2` (String, Optional): The secondary address line for the payee (if any).
* `TownCity` (String, Required): The town or city where the payee is located.
* `State` (String, Required): The state or region where the payee is located.
* `Country` (String, Required): The country where the payee is located.
* `Postcode` (String, Required): The postal code associated with the payee's address.
* `Transmitter` (Object, Optional): Transmitter information, required for financial institutions.
* `Transmitter.FirstPartyTransfer` (Boolean, Required): Is this payee for first party transfers?
* `Transmitter.Name` (String, Required if not a first party transfer): Transmitter's name.
* `Transmitter.AccountNumber` (String, Optional): Transmitter's account number.
* `Transmitter.AddressLine1` (String, Required if not a first party transfer): Transmitter's address line 1.
* `Transmitter.AddressLine2` (String, Optional): Transmitter's address line 2.
* `Transmitter.TownCity` (String, Required if not a first party transfer): Transmitter's town or city.
* `Transmitter.State` (String, Required if not a first party transfer): Transmitter's state. For USA use the ANSI 2-letter state codes.
* `Transmitter.Postcode` (String, Required if not a first party transfer): Transmitter's postcode.
* `Transmitter.CountryCode` (String, Required if not a first party transfer): Transmitter's alpha-3 country code.
* `Transmitter.Type` (String, Required if not a first party transfer): Transmitter's type, either 'Individual' or 'Company'.
* `Transmitter.DateOfBirth` (String, Required if type is 'Individual', ISO 8061): The transmitter's date of birth in "YYYY-MM-DD" format.

#### Request Body Example:

<pre class="language-json"><code class="lang-json">{
    	"CustomersId":1545,
        "CustomerAssetAccountsId":3684,
<strong>        "PayeeType":"Personal",
</strong>        "AccountNumber":"12345678922",
        "RoutingNumber":null,
        "bic":"NAIAGB23",
        "IntermediaryBic":"XXXX",
        "iban":"Foo",
        "PayeesReference":"MYPAYEE123",
	"Name":"My Payee",
	"AddressLine1":"Line1",
	"AddressLine2":"Line2",
	"TownCity":"MyCity",
	"State":"Essex",
	"Postcode":"MK1 9AJ",
        "Country":"GBR",
        "Transmitter":{
            "FirstPartyTransfer": true,
            "Name": "John Doe",
            "AccountNumber": "123456789",
            "AddressLine1": "123 Main St",
            "AddressLine2": "Apt 4B",
            "TownCity": "New York",
            "State": "NY",
            "Postcode": "10001",
            "CountryCode": "USA",
            "Type": "Individual",
            "DateOfBirth": "1988-04-21"
        }
}
</code></pre>

**Response Body (Success): `application/json`**

* `id` (Integer): A generated ID that references the newly created payee.
* `details` (Object): An object containing details about the newly created payee:
  * `id` (Integer): Same as the outer `id` field for ease of access.
  * `customersId` (Integer): The customer's ID for whom the payee was created.
  * `customerAssetAccountsId` (Integer): Customer's account from which funds will be sent. to payee.
  * `payeeType` (String): The type of payee, `Personal` or `Company`.
  * `payeeReference` (String): Customer defined payee reference.
  * `routingNumber` (String): The routing number of the payee's bank.
  * `accountNumber` (String): The bank account number of the payee.
  * `bic` (String): The SWIFT/BIC code of the payee.
  * `IntermediaryBic` (String): Payee's intermediary BIC number
  * `iban` (String): The International Bank Account Number of the payee.
  * `name` (String): The full name of the payee.
  * `addressLine1` (String): The primary address line for the payee.
  * `addressLine2` (String): The secondary address line for the payee.
  * `townCity` (String): The town or city where the payee is located.
  * `state` (String): The state or region where the payee is located.
  * `postcode` (String): The postal code for the payee's address.
  * `country` (String): The country where the payee is located.
  * `bankName` (String): The name of the payee's bank.
  * `transmitterFirstPartyTransfer` (Boolean): Is this payee for first party transfers?
  * `transmitterName` (String): Transmitter's name.
  * `transmitterAccountNumber` (String): Transmitter's account number.
  * `transmitterAddressLine1` (String): Transmitter's address line 1.
  * `transmitterAddressLine2` (String): Transmitter's address line 2.
  * `transmitterTownCity` (String): Transmitter's town or city.
  * `transmitterState` (String): Transmitter's state.
  * `transmitterPostcode` (String): Transmitter's postcode.
  * `transmitterCountryCode` (String): Transmitter's alpha-3 country code.
  * `transmitterType` (String): Transmitter's type, either 'Individual' or 'Company'.
  * `transmitterDateOfBirth` (String, ISO 8061): The transmitter's date of birth in "YYYY-MM-DD" format.
* `status` (Integer): The status code, typically "1" for success.
* `errors` (Array): An array containing any error messages related to the request.

#### Response Body Example:

<pre class="language-json"><code class="lang-json">{
    "id": 1732,
    "details": {
        "id": 1732,
        "customersId": 1545,
        "customerAssetAccountsId": 3684,
        "payeeType": "Personal",
        "payeesReference": "MYPAYEE123",
        "routingNumber": null,
        "accountNumber": "12345678922",
        "bic": "NAIAGB23",
        "IntermediaryBic":"XXXX",
        "iban": "Foo",
        "name": "My Payee",
        "addressLine1": "Line1",
        "addressLine2": "Line2",
        "townCity": "MyCity",
        "state": "Essex",
        "postcode": "MK1 9AJ",
        "country": "GBR",
        "bankName": "",
<strong>        "transmitterFirstPartyTransfer": true,
</strong>        "transmitterName": "John Doe",
        "transmitterAccountNumber": "123456789",
        "transmitterAddressLine1": "123 Main St",
        "transmitterAddressLine2": "Apt 4B",
        "transmitterTownCity": "New York",
        "transmitterState": "NY",
        "transmitterPostcode": "10001",
        "transmitterCountryCode": "USA"
        "transmitterType": "Individual",
        "transmitterDateOfBirth": "1988-04-21"
    },
    "status": "1",
    "errors": []
}
</code></pre>

**Possible Error Response:**

* `Required` (Error Code): Indicates that a required field is missing or has a zero value.
* `Invalid` (Error Code): Suggests that a field contains an invalid value.
* `Documents_Not_Verified` (Error Code): This action cannot be performed for the customer due to KYC (Know Your Customer) requirements not being met.

***

## Edit Payee

Users can update the details of someone they've set up to send payments to (a payee). They'll need to provide specific information like the account details they wish to change. Once submitted, the system updates the payee's details, confirming the updates with the user or reporting why it wasn't able to if there's an issue. **Only non-null fields will be updated**. This endpoint cannot be used to edit card payees.

* **Endpoint:** `/api/v3/customer/payees/edit`
* **Method:** `PATCH`

{% openapi src="/files/eODaclmiV5Dxiry7JC14" path="/api/v3/customer/payees/edit" method="patch" %}
[public-api-customer-role (1).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-694e446cdf6eb05828d1545398e8607aeb6ae7bd%2Fpublic-api-customer-role%20\(1\).json?alt=media)
{% endopenapi %}

**Request Body Parameters: `application/json`**

**Only non-null fields will be updated!**

* `Id` (Integer, Required): The ID of the payee to be edited.
* `PayeeType` (String, Optional): The type of payee, values can be `Personal` or `Company`.
* `RoutingNumber` (String, Optional): The routing number of the payee's bank for domestic transactions.
* `AccountNumber` (String, Optional): The bank account number of the payee.
* `BankName` (String, Optional): The bank's name, which will be looked up based on other information if not included.
* `Bic` (String, Optional): The SWIFT/BIC code for international banking purposes.
* `IntermediaryBic` (String, Optional, For international payees): Bank intermediary SWIFT/BIC code
* `Iban` (String, Optional): The International Bank Account Number for international transactions.
* `PayeesReference` (String, Optional): A customer-defined reference for the payee.
* `Name` (String, Optional): The full name of the payee.
* `AddressLine1` (String, Optional): The primary address line for the payee.
* `AddressLine2` (String, Optional): The secondary address line for the payee (if any).
* `TownCity` (String, Optional): The town or city where the payee is located.
* `State` (String, Optional): The state or region where the payee is located.
* `Country` (String, Optional): The country where the payee is located.
* `Postcode` (String, Optional): The postal code associated with the payee's address.
* `Transmitter` (Object, Optional): Transmitter information, required for financial institutions.
* `Transmitter.FirstPartyTransfer` (Boolean, Required): Is this payee for first party transfers?
* `Transmitter.Name` (String, Required if not a first party transfer): Transmitter's name.
* `Transmitter.AccountNumber` (String, Optional): Transmitter's account number.
* `Transmitter.AddressLine1` (String, Required if not a first party transfer): Transmitter's address line 1.
* `Transmitter.AddressLine2` (String, Optional): Transmitter's address line 2.
* `Transmitter.TownCity` (String, Required if not a first party transfer): Transmitter's town or city.
* `Transmitter.State` (String, Required if not a first party transfer): Transmitter's state. For USA use the ANSI 2-letter state codes.
* `Transmitter.Postcode` (String, Required if not a first party transfer): Transmitter's postcode.
* `Transmitter.CountryCode` (String, Required if not a first party transfer): Transmitter's alpha-3 country code.
* `Transmitter.Type` (String, Required if not a first party transfer): Transmitter's type, either 'Individual' or 'Company'.
* `Transmitter.DateOfBirth` (String, Required if type is 'Individual', ISO 8061): The transmitter's date of birth in "YYYY-MM-DD" format.

Request Body Example:

```json
{
    "id": 2288,
    "PayeeType": "Personal",
    "RoutingNumber": "",
    "AccountNumber": "521101580",
    "BankName": "My Bank",
    "Bic": "CZNBVN2XXXX",
    "IntermediaryBic":"XXXX",
    "Iban": "12345Test",
    "PayeesReference": "RefExample",
    "Name": "Name Surname",
    "AddressLine1": "Address Line 1",
    "TownCity": "Austin",
    "State": "TX",
    "Country": "VNM",
    "Postcode": "123ABC",
    "Transmitter":{
            "FirstPartyTransfer": true,
            "Name": "John Doe",
            "AccountNumber": "123456789",
            "AddressLine1": "123 Main St",
            "AddressLine2": "Apt 4B",
            "TownCity": "New York",
            "State": "NY",
            "Postcode": "10001",
            "CountryCode": "USA",
            "Type": "Individual",
            "DateOfBirth": "1988-04-21"
    }
}
```

**Response Body Parameters: `application/json`**

* `id` (Integer): A reference ID for the payee; not used in the example.
* `details` (Object): An object containing updated details about the payee, including:
  * `id` (Integer): The ID of the payee that was edited.
  * `customersId` (Integer): The customer's ID associated with the edited payee.
  * `customerAssetAccountsId` (Integer): Customer's account from which funds will be sent. to payee.
  * `payeeType` (String): The updated type of payee, `Personal` or `Company`.
  * `payeesReference` (String): The updated customer defined payee reference.
  * `routingNumber` (String): The updated routing number of the payee's bank.
  * `accountNumber` (String): The updated bank account number of the payee.
  * `bic` (String): The updated SWIFT/BIC code of the payee.
  * `IntermediaryBic` (String): Payee's intermediary BIC number
  * `iban` (String): The updated International Bank Account Number of the payee.
  * `name` (String): The updated name of the payee.
  * `addressLine1` (String): The updated address line for the payee.
  * `addressLine2` (String, Nullable): The updated address line 2 for the payee.
  * `townCity` (String): The updated town or city where the payee is located.
  * `state` (String): The updated state or region where the payee is located.
  * `postcode` (String): The updated postal code for the payee's address.
  * `country` (String): The updated country where the payee is located.
  * `bankName` (String): The updated bank name of the payee.
  * `transmitterFirstPartyTransfer` (Boolean): Is this payee for first party transfers?
  * `transmitterName` (String): Transmitter's name.
  * `transmitterAccountNumber` (String): Transmitter's account number.
  * `transmitterAddressLine1` (String): Transmitter's address line 1.
  * `transmitterAddressLine2` (String): Transmitter's address line 2.
  * `transmitterTownCity` (String): Transmitter's town or city.
  * `transmitterState` (String): Transmitter's state.
  * `transmitterPostcode` (String): Transmitter's postcode.
  * `transmitterCountryCode` (String): Transmitter's alpha-3 country code.
  * `transmitterType` (String): Transmitter's type, either 'Individual' or 'Company'.
  * `transmitterDateOfBirth` (String, ISO 8061): The transmitter's date of birth in "YYYY-MM-DD" format.

**Success Response Example:**

```json
{
    "id": 2288,
    "details": {
        "id": 2288,
        "customersId": 1545,
        "customerAssetAccountsId": 1707,
        "payeeType": "Personal",
        "payeesReference": "RefExample",
        "routingNumber": null,
        "accountNumber": "521101580",
        "bic": "CZNBVN2XXXX",
        "intermediaryBic": "XXXX",
        "iban": "12345Test",
        "name": "Name Surname",
        "addressLine1": "Address Line 1",
        "addressLine2": "Line2",
        "townCity": "Austin",
        "state": "TX",
        "postcode": "123ABC",
        "country": "VNM",
        "bankName": "My Bank",
        "transmitterFirstPartyTransfer": true,
        "transmitterName": "John Doe",
        "transmitterAccountNumber": "123456789",
        "transmitterAddressLine1": "123 Main St",
        "transmitterAddressLine2": "Apt 4B",
        "transmitterTownCity": "New York",
        "transmitterState": "NY",
        "transmitterPostcode": "10001",
        "transmitterCountryCode": "USA",
        "transmitterType": "Individual",
        "transmitterDateOfBirth": "1988-04-21"
    },
    "status": "1",
    "errors": []
}
```

**Error Codes:**

* `Required` (Error Code): Indicates that a required field is missing or has a zero value.
* `Invalid` (Error Code): Suggests that a field contains an invalid value.
* `Documents_Not_Verified` (Error Code): The action cannot be performed for the customer due to KYC (Know Your Customer) requirements not being met.

**Error Response Example:**

```json
{
  "id": 0,
  "details": null,
  "status": "0",
  "errors": [
    {
      "errorType": "BadRequest",
      "fieldName": "PayeeType",
      "messageCode": "Invalid"
    }
  ]
}
```

***

## Get Payee by ID

Users can retrieve the details of someone they've set up to send payments to (a payee). They'll need to provide the specific ID of the payee to retrieve information. This endpoint should not be used for card payees, use the [card view endpoint](#view-card-payee) instead.

* **Endpoint:** `/api/v4/customer/payees/get`
* **Method:** `GET`

## Get payee by Id

> Request query:
> \
> &#x20;\- Id: Payee's Id
> \
> &#x20;
> \
> Response:
> \
> &#x20;\- Id: Payee's Id
> \
> &#x20;\- CustomersId: Customer's Id
> \
> &#x20;\- CustomerAssetAccountsID: Customer's asset account id
> \
> &#x20;\- PayeeType: Payee type
> \
> &#x20;\- PayeesReference: Customer defined payee reference
> \
> &#x20;\- RoutingNumber: Payee's routing number
> \
> &#x20;\- AccountNumber: Payee's account number
> \
> &#x20;\- Bic: Payee's BIC number
> \
> &#x20;\- IntermediaryBic : Payee's intermediary BIC number
> \
> &#x20;\- Iban: Payee's IBAN number
> \
> &#x20;\- Name: Payee's name
> \
> &#x20;\- AddressLine1: Payee address line 1
> \
> &#x20;\- AddressLine2: Payee address line 2
> \
> &#x20;\- TownCity: Payee's town or city
> \
> &#x20;\- State: Payee's state
> \
> &#x20;\- Postcode: Payee's postcode
> \
> &#x20;\- Country: Payee's country
> \
> &#x20;\- BankName: Payee's bank name
> \
> &#x20;\- CurrencyCode: Payee's currency code
> \
> &#x20;\- TransmitterFirstPartyTransfer: Is this payee for first party transfers
> \
> &#x20;\- TransmitterName: Transmitter name
> \
> &#x20;\- TransmitterAccountNumber: Transmitter account number
> \
> &#x20;\- TransmitterAddressLine1: Transmitter address line 1
> \
> &#x20;\- TransmitterAddressLine2: Transmitter address line 2
> \
> &#x20;\- TransmitterTownCity: Transmitter town or city
> \
> &#x20;\- TransmitterState: Transmitter state
> \
> &#x20;\- TransmitterPostcode: Transmitter postcode
> \
> &#x20;\- TransmitterCountryCode: Transmitter country code  &#x20;
> \
> &#x20;\- Transmitter.Type: Transmitter type
> \
> &#x20;\- Transmitter.DateOfBirth: Transmitter date of birth
> \
> &#x20;\- SupportedTransferTypes: Payee's allowed transfer types
> \
> &#x20;
> \
> Possible validation errors:
> \
> &#x20;\- Required,
> \
> &#x20;\- Invalid

```json
{"openapi":"3.0.1","info":{"title":"Customer API v1.0 - Production","version":"v1.0"},"tags":[{"name":"PayeesV4Module"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"JWT Authorization header using the Bearer scheme. \n\nExample: \"Authorization: Bearer {token}\" \n\nTokens can be generated using the /api/v1/public/auth/login endpoint.","name":"Authorization","in":"header"}},"schemas":{"Results.ObjectResultDto_CustomerRole.PayeesV4.PayeeDto":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"details":{"$ref":"#/components/schemas/CustomerRole.PayeesV4.PayeeDto"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false},"CustomerRole.PayeesV4.PayeeDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"customersId":{"type":"integer","format":"int32"},"customerAssetAccountsId":{"type":"integer","format":"int32","nullable":true},"payeeType":{"$ref":"#/components/schemas/PayeeTypes"},"payeesReference":{"type":"string","nullable":true},"routingNumber":{"type":"string","nullable":true},"accountNumber":{"type":"string","nullable":true},"bic":{"type":"string","nullable":true},"intermediaryBic":{"type":"string","nullable":true},"iban":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"addressLine1":{"type":"string","nullable":true},"addressLine2":{"type":"string","nullable":true},"townCity":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postcode":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"bankName":{"type":"string","nullable":true},"currencyCode":{"type":"string","nullable":true},"transmitterFirstPartyTransfer":{"type":"boolean","nullable":true},"transmitterName":{"type":"string","nullable":true},"transmitterAccountNumber":{"type":"string","nullable":true},"transmitterAddressLine1":{"type":"string","nullable":true},"transmitterAddressLine2":{"type":"string","nullable":true},"transmitterTownCity":{"type":"string","nullable":true},"transmitterState":{"type":"string","nullable":true},"transmitterPostcode":{"type":"string","nullable":true},"transmitterCountryCode":{"type":"string","nullable":true},"transmitterType":{"type":"string","nullable":true},"transmitterDateOfBirth":{"type":"string","nullable":true},"supportedTransferTypes":{"type":"string","nullable":true}},"additionalProperties":false},"PayeeTypes":{"enum":["Personal","Company"],"type":"string"},"Results.Base.ErrorResultDto":{"type":"object","properties":{"fieldName":{"type":"string","nullable":true},"messageCode":{"type":"string","nullable":true}},"additionalProperties":false},"Results.ResultDto":{"type":"object","properties":{"id":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true,"readOnly":true},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Results.Base.ErrorResultDto"},"nullable":true}},"additionalProperties":false}}},"paths":{"/api/v4/customer/payees/get":{"get":{"tags":["PayeesV4Module"],"summary":"Get payee by Id","description":"Request query:\r\n - Id: Payee's Id\r\n \r\nResponse:\r\n - Id: Payee's Id\r\n - CustomersId: Customer's Id\r\n - CustomerAssetAccountsID: Customer's asset account id\r\n - PayeeType: Payee type\r\n - PayeesReference: Customer defined payee reference\r\n - RoutingNumber: Payee's routing number\r\n - AccountNumber: Payee's account number\r\n - Bic: Payee's BIC number\r\n - IntermediaryBic : Payee's intermediary BIC number\r\n - Iban: Payee's IBAN number\r\n - Name: Payee's name\r\n - AddressLine1: Payee address line 1\r\n - AddressLine2: Payee address line 2\r\n - TownCity: Payee's town or city\r\n - State: Payee's state\r\n - Postcode: Payee's postcode\r\n - Country: Payee's country\r\n - BankName: Payee's bank name\r\n - CurrencyCode: Payee's currency code\r\n - TransmitterFirstPartyTransfer: Is this payee for first party transfers\r\n - TransmitterName: Transmitter name\r\n - TransmitterAccountNumber: Transmitter account number\r\n - TransmitterAddressLine1: Transmitter address line 1\r\n - TransmitterAddressLine2: Transmitter address line 2\r\n - TransmitterTownCity: Transmitter town or city\r\n - TransmitterState: Transmitter state\r\n - TransmitterPostcode: Transmitter postcode\r\n - TransmitterCountryCode: Transmitter country code   \r\n - Transmitter.Type: Transmitter type\r\n - Transmitter.DateOfBirth: Transmitter date of birth\r\n - SupportedTransferTypes: Payee's allowed transfer types\r\n \r\nPossible validation errors:\r\n - Required,\r\n - Invalid","operationId":"GET-api-v4-customer-payees-get","parameters":[{"name":"id","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"otp","in":"header","description":"One time pass for the request","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ObjectResultDto_CustomerRole.PayeesV4.PayeeDto"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Results.ResultDto"}}}}}}}}}
```

***

## List Payees

Retrieve a list of payees associated with a customer. Card payees will not be present in this list and have their own [list endpoint](#list-card-payees).

* **Endpoint:** `/api/v3/customer/payees/list`
* **Method:** `GET`

{% openapi src="/files/eODaclmiV5Dxiry7JC14" path="/api/v3/customer/payees/list" method="get" %}
[public-api-customer-role (1).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-694e446cdf6eb05828d1545398e8607aeb6ae7bd%2Fpublic-api-customer-role%20\(1\).json?alt=media)
{% endopenapi %}

***

## Delete Payee

Allows a user to delete a Payee, removing it from being an option for further transfer destinations. This endpoint is also used to delete card payees.

* **Endpoint:** `/api/v1/customer/payees/delete`
* **Method:** `DELETE`

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/payees/delete" method="delete" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

***

## Create Card Payee

Add a card (Visa Direct) payee using card details.

* **Endpoint:** `/api/v1/customer/payees/card/create`
* **Method:** `POST`

{% openapi src="/files/RRuLP4J82ozRCIdDailx" path="/api/v1/customer/payees/card/create" method="post" %}
[doc.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-9b1a0ae3b92118eff05a649feb9228fa39093cca%2Fdoc.json?alt=media)
{% endopenapi %}

***

## View Card Payee

View details for a card payee

* **Endpoint:** `/api/v1/customer/payees/card/get`
* **Method:** `GET`

{% openapi src="/files/RRuLP4J82ozRCIdDailx" path="/api/v1/customer/payees/card/get" method="get" %}
[doc.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-9b1a0ae3b92118eff05a649feb9228fa39093cca%2Fdoc.json?alt=media)
{% endopenapi %}

***

## List Card Payees

List all available card payees

* **Endpoint:** `/api/v1/customer/payees/card/list`
* **Method:** `GET`

{% openapi src="/files/RRuLP4J82ozRCIdDailx" path="/api/v1/customer/payees/card/list" method="get" %}
[doc.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-9b1a0ae3b92118eff05a649feb9228fa39093cca%2Fdoc.json?alt=media)
{% endopenapi %}

***

## **Initiate ACH Pull**

Allows a manager to initiate an ACH pull request from a customer's payee. If used with a card payee, will instead pull using Visa Direct.

* **Endpoint:** `/api/v1/customer/payees/pullfunds`
* **Method:** `POST`

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/payees/pullfunds" method="post" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

**Request Body Parameters: `application/json`**

<table data-full-width="true"><thead><tr><th width="282">Request Body Paramerer</th><th width="261">Format</th><th width="257">Description</th><th>Required</th></tr></thead><tbody><tr><td>PayeesId</td><td>Integer</td><td>PayeesId where the bank can pull funds from</td><td><mark style="color:green;">Yes</mark></td></tr><tr><td>Amount</td><td>Decimal</td><td>Amount to be pulled from payee</td><td><mark style="color:green;">Yes</mark></td></tr><tr><td>CustomerAssetAccountsId</td><td>Integer</td><td>The destination customer account id</td><td><mark style="color:green;">Yes</mark></td></tr><tr><td>Reference</td><td>String</td><td><p><strong>For pooled account this should be the reference of the pooled account.</strong></p><p>Maximum 15 characters allowed</p></td><td><mark style="color:green;">Yes</mark></td></tr></tbody></table>

#### Request Body Example

```json
{
        "PayeesId":1204,
        "Amount":100,
        "CustomerAssetAccountsId":2141,
        "Reference":"REF2141"
}
```

#### **Response Body**

<table data-full-width="true"><thead><tr><th width="354">Response Body Parameter</th><th width="140">Format</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>Integer</td><td>Transfer Id</td></tr><tr><td><strong>details.</strong></td><td></td><td></td></tr><tr><td>details.id</td><td>Integer</td><td>Transaction Id</td></tr><tr><td>details.accountsId</td><td>Integer</td><td>Transaction account Id</td></tr><tr><td>details.fromTransactionsId</td><td>Integer</td><td>Nullable linked from transaction Id</td></tr><tr><td>details.fromAccountsId</td><td>Integer</td><td>Nullable linked from account Id</td></tr><tr><td>details.toTransactionsId</td><td>Integer</td><td>Nullable linked to transaction Id</td></tr><tr><td>details.toAccountsId</td><td>Integer</td><td>Nullable linked to account Id</td></tr><tr><td>details.amount</td><td>Decimal</td><td>Transaction amount</td></tr><tr><td>details.description</td><td>String</td><td>Transaction description</td></tr><tr><td>details.dateTime</td><td>ISO 8601</td><td>Transaction date</td></tr><tr><td>details.bPending</td><td>Bool</td><td>Is transaction pending</td></tr><tr><td>details.bApproved</td><td>Bool</td><td>Is screening approved</td></tr></tbody></table>

#### Request Body Example

```json
{
    "id": 22117,
    "details": {
        "id": 31605,
        "accountsId": 2141,
        "fromTransactionsId": null,
        "fromAccountsId": null,
        "toTransactionsId": null,
        "toAccountsId": null,
        "amount": 100.000000000000000000,
        "description": "Funding Ibanera USD Account",
        "dateTime": "2024-04-15T11:21:08.8533333+00:00",
        "bPending": true,
        "bApproved": true
    },
    "status": "1",
    "errors": []
}
```

#### Potential Error Codes

| Error message code example            | Description                                                                                                                         |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Required                              | Required field not provided                                                                                                         |
| Invalid                               | Provided destination account is invalid or provided payee id is invalid                                                             |
| Funding\_Already\_Pending             | If there is already some pull funds are pending on the destination customer account, not allowed to do another pull to the account. |
| Invalid\_Source\_Account              | Provided source account is invalid                                                                                                  |
| Invalid\_Asset                        | Asset associated with the account is not fiat currency or both account have different assets.                                       |
| Ach\_limit\_exceed\_5000              | The requested amount is greater than the allowed ach limit                                                                          |
| Invalid\_Reference\_For\_FBO\_Account | For pooled destination account, given reference should match with the destination account reference                                 |
| Internal\_Error                       | Any unknown error                                                                                                                   |


# Transfers

This section covers Transfers, which serves as the hub for managing both crypto and fiat transfers. This section guides users to two key areas: [**Crypto Transfers**](/api-endpoints/transfers/crypto-transfers) and [**Fiat Transfers**](/api-endpoints/transfers/transfers), each handling respective currency transactions.

The API supports both internal and external transfers, allowing seamless movement of funds within the platform and to external accounts or wallets. Navigate to dedicated pages for detailed instructions and endpoint references tailored to each transfer type.


# Fiat Transfers

## Overview

The Transfers module of the Customer API facilitates the movement of funds and manages transfer-related operations with a suite of endpoints tailored to cover various functionalities:

1. [**Create Internal Fiat Transfer**](#create-internal-fiat-transfer): This endpoint allows customers to conduct internal fund transfers between two customer asset accounts within the system. The users need to specify the source and destination account IDs, the amount to be transferred, and a reference note for the transaction.
2. [**Create External Fiat Transfer**](#create-external-fiat-transfer): Customers can perform external transfers from their asset account using this endpoint. It supports both domestic and international transfers, requiring information about the source account, transfer type, payee details, saved payee preferences, amount, reference note, and the purpose code for the transaction.
3. [**Create External Fiat Transfer With Originator**](#create-external-fiat-transfer-with-originator): Customers can perform external transfers from their asset account using this endpoint. User's have the ability to set the transaction's originator, and thus affect how the sender's details appear in the receiver's account. It supports both domestic and international transfers, requiring information about the source account, transfer type, payee details, saved payee preferences, amount, reference note, and the purpose code for the transaction.
4. [**Get Purpose Codes**](#get-purpose-codes): This endpoint provides a list of available purpose codes that are to be used for external fiat transfers. It helps in categorizing the transfer types for internal use, such as "Transfer to own account" or "Family Maintenance".
5. [**Get Reverse Inbound Transfer Details**](#get-reverse-inbound-transfer-details) - This operation gives a user necessary details to call the POST endpoint. This includes a list of reasons for transaction reversal.
6. [**Reverse Inbound Transfer**](#reverse-inbound-transfer) - This operation allows the user to reverse an inbound external transfer.
7. [**Lookup Bank Details**](#lookup-bank-details): This endpoint allows customers to look up additional bank details given a SWIFT code (more lookup options coming soon).
8. [**Request FX Quote**](#request-fx-transfer-quote) : Request quote for foreign transfers
9. [**Execute FX Quote**](#execute-fx-transfer) : Execute a given foreign transfer quote

***

## Create Internal Fiat Transfer

Make an internal fiat transfer between two customer asset accounts.

{% openapi src="/files/BHyeixWXoWKNBsZwNLOq" path="/api/v1/customer/transfers/fiat/createinternaltransfer" method="post" %}
[Aug30Prod.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-04e35a634e041c24850e60fca7ca7d2f4a8af82b%2FAug30Prod.json?alt=media)
{% endopenapi %}

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

#### Example Request Body

```json
{
   "SourceAccountId":2141,
   "DestinationAccountId":2143,
   "Amount": 1000,
   "Reference": "Internal Fiat Transfer Test"
}
```

#### Example Success Response

<pre class="language-json"><code class="lang-json">{
<strong>    "id": 1008,
</strong>    "status": "1",
    "errors": []
}
</code></pre>

***

## Review External Transfer Fee

Review external transfer fee from a customer asset account, using either a Wire or ACH.&#x20;

* **Endpoint**: `/api/v3/customer/transfers/fiat/reviewexternaltransferfee`
* **Method**: `POST`

### Transfer Types

External Fiat Transfer currently supports four different **`TransferTypes`**. Depending on your account type, you can access the following:

1. **`Wire`** - FedWire, available to US accounts.
2. **`ACH`** - Available to US accounts.
3. **`RTP`** - Realtime Domestic US Payments, also known as FedNow. Available to US accounts.
4. **`SWIFT`** - For international accounts.
5. **`P2C`** - Use only with `PayeesId` set to a card-type payee.

### Request Body Parameters

<table><thead><tr><th width="267">Parameter Name</th><th width="200">Type</th><th>Description</th></tr></thead><tbody><tr><td>transmitter</td><td>Object, <strong>Required for Financial Institutions</strong></td><td>Information relating to the transmittere of payment</td></tr><tr><td>transmitter.firstPartyTransfer</td><td>Boolean</td><td>True if the payment is a first party transfer. <strong>If true, other transmitter fields are not required.</strong></td></tr><tr><td>transmitter.type</td><td>String</td><td>'Company' or 'Individual'</td></tr><tr><td>transmitter.dateOfBirth</td><td>datetime</td><td>If Transmitter type is 'Individual', date of birth is required</td></tr><tr><td>transmitter.name</td><td>String</td><td>Name of Transmitter</td></tr><tr><td>transmitter.accountNumber</td><td>String, Optional</td><td>Account Number for the Transmitter</td></tr><tr><td>transmitter.addressLine1</td><td>String</td><td>Address Line 1 for transmitter</td></tr><tr><td>transmitter.addressLine2</td><td>String, Optional</td><td>Address Line 2 for transmitter</td></tr><tr><td>transmitter.townCity</td><td>String</td><td>Town / City for transmitter</td></tr><tr><td>transmitter.state</td><td>String</td><td>State / Province for transmitter</td></tr><tr><td>transmitter.postcode</td><td>String</td><td>Post Code for transmitter</td></tr><tr><td>transmitter.countryCode</td><td>String</td><td>3 Letter Country Code for transmitter (ex. USA)</td></tr><tr><td></td><td></td><td></td></tr><tr><td>payee</td><td>Object, Required</td><td>Payee / Beneficary information</td></tr><tr><td>payee.payeesId</td><td>Number</td><td>Optional Payees ID of an existing payee, for sending payments to an existing payee. If provided, the other payee fields are not required.</td></tr><tr><td>payee.name</td><td>String</td><td>Name of Payee</td></tr><tr><td>payee.type</td><td>String</td><td>'Personal' or 'Company'</td></tr><tr><td>payee.countryCode</td><td>String</td><td>3 Letter Country Code for recieving bank (ex. USA)</td></tr><tr><td>payee.bankName</td><td>String</td><td>Name of Receiving Bank</td></tr><tr><td>payee.routingNumber</td><td>String</td><td>ABA Routing Number, not required if <strong>swiftCode</strong> is provided</td></tr><tr><td>payee.swiftCode</td><td>String</td><td>SWIFT Bic, not required if <strong>routingNumber</strong> is provided</td></tr><tr><td>payee.intermediarySwiftCode</td><td>String, Optional</td><td>Optional Intermediary Bank SWIFT Bic. Only available for SWIFT transfers.</td></tr><tr><td>payee.accountNumber</td><td>String</td><td>Account Number of payee</td></tr><tr><td>payee.accountName</td><td>String</td><td>Name of the payee's account. If unknown, use the payee name</td></tr><tr><td>payee.addressLine1</td><td>String</td><td>Address Line 1 for payee</td></tr><tr><td>payee.addressLine2</td><td>String, Optional</td><td>Address Line 2 for payee</td></tr><tr><td>payee.townCity</td><td>String</td><td>Town / City for payee</td></tr><tr><td>payee.state</td><td>String</td><td>State / Province for payee</td></tr><tr><td>payee.postcode</td><td>String</td><td>Post Code for payee</td></tr><tr><td>payee.addressCountryCode</td><td>String</td><td>3 Letter Country Code for payee (ex. USA)</td></tr><tr><td>bSavePayee</td><td>Boolean</td><td>True if you would like to save the payee details for future use</td></tr><tr><td></td><td></td><td></td></tr><tr><td>sourceAccountId</td><td>Number</td><td>Account ID corresponding to the account to be debited</td></tr><tr><td>transferType</td><td>String</td><td>Transfer rail (ex. 'SWIFT', 'Wire', etc)</td></tr><tr><td>amount</td><td>Number</td><td>Amount to be sent. The currency is implied by the currency of the sourceAccountId</td></tr><tr><td>bankFeeSplitType</td><td>String</td><td><strong>For SWIFT transfers only</strong>, specify 'Full Bank Fee', 'Half Bank Fee', or 'No Bank Fee'. If none is provided, default is 'Half Bank Fee'</td></tr><tr><td>reference</td><td>String</td><td>Reference message to be sent to the receiving bank. (Limit 140 characters)</td></tr><tr><td>purposeCode</td><td>String, Enum</td><td><a href="/terminology/enumerations-codes-and-definitions/transfer-purpose-codes-reference">Refer to our list of Purpose Codes.</a> <strong>Required for Wire transfers sent to an international payee.</strong></td></tr><tr><td>purpose</td><td>String</td><td>If a purposeCode is not provided, you may use purpose, which is a string to specify the purpose of the payment (max 100 chars). You must provide either purpose or purposeCode, however purposeCode is required for Wire transfers sent to payees outside the USA</td></tr></tbody></table>

***

## Create External Fiat Transfer

Make an external transfer from a customer asset account, using either a Wire or ACH. Refer to [Purpose Codes](#get-purpose-codes) to categorize a transfer.

* **Endpoint**: `/api/v3/customer/transfers/fiat/createexternaltransfer`
* **Method**: `POST`

### Transfer Types

Create External Fiat Transfer currently supports four different **`TransferTypes`**. Depending on your account type, you can access the following:

1. **`Wire`** - FedWire, available to US accounts.
2. **`ACH`** - Available to US accounts.
3. **`RTP`** - Realtime Domestic US Payments, also known as FedNow. Available to US accounts.
4. **`SWIFT`** - For international accounts.
5. **`P2C`** - Use only with `PayeesId` set to a card-type payee.

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

### Request Body Parameters

<table><thead><tr><th width="267">Parameter Name</th><th width="200">Type</th><th>Description</th></tr></thead><tbody><tr><td>transmitter</td><td>Object, <strong>Required for Financial Institutions</strong></td><td>Information relating to the transmittere of payment</td></tr><tr><td>transmitter.firstPartyTransfer</td><td>Boolean</td><td>True if the payment is a first party transfer. <strong>If true, other transmitter fields are not required.</strong></td></tr><tr><td>transmitter.type</td><td>String</td><td>'Company' or 'Individual'</td></tr><tr><td>transmitter.dateOfBirth</td><td>datetime</td><td>If Transmitter type is 'Individual', date of birth is required</td></tr><tr><td>transmitter.name</td><td>String</td><td>Name of Transmitter</td></tr><tr><td>transmitter.accountNumber</td><td>String, Optional</td><td>Account Number for the Transmitter</td></tr><tr><td>transmitter.addressLine1</td><td>String</td><td>Address Line 1 for transmitter</td></tr><tr><td>transmitter.addressLine2</td><td>String, Optional</td><td>Address Line 2 for transmitter</td></tr><tr><td>transmitter.townCity</td><td>String</td><td>Town / City for transmitter</td></tr><tr><td>transmitter.state</td><td>String</td><td>State / Province for transmitter</td></tr><tr><td>transmitter.postcode</td><td>String</td><td>Post Code for transmitter</td></tr><tr><td>transmitter.countryCode</td><td>String</td><td>3 Letter Country Code for transmitter (ex. USA)</td></tr><tr><td></td><td></td><td></td></tr><tr><td>payee</td><td>Object, Required</td><td>Payee / Beneficary information</td></tr><tr><td>payee.payeesId</td><td>Number</td><td>Optional Payees ID of an existing payee, for sending payments to an existing payee. If provided, the other payee fields are not required.</td></tr><tr><td>payee.name</td><td>String</td><td>Name of Payee</td></tr><tr><td>payee.type</td><td>String</td><td>'Personal' or 'Company'</td></tr><tr><td>payee.countryCode</td><td>String</td><td>3 Letter Country Code for recieving bank (ex. USA)</td></tr><tr><td>payee.bankName</td><td>String</td><td>Name of Receiving Bank</td></tr><tr><td>payee.routingNumber</td><td>String</td><td>ABA Routing Number, not required if <strong>swiftCode</strong> is provided</td></tr><tr><td>payee.swiftCode</td><td>String</td><td>SWIFT Bic, not required if <strong>routingNumber</strong> is provided</td></tr><tr><td>payee.intermediarySwiftCode</td><td>String, Optional</td><td>Optional Intermediary Bank SWIFT Bic. Only available for SWIFT transfers.</td></tr><tr><td>payee.accountNumber</td><td>String</td><td>Account Number of payee</td></tr><tr><td>payee.accountName</td><td>String</td><td>Name of the payee's account. If unknown, use the payee name</td></tr><tr><td>payee.addressLine1</td><td>String</td><td>Address Line 1 for payee</td></tr><tr><td>payee.addressLine2</td><td>String, Optional</td><td>Address Line 2 for payee</td></tr><tr><td>payee.townCity</td><td>String</td><td>Town / City for payee</td></tr><tr><td>payee.state</td><td>String</td><td>State / Province for payee</td></tr><tr><td>payee.postcode</td><td>String</td><td>Post Code for payee</td></tr><tr><td>payee.addressCountryCode</td><td>String</td><td>3 Letter Country Code for payee (ex. USA)</td></tr><tr><td>bSavePayee</td><td>Boolean</td><td>True if you would like to save the payee details for future use</td></tr><tr><td></td><td></td><td></td></tr><tr><td>sourceAccountId</td><td>Number</td><td>Account ID corresponding to the account to be debited</td></tr><tr><td>transferType</td><td>String</td><td>Transfer rail (ex. 'SWIFT', 'Wire', etc)</td></tr><tr><td>amount</td><td>Number</td><td>Amount to be sent. The currency is implied by the currency of the sourceAccountId</td></tr><tr><td>bankFeeSplitType</td><td>String</td><td><strong>For SWIFT transfers only</strong>, specify 'Full Bank Fee', 'Half Bank Fee', or 'No Bank Fee'. If none is provided, default is 'Half Bank Fee'</td></tr><tr><td>reference</td><td>String</td><td>Reference message to be sent to the receiving bank. (Limit 140 characters)</td></tr><tr><td>purposeCode</td><td>String, Enum</td><td><a href="/terminology/enumerations-codes-and-definitions/transfer-purpose-codes-reference">Refer to our list of Purpose Codes.</a> <strong>Required for Wire transfers sent to an international payee.</strong></td></tr><tr><td>purpose</td><td>String</td><td>If a purposeCode is not provided, you may use purpose, which is a string to specify the purpose of the payment (max 100 chars). You must provide either purpose or purposeCode, however purposeCode is required for Wire transfers sent to payees outside the USA</td></tr></tbody></table>

### Transfer Purpose

External fiat transfers may require a payment purpose to be submitted in the request body. A list of applicable payment purpose codes for a particular transfer is returned from the [Purpose Codes](#get-purpose-codes) endpoint. If the `purposeCode` is omitted or specified as 'Other', then you should submit a customer purpose in the `purpose` field.

**Note: When a purpose code is required, it will be listed in the** [**Purpose Codes**](#get-purpose-codes) **endpoint. If no purpose codes are returned from this endpoint, then** `purposeCode` **is not required and you should specify the purpose of the payment in** `purpose`**.**

<table><thead><tr><th width="179">Param Name</th><th width="93">Type</th><th>Description</th></tr></thead><tbody><tr><td>PurposeCode</td><td>String</td><td><a href="/terminology/enumerations-codes-and-definitions/transfer-purpose-codes-reference">Refer to our list of purpose codes here.</a></td></tr><tr><td>Purpose</td><td>String</td><td>Provide a string for purpose reason. Limit 100 chars. [a-z], [A-Z], [0-9]</td></tr></tbody></table>

### Payee Request Parameters

When configuring a [payee](/terminology/payees), you can either use `payeesId` to use an existing payee, or provide payee information directly. Additionally, you can refer to the [Payees API Endpoints](https://github.com/gradam26/Phoenix-Documentation/blob/main/customer-api/api-endpoints/broken-reference/README.md) to access various functionality such as creating, retrieving, modifying, and deleting payees.

```json
{
  ...
  "payee": {
    // Option 1: Use payeesId to reference a Payee
    "payeesId": 0,
    
    // Option 2: Use the following fields to detail a payee
    
    //Either Routing Number or Swift Code is available
    "routingNumber": "string",
    "swiftCode": "string",
    "bankName": "string",
    "countryCode": "string", // country code for the receiving bank
    "intermediarySwiftCode":"string",
    "accountNumber": "string",
    "accountName": "string",
    
    "type": "string",
    "name": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "addressCountryCode": "string",
    "townCity": "string",
    "state": "string",
    "postcode": "string",
    "addressCountryCode": "string" //country code for the payee's address
  },
  ...
}
```

### Transmitter Information

Financial Institutions are required to submit information regarding the transmitter of a payment. You can submit this information in the transmitter object. For transactions that are first party transfer, you can specify `firstPartyTransfer: true`

#### Third Party Payment Example

```json
{
    ...
    "transmitter": {
        "firstPartyTransfer": false,
        
        "name": "John Doe",
        "type": "Company",
        "dateOfBirth": "1990-10-08T00:00:00.000Z"
        "accountNumber": "1234567890",
        "addressLine1": "123 Main St",
        "addressLine2": "Unit 1A",
        "townCity": "Cityville",
        "state": "WY",
        "postcode": "12345",
        "countryCode": "USA"
        
  },
  ...
}
```

#### First Party Payment Example

```json
{
    ...
    "transmitter": {
        "firstPartyTransfer": true
  },
  ...
}
```

### Example Request Body

The format of the request body is different between Domestic USA transfers and international transfers. Refer to the following examples for reference:

#### Domestic Wire Transfer Request Body

```json
{
        "sourceAccountId":2141,
        "transferType": "Wire",
        "payee":{
                "countryCode":"USA",
                "bankName": "ABC Bank",
                "routingNumber":"125000105",
                "accountNumber":"2140632999",
                "accountName":"Test account",
                "type":"Personal",
                "name":"Test Account",
                "addressLine1":"123 Main St",
                "townCity":"New York",
                "state":"NY",
                "postcode":"10001",
                "addressCountryCode": "USA"
        },
        "bSavePayee":true, 
        "amount": 100,
        "reference": "Test Transfer", 
        "purposeCode" : "PUC002"
}
```

#### International Swift Transfer Request Body

International transfers utilize the `SWIFT` TransferType. Customers can specify the `BankFeeSplitType`, which enables a customer to decide the bearer of bank charges. You can choose between the following values for `BankFeeSplitType`:

* `"Full Bank Fee"` - This option is known as 'OURS'
* `"Half Bank Fee"` - This option is known as 'SHA'
* `"No Bank Fee"` - This option is known as 'BEN'

```json
{
        "sourceAccountId": 2141,
        "transferType": "SWIFT",
        "bankFeeSplitType": "Full Bank Fee",
        "transmitter": {
                "firstPartyTransfer": false,
                "name": "John Doe",
                "accountNumber": "1234567890",
                "addressLine1": "123 Main St",
                "addressLine2": "Unit 1A",
                "townCity": "Cityville",
                "state": "WY",
                "postcode": "12345",
                "countryCode": "USA",
                "type": "Individual",
                "dateOfBirth": "1990-10-08T00:00:00.000Z"
        },
        "payee": {
                "countryCode": "SGP",
                "bankName": "ABC Bank",
                "swiftCode": "DBSSSGSG",
                "intermediaryBic":"XXXX",
                "accountNumber": "12342346545123",
                "accountName": "Checking Account",
                "type":"Company",
                "name": "Sample Company LLC",
                "addressLine1": "62 UBI road 1",
                "townCity": "Oxley Bizhub 2",
                "postcode": "408734",
                "addressCountryCode": "SGP"
        },
        "bSavePayee": true,
        "amount": 50,
        "reference": "Transaction reference to be sent to beneficiary (140 chars)", 
        "purpose": "Purpose of the transfer (100 chars)"
}
```

#### Example Success Response

```json
{
    "id": 22026,
    "details": {
        "id": 30939,
        "accountsId": 2141,
        "fromTransactionsId": null,
        "fromAccountsId": null,
        "toTransactionsId": null,
        "toAccountsId": null,
        "amount": -10,
        "description": "External transfer - Family Maintenance",
        "dateTime": "2024-02-15T17:05:09.97+00:00",
        "bPending": true
    },
    "status": "1",
    "errors": []
}
```

***

## Create External Fiat Transfer With Originator

Make an external transfer with a user defined originator from a customer asset account, using either a Wire or ACH. Refer to [Purpose Codes](#get-purpose-codes) to categorize a transfer.

### Transfer Types

Create External Fiat Transfer currently supports four different **`TransferTypes`**. Depending on your account type, you can access the following:

1. **`Wire`** - FedWire, available to US accounts.
2. **`ACH`** - Available to US accounts.
3. **`RTP`** - Realtime Domestic US Payments, also known as FedNow. Available to US accounts.
4. **`SWIFT`** - For international accounts.
5. **`P2C`** - Use only with `PayeesId` set to a card-type payee.

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

### Request Body Parameters

<table><thead><tr><th width="267">Parameter Name</th><th width="200">Type</th><th>Description</th></tr></thead><tbody><tr><td>transmitter</td><td>Object, <strong>Required for Financial Institutions</strong></td><td>Information relating to the transmittere of payment</td></tr><tr><td>transmitter.firstPartyTransfer</td><td>Boolean</td><td>True if the payment is a first party transfer. <strong>If true, other transmitter fields are not required.</strong></td></tr><tr><td>transmitter.name</td><td>String</td><td>Name of Transmitter</td></tr><tr><td>transmitter.accountNumber</td><td>String, Optional</td><td>Account Number for the Transmitter</td></tr><tr><td>transmitter.addressLine1</td><td>String</td><td>Address Line 1 for transmitter</td></tr><tr><td>transmitter.addressLine2</td><td>String, Optional</td><td>Address Line 2 for transmitter</td></tr><tr><td>transmitter.townCity</td><td>String</td><td>Town / City for transmitter</td></tr><tr><td>transmitter.state</td><td>String</td><td>State / Province for transmitter</td></tr><tr><td>transmitter.postcode</td><td>String</td><td>Post Code for transmitter</td></tr><tr><td>transmitter.countryCode</td><td>String</td><td>3 Letter Country Code for transmitter (ex. USA)</td></tr><tr><td></td><td></td><td></td></tr><tr><td>payee</td><td>Object, Required</td><td>Payee / Beneficary information</td></tr><tr><td>payee.payeesId</td><td>Number</td><td>Optional Payees ID of an existing payee, for sending payments to an existing payee. If provided, the other payee fields are not required.</td></tr><tr><td>payee.name</td><td>String</td><td>Name of Payee</td></tr><tr><td>payee.type</td><td>String</td><td>'Personal' or 'Company'</td></tr><tr><td>payee.countryCode</td><td>String</td><td>3 Letter Country Code for recieving bank (ex. USA)</td></tr><tr><td>payee.bankName</td><td>String</td><td>Name of Receiving Bank</td></tr><tr><td>payee.routingNumber</td><td>String</td><td>ABA Routing Number, not required if <strong>swiftCode</strong> is provided</td></tr><tr><td>payee.swiftCode</td><td>String</td><td>SWIFT Bic, not required if <strong>routingNumber</strong> is provided</td></tr><tr><td>payee.intermediarySwiftCode</td><td>String, Optional</td><td>Optional Intermediary Bank SWIFT Bic. Only available for SWIFT transfers.</td></tr><tr><td>payee.accountNumber</td><td>String</td><td>Account Number of payee</td></tr><tr><td>payee.accountName</td><td>String</td><td>Name of the payee's account. If unknown, use the payee name</td></tr><tr><td>payee.addressLine1</td><td>String</td><td>Address Line 1 for payee</td></tr><tr><td>payee.addressLine2</td><td>String, Optional</td><td>Address Line 2 for payee</td></tr><tr><td>payee.townCity</td><td>String</td><td>Town / City for payee</td></tr><tr><td>payee.state</td><td>String</td><td>State / Province for payee</td></tr><tr><td>payee.postcode</td><td>String</td><td>Post Code for payee</td></tr><tr><td>payee.addressCountryCode</td><td>String</td><td>3 Letter Country Code for payee (ex. USA)</td></tr><tr><td>bSavePayee</td><td>Boolean</td><td>True if you would like to save the payee details for future use</td></tr><tr><td></td><td></td><td></td></tr><tr><td>originator</td><td>Object</td><td>Information relating to the originator</td></tr><tr><td>originator.companyId</td><td>String</td><td>Company ID of the originator</td></tr><tr><td>originator.name</td><td>String</td><td>Name of Orignator</td></tr><tr><td>originator.AddressLine1</td><td>String</td><td>Address line 1 for originator</td></tr><tr><td>originator.AddressLine2</td><td>String</td><td>Address line 2 for originator</td></tr><tr><td>originator.AddressLine3</td><td>String</td><td>Address line 3 for originator</td></tr><tr><td>originator.Data</td><td>String</td><td>Additional data to be sent with Originator Information</td></tr><tr><td></td><td></td><td></td></tr><tr><td>sourceAccountId</td><td>Number</td><td>Account ID corresponding to the account to be debited</td></tr><tr><td>transferType</td><td>String</td><td>Transfer rail (ex. 'SWIFT', 'Wire', etc)</td></tr><tr><td>amount</td><td>Number</td><td>Amount to be sent. The currency is implied by the currency of the sourceAccountId</td></tr><tr><td>bankFeeSplitType</td><td>String</td><td><strong>For SWIFT transfers only</strong>, specify 'Full Bank Fee', 'Half Bank Fee', or 'No Bank Fee'. If none is provided, default is 'Half Bank Fee'</td></tr><tr><td>reference</td><td>String</td><td>Reference message to be sent to the receiving bank. (Limit 140 characters)</td></tr><tr><td>purposeCode</td><td>String, Enum</td><td>The list of applicable purpose codes for a transfer can vary, depending on the sending bank and the receiving country. Before making a transfer, a call should be made to the <a href="#get-purpose-codes">Purpose Codes Endpoint</a> to get a list of acceptable purpose codes. If no purpose codes are returned by this endpoint, then a purpose code need not be provided for this transfer, but a purpose should be provided in the <code>purpose</code> field, in such a case.</td></tr><tr><td>purpose</td><td>String</td><td>If a purpose code is not required, you should specify the purpose of the payment here (max 100 chars). If the purpose code corresponding to 'Other' is used, then the custom purpose must be provided here.</td></tr></tbody></table>

### Payee Request Parameters

When configuring a [payee](/terminology/payees), you can either use `payeesId` to use an existing payee, or provide payee information directly. Additionally, you can refer to the [Payees API Endpoints](https://github.com/gradam26/Phoenix-Documentation/blob/main/customer-api/api-endpoints/broken-reference/README.md) to access various functionality such as creating, retrieving, modifying, and deleting payees.

```json
{
  ...
  "payee": {
    // Option 1: Use payeesId to reference a Payee
    "payeesId": 0,
    
    // Option 2: Use the following fields to detail a payee
    
    //Either Routing Number or Swift Code is available
    "routingNumber": "string",
    "swiftCode": "string",
    "bankName": "string",
    "countryCode": "string",
    "intermediarySwiftCode":"string",
    "accountNumber": "string",
    "accountName": "string",
    
    "type": "string",
    "name": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "addressCountryCode": "string",
    "townCity": "string",
    "state": "string",
    "postcode": "string"
  },
  ...
}
```

### Transmitter Information

Financial Institutions are required to submit information regarding the transmitter of a payment. You can submit this information in the transmitter object.

#### Third Party Payment Example

```json
{
    ...
    "transmitter": {
        "firstPartyTransfer": false,
        
        "name": "John Doe",
        "accountNumber": "1234567890",
        "addressLine1": "123 Main St",
        "addressLine2": "Unit 1A",
        "townCity": "Cityville",
        "state": "WY",
        "postcode": "12345",
        "countryCode": "USA"
  },
  ...
}
```

#### First Party Payment Example

```json
{
    ...
    "transmitter": {
        "firstPartyTransfer": true
  },
  ...
}
```

### Originator Request Parameters

The settable parameters for the originator depend on whether the transfer is a Wire or an ACH transfer.

```json
{
  ...
  "Originator":{
        //Required for ACH transfers
        "CompanyId":"string",
        
        //Required
        "Name":"string",
        
        //Optional for Wire transfers. Must be null for ACH transfers
        "AddressLine1":"string",
        
        //Optional for Wire transfers. Must be null for ACH transfers
        "AddressLine2":"string",
        
        //Optional for Wire transfers. Must be null for ACH transfers
        "AddressLine3":"string",
        
        //Optional for ACH transfers. Must be null for Wire transfers
        "Data":"string"
    },
  ...
}
```

### Example Request Body

The format of the request body is different between Domestic USA transfers and international transfers. Refer to the following examples for reference:

#### Domestic Wire Transfer Request Body

```json
{
   "SourceAccountId":2141,
   "TransferType":"Wire",
    "Payee":{
        "CountryCode":"USA",
        "RoutingNumber":"125000105",
        "AccountNumber":"2140632999",
        "AccountName":"Test account",
        "Type":"Personal",
        "Name":"Test Account",
        "AddressLine1":"1 TestAddress",
        "TownCity":"TestTown",
        "State":"TestCounty",
        "Postcode":"N19AA",
        "addressCountryCode": "GBR"
    },
    "Originator":{
        "CompanyId":null,
        "Name":"Test name",
        "AddressLine1":"street address",
        "AddressLine2":"town",
        "AddressLine3":"country",
        "Data":null
    },
    "bSavePayee":true,
   "Amount": 10,
   "Reference": "Test Transfer",
   "PurposeCode" : "PUC002"
}
```

#### International Wire Transfer Request Body

```json
{
    "SourceAccountId": 2141,
    "TransferType": "Wire",
    "Payee": {
        "CountryCode": "SGP",
        "SwiftCode": "DBSSSGSG",
        "IntermediaryBic":"XXXX",
        "AccountNumber": "12342346545123",
        "AccountName": "Sebi Scaria",
        "Type":"Company",
        "Name": "Sebi Scaria",
        "AddressLine1": "62 UBI road 1",
        "TownCity": "Oxley Bizhub 2",
        "Postcode": "408734",
        "addressCountryCode": "SGP"
    },
    "Originator":{
        "CompanyId":null,
        "Name":"Test name",
        "AddressLine1":"street address",
        "AddressLine2":"town",
        "AddressLine3":"country",
        "Data":null
    },
    "bSavePayee":true,
    "Amount": 50,
    "Reference": "Test Transfer",
    "PurposeCode": "PUC002"
}
```

#### Example Success Response

```json
{
    "id": 22026,
    "details": {
        "id": 30939,
        "accountsId": 2141,
        "fromTransactionsId": null,
        "fromAccountsId": null,
        "toTransactionsId": null,
        "toAccountsId": null,
        "amount": -10,
        "description": "External transfer - Family Maintenance",
        "dateTime": "2024-02-15T17:05:09.97+00:00",
        "bPending": true
    },
    "status": "1",
    "errors": []
}
```

***

## **Get Purpose Codes**

Get list of available purpose codes to be used for external fiat transfer.

{% openapi src="/files/Hjz8QmhGFMo5fJZtFAnU" path="/api/v2/customer/transfers/purpose-codes" method="get" %}
[IbaneraPublicAPINov28.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-974e6d330337fedb36c54f06bd07f7e93354d4b4%2FIbaneraPublicAPINov28.json?alt=media)
{% endopenapi %}

#### Example Success Response

<pre class="language-json"><code class="lang-json">{
    "id": 0,
    "details": {
    "purposeCodes": [
        {
            "code": "PUC001",
            "description": "Transfer to own account"
        },
        {
            "code": "PUC002",
            "description": "Family Maintenance"
        }]
<strong>    },
</strong>    "pageSize": 10,
    "pageNumber": 1,
    "status": "1",
    "errors": []
}
</code></pre>

#### Query Parameters

* `customerAssetAccountsId` (Integer) - The ID of the source account making the external fiat transfer (REQUIRED),
* `payeesId` (Integer) - The ID of the payee in the external fiat transfer. Required if `countryCode` is not specified, optional otherwise.
* `countryCode` (String) - The country code of the payee in ISO/ISO2 format. Required if `payeesId` is not specified, optional otherwise.

***

## Get Reverse Inbound Transfer Details

This operation gives the user necessary details to call the POST endpoint to reverse an inbound transfer.

* **Endpoint**: `/api/v1/customer/accounts/reverse-inbound-transfer`
* **Method**: GET

{% openapi src="/files/2Br9p0GaFFN3h8AcMXVe" path="/api/v1/customer/accounts/reverse-inbound-transfer" method="get" %}
[public-api-customer-role (7).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-494a9abe6f98f452f0246f0ba52129ca0d7a1a0d%2Fpublic-api-customer-role%20\(7\).json?alt=media)
{% endopenapi %}

* **Query Parameters**:
  * `customersId` (Integer): The ID of the customer account from which the withdrawal is to be made.

**Response Body Parameters**:

* `id` (Integer): A reference ID for the transaction; not used in the example.
* `details.purposes` (JSON Array): List of possible purposes for reversal.
* `details.purposes.id` (Integer): The ID of the purpose.
* `details.purposes.name` (String): Description of the purpose.

**Success Response Example**:

```json
{
    "id": 0,
    "details": {
        "purposes": [
            {
                "id": 1000,
                "name": "Unable to Identify Beneficiary"
            },
            {
                "id": 1001,
                "name": "Unexpected Transaction"
            },
            {
                "id": 1002,
                "name": "Transaction Not Allowed"
            },
            {
                "id": 1003,
                "name": "Other"
            }
        ]
    },
    "status": "1",
    "errors": []
}
```

***

## Reverse Inbound Transfer

This operation allows the user to reverse an inbound transfer.

* **Endpoint**: `/api/v1/customer/accounts/reverse-inbound-transfer`
* **Method**: POST

{% openapi src="/files/2Br9p0GaFFN3h8AcMXVe" path="/api/v1/customer/accounts/reverse-inbound-transfer" method="post" %}
[public-api-customer-role (7).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-494a9abe6f98f452f0246f0ba52129ca0d7a1a0d%2Fpublic-api-customer-role%20\(7\).json?alt=media)
{% endopenapi %}

* **Request Body Parameters**:
  * `customersId` (Integer): The ID of the customer account from which the withdrawal is to be made.

**Request Example**:

```json
{
    "customersId":2036,
    "transactionId":18410,
    "purposeId":1001,
    "purposeOther":null
}
```

**Response Body Parameters**:

* `id` (Integer): A reference ID for the transaction; not used in the example.
* `details.transactionId` (JSON Array): Id of the transaction being reversed.

**Success Response Example**:

```json
{
    "id": 0,
    "details": {
        "transactionId": 18410
    },
    "status": "1",
    "errors": []
}
```

***

## Lookup Bank Details

This endpoint allows customers to look up additional bank details given a SWIFT code (more lookup options coming soon).

{% openapi src="/files/KlhqfMbFdzICqhEfXAuz" path="/api/v1/customer/transfers/lookupbankdetails" method="get" %}
[customer.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-a0929f3058977c57c815eeb0fb06e2d4ccd7c879%2Fcustomer.json?alt=media)
{% endopenapi %}

## Request FX Transfer Quote

This operation request a quote for a foreign transfer with either source amount or destination amount and returns the estimated source and destination amounts with the quote id.

* **Endpoint**: `/api/v1/customer/transfers/fx-request-quote`
* **Method**: POST

{% openapi src="/files/kTRxH8DGgDZLoc0jBJV3" path="/api/v1/customer/transfers/fx-request-quote" method="post" %}
[customerapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-dbb100afb6fc88ad2113dc57a243cea9e9bfe46a%2Fcustomerapi.json?alt=media)
{% endopenapi %}

**Request Example**:

```json
{
    "SourceAmount": "10",
    "PayeesId": 4451,
    "PurposeCode": "PUC002",
    "Reference": "REF16149",
    "CustomerAssetAccountsId": 14259,
    "TransferType": "Wire"
}
```

**Success Response Example**:

```json
{
    "id": 1,
    "details": {
        "commandSourceAmount": 10.0,
        "commandDestinationAmount": null,
        "estimateSourceAmount": 10.0,
        "estimateDestinationAmount": 9.48,
        "fxFeePercentage": 0.200,
        "exchangeFeeAmount": 0.24,
        "estimateTotalSourceAmount": 10.0,
        "estimateTotalDestinationAmount": 9.24,
        "quotedFXRate": "0.947601",
        "quotedFXRateID": 1247,
        "quotedFxRateExpiry": "2024-12-11T10:39:51.154Z"
    },
    "status": "1",
    "errors": []
}
```

## Execute FX Transfer

This operation execute a given FX transfer quote .

* **Endpoint**: `/api/v1/customer/transfers/executefxtransfer`
* **Method**: POST

{% openapi src="/files/kTRxH8DGgDZLoc0jBJV3" path="/api/v1/customer/transfers/executefxtransfer" method="post" %}
[customerapi.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-dbb100afb6fc88ad2113dc57a243cea9e9bfe46a%2Fcustomerapi.json?alt=media)
{% endopenapi %}

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

**Request Example**:

```json
{    
    "CustomerAssetAccountsId": 14259,
    "TransferType": "Wire",
    "PayeesId": 4451,
    "FxRateId":1247,    
    "Reference": "REF16149",    
    "BeneficiaryReference": "REF16149",    
    "PurposeCode": "PUC002"
}
```

**Success Response Example**:

```json
{
    "id": 61825,
    "details": {
        "id": 61825,
        "accountsId": 14259,
        "fromTransactionsId": null,
        "fromAccountsId": null,
        "toTransactionsId": null,
        "toAccountsId": null,
        "amount": -10.000000000000000000,
        "description": "USD International Transfer",
        "dateTime": "2024-12-10T10:40:10.06+00:00",
        "bPending": true,
        "transmitterId": "CST10024-4451"
    },
    "status": "1",
    "errors": []
}
```


# Crypto Transfers

## Overview

The Transfers module of the Customer API facilitates the movement of funds and manages transfer-related operations with a suite of endpoints tailored to cover various functionalities.

This section provides endpoints to withdraw cryptocurrency from a customer asset account to an external blockchain wallet address. Users can either withdraw to a new wallet address or to a previously saved wallet.

**Retrieving Your Wallet's Deposit Address**

1. [**Get Deposit Address for a Crypto Asset Account**](#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.

#### Internal Transfers - Making Transfers between your Accounts

1. [**Create Internal Crypto Transfer**](#create-internal-crypto-transfer): This endpoint allows customers to conduct internal cryptocurrency transfers between two customer asset accounts within the system. The users need to specify the source and destination account IDs, the amount to be transferred.

#### Asset Wallet Aliases - Create and Manage Saved Wallet Aliases

1. [**Create Asset Wallet Alias**](#create-asset-wallet-alias)
2. [**Edit an Asset Wallet Alias**](#edit-an-asset-wallet-alias)
3. [**Get an Asset Wallet Alias by ID**](#get-an-asset-wallet-alias-by-id)
4. [**List Asset Wallet Aliases**](#list-asset-wallet-aliases)
5. [**Delete an Asset Wallet Alias**](#delete-asset-wallet-aliases)

#### External Transfers

1. [**Withdraw Crypto to a New Wallet**](#withdraw-to-a-new-wallet): This endpoint initiates a withdrawal of cryptocurrency from a customer asset account to a new external wallet address.
2. [**Withdraw Crypto to a Saved Wallet**](#withdraw-crypto-to-a-saved-wallet): This endpoint initiates a withdrawal of cryptocurrency from a customer asset account to an existing/saved external wallet address.
3. **(DEPRECATED)** [**Withdraw Crypto from Customer Account to External Wallet**](#deprecated-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.

***

## 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**: GET
* **Request Body Parameters**:
  * `accountsId` (Integer): The ID of the customer account to retrieve a deposit address for.

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/accounts/crypto/depositaddress" method="get" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

***

## Internal Transfers

### Create Internal Crypto Transfer

This endpoint initiates a transfer of crypto currency between two asset accounts that are accessible by a manager. The endpoint requires parameters for the source account ID, the destination account ID, and the amount for the transfer. The asset to be transferred is inferred by the asset account ID.

* **Endpoint:** `/api/v1/customer/accounts/crypto/move`
* **Method:** `POST`

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

#### Request Body Example

```json
{
    "fromAccountsId": 1001, // Integer - Required
    "toAccountsId" : 1002, // Integer - Required
    "amount": 0.01 // Decimal - Required
}
```

#### Response Body Example

```json
{
    "id": 0,
    "details": {
        "customersId": 1001,
        "customerReference": "your-customer-reference",
        "fromTransaction": {
            "id": 10001,
            "accountsId": 1001,
            "fromTransactionsId": null,
            "fromAccountsId": null,
            "toTransactionsId": 10002,
            "toAccountsId": 1002,
            "amount": -0.010000000000000000,
            "description": "Transfer of crypto to managing account 1001",
            "dateTime": "2024-01-01T18:21:39.7633333+00:00",
            "bPending": true
        },
        "toTransaction": {
            "id": 10002,
            "accountsId": 1002,
            "fromTransactionsId": 10001,
            "fromAccountsId": 1001,
            "toTransactionsId": null,
            "toAccountsId": null,
            "amount": 0.010000000000000000,
            "description": "Receipt of crypto from managee account 1002",
            "dateTime": "2024-01-01T18:21:39.77+00:00",
            "bPending": true
        }
    },
    "status": "1",
    "errors": []
}
```

***

## Asset Wallet Aliases

### Create Asset Wallet Alias

* **Endpoint**: `/api/v1/customer/assetwalletaliases/create`
* **Method**: POST

**Request Body Example**

```json
{
  "CustomersId": 1234,
  "WalletAddress": "0x.....1234", 
  "AssetCode": "ETH",
  "Alias": "John's External Wallet"
  "Tag": "John's ETH Wallet"
}
```

**Response Body Example**

```json
{
  "id": 0,
  "details": {
    "id": 0,
    "customersId": 0,
    "alias": "string",
    "walletAddress": "string",
    "assetCode": "string",
    "tag": "string"
  },
  "status": "1",
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

### Edit an Asset Wallet Alias

* **Endpoint**: `/api/v1/customer/assetwalletaliases/edit`
* **Method**: PATCH

**Request Body Example**

```json
{
  "id": 1234,
  "alias": "John's External Wallet #2"
}
```

**Response Body Example**

```json
{
  "id": 0,
  "details": {
    "id": 0,
    "customersId": 0,
    "alias": "string",
    "walletAddress": "string",
    "assetCode": "string",
    "tag": "string"
  },
  "status": "1",
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

### Get an Asset Wallet Alias by ID

* **Endpoint**: `/api/v1/customer/assetwalletaliases/get`
* **Method**: GET

**Request Query Parameter**

<table><thead><tr><th width="160.1640625">Parameter</th><th width="113.72265625">Type</th><th>Description</th></tr></thead><tbody><tr><td>Id</td><td>int</td><td>ID of the previously generated Asset Wallet Alias</td></tr></tbody></table>

**Response Body Example**

```json
{
  "id": 0,
  "details": {
    "id": 0,
    "customersId": 0,
    "alias": "string",
    "walletAddress": "string",
    "assetCode": "string",
    "tag": "string"
  },
  "status": "1",
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

### List Asset Wallet Aliases

* **Endpoint**: `/api/v1/customer/assetwalletaliases/list`
* **Method**: GET

**Request Query Parameter**

<table><thead><tr><th width="160.1640625">Parameter</th><th width="113.72265625">Type</th><th>Description</th></tr></thead><tbody><tr><td>CustomersID</td><td>int</td><td>Filter asset wallet aliases by customer ID</td></tr><tr><td>WalletAddress</td><td>string</td><td>Filter asset wallet aliases by wallet address</td></tr><tr><td>AssetCode</td><td>string</td><td>Filter asset wallet aliases by asset code</td></tr></tbody></table>

**Response Body Example**

```json
{
  "id": 0,
  "details": {
    "id": 0,
    "details": [
      {
        "id": 0,
        "customersId": 0,
        "assetCode": "string",
        "alias": "string",
        "walletAddress": "string",
        "tag": "string"
      }
    ],
    "pageSize": 0,
    "pageNumber": 0,
    "numberOfPages": 0,
    "status": "string",
    "errors": [
      {
        "fieldName": "string",
        "messageCode": "string"
      }
    ]
  },
  "status": "1",
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

### Delete Asset Wallet Aliases

* **Endpoint**: `/api/v1/customer/assetwalletaliases/delete`
* **Method**: DELETE

**Request Query Parameter**

<table><thead><tr><th width="160.1640625">Parameter</th><th width="113.72265625">Type</th><th>Description</th></tr></thead><tbody><tr><td>Id</td><td>int</td><td>ID of the previously generated Asset Wallet Alias</td></tr></tbody></table>

**Response Body Example**

```json
{
  "id": 0,
  "status": "1", // 1 when successful, 0 when error
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

***

## External Transfers

### Withdraw to a New Wallet

This endpoint initiates a withdrawal of cryptocurrency from a customer asset account to a new external wallet address.\
Users must specify the customer asset account ID, the amount to withdraw, the destination wallet address, nickname for the wallet address.\
Optionally, users can:\
Provide a tag if required for certain assets (e.g., XRP)\
Set the Deduct Gas Fee property for native tokens such as BTC and ETH, which defaults to true.

* **Endpoint**: `/api/v1/customer/accounts/crypto/withdrawnewwallet`
* **Method**: POST

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

**Request Body Example**

<table><thead><tr><th width="258.328125">Name</th><th width="126.20001220703125">Type</th><th width="155">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>customerAssetAccountsId</code></td><td>int</td><td>Yes</td><td>Customer asset account to withdraw crypto from</td></tr><tr><td><code>amount</code></td><td>decimal</td><td>Yes</td><td>Amount to withdraw (must be >0)</td></tr><tr><td><code>destinationAddress</code></td><td>string</td><td>Yes</td><td>on-chain address to withdraw</td></tr><tr><td><code>destinationWalletNickname</code></td><td>string</td><td>Yes</td><td>nickname that can be saved and re-used in the future to alias the crypto wallet address</td></tr><tr><td><code>deductGasFee</code></td><td>boolean</td><td>Yes</td><td>true value indicates that the gas fee will be deducted from the amount</td></tr><tr><td><code>tag</code></td><td>string</td><td>No (Required only for XRP)</td><td>Associated with destination Address</td></tr></tbody></table>

**Response**

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

```json
{
  "id": 0,
  "details": {
    "id": 0,
    "accountsId": 0,
    "amount": 0,
    "description": "string",
    "dateTime": "2025-04-29T01:53:25.919Z",
    "bPending": true,
    "assetWalletAliasesId": 0
  },
  "status": "string",
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "id": 0,
    "details": null,
    "status": "0",
    "errors": [
        {
            "fieldName": "DestinationAddress",
            "messageCode": "Required"
        },
        {
            "fieldName": "DestinationWalletNickname",
            "messageCode": "Required"
        },
        {
            "fieldName": "CustomerAssetAccountsId",
            "messageCode": "Required"
        },
        {
            "fieldName": "Amount",
            "messageCode": "Invalid"
        },
        {
            "fieldName": "Tag",
            "messageCode": "Destination Tag is required for ETH withdraw"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Request Body Example

```json
{
  "customerAssetAccountsId": 6112,
  "amount": 10,
  "destinationAddress": "0x221ca5B61153e3Cc684EB76FEe817b54B63d501A",
  "destinationWalletNickname": "Test wallet",
  "deductGasFee": true, // Applicable for native assets, set to false to send exact amount
  "Tag": "12345"
}
```

#### Response Body Example

```json
{
        "id": 123543,
        "details": {
                "Id": 1234,
                "AccountsId": 1234,
                "Amount": 10,
                "Description":"ETH withdrawal",
                "DateTime":"2025-01-29T00:00:00.0000000Z",
                "bPending":true,
                "AssetWalletAliasesId": 1234
        },
        "status": "1", // 1 if success, 0 if failure
        "errors": [{
                "fieldName": "string",
                "messageCode": "string"
        }]
}
```

***

### Withdraw Crypto to a Saved Wallet

This endpoint initiates a withdrawal of cryptocurrency from a customer asset account to an existing/saved external wallet address. Users must specify the customer asset account ID, the amount to withdraw, asset wallet address alias id.

\
Optionally, users can set the Deduct Gas Fee property for native tokens such as BTC and ETH, which defaults to true.

* **Endpoint**: `/api/v1/customer/accounts/crypto/withdrawsavedwallet`
* **Method**: POST

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

**Request Body Parameters**

<table><thead><tr><th width="271.2890625">Name</th><th width="126.20001220703125">Type</th><th width="94.47265625">Required</th><th width="259.5859375">Description</th></tr></thead><tbody><tr><td><code>customerAssetAccountsId</code></td><td>int</td><td>Yes</td><td>Customer asset account to withdraw crypto from</td></tr><tr><td><code>amount</code></td><td>decimal</td><td>Yes</td><td>Amount to withdraw (must be >0)</td></tr><tr><td><code>assetWalletAddressAliasId</code></td><td>string</td><td>Yes</td><td>Id of the crpyto wallet address-nickname pairing</td></tr><tr><td><code>deductGasFee</code></td><td>boolean</td><td>Yes</td><td>true value indicates that the gas fee will be deducted from the amount</td></tr></tbody></table>

**Response**

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

```json
{
  "id": 0,
  "details": {
    "id": 0,
    "accountsId": 0,
    "amount": 0,
    "description": "string",
    "dateTime": "2025-04-29T03:21:50.484Z",
    "bPending": true,
    "assetWalletAliasesId": 0
    "destinationWalletAddress": "string"
  },
  "status": "1", // 1 if success, 0 if failure
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
    "id": 0,
    "details": null,
    "status": "0",
    "errors": [
        {
            "fieldName": "CustomerAssetAccountsId",
            "messageCode": "Required"
        },
        {
            "fieldName": "Amount",
            "messageCode": "Invalid"
        },
        {
            "fieldName": "AssetWalletAddressAliasId",
            "messageCode": "Required"
        },
        {
            "fieldName": "Tag",
            "messageCode": "Destination Tag is required for ETH withdraw"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Request Body Example

```json
{
  "customerAssetAccountsId": 6112,
  "amount": 10,
  "assetWalletAddressAliasId": 1049,
  "deductGasFee": true
}
```

#### Response Body Example

```json
{
  "id": 123543,
  "details": {
    "Id": 123456,
    "AccountsId": 6112,
    "Amount": 10,
    "Description":"ETH withdrawal",
    "DateTime":"2025-04-29T03:23:09.1466667Z",
    "bPending":true,
    "AssetWalletAliasesId":1050,
    "DestinationWalletAddress":"0x221ca5B61153e3Cc684EB76FEe817b54B63d501A"
  },
  "status": "1", // 1 if success, 0 if failure
  "errors": [
    {
      "fieldName": "string",
      "messageCode": "string"
    }
  ]
}
```

***

## (DEPRECATED) Withdraw Crypto from Customer Account to External Wallet

#### **NOTE: This endpoint is deprecated. We suggest using the newly updated enpoints above.**

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

#### Optional Request Headers:

* `IdempotencyKey`: Unique GUID value generated by user to identify and avoid subsequent retries of a request (optional)

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

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/accounts/crypto/withdraw" method="post" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

**Request Example**:

```json
{
  "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**:

```json
{
  "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**:

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


# Transaction Cancellation

## Overview

The Transaction Cancellation Module provides an avenue for customers to cancel standalone outgoing transfers from their Ibanera accounts (wallets) to external accounts (wallet).

Customers can obtain a real-time snapshot of whether or not a given transaction is eligible for cancellation, and submit requests for their transactions to be cancelled and subsequently refunded.

Due to the time-sensitive nature of pending transfers, it is possible that not all cancellation requests will succeed, in which case the transaction will proceed to completion.

Customers can only submit one cancellation request for any given transaction, and any additional requests to cancel that transaction will be ignored.

Here is an overview of the endpoints within this module:

1. [Get Transaction Cancellation Eligibility](#get-transaction-cancellation-eligibility): Provides a real-time snapshot of whether or not the transaction can be cancelled through this module.
2. [Submit Transaction Cancellation Request](#submit-transaction-cancellation-request): If successfully called, this endpoint enqueues a request to cancel a specific transaction. A successful response does not guarantee that the transaction will be cancelled, but rather that a request has been submitted.

## Get Transaction Cancellation Eligibility

This endpoint will determine the current status of a transaction referenced by ID, and indicate to the caller whether or not the transaction may be cancelled, accurate at the time of calling.

The ID of the transaction is required. If the transaction belongs to a managed customer, then the caller may optionally provide the ID of the managed customer, but this is not required.

{% openapi src="/files/oxfUc5i1AIwcWso0zCNl" path="/api/v1/customer/transactions/cancel" method="get" %}
[public-api-openapi (1).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-6c3cc3fb431d988a98ea6e4a3f143374bde1fe7e%2Fpublic-api-openapi%20\(1\).json?alt=media)
{% endopenapi %}

* **Endpoint**: `/api/v1/customer/transactions/cancel`
* **Method**: GET
* **Query Parameters**:
  * `transactionsId` (Integer): The ID of the transaction (REQUIRED)
  * `customersId` (Integer): The ID of the managed customer (OPTIONAL)

#### Response Body Parameters and Types:

* `id` (Integer): The ID of the transaction passed in the request, if successfully found. If the transaction is not found, this field will default to zero.
* `details` (Object): Contains details about the transaction.
  * `bCancellable` (Boolean): Indicates whether or not the transaction may be cancelled
* `status` (String): The status of the request. "1" indicates success, "0" indicates failure.
* `errors` (Array): Any error messages, if present.

#### Successful Response Example

```json
{
  "id": 84253,
  "details": {
    "bCancellable": true
  },
  "status": "1",
  "errors": []
}
```

## Submit Transaction Cancellation Request

This endpoint will attempt to enqueue a cancellation request for a transaction, referenced by ID. Successfully submitted cancellation requests are processed asynchronously by our system. Note that a successful response means a request has been submitted, and is not a guarantee that the transaction has been cancelled.

The ID of the transaction must be provided. If the transaction belongs to a managed customer, then the caller may provide the ID of the managed customer, but this is not required.

This endpoint will return a HTTP 200 OK response in the event a cancellation request has successfully been submitted. If a transaction is deemed ineligible for cancellation, then the endpoint will return a HTTP 400 Bad Request error.

* **Endpoint**: `/api/v1/customer/transactions/cancel`
* **Method**: POST

#### Request Body Parameters

* `transactionsId` (Integer): The ID of the transaction to cancel. (REQUIRED)
* `customersId` (Integer): The ID of the managed customer to whom the transaction belongs. (OPTIONAL)

{% openapi src="/files/oxfUc5i1AIwcWso0zCNl" path="/api/v1/customer/transactions/cancel" method="post" %}
[public-api-openapi (1).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-6c3cc3fb431d988a98ea6e4a3f143374bde1fe7e%2Fpublic-api-openapi%20\(1\).json?alt=media)
{% endopenapi %}

#### Request Example

```json
{
  "transactionsId": 84253,
  "customersId": 14045
}
```

#### Response Body Parameters

* `id` (Integer): The ID of the transaction cancellation request, if successfully generated. If no cancellation request was submitted, this field will default to zero.
* `details` (Object): Contains details about the cancellation request.
  * `transactionsId` (Integer): The ID of the transaction to be cancelled.
  * `cancellationRequestsCode` (String): The reference code of the transaction cancellation request, if submitted.
* `status` (String): The status of the request. "1" indicates success, "0" indicates failure.
* `errors` (Array): Any error messages, if present.

#### Successful Response Example

```json
{
  "id": 1015,
  "details": {
    "transactionsId": 84253,
    "cancellationRequestsCode": "CTXCRQ1015"
  },
  "status": "1",
  "errors": []
}
```


# Managees

## Overview

The Managees module provides a set of API endpoints designed for managers to onboard and manage their linked managees within the platform. The endpoints facilitate various operations, from creating managee profiles to listing all managees and generating widget user references for enhanced user interaction with the platform's widgets.

**API Endpoints for the Managees Module:**

1. [**Create Managee**](#create-a-managee)**:** This endpoint is used by managers to create a new customer profile for a personal customer. The user also inputs additional data necessary for KYC screening.
2. [**List Managees**](#list-managees)**:** Managers can use this endpoint to retrieve a list of all managees they have created. The list provides essential information about each managee, such as their ID, name, date added, verification status, and any associated widget references. This is a GET request with pagination capabilities to effectively manage large numbers of managees.
3. [**Get List of Accounts for a Managee by ID**](#get-list-of-accounts-for-a-managee-by-id)**: (DEPRECATED)** Retrieves a list of accounts belonging to a managee. You can filter the list by the managee's ID, the asset (currency), and control pagination with page number and size.
4. [**Create Widget User**](#create-widget-user)**:** This POST endpoint enables managers to create a widget user reference for their managees, which facilitates the managee's interaction with the platform's widgets. A widget user reference is associated with the managee, allowing for a more dynamic and engaging user experience within the platform interface.
5. [**Upload KYC Document**](#upload-kyc-document): Upload Documents for a newly created Managee Customer, if using external KYC.

These API calls are integral to managee account management as they allow for seamless operations concerning the create-list-manage lifecycle of managee profiles under a manager account. Through their use, managers can streamline operations, ensure account accuracy, and deliver a more refined platform experience to their managees.

***

## Create a Managee

This endpoint enables the onboarding of a Managee customer with detailed KYC requirements. It supports two verification flows: manual document upload and Jumio-based identity verification. Allows a manager to create a linked customer, referred to as a managee. The user provides additional information necessary for KYC screening. A file with proof of address is also required. The response contains a Jumio Link, from which the customer can enter and verify their identity information. A manager can set up a new customer account under their purview by entering the customer's (managee's) details into the system.

### Create Managee

<sup><mark style="color:orange;background-color:yellow;">**POST**<mark style="color:orange;background-color:yellow;"></sup> <sup>/api/v6/customer/managees/create</sup>

### KYC Collection

Ibanera collects KYC for Managee customers. This endpoint offers the flexibility of either using Ibanera's ID Verification provider, Jumio, or using your own IDv solution. The below section outlines each approach can be executed.

**Using Ibanera's ID Verification**

* <sub>bUseJumio is not included (defaults to true).</sub>
* <sub>KYC will be handled via a Jumio verification link returned in the response.</sub>
* <sub>Proof of Address document is sent directly in this request (proofOfAddressFile and proofOfAddressType fields).</sub>
* <sub>No need to upload documents separately.</sub>

| `emailAddress`                      | string             | Required, must be a valid email                                                                                                                                     |
| ----------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `manageesReference`                 | string             | Required, reference for the customer                                                                                                                                |
| `parentCustomersId`                 | integer (int32)    | Optional                                                                                                                                                            |
| `fiatCurrencyCode`                  | string             | Required                                                                                                                                                            |
| `fullName`                          | string             | Required                                                                                                                                                            |
| `firstGivenName`                    | string             | Required                                                                                                                                                            |
| `lastSurname`                       | string             | Required                                                                                                                                                            |
| `townCity`                          | string             | Required                                                                                                                                                            |
| `addressCountryISO`                 | string             | Required, 2-letter ISO country code                                                                                                                                 |
| `addressLine1`                      | string             | Required                                                                                                                                                            |
| `addressLine2`                      | string             | Optional                                                                                                                                                            |
| `stateProvince`                     | string             | Required                                                                                                                                                            |
| `postcode`                          | string             | Required                                                                                                                                                            |
| `phoneNumber`                       | string             | Required                                                                                                                                                            |
| `dateOfBirth`                       | string (date-time) | Required, e.g., "1990-01-01T00:00:00Z"                                                                                                                              |
| `taxNumber`                         | string             | Required                                                                                                                                                            |
| `nationalityISO`                    | string             | Required, ISO country code                                                                                                                                          |
| `occupation`                        | string             | Required                                                                                                                                                            |
| `sendInvite`                        | boolean            | Required                                                                                                                                                            |
| `sourceFundsTypes`                  | array of string    | Optional                                                                                                                                                            |
| `otherSourceOfFunds`                | string             | Optional                                                                                                                                                            |
| `estimatedNetWorth`                 | number (double)    | Optional                                                                                                                                                            |
| `estimatedGrossAnnualIncome`        | number (double)    | Optional                                                                                                                                                            |
| `otherBanks`                        | array of string    | Optional                                                                                                                                                            |
| `bActivelyEmployed`                 | boolean            | Optional                                                                                                                                                            |
| `employedCompanyName`               | string             | Optional                                                                                                                                                            |
| `employedJobTitle`                  | string             | Optional                                                                                                                                                            |
| `purposeOfOpeningAccountTypes`      | array of string    | Optional                                                                                                                                                            |
| `monthlyTurnover`                   | number (double)    | Optional                                                                                                                                                            |
| `anticipatedTransactionActivity`    | number (double)    | Optional                                                                                                                                                            |
| `purchaseCryptoMonthlyVolume`       | number (double)    | Optional                                                                                                                                                            |
| `purchaseCryptoAverageAmount`       | number (double)    | Optional                                                                                                                                                            |
| `purchaseCryptoTotalAmountPerMonth` | number (double)    | Optional                                                                                                                                                            |
| `sellingCryptoAverageAmount`        | number (double)    | Optional                                                                                                                                                            |
| `sellingCryptoMonthlyVolume`        | number (double)    | Optional                                                                                                                                                            |
| `sellingCryptoTotalAmountPerMonth`  | number (double)    | Optional                                                                                                                                                            |
| `totalMonthlyVolume`                | number (double)    | Optional                                                                                                                                                            |
| `totalAverageAmount`                | number (double)    | Optional                                                                                                                                                            |
| `totalMonthlyAmount`                | number (double)    | Optional                                                                                                                                                            |
| `btcTradingPercentage`              | number (double)    | Optional                                                                                                                                                            |
| `ethTradingPercentage`              | number (double)    | Optional                                                                                                                                                            |
| `usdcTradingPercentage`             | number (double)    | Optional                                                                                                                                                            |
| `otherCoinsTradingPercentage`       | number (double)    | Optional                                                                                                                                                            |
| `bIrsTax`                           | boolean            | Optional                                                                                                                                                            |
| `bForeignAccountTax`                | boolean            | Optional                                                                                                                                                            |
| `bNotCriminal`                      | boolean            | Optional                                                                                                                                                            |
| `bAccurateInfo`                     | boolean            | Optional                                                                                                                                                            |
| `proofOfAddressFile`                | string             | Required, base64-encoded JPEG/PNG, max 10MB                                                                                                                         |
| `proofOfAddressType`                | string (enum)      | Required, values: Unknown, BankStatement, CouncilBill, CreditCardStatement, LeaseAgreement, LoanApplication, MortgageApplication, PhoneBill, TaxReturn, UtilityBill |
| `bCreateDDA`                        | boolean            | <p>Optional<br><br>To Automatically Create Managee DDA account with onboarding</p>                                                                                  |

**Sample Request Body Parameters:**

```
{
  "emailAddress": "john.doe@ibanera.com",
  "manageesReference": "USA12345",
  "fiatCurrencyCode": "USD",
  "fullName": "John Doe",
  "firstGivenName": "John",
  "lastSurname": "Doe",
  "townCity": "New York",
  "addressCountryISO": "USA",
  "addressLine1": "123 Main Street",
  "addressLine2": "Apt 4B",
  "stateProvince": "NY",
  "postcode": "10001",
  "phoneNumber": "+12125551234",
  "dateOfBirth": "1985-07-15",
  "taxNumber": "999-45-6789",
  "nationalityISO": "USA",
  "occupation": "Software Engineer",
  "sendInvite": true,
  "sourceFundsTypes": [
    "Salary"
  ],
  "otherSourceOfFunds": "Freelancing",
  "estimatedNetWorth": 150000.00,
  "estimatedGrossAnnualIncome": 90000.00,
  "otherBanks": [
    "Bank of America"
  ],
  "bActivelyEmployed": true,
  "employedCompanyName": "Tech Solutions Inc.",
  "employedJobTitle": "Senior Developer",
  "purposeOfOpeningAccountTypes": [
    "DigitalAsset"
  ],
  "monthlyTurnover": 10000.00,
  "anticipatedTransactionActivity": 8000.00,
  "purchaseCryptoMonthlyVolume": 2000.00,
  "purchaseCryptoAverageAmount": 500.00,
  "purchaseCryptoTotalAmountPerMonth": 2000.00,
  "sellingCryptoAverageAmount": 400.00,
  "sellingCryptoMonthlyVolume": 1600.00,
  "sellingCryptoTotalAmountPerMonth": 1600.00,
  "totalMonthlyVolume": 3600.00,
  "totalAverageAmount": 450.00,
  "totalMonthlyAmount": 3600.00,
  "btcTradingPercentage": 50.0,
  "ethTradingPercentage": 30.0,
  "usdcTradingPercentage": 10.0,
  "otherCoinsTradingPercentage": 10.0,
  "bIrsTax": true,
  "bForeignAccountTax": false,
  "bNotCriminal": true,
  "bAccurateInfo": true,
  "proofOfAddressFile": "BASE64_ENCODED_STRING_HERE",
  "proofOfAddressType": "UtilityBill",
  "bCreateDDA": true
}
```

Upon successful creation, the API will return a Jumio verification link that the user must follow to complete KYC. This verification link is accessible in the jumioLink field.

**Response Body Parameters:**

* id (Integer): A placeholder ID not actively used in the response.
* details (Object):
  * manageesId(bigint): Newly Created Customer ID
  * jumioLink(Array of Objects): Newly created customer will require to validate email from portl link (e.g. <https://customer-uat.ibanera.com>) before further identity verification on this jumio link.

**Response Body Example**

```
{
    "id": 0,
    "details": {
        "manageesId": 14973,
        "jumioLink": "https://customer-uat.ibanera.com/manageesidverification?token=1naM3iyljym7wz%2f5C6yujA%3d%3d"
    },
    "status": "1",
    "errors": []
}
```

#### Using External IDv Provider

When using an external IDv provider, there are two steps to the onboarding process. The first step is to submit the customer details as defined below. Once the customer is created, you must then use an additional API endpoint to Upload Documents, which would be the externally collected ID verification documents.

`bUseJumio` = false (IDv Collected Externally)

| `emailAddress`                      | string             | Required, must be a valid email        |
| ----------------------------------- | ------------------ | -------------------------------------- |
| `manageesReference`                 | string             | Required, reference for the customer   |
| `parentCustomersId`                 | integer (int32)    | Optional                               |
| `fiatCurrencyCode`                  | string             | Required                               |
| `fullName`                          | string             | Required                               |
| `firstGivenName`                    | string             | Required                               |
| `lastSurname`                       | string             | Required                               |
| `townCity`                          | string             | Required                               |
| `addressCountryISO`                 | string             | Required, 2-letter ISO country code    |
| `addressLine1`                      | string             | Required                               |
| `addressLine2`                      | string             | Optional                               |
| `stateProvince`                     | string             | Required                               |
| `postcode`                          | string             | Required                               |
| `phoneNumber`                       | string             | Required                               |
| `dateOfBirth`                       | string (date-time) | Required, e.g., "1990-01-01T00:00:00Z" |
| `taxNumber`                         | string             | Required                               |
| `nationalityISO`                    | string             | Required, ISO country code             |
| `occupation`                        | string             | Required                               |
| `sendInvite`                        | boolean            | Required                               |
| `sourceFundsTypes`                  | array of string    | Optional                               |
| `otherSourceOfFunds`                | string             | Optional                               |
| `estimatedNetWorth`                 | number (double)    | Optional                               |
| `estimatedGrossAnnualIncome`        | number (double)    | Optional                               |
| `otherBanks`                        | array of string    | Optional                               |
| `bActivelyEmployed`                 | boolean            | Optional                               |
| `employedCompanyName`               | string             | Optional                               |
| `employedJobTitle`                  | string             | Optional                               |
| `purposeOfOpeningAccountTypes`      | array of string    | Optional                               |
| `monthlyTurnover`                   | number (double)    | Optional                               |
| `anticipatedTransactionActivity`    | number (double)    | Optional                               |
| `purchaseCryptoMonthlyVolume`       | number (double)    | Optional                               |
| `purchaseCryptoAverageAmount`       | number (double)    | Optional                               |
| `purchaseCryptoTotalAmountPerMonth` | number (double)    | Optional                               |
| `sellingCryptoAverageAmount`        | number (double)    | Optional                               |
| `sellingCryptoMonthlyVolume`        | number (double)    | Optional                               |
| `sellingCryptoTotalAmountPerMonth`  | number (double)    | Optional                               |
| `totalMonthlyVolume`                | number (double)    | Optional                               |
| `totalAverageAmount`                | number (double)    | Optional                               |
| `totalMonthlyAmount`                | number (double)    | Optional                               |
| `btcTradingPercentage`              | number (double)    | Optional                               |
| `ethTradingPercentage`              | number (double)    | Optional                               |
| `usdcTradingPercentage`             | number (double)    | Optional                               |
| `otherCoinsTradingPercentage`       | number (double)    | Optional                               |
| `bIrsTax`                           | boolean            | Optional                               |
| `bForeignAccountTax`                | boolean            | Optional                               |
| `bNotCriminal`                      | boolean            | Optional                               |
| `bAccurateInfo`                     | boolean            | Optional                               |

#### **KYC Verification DTO**

| `documentType`                 | [**Document Type**](#document-type-1)                                                   | Type of document used (e.g., `ID_CARD`)    |
| ------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------ |
| `subType`                      | [**Document Sub Type**](#document-sub-type-1)                                           | Sub-category (e.g., `NATIONAL_ID`)         |
| `issuingCountry`               | string (ISO3)                                                                           | Issuing country (e.g., `USA` for Pakistan) |
| `firstName`                    | string                                                                                  | First name from the document               |
| `lastName`                     | string                                                                                  | Last name from the document                |
| `dateOfBirth`                  | string (date)                                                                           | Date of birth in ISO format                |
| `expiryDate`                   | string (date)                                                                           | Document expiry date                       |
| `documentNumber`               | string                                                                                  | Unique number of the document              |
| `gender`                       | string                                                                                  | Gender (e.g., `M` for Male)                |
| `workFlowDecisionResult`       | [**WorkflowDetailsDecisionTypes**](#workflowdetailsdecisiontypes-1)                     | Overall workflow decision (e.g., `PASSED`) |
| `workflowDetailsCategoryTypes` | [**WorkflowDetailsCapabilityCategoryTypes**](#workflowdetailscapabilitycategorytypes-1) | Category type (e.g., `ID`)                 |

#### Capabilities (Nested) DTO

| `liveLinessDecisionResult` | [**WorkflowDetailsDecisionTypes**](#workflowdetailsdecisiontypes-1) | Liveness check result (e.g., `PASSED`)  |
| -------------------------- | ------------------------------------------------------------------- | --------------------------------------- |
| `similarityDecisionResult` | [**WorkflowDetailsDecisionTypes**](#workflowdetailsdecisiontypes-1) | Face similarity result (e.g., `PASSED`) |

#### Enumeration Values

#### **Document Type**

| PASSPORT         | Customer Passport, clearly displaying key identification details page |
| ---------------- | --------------------------------------------------------------------- |
| DRIVING\_LICENSE | Drivers License documentation                                         |
| ID\_CARD         | Identification Card document                                          |
| VISA             | Customer Visa document                                                |

#### **Document Sub Type**

| NOTIONAL\_ID               | Customer Passport, clearly displaying key identification details page             |
| -------------------------- | --------------------------------------------------------------------------------- |
| CONSULAR\_ID               | Drivers License documentation                                                     |
| ELECTORAL\_ID              | Identification Card document                                                      |
| RESIDENT\_PERMIT\_ID       | Customer Visa document                                                            |
| TAX\_ID                    | Customer selfie photo, must be clear                                              |
| STUDENT\_ID                | Customer Proof of Address, must be within 90 days to be accepted                  |
| PASSPORT\_CARD\_ID         | Passport Identification Card                                                      |
| MILITARY\_ID               | Military Identification Card                                                      |
| PUBLIC\_SAFETY\_ID         | Public Safety Identification Card                                                 |
| HEALTH\_ID                 | Health Identification Card                                                        |
| OTHER\_ID                  | Other Identification Card                                                         |
| VISA                       | Visa Identification Card                                                          |
| REGULAR\_DRIVING\_LICENSE  | Use when DocumentType is DRIVING\_LICENSE, for regular drivers license            |
| LEARNING\_DRIVING\_LICENSE | Use when DocumentType is DRIVING\_LICENSE, for learners drivers license or permit |
| E\_PASSPORT                | Use when DocumentType is PASSPORT                                                 |

#### Supporting Document Type

| BankStatement       | Official bank-issued statement showing account details and customer address.   |
| ------------------- | ------------------------------------------------------------------------------ |
| CouncilBill         | Bill from local government or municipality sent to a residential address.      |
| CreditCardStatement | Statement from a credit card company showing transactions and billing address. |
| LeaseAgreement      | Legal document outlining rental terms and the tenant's residential address.    |
| LoanApplication     | Submitted form for a loan, containing personal and address details.            |
| MortgageApplication | Application for a mortgage including applicant and property address info.      |
| PhoneBill           | Landline or mobile phone bill with user’s name and billing address.            |
| TaxReturn           | Government-submitted tax form that includes taxpayer's address.                |
| UtilityBill         | Bill for essential services (water, electricity, gas) confirming residency.    |

#### Document Side

| Front | Front side of Identification Document |
| ----- | ------------------------------------- |
| Back  | Back side of Identification Document  |
| Face  | Selfie of customer                    |

#### Decision Results

| NOT\_EXECUTED | ID Verification Workflow not executed        |
| ------------- | -------------------------------------------- |
| PASSED        | ID Verification Workflow Passed Successfully |
| REJECTED      | ID Verification was Rejected                 |
| WARNING       | ID Verification completed with warning       |

#### WorkflowDetailsDecisionTypes

| `NOT_EXECUTED` | The check or verification step was not executed.                               |
| -------------- | ------------------------------------------------------------------------------ |
| `PASSED`       | The verification step passed successfully.                                     |
| `REJECTED`     | The verification step failed and was explicitly rejected.                      |
| `WARNING`      | The verification step completed with a warning that may require manual review. |

#### WorkflowDetailsCapabilityCategoryTypes

| `ID`       | Identity document verification (e.g., ID card)                        |
| ---------- | --------------------------------------------------------------------- |
| `FACEMAP`  | Facial mapping used for biometric comparison                          |
| `DOCUMENT` | Supporting document verification (e.g., utility bill, bank statement) |
| `SELFIE`   | Live selfie verification                                              |

#### Source of Funds Types

<table><thead><tr><th>Value</th><th>Description</th><th data-hidden></th></tr></thead><tbody><tr><td>Salary</td><td>Salary</td><td></td></tr><tr><td>Savings</td><td>Savings</td><td></td></tr><tr><td>SelfEmployed</td><td>Self Employed</td><td></td></tr><tr><td>Loans</td><td>Loans/Borrowed Funds</td><td></td></tr></tbody></table>

#### Purpose Of Opening Account Types

<table><thead><tr><th>Value</th><th>Description</th><th data-hidden></th></tr></thead><tbody><tr><td>DigitalAsset</td><td>Digital Asset OTC Desk</td><td></td></tr><tr><td>CryptoLoans</td><td>Crypto Loans</td><td></td></tr><tr><td>PeerToPeer</td><td>Peer to Peer Transfer</td><td></td></tr><tr><td>CreditDebit</td><td>Credit or Debit Services</td><td></td></tr></tbody></table>

**Request Payload Example**

```
{
  "bUseJumio": false,
  "emailAddress": "john.doe62@ibanera.com",
  "manageesReference": "USA1234",
  "fiatCurrencyCode": "USD",
  "fullName": "John Doe",
  "firstGivenName": "John",
  "lastSurname": "Doe",
  "townCity": "Columbus",
  "addressCountryISO": "USA",
  "addressLine1": "742 Evergreen Terrace",
  "stateProvince": "OH",
  "postcode": "43215",
  "phoneNumber": "+16145551234",
  "dateOfBirth": "1988-05-20",
  "taxNumber": "123-45-6789",
  "nationalityISO": "USA",
  "occupation": "Software Engineer",
  "sendInvite": true,
  "sourceFundsTypes": [
    "Salary",
    "Savings"
  ],
  "otherSourceOfFunds": "Freelance Projects",
  "estimatedNetWorth": 250000.00,
  "estimatedGrossAnnualIncome": 95000.00,
  "otherBanks": [
    "Chase",
    "Wells Fargo"
  ],
  "bActivelyEmployed": true,
  "employedCompanyName": "Innovative Tech Corp",
  "employedJobTitle": "Senior Developer",
  "purposeOfOpeningAccountTypes": [
    "DigitalAsset",
    "Investment"
  ],
  "monthlyTurnover": 8000.00,
  "anticipatedTransactionActivity": 7500.00,
  "purchaseCryptoMonthlyVolume": 1500.00,
  "purchaseCryptoAverageAmount": 500.00,
  "purchaseCryptoTotalAmountPerMonth": 1500.00,
  "sellingCryptoAverageAmount": 400.00,
  "sellingCryptoMonthlyVolume": 1200.00,
  "sellingCryptoTotalAmountPerMonth": 1200.00,
  "totalMonthlyVolume": 2700.00,
  "totalAverageAmount": 450.00,
  "totalMonthlyAmount": 2700.00,
  "btcTradingPercentage": 40.0,
  "ethTradingPercentage": 35.0,
  "usdcTradingPercentage": 15.0,
  "otherCoinsTradingPercentage": 10.0,
  "bIrsTax": true,
  "bForeignAccountTax": false,
  "bNotCriminal": true,
  "bAccurateInfo": true,
  "kycVerificationDetails": {
    "documentType": "ID_CARD",
    "subType": "STATE_ID",
    "issuingCountry": "USA",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1988-05-20T00:00:00",
    "expiryDate": "2032-08-15T00:00:00",
    "documentNumber": "D1234567",
    "gender": "M",
    "workFlowDecisionResult": "PASSED",
    "workflowDetailsCategoryTypes": "ID",
    "capabilities": {
      "liveLinessDecisionResult": "PASSED",
      "similarityDecisionResult": "PASSED"
    }
  }
}
```

**Response Payload (Success Example)**

```
{
    "id": 0,
    "details": {
        "manageesId": 14981,
        "kycDocumentsRequired": [
            {
                "type": "ID_CARD",
                "supportingDocumentTypes": null,
                "sidesRequired": [
                    "Front",
                    "Back"
                ]
            },
            {
                "type": "SELFIE",
                "supportingDocumentTypes": null,
                "sidesRequired": [
                    "Face"
                ]
            },
            {
                "type": "PROOF_OF_ADDRESS",
                "supportingDocumentTypes": [
                    "BankStatement",
                    "CouncilBill",
                    "CreditCardStatement",
                    "LeaseAgreement",
                    "LoanApplication",
                    "MortgageApplication",
                    "PhoneBill",
                    "TaxReturn",
                    "UtilityBill"
                ],
                "sidesRequired": [
                    "Front"
                ]
            }
        ]
    },
    "status": "1",
    "errors": []
}
```

**Response Payload (Failure Example)**

```
{
    "id": 0,
    "details": null,
    "status": "0",
    "errors": [
        {
            "fieldName": "ErrorLabel",
            "messageCode": "User already exists"
        }
    ]
}
```

#### Possible Error Message Codes

<table><thead><tr><th width="322">Error Message Code Example</th><th>Description</th></tr></thead><tbody><tr><td>Required</td><td>Named field missing</td></tr><tr><td>Invalid_Length</td><td>Named field length invalid</td></tr><tr><td>Invalid_Format</td><td>Named field format invalid</td></tr><tr><td>Username_Not_Available</td><td>User with requested email already exists</td></tr><tr><td>Currency_Invalid</td><td>Currency not supported</td></tr><tr><td>Nationality_Invalid</td><td>Requested user nationality not supported</td></tr><tr><td>Address_Country_Invalid</td><td>Address country not supported</td></tr><tr><td>Percentage_Invalid</td><td>Percentages must be between 0 and 100</td></tr><tr><td>Total_Percentage_Invalid</td><td>Total percentage must be at most 100</td></tr><tr><td>Type_Duplicated</td><td>Duplicate entries in array</td></tr><tr><td>IrsTax_Invalid</td><td>User must agree to terms</td></tr><tr><td>ForeignAccountTax_Invalid</td><td>User must agree to terms</td></tr><tr><td>NotCriminal_Invalid</td><td>User must agree to terms</td></tr><tr><td>AccurateInfo_Invalid</td><td>User must agree to terms</td></tr></tbody></table>

Once submitted successfully, the API will respond with the kycDocumentsRequired to complete the onboarding. These documents can be submitted via the Upload Document endpoint below.

## Upload KYC Document

Upload individual KYC documents (e.g., ID Front, ID Back, Face Photo) associated with the ManageesId Id received from [**Create Managee**](#create-a-managee).

<sub><mark style="color:orange;background-color:yellow;">**POST**<mark style="color:orange;background-color:yellow;"></sub> <sub>/api/v6/customer/managees/uploaddocument</sub>

<sub>**Request Format:**</sub> <sub>multipart/form-data</sub>

**Request Payload**

| **Parameter**              | **Type** | **Description**                                                           |
| -------------------------- | -------- | ------------------------------------------------------------------------- |
| **ManageesId**             | int      | Unique identifier of the customer, obtained from onboard endpoint         |
| **Type**                   | enum     | Type of document being uploaded, obtained from result of onboard endpoint |
| **DocumentSide**           | enum     | Side of the document (e.g., Front, Back, Face)                            |
| **File**                   | file     | The document file to be uploaded                                          |
| **SupportingDocumentType** | enum     | Only required for `PROOF_OF_ADDRESS`                                      |

**Enumeration Values:**

* [**Type**](#document-type)
* [**DocumentSide**](#document-side)
* [**SupportingDocumentType**](#supporting-document-type)

**Response Payload (Success Example)**

```
{
    "id": 0,
    "details": {
        "bSuccess": true,
        "documentID": "743f1614-6cb5-486a-a2bc-0c1eb14a1168"
    },
    "status": "1",
    "errors": []
}
```

**Response Payload (Failure Example)**

```
{
    "id": 0,
    "status": "0",
    "errors": [
        {
            "fieldName": "ManageesId",
            "messageCode": " ManageesId is required"
        }
    ]
}
```

***

## List Managees

Retrieve a paginated list of basic data for all managees linked to the manager. Managers can view a list of all their linked customers, sortable and navigable through numerous pages.

* **Endpoint**: `/api/v2/customer/managees/list`
* **Method**: GET

{% openapi src="/files/8wfNPb3MIn4CPnxhg0ir" path="/api/v2/customer/managees/list" method="get" %}
[public-api-customer-role (8).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-f4945577c49293d171bc558d4321443c27fcf223%2Fpublic-api-customer-role%20\(8\).json?alt=media)
{% endopenapi %}

**Query Parameters**:

* `PageNumber`: Page to view
* `PageSize`: Results per page

**Success Response Parameters**:

* `id` (Integer): An identifier for the list operation; might not be used in the response.
* `details` (Array of Objects): An array containing managee objects with the following structure:
  * `manageesId` (Integer): The unique ID of the managee user.
  * `manageesReference` (String): Your reference for the managee.
  * `name` (String): Managee’s full name.
  * `addDate` (DateTime): Date and time when the managee was created, formatted in ISO 8601.
  * `verificationStatus` (String): Current verification status of the managee ("Pending," "Accepted," or "Rejected").
  * `widgetUserReference` (String): Widget user reference associated with the managee, if any.
  * `parentCustomersId` (Integer): ID of the managee's parent customer.
* `pageSize` (Integer): The number of results per page returned in the response.
* `pageNumber` (Integer): The current page number in the paginated list.
* `numberOfPages` (Integer): The total number of available pages.
* `status` (String): Indicates the status code of the response ("1" for success).
* `errors` (Array): Contains error details if any occurred during the request.

#### Response Body Example:

```json
{
    "id": 1777,
    "details": [
        {
            "manageesId": 14359,
            "manageesReference": "34233rqcpomrkvr3g56",
            "name": "Jaden Kris",
            "addDate": "2024-07-24T15:12:46.547",
            "verificationStatus": "Pending",
            "widgetUserReference": null,
            "parentCustomersId": 14358
        }
    ],
    "pageSize": 10,
    "pageNumber": 7,
    "numberOfPages": 7,
    "status": "1",
    "errors": []
}
```

**Response with Errors Parameters**:

* `id` (Integer): Reference identifier for the request; often not used with errors.
* `details` (null): Typically null when errors are present.
* `status` (String): Status code of the operation ("0" for errors).
* `errors` (Array of Objects): An array of error objects, each containing:
  * `fieldName` (String): The field name that caused the error.
  * `messageCode` (String): Specific code indicating the error (e.g., "Invalid").

#### Possible Error Message Codes

| Error Message Code Example | Description             |
| -------------------------- | ----------------------- |
| Invalid                    | Named parameter invalid |

***

## Get List of Accounts for a Managee by ID

**This endpoint is deprecated and may have functionality issues. This endpoint was replaced by the new** [**List Asset Accounts for Customer**](/api-endpoints/accounts#list-asset-accounts-for-customer) **endpoint (**[**Accounts Module API**](/api-endpoints/accounts)**). Please use** [**List Asset Accounts for Customer**](/api-endpoints/accounts#list-asset-accounts-for-customer) **for this purpose.**

This endpoint retrieves a list of accounts belonging to a managee. You can filter the list by the managee's ID, the asset (currency), and control pagination with page number and size. This functionality is like a filterable list that shows all the accounts for individuals or entities managed by another party. It allows the user to see only specific accounts, sort it by the type of money in the account (like USD), and break the list into readable chunks (pages).

* **Endpoint**: `/api/v1/customer/manageeaccounts/list`
* **Method**: GET
* **Query Parameters**:
  * `ManageesId` (Integer): Managee's ID for filtering (optional).
  * `Asset` (String): Asset code for filtering (optional).
  * `PageNumber` (Integer): The page number for pagination, default is 1 (optional).
  * `PageSize` (Integer): The number of records per page, default is 10 (optional).\\

{% openapi src="/files/v26YtDRIkV6wiBPah7nY" path="/api/v1/customer/manageeaccounts/list" method="get" %}
[PublicAPI-April16.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-c8d5f9dcad96517eae48c21ca883167a3d1730b6%2FPublicAPI-April16.json?alt=media)
{% endopenapi %}

**Response Body Parameters and Types**:

* `id` (Integer): A reference ID for the account list.
* `details` (Array of Objects): A list of account objects, each with the following structure:
  * `id` (Integer): The unique ID for the account.
  * `manageesId` (Integer): The related managee’s ID for this account.
  * `name` (String): The name associated with the account.
  * `routingNumber` (String): The account routing number for financial transactions.
  * `accountNumber` (String): The specific account number.
  * `asset` (String): Currency code of the account’s asset.
  * `totalBalance` (Decimal): The total money held in the account.
  * `availableBalance` (Decimal): The funds available for withdrawal or spending.
  * `pendingBalance` (Decimal): Amounts that are in the process of being deposited or withdrawn.
  * `bSuppressed` (Boolean): Indicates whether the account is currently suppressed (hidden) or active.
  * `dateAdded` (String): Date and time the account was created, in ISO 8601 format.
* `pageSize` (Integer): Numerical size of the current page in the paginated response.
* `pageNumber` (Integer): Current page number within the paginated set.
* `numberOfPages` (Integer): Total number of response pages available.
* `status` (String): The operation's success status; '1' for success.
* `errors` (Array): An array of error objects, detailing any issues encountered with the request.

**Success Response Example**:

The response returns a list of managee accounts with details including the account's name, routing number, account number, asset, balances, and addition date.

```json
{
  "id": 1025,
  "details": [
    {
      "id": 1055,
      "manageesId": 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": []
}
```

***

## Create Widget User

This endpoint allows the creation of a widget user reference for the managee to facilitate the use of the crypto widget. Special identifiers for managees are generated to give them access to easier checkouts, as customer information will already be provided.

* **Endpoint**: `/api/v1/customer/managees/createwidgetuser`
* **Method**: POST

{% openapi src="/files/jJ7E6wWPcyFuZH6ofuNu" path="/api/v1/customer/managees/createwidgetuser" method="post" %}
[Customer API - Customer v5.0.7.json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-1018aaf3121ec8a24cd8dd89c9a572d034369d99%2FCustomer%20API%20-%20Customer%20v5.0.7.json?alt=media)
{% endopenapi %}

**Request Body**:

* `manageesId` (Integer): The managee's ID for who the widget user is being created.
* `widgetUserReference` (String, max length 100): The widget user reference associated with the managee.

**Success Response Parameters**:

* `id` (Integer): A reference ID for the createwidgetuser operation, not typically used in the response.
* `status` (String): The status code of the operation ("1" for success).
* `errors` (Array): An empty array, indicating that no errors occurred during the request.

**Success Response Example**:

```json
{
  "id": 0,
  "status": "1"
  "errors": []
}
```

**Response Example with Errors**:

```json
{
  "id": 0,
  "details": null,
  "status": "0",
  "errors": [
    {
      "fieldName": "ManageesId",
      "messageCode": "Managee_Not_Found"
    }
  ]
}
```

#### Possible Error Message Codes

<table><thead><tr><th width="296">Error Message Code Example</th><th>Description</th></tr></thead><tbody><tr><td>Widget_Client_Not_Found</td><td>Manager does not have associated widget client</td></tr><tr><td>Managee_Not_Found</td><td>Managee’s Id is invalid</td></tr><tr><td>Managee_Not_Verified</td><td>Managee is not verified</td></tr><tr><td>Widget_User_Already_Exists</td><td>Managee already has an associated widget user</td></tr><tr><td>Already_Used</td><td>WidgetUserReference already used before</td></tr></tbody></table>


# Information Requests (RFIs)

## Overview

When transactions are flagged as high-risk, they are marked as pending on our system. Our compliance team will review transactions and may ask a customer for further information on a transaction to better understand the nature of the request. If an administrator needs more details to make this decision, they can send an information request (RFI) to the customer. This module will enable API users to retrieve information requests and respond with supporting documents and information.

When a information request is issued, API users will receive a [callback notification](/callbacks/information-requests#information-requested-callback). Similarly, when a request is updated (either being accepted, rejected, or requires more information), [another callback request is sent.](/callbacks/information-requests#information-request-updated-callback)

#### Endpoints in this Section:

1. [**List Information Requests**](#list-information-requests) - Retrieves a list of information requests (RFIs). Optional filters can be applied to narrow down the list by customer.
2. [**Get Information Request Details**](#get-information-request-details) - Retrieves detailed information about a specific information request using its unique ID.
3. [**Submit Information Request**](#submit-information-request) - Allows a customer to submit information and documents in response to an RFI.

***

## List Information Requests

Retrieves a list of information requests (RFIs). Optional filters can be applied to narrow down the list by customer.

* **Endpoint:** `/api/v1/customer/informationrequests/getinformationrequestlist`
* **Method:** GET
* **Response Format:** application/json

#### `GET` Query Parameters

<table data-header-hidden><thead><tr><th width="198"></th><th width="103"></th><th></th></tr></thead><tbody><tr><td><strong>Request body parameter</strong></td><td><strong>Format</strong></td><td><strong>Description</strong></td></tr><tr><td>CustomersId</td><td>int</td><td>Filter by this id (optional)</td></tr><tr><td>PageNumber</td><td>int</td><td>Page number (optional – default 1)</td></tr><tr><td>PageSize</td><td>int</td><td>Number of results per page (optional – default 10)</td></tr></tbody></table>

#### Example Success Response

```json
{
    "id": 14152,
    "details": [
       {
            "id": 1004,
            "status": "More Information Required",
            "addDate": "2024-03-20T12:29:16.023",
            "expiryDate": "2024-03-27T12:29:16.023",
            "orderType": "OUT",
            "name": "Addison Payee",
            "reference": "United States Dollar: CTX31165",
            "amount": -20.000000000000000000,
            "currencySymbol": "$",
            "assetCode": "USD"
        },
        …
    ],
    "pageSize": 10,
    "pageNumber": 1,
    "numberOfPages": 2,
    "status": "1",
    "errors": []
}
	

```

<table data-header-hidden><thead><tr><th width="204"></th><th></th></tr></thead><tbody><tr><td><strong>Error message code example</strong></td><td><strong>Description</strong></td></tr><tr><td>Invalid</td><td>Invalid request values</td></tr><tr><td>Unauthorized</td><td>User is not authorized for this action</td></tr></tbody></table>

***

## Get Information Request Details

Retrieves detailed information about a specific information request using its unique ID.

* **Endpoint:** /api/v1/customer/informationrequests/ getinformationrequestdetails
* **Method:** GET
* **Response Format:** application/json

#### `GET` Query Parameters

<table data-header-hidden><thead><tr><th width="231"></th><th width="103"></th><th></th></tr></thead><tbody><tr><td><strong>Request body parameter</strong></td><td><strong>Format</strong></td><td><strong>Description</strong></td></tr><tr><td>informationRequestsId</td><td>int</td><td>The information request to access</td></tr></tbody></table>

#### Example Success Response

```json
{
    "id": 1004,
    "details": {
        "Id": 1004,
        "Status": "More Information Required",
        "OrderType": "OUT",
        "Name": "Sample Customer",
        "TransactionID": 123456,
        "PaymentDescription": "External transfer - Deposit",
        "TransactionDate": "01-02-2025",
        "currencySymbol": "$",
        "assetCode": "USD",
        "amount": -20.000000000000000000,
        "description": "Dear Customer, Please provide the .....",
        "responseFormGuid": "F0A88644-A105-4CF1-ACE0-B570F1411783"
    },
    "status": "1",
    "errors": []
}
```

<table data-header-hidden><thead><tr><th width="201"></th><th></th></tr></thead><tbody><tr><td><strong>Error message code example</strong></td><td><strong>Description</strong></td></tr><tr><td>Not_Found</td><td>InformationRequestsID not found</td></tr><tr><td>Invalid</td><td>User is not valid for this action</td></tr></tbody></table>

***

## Submit Information Request

Allows a customer to submit information and documents in response to an RFI.

* **Endpoint:** /api/v1/customer/informationrequests/submitinformationrequest
* **Method:** POST
* **Request format:** form-data
* **Response format:** application/json

<table data-header-hidden data-full-width="true"><thead><tr><th width="504"></th><th width="103"></th><th></th></tr></thead><tbody><tr><td><strong>Request body parameter</strong></td><td><strong>Format</strong></td><td><strong>Description</strong></td></tr><tr><td>CustomerAssetAccountsTransactionsInformationRequestsId</td><td>int</td><td>Id</td></tr><tr><td>ResponseFormGuid</td><td>string</td><td>GUID for identifying responses</td></tr><tr><td>SupportingInformation</td><td>string</td><td>Text response</td></tr><tr><td>SupportingDocumentUploads</td><td>file</td><td>One or more files to be uploaded as evidence</td></tr></tbody></table>

**Request Body**

```
CustomerAssetAccountsTransactionsInformationRequestsId
1004

ResponseFormGuid
BCBE8BF9-1171-4F60-B434-694C19BFDD9F

SupportingInformation
Example supporting information

SupportingDocumentUploads
/C:/Path/To/File/dummy.pdf

SupportingDocumentUploads
/C:/ Path/To/File/dummy_2.pdf	
```

**Example Success Response**

```json
{
  "id": 1046,
  "status": "1",
  "errors": []
}	
```

<table data-header-hidden><thead><tr><th width="272"></th><th width="103"></th><th></th></tr></thead><tbody><tr><td><strong>Request body parameter</strong></td><td><strong>Format</strong></td><td><strong>Description</strong></td></tr><tr><td>id</td><td>int</td><td>Id of the response</td></tr></tbody></table>

<table data-header-hidden><thead><tr><th width="292"></th><th></th></tr></thead><tbody><tr><td><strong>Error message code example</strong></td><td><strong>Description</strong></td></tr><tr><td>Not_Found</td><td>InformationRequestsID not found</td></tr><tr><td>Invalid User</td><td>User is not valid for this action</td></tr><tr><td>Information_request_not_found</td><td>Information request does not exist with the expected status</td></tr><tr><td>Information_response_not_needed</td><td>Information response does not exist with the expected status</td></tr><tr><td>Response_form_already_submitted</td><td>Response form has been submitted with this GUID</td></tr></tbody></table>


# Quick Buy

The Quick Buy module provides infrastructure to perform buy exchanges on behalf of customers, using a customer's external payment card. This module includes a series of endpoints tailored to the needs of users looking to perform and monitor quick buy exchanges for their customers, as well as manage their saved cards.

Offering functions from quoting to execution, along with detailed tracking mechanisms, the Quick Buy module endpoints include:

**Onboarding**:

* [**Create QuickBuy Customer**](#create-quickbuy-customer) - Onboard a new customer account for using QuickBuy.
* [**Upload Documents (For QuickBuy Customer Onboarding)**](#upload-documents-for-quickbuy-customer-onboarding) - Upload Documents for a newly onboarded QuickBuy Customer, if using external KYC.

**Card Management**:

* [**List Cards**](#list-cards) - Retrieve a list of payment cards associated with a customer.
* [**Get Card by ID**](#get-card-by-id) - Enables a user to retrieve information about a payment card by submitting the ID of the payment card.
* [**Delete Card**](#delete-card) - Allows a user to delete a payment card, removing it from being an option for further exchanges.

**Exchanges**:

* [**Get Available Asset Pairs**](#get-available-asset-pairs): Provides a list of asset pairs enabled for the API user and available for quick buy. The response will also include information on limits and minimums associated with each asset pair for exchanges.
* [**Get Quote**](#get-quote)**:** Provides an estimate for a quick buy exchange, detailing the price and amount before the actual exchange is executed, ensuring that the customer is informed about the potential transaction.
* [**Submit Exchange**](#submit-exchange)**:** This endpoint will allow a customer to initiate a quick buy exchange. The customer can either use a saved payment card or enter details of a payment card. The user has the option of saving the payment card for use in further exchanges.
* [**List Exchanges**](#list-exchanges): Provides a generated list of quick buy exchanges, with the ability to filter by customer, order type, and more.
* [**Get Order by ID**](#list-exchanges): Provides a details of a quick buy order buy submitting the ID of the exchange.

***

## Create QuickBuy Customer

This endpoint facilitates the onboarding of a QuickBuy-only customer with minimal required information. It is intended for widget-based applications and other simplified onboarding interfaces strictly for the QuickBuy product, providing a leaner alternative to the full managee onboarding process.

* **Endpoint**: `/api/v1/customer/quick-buy/onboard`
* **Method**: POST

Important to Note

* Customers created via this endpoint cannot access Ibanera banking services.
* For real-time status update, use the Customer Detail API /api/v1/customer/details.
* If the response contains `jumioLink`, the customer must complete that verification step before eligible to submit exchanges.

### KYC Collection

Ibanera collects KYC for QuickBuy/Portl customers. This endpoint offers the flexibility of either using Ibanera's ID Verification provider, Jumio, or using your own IDv solution. The below section outlines each approach can be executed.

### Using Ibanera's ID Verification

**`bUseJumio`** = true (Jumio Verification Required)

#### Request Body Parameters

```json
{
  "bUseJumio": true,
  "customerReference": "your-customer-reference-1234",
  "email": "user.email@ibanera.com",
  "firstName":"John",
  "lastName": "Doe",
  "dob": "1995-01-15",
  "phone": "+18001234567",
  "address": {
    "line1": "123 Main St",
    "line2": "Unit 1a",
    "city": "City",
    "state": "TX",
    "postcode": "12345",
    "countryISO": "US"
  },
  "nationalityISO": "US",
  "bAcceptTermsAndConditions": true,
  "bAcceptPrivacyPolicy": true
}
```

Upon successful creation, the API will return a Jumio verification link that the user must follow to complete KYC. This verification link is accessible in the **`jumioLink`** field.

**Response Body Parameters:**

* `id` (Integer): A placeholder ID not actively used in the response.
* `details` (Object):
  * `customersId`(bigint): Newly Created Customer ID
  * `jumioLink`(Array of Objects): Newly created customer will require to validate email from portl link (e.g. [https://portl-uat.ibanera.com](https://portl-uat.ibanera.com/)) before further identity verification on this jumio link.

**Response Body Example**

```json
{
    "id": 0,
    "details": {
        "customersId": 12345,
        "jumioLink": "https://customer-uat.ibanera.com/manageesidverification?token=IXMFastM8ZcQSt...."
    },
    "status": "1",
    "errors": []
}
```

### Using External IDv Provider

When using an external IDv provider, there are two steps to the onboarding process. The first step is to submit the customer details as defined below. Once the customer is created, you must then [use an additional API endpoint to Upload Documents](https://github.com/gradam26/Phoenix-Documentation/blob/main/customer-api/api-endpoints/quick-buy-1.md#upload-documents-for-quickbuy-customer-onboarding), which would be the externally collected ID verification documents.

`bUseJumio` = false (IDv Collected Externally)

#### Enumeration Values

**DocumentType**

<table><thead><tr><th width="286.5859375">Name</th><th>Description</th></tr></thead><tbody><tr><td>PASSPORT</td><td>Customer Passport, clearly displaying key identification details page</td></tr><tr><td>DRIVING_LICENSE</td><td>Drivers License documentation</td></tr><tr><td>ID_CARD</td><td>Identification Card document</td></tr><tr><td>VISA</td><td>Customer Visa document</td></tr></tbody></table>

**Document Sub Type**

<table><thead><tr><th width="286.5859375">Name</th><th>Description</th></tr></thead><tbody><tr><td>NOTIONAL_ID</td><td>Customer Passport, clearly displaying key identification details page</td></tr><tr><td>CONSULAR_ID</td><td>Drivers License documentation</td></tr><tr><td>ELECTORAL_ID</td><td>Identification Card document</td></tr><tr><td>RESIDENT_PERMIT_ID</td><td>Customer Visa document</td></tr><tr><td>TAX_ID</td><td>Customer selfie photo, must be clear</td></tr><tr><td>STUDENT_ID</td><td>Customer Proof of Address, must be within 90 days to be accepted</td></tr><tr><td>PASSPORT_CARD_ID</td><td>Passport Identification Card</td></tr><tr><td>MILITARY_ID</td><td>Military Identification Card</td></tr><tr><td>PUBLIC_SAFETY_ID</td><td>Public Safety Identification Card</td></tr><tr><td>HEALTH_ID</td><td>Health Identification Card</td></tr><tr><td>OTHER_ID</td><td>Other Identification Card</td></tr><tr><td>VISA</td><td>Visa Identification Card</td></tr><tr><td>REGULAR_DRIVING_LICENSE</td><td>Use when DocumentType is DRIVING_LICENSE, for regular drivers license</td></tr><tr><td>LEARNING_DRIVING_LICENSE</td><td>Use when DocumentType is DRIVING_LICENSE, for learners drivers license or permit</td></tr><tr><td>E_PASSPORT</td><td>Use when DocumentType is PASSPORT</td></tr></tbody></table>

#### Decision Results

| Name          | Description                                  |
| ------------- | -------------------------------------------- |
| NOT\_EXECUTED | ID Verification Workflow not executed        |
| PASSED        | ID Verification Workflow Passed Successfully |
| REJECTED      | ID Verification was Rejected                 |
| WARNING       | ID Verification completed with warning       |

### Request Payload Example

```json
{
    "bUseJumio": false,
    "customerReference": "your-customer-reference-1234",
    "email": "user.email@ibanera.com",
    "firstName":"John",
    "lastName": "Doe",
    "dob": "1995-01-15",
    "phone": "+18001234567",
    "address": {
        "line1": "123 Main St",
        "line2": "Unit 1A",
        "city": "City",
        "state": "TX",
        "postcode": "12345",
        "countryISO": "US"
    },
    "nationalityISO": "US",
    "bAcceptTermsAndConditions": true,
    "bAcceptPrivacyPolicy": true,
    "kycVerificationDetails": {
        "documentType": "ID_CARD",
        "subType": "NATIONAL_ID",
        "issuingCountry": "USA",
        "firstName": "JOHN",
        "lastName": "DOE",
        "dateOfBirth": "1995-01-15",
        "expiryDate": "2028-01-15",
        "documentNumber": "1234567890",
        "gender": "M",
        "workFlowDecisionResult": "PASSED", // "PASSED" means that the IDv solution confirmed the identity
        "capabilities": {
            "liveLinessDecisionResult": "PASSED", // "PASSED" means liveliness was checked and passed
            "similarityDecisionResult": "PASSED" // "PASSED" means similarity checks between selfie and ID document was checked and passed
        }
    }
}
```

Once submitted successfully, the API will respond with the `kycDocumentsRequired` to complete the onboarding. These documents can be submitted via the Upload Document endpoint below.

#### Response Payload (Success Example)

```json
{
    "id": 3044,
    "details": {
        "customersId": 15070,
        "kycDocumentsRequired": [
            {
                "type": "ID_CARD",
                "supportingDocumentTypes": null,
                "sidesRequired": [
                    "Front",
                    "Back"
                ]
            },
            {
                "type": "SELFIE",
                "supportingDocumentTypes": null,
                "sidesRequired": [
                    "Face"
                ]
            }
        ]
    },
    "status": "1",
    "errors": []
}
```

#### Response Payload (Failure Example)

```json
{
    "id": 0,
    "details": null,
    "status": "0",
    "errors": [
        {
            "fieldName": "ErrorLabel",
            "messageCode": "User already exists"
        }
    ]
}
```

***

## Upload Documents (For QuickBuy Customer Onboarding)

Upload individual KYC documents (e.g., ID Front, ID Back, Face Photo) associated with the Customer Id received from Step 1.

***

* **Endpoint**: POST `/api/v1/customer/quick-buy/uploaddocument`
* **Request Format**: `multipart/form-data`

***

Validation:

* **Max allowed file size**: 10 MB
* **Only image/PDF formats allowed.**

***

📄 **Request Payload**

| **Parameter**    | **Type** | **Description**                                                           |
| ---------------- | -------- | ------------------------------------------------------------------------- |
| **CustomerId**   | int      | Unique identifier of the customer, obtained from onboard endpoint         |
| **Type**         | enum     | Type of document being uploaded, obtained from result of onboard endpoint |
| **DocumentSide** | enum     | Side of the document (e.g., Front, Back, Face)                            |
| **File**         | file     | The document file to be uploaded                                          |

#### <kbd>Type</kbd> Enumeration Values

<table><thead><tr><th width="154.8125">Name</th><th>Description</th></tr></thead><tbody><tr><td>Front</td><td>Front side of Identification Document</td></tr><tr><td>Back</td><td>Back side of Identification Document</td></tr><tr><td>Face</td><td>Selfie of customer</td></tr></tbody></table>

#### Response Payload (Success Example)

```json
{
    "id": 0,
    "details": {
        "bSuccess": true,
        "documentID": "912afb60-fe22-4634-9428-54d5e5ebf3e1"
    },
    "status": "1",
    "errors": []
}
```

***

**Response Payload (Failure Example)**

```json
{
    "id": 0,
    "status": "0",
    "errors": [
        {
            "fieldName": "CustomerId",
            "messageCode": "CustomerId is required"
        }
    ]
}
```

***

## List Cards

Retrieve a list of payment cards associated with a customer

* **Endpoint:** `/api/v1/customer/quick-buy/cards/list`
* **Method:** `GET`

{% openapi src="/files/h5NAeoFyfsXzFQlbLTLb" path="/api/v1/customer/quick-buy/cards/list" method="get" %}
[public-api-customer-role (2).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-45eb0e19300a8551d834f5aa05923e6506ffd44e%2Fpublic-api-customer-role%20\(2\).json?alt=media)
{% endopenapi %}

#### Request Query Example

```url
{{endpoint}}/api/v1/customer/quick-buy/cards/list?customersId=14349
```

#### Response Body Example

```json
{
    "id": 0,
    "details": [
        {
            "id": 1227,
            "cardholderName": "John Doe",
            "cardDescription": "ECMC...0004",
            "cardType": "ECMC_CREDIT",
            "cardLast4Digits": "0004",
            "expiryDate": null
        }
    ],
    "status": "1",
    "errors": []
}
```

***

## Get Card by ID

Enables a user to retrieve information about a payment card by submitting the ID of the payment card.

* **Endpoint:** `/api/v1/customer/quick-buy/cards/getbyid`
* **Method:** `GET`

{% openapi src="/files/h5NAeoFyfsXzFQlbLTLb" path="/api/v1/customer/quick-buy/cards/getbyid" method="get" %}
[public-api-customer-role (2).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-45eb0e19300a8551d834f5aa05923e6506ffd44e%2Fpublic-api-customer-role%20\(2\).json?alt=media)
{% endopenapi %}

Request Query Example

```url
{{endpoint}}/api/v1/customer/quick-buy/cards/getbyid?customersId=14349&paymentCardsId=1229
```

#### Response Body Example

```json
{
    "id": 0,
    "details": {
        "id": 1229,
        "cardholderName": "John Doe",
        "cardDescription": "VISA...1111",
        "cardType": "VISA_CREDIT",
        "cardLast4Digits": "1111",
        "expiryDate": "2025-12-31T00:00:00"
    },
    "status": "1",
    "errors": []
}
```

***

## Delete Card

Allows a user to delete a payment card, removing it from being an option for further exchanges.

* **Endpoint:** `/api/v1/customer/quick-buy/cards/delete`
* **Method:** `POST`

{% openapi src="/files/h5NAeoFyfsXzFQlbLTLb" path="/api/v1/customer/quick-buy/cards/delete" method="post" %}
[public-api-customer-role (2).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-45eb0e19300a8551d834f5aa05923e6506ffd44e%2Fpublic-api-customer-role%20\(2\).json?alt=media)
{% endopenapi %}

#### Request Query Example

```url
{{endpoint}}/api/v1/customer/quick-buy/cards/delete?customersId=14349&paymentCardsId=1226
```

#### Response Body Example

```json
{
    "id": 1226,
    "status": "1",
    "errors": []
}
```

***

## Get Available Asset Pairs

Provides a list of asset pairs enabled for the API user and available for quick buy. The response will also include information on limits and minimums associated with each asset pair for exchanges.

* **Endpoint:** `/api/v1/customer/quick-buy/orders/assets`
* **Method:** `GE`

{% openapi src="/files/h5NAeoFyfsXzFQlbLTLb" path="/api/v1/customer/quick-buy/orders/assets" method="get" %}
[public-api-customer-role (2).json](https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-45eb0e19300a8551d834f5aa05923e6506ffd44e%2Fpublic-api-customer-role%20\(2\).json?alt=media)
{% endopenapi %}

#### Request Query Example

```url
{{endpoint}}/api/v1/customer/quick-buy/orders/assets
```

#### Response Body Example

```json
{
    "id": 0,
    "details": [
        {
            "assetCode": "BTC",
            "assetSymbol": "₿",
            "assetName": "Bitcoin",
            "buyPrice": 67466.800000000000000000,
            "minAmount": 0.000100000000000000,
            "maxAmount": 10.000000000000000000,
            "minPrice": 15.000000000000000000,
            "maxPrice": 200000.000000000000000000,
            "maxDecimalPrecision": 0
        }
    ],
    "status": "1",
    "errors": []
}
```

***

## Get Quote

This endpoint provides a quoted market price for a proposed asset exchange for a particular customer, detailing the amount and price for an exchange. By specifying details of the desired trade, a customer can see the cost or proceeds they might expect from completing a transaction, including any applicable fees. This helps customers decide whether to proceed with an exchange based on real-time financial data. For quick buy exchanges, all exchanges will refer to the specified crypto currency being bought in exchange for fiat currency.

* **Endpoint:** `/api/v2/customer/quick-buy/orders/quote`
* **Method:** GET

**Query Parameters:**

* `customersId` (Integer): ID of the customer making the exchange—required.
* `assetCode` (String): The crypto currency to be bought, such as "BTC"—required.
* `assetAmount` (Decimal, Nullable): Desired amount of crypto currency to be bought. Must be null if currencyAmount is specified.
* `currenyAmount` (Decimal, Nullable): Desired amount of currency to be exchanged. Must be null if assetAmount is specified.
* `currencyCode` (String): The fiat currency to acquire a payment in. (USD or EUR)

**Response Body Parameters:**

* `id` (Integer): Not used.
* `details` (Object): Contains the quote details.
  * `customersId` (Integer): ID of the customer.
  * `assetCode` (String): Crypto currency asset to be bought in the exchange.
  * `currenyCode` (String): Fiat currency asset involved in the exchange.
  * `assetAmount` (Decimal): Amount of crypto currency asset to be bought.
  * `currencyAmount` (Decimal): Amount of fiat currency required for exchange.

#### Request Query Example

```url
{{endpoint}}/api/v2/customer/quick-buy/orders/quote?customersId=14349&AssetCode=BTC&CurrencyCode=USD&CurrencyAmount=100
```

#### Response Body Example

```json
{
    "id": 14349,
    "details": {
        "customersId": 14349,
        "assetCode": "BTC",
        "currencyCode": "USD",
        "assetAmount": 0.00705853,
        "currencyAmount": 500.0
    },
    "status": "1",
    "errors": []
}
```

#### Possible Error Codes

| Error Message Code         | Description                                                       |
| -------------------------- | ----------------------------------------------------------------- |
| Required                   | Named field 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 |
| Amount\_Must\_Be\_Positive | Invalid or missing amount                                         |

***

## Submit Exchange

This endpoint is intended for initiating a quick buy exchange, enabling a customer to purchase an asset at a specified price.

**This API endpoint will capture payment details and return a `VerificationURL` (3D Secure). The order will only be processed once the `VerificationURL` is accessed on the client's device.**

* **Endpoint:** `/api/v2/customer/quick-buy/orders/submit`
* **Method:** `POST`

**Request Body Parameters:**

* `customersId` (Integer): ID of the customer making the exchange—required.
* `currencyCode` (String): The fiat currency to be spent. ("USD" or "EUR")
* `assetCode` (String): The crypto currency to be bought, such as "BTC"—required.
* `assetAmount` (Decimal, Required): Desired amount of crypto currency to be bought.
* `currenyAmount` (Decimal, Required): Desired amount of currency to be exchanged.
* `paymentRedirectUrl` (String, Required): URL of the website that the user will be redirected to once they access the verification URL.
* `paymentCardsId` (Integer, Nullable): Id of saved payment card. Must be null if CardDetails is not null.
* `cardDetails` (JSON Object): Details of payment card. Must be null if paymentCardsId is not null.
  * `cardNumber` (String, Required): Card number.
  * `cvv` (String, Required): Card CVV
  * `cardHolderName` (String, Required): Cardholder name.
  * `addressLine1` (String, Required): Cardholder address line 1.
  * `addressLine2` (String): Cardholder address line 2.
  * `townCity` (String, Required): Cardholder town or city.
  * `countryISO2` (String, Required): Cardholder country of address.
  * `stateProvince` (String, Required): Cardholder state or province.
  * `postCode` (String, Required): Cardholder ZIP/Postal Code.
  * `expMonth` (Integer, Required): Card expiration month.
  * `expYear` (Integer, Required): Card expiration year.
  * `bSaveCard` (Boolean, Required): Indicates whether the payment card should be saved.
  * `EmailAddress` (String, Required): The email address associated with the card holder.
  * `PhoneNumber` (String, Required): The phone number associated with the card holder. Must include the numeric country code (Example: +1 for USA).

**Request Example:**

```json
{
    "customersId": 14349,
    "assetCode": "BTC",
    "currencyCode": "USD",
    "assetAmount": 0.00718246,
    "currencyAmount": 500,
    "paymentRedirectUrl": "https://ibanera.com", // URL where the user will be redirected after verification
    "paymentCardsId": null,
    "cardDetails": {
        "cardNumber": "4111111111111111",
        "cvv": "123",
        "cardholderName": "John Doe",
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "townCity": "Springfield",
        "countryISO2": "US",
        "stateProvince": "IL",
        "postCode": "62704",
        "expMonth": 12,
        "expYear": 2025,
        "bSaveCard": true,
        "EmailAddress": "your-email@ibanera.com",
        "PhoneNumber": "+18001234567"
    }
}
```

**Response Body Parameters:**

* `id` (Integer): Not used.
* `details` (Object):
  * `status` (String): The status of the transaction, such as "Pending".
    * Possible values: `Pending`, `Failed`, `Approved`, `ActionRequired`.
  * `exchangesId`(Integer): The ID of the associated asset exchange.

**Success Response Example:**

Note that an order is only processed once the `verificationURL` is accessed from the client device!

```json
{
    "id": 0,
    "details": {
        "status": "ActionRequired",
        "exchangesId": 14483,
        "verificationURL": "https://ggapi.ibanera.com/secure/start?hash=4dg..."
    },
    "status": "1",
    "errors": []
}
```

#### Getting Order Status

Upon accessing the `verificationURL` from the client device, the order will be processed. The `verificationURL` will then redirect to the `paymentRedirectUrl` provided in your request body.

When the system redirects the user to the provided `paymentRedirectUrl`, the URL will also include a URL parameter to indicate the status of the order.

{% code title="Redirect URL example, with sample status" %}

```url
https://ibanera.com/?status=AUTHORISED
```

{% endcode %}

#### Order Statuses

<table><thead><tr><th width="191.015625">Status</th><th>Description</th></tr></thead><tbody><tr><td>AUTHORISED</td><td>Card was successfully authorized, order will complete once captured (within minutes)</td></tr><tr><td>REFUSED</td><td>Card was refused / declined by card issuer</td></tr><tr><td>FAILED</td><td>Failed attempt, please try again or contact us</td></tr><tr><td>CAPTURED</td><td>Card was successfully captured, order will proceed</td></tr><tr><td>CANCELLED</td><td>Payment was cancelled. Order will reverse.</td></tr><tr><td>REFUNDED</td><td>Payment was refunded</td></tr></tbody></table>

#### Card Decline Response Example:

```json
{
    "id": 0,
    "details": {
        "status": "Failed",
        "message": "Decline reason would be here..."
    },
    "status": "1",
    "errors": []
}
```

#### Possible Error Codes

| Error Message Code       | Description                                                       |
| ------------------------ | ----------------------------------------------------------------- |
| Required                 | Named field 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 |

***

## List Exchanges

Provides a system generated list of quick buy exchanges, with ability to filter by the the customersID or asset pair.

* **Endpoint:** `/api/v1/customer/quick-buy/orders/list`
* **Method:** `GET`

#### Request Query

**Optional Request Query Parameters:**

* `customersId` (Integer): The ID of the customer initiating the purchase.
* `assetPair` (String): The asset pair to be filtered, such as "BTC/USDC".
* `PageNumber` (Integer): List page number (default = 1)
* `PageSize` (Integer): List page size (default = 10)

#### Request Query Example

```url
{{endpoint}}/api/v1/customer/quick-buy/orders/list?customersId=14349
```

#### Response Body Example

<pre class="language-json"><code class="lang-json">
{
    "id": 1777,
    "details": [
        {
            "id": 14487,
            "exchangeType": "Buy",
            "status": "Completed", // Indicates the status of the order
            "paymentStatus": "CAPTURED", // Indicates the status of the card payment
            "creditTransactionsId": 79311,
            "customersId": 14349,
            "assetPair": "BTC/USD",
            "requestAmount": 0.007113640000000000,
            "requestPrice": 500.000000000000000000,
            "executedAmount": 0.007144470000000000,
            "executedPrice": 500.000000000000000000,
            "commissionFee": 21.530000000000000000,
            "transferType": null,
            "bHasOpenRfi": false,
            "paymentCardsId": 1229,
            "cardDescription": "VISA...1111"
        },
        {
            "id": 14484,
            "exchangeType": "Buy",
            "status": "Pending",
            "paymentStatus": "AUTHORISED",
            "creditTransactionsId": 78928,
            "customersId": 14349,
            "assetPair": "BTC/USD",
            "requestAmount": 0.007080710000000000,
            "requestPrice": 500.000000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 21.530000000000000000,
            "transferType": null,
            "bHasOpenRfi": false,
            "paymentCardsId": 1229,
            "cardDescription": "VISA...1111"
<strong>        }
</strong>    ],
    "pageSize": 10,
    "pageNumber": 1,
    "numberOfPages": 2,
    "status": "1",
    "errors": []
}
</code></pre>

***

## Get Order by Id

Provides a system generated list of quick buy exchanges, with ability to filter by the the customersID or asset pair.

* **Endpoint:** `/api/v1/customer/quick-buy/orders/getbyid`
* **Method:** `GET`

#### Request Query

**Optional Request Query Parameters:**

* `customersId` (Integer): The ID of the customer initiating the purchase.
* `assetPair` (String): The asset pair to be filtered, such as "BTC/USDC".
* `PageNumber` (Integer): List page number (default = 1)
* `PageSize` (Integer): List page size (default = 10)

#### Request Query Example

```url
{{endpoint}}/api/v1/customer/quick-buy/orders/getbyid?exchangesId=14468
```

#### Response Body Example

```json
{
    "id": 1777,
    "details": {
        "id": 14468,
        "exchangeType": "Buy",
        "status": "Completed", // Indicates the status of the order
        "paymentStatus": "CAPTURED", // Indicates the status of the card payment
        "creditTransactionsId": 76573,
        "customersId": 14349,
        "assetPair": "BTC/USD",
        "requestAmount": 0.007186150000000000,
        "requestPrice": 500.000000000000000000,
        "executedAmount": 0.007211890000000000,
        "executedPrice": 500.000000000000000000,
        "commissionFee": 21.530000000000000000,
        "transferType": null,
        "bHasOpenRfi": false,
        "paymentCardsId": 1226,
        "cardDescription": "VISA...1111"
    },
    "status": "1",
    "errors": []
}
```

#### Payment Status Definitions

<table><thead><tr><th width="191.015625">Status</th><th>Description</th></tr></thead><tbody><tr><td>AUTHORISED</td><td>Card was successfully authorized, order will complete once captured (within minutes)</td></tr><tr><td>REFUSED</td><td>Card was refused / declined by card issuer</td></tr><tr><td>FAILED</td><td>Failed attempt, please try again or contact us</td></tr><tr><td>CAPTURED</td><td>Card was successfully captured, order will proceed</td></tr><tr><td>CANCELLED</td><td>Payment was cancelled. Order will reverse.</td></tr><tr><td>REFUNDED</td><td>Payment was refunded</td></tr></tbody></table>


# Simulated Testing

## Overview

The Simulations module of the Customer API is a component designed to simulate events. This module is only available in our sandbox environment and features one primary API endpoint at this time:

## Simulate Deposit

This endpoint enables an API user to simulate a deposit to a specified customer account under the API's control.

* **Endpoint**: `/api/v1/customer/simulations/payins`
* **Method**: `POST`

**JSON Request Body Parameters:**

<table><thead><tr><th width="218">Parameter Name</th><th width="129">Type</th><th>Description</th></tr></thead><tbody><tr><td>DestinationAccountId</td><td>Integer</td><td>Account ID to simulate deposit to</td></tr><tr><td>TransferType</td><td>String</td><td><p>Possible Values:</p><p>(US Domestic Account)</p><p><strong>ACH</strong></p><p><strong>WIRE</strong></p><p>(International Account)</p><p><strong>SWIFT</strong></p></td></tr><tr><td>Amount</td><td>Decimal</td><td>Amount to deposit</td></tr><tr><td>Name</td><td>String</td><td>Destination account holder name (optional)</td></tr><tr><td>Reference</td><td>String</td><td><p>Reference message to be sent.</p><p>Required for FBO/Pooled accounts, otherwise optional.</p></td></tr></tbody></table>

**Request Body Example (JSON)**

```json
{
    "DestinationAccountId": 1001,
    "TransferType": "ACH",
    "Amount": 5,
    "Name": "Customer Name",
    "Reference": "1234567890"
}
```

**Success Response Example (JSON)**

```json
{
    "id": 0,
    "status": "1",
    "errors": []
}
```


# Callbacks

## Overview

Webhook callbacks can be enabled for customers to receive updated on accounts, transactions and exchanges as they happen. To do so please contact the support team and provide a callback URL you with to use for it. You will be provided with a hash secret for authenticating callbacks.

Callback requests have the following properties:

* Content type is of type `application/json`.
* It will contain `webhook-signature` header. It is generated by using a SHA256 hashing algorithm on a concatenated string of `requestBody + hashSecret`. Use the hash secret provided to you to verify the authenticity of the request before processing it.
* It's content will contain a JSON object with following fields:
  * Id - GUID for the request.
  * Type–Callback type code indicating what type of event has occurred.
  * Data (object): containing details about the event. Details depend on the event type.
* A 200 HTTP response code is expected. If a different response is returned, the request will be retried with exponential backoff for 2 hours.

### [Continue to the next page for information on Callback Types and Formatting](/callbacks/fiat-deposit-received)


# Managee Jumio Completed

## Overview

This callback is sent when a customer under management has completed the Jumio KYC process. Once the Jumio process is complete, the account will reviewed by Ibanera's compliance team. Prior to receieving this callback, a manager can prompt a new customer to complete the Jumio process by accessing the [`jumioLink` from creating a managee](/api-endpoints/managees#create-a-managee-v2).

## Data Object

<table><thead><tr><th width="260">Field</th><th>Description</th></tr></thead><tbody><tr><td>ManageesId</td><td>Id of the managee / Customer</td></tr><tr><td>ManageeCustomerUsersId</td><td><p>ID of the CustomerUser that completed Jumio. A <strong>Customer</strong> represents the account entity, whereas a <strong>CustomerUser</strong> represents a singular user that is linked to a <strong>Customer.</strong></p><p>Accounts for personal customers will only have one CustomerUser per Customer.</p><p>Accounts for Businesses, may have several CustomerUser per Customer, where the Customer represents the Business, and the CustomerUser represents a user that can access the Business account.</p></td></tr><tr><td>DateJumioCompleted</td><td>Date of Jumio Completion</td></tr></tbody></table>

## Data Example

```json
{
      "Id":"8b3291e8-633a-4aa0-a548-61b479dde915",
      "Type":"MANAGEE_JUMIO_COMPLETED",
      "Data":
            {
                  "ManageesId":14017,
                  "ManageeCustomerUsersId":14040,
                  "DateJumioCompleted":"2024-04-04T15:41:52.15"
            }
}
```


# Cryptocurrency Transfers

### Overview

Callbacks for cryptocurrency transfers can be categorized into four different notification types:

* `CRYPTO_DEPOSIT_CREATED`
* `CRYPTO_DEPOSIT_UPDATED`
* `CRYPTO_WITHDRAWAL_CREATED`
* `CRYPTO_WITHDRAWAL_UPDATED`

All four notifications have the same data field form. These notifications are sent when a cryptocurrency deposit is received, when a withdrawal is created or when either of the two is updated.

The status field describes the state of the transfer and can be any of the following values:

* `Pending`
* `Frozen`
* `Failed`
* `Completed`

`Failed` and `Completed` are both terminal states. Deposits will be Frozen if they don’t pass AML checks.

### Data Object:

| Field                 | Description                                |
| --------------------- | ------------------------------------------ |
| AccountsId            | Associated account Id (will be deprecated) |
| TransactionsId        | Associated transaction Id                  |
| SourceAccountsId      | Associated source account                  |
| DestinationAccountsId | Associated destination account             |
| TransactionHash       | Transaction hash                           |
| SourceAddress         | Transfer source address                    |
| DestinationAddress    | Transfer destination address               |
| Amount.Asset          | Asset code                                 |
| Amount.Amount         | Amount deposited or withdrawn              |
| NetworkFee.Asset      | Network fee asset code                     |
| NetworkFee.Amount     | Network fee amount                         |
| Status                | Transfer status                            |

### Data Example

```json
{
    "Id": "1772fe26-f6b3-497c-9ab6-fe2f7929aaff",
    "Type": "CRYPTO DEPOSIT CREATED"
    "Data": {
        "AccountsId": 1598,
        "TransactionsId": 13339,
        "SourceAccountsId": 1598,
        "DestinationAccountsId": 1688,
        "TransactionHash": "Oxd04631fa738e60209a4814d2699205768c1441aea490f4cb1adf5e2ce53cf367"
        "SourceAddress": "Ox75C0c372da875a4Fc78E8A37f58618a6D18904e8"
        "DestinationAddress": "OxB8a10b113f13fA0C51a6a8d9a121a4c0bfb52154"
        "Amount": {
        "Asset": "USDC"
        "Amount": 1.0
        },
        "NetworkFee":{
            "Asset": "ETH"
            "Amount": 0.000008518119213712
        },
        "Status": "Pending"
    }
}
```


# Exchange Status Updated

## Overview

When this event occurs, the provided callback URL will receive a JSON-formatted message with the above details. If the application successfully receives the webhook, it should respond with a 200 HTTP status code; otherwise, the banking platform will retry sending the message for a certain period.

For developers, it's important to manage these callbacks properly, including validating the received messages using the provided secret, to ensure proper synchronization between the banking platform and the application.

Possible exchange status values:

* `WaitingForApproval`
* `Rejected`
* `WaitingForConfirmation`
* `AwaitingRfi`
* `Pending`
* `Completed`
* `Failed`

## Callback Request Parameters

* `Id` is the unique identifier for the exchange transaction.
* `ExchangeType` represents whether the exchange is a buy or sell transaction. (Buy, Sell)
* `Status` indicates the current status of the exchange (e.g., Pending, Completed, Failed).
* `FromTransactionsId` and `ToTransactionsId` are identifiers for the respective transactions involved in the exchange.
* `ManageesId` is the identifier for the individual or entity on whose behalf the exchange is being conducted.
* `AssetPair` is a string represents the currency pair being exchanged.
* `RequestAmount` and `RequestPrice` refer to the amount and price requested for the exchange.
* `ExecutedAmount` and `ExecutedPrice` are the actual executed amount and price after the exchange is completed.
* `CommissionFee` is any applicable fee for conducting the exchange.
* `PayeesId` represents the payee's Id.
* `TransferType` - Transfer type if payees Id is not null
* `bHasOpenRfi` is a flag indicating if request for information is pending to be submitted
* `FromCustomerAssetAccountId` and `ToCustomerAssetAccountId` are account identifiers involved in the exchange.

### Callback Example

<pre class="language-json"><code class="lang-json">{ 
    "Id": "f9b5e465-69b5-4c6d-91c2-fb4dd64d4d20", 
    "Type": "EXCHANGE_STATUS_UPDATED",
<strong>    "Data": {
</strong>        "Id": 11669,
        "ExchangeType": 0,
        "Status": "Completed", 
        "FromTransactionsId": 13471, 
        "ToTransactionsId": 13473, 
        "ManageesId": 1436,
        "AssetPair": "USDC/USD", 
        "RequestAmount": 24.75, 
        "RequestPrice": 25, 
        "ExecutedAmount": 24.75, 
        "ExecutedPrice": null, 
        "CommissionFee": 0.12,
        "PayeesId": null,
        "TransferType": null, 
        "bHasOpenRfi": true, 
        "FromCustomerAssetAccountId": 1184,
<strong>    }
</strong>}
</code></pre>


# Fiat Deposit Received

## Overview

When this event occurs, the provided callback URL will receive a JSON-formatted message with the above details. If the application successfully receives the webhook, it should respond with a 200 HTTP status code; otherwise, the banking platform will retry sending the message for a certain period.

For developers, it's important to manage these callbacks properly, including validating the received messages using the provided secret, to ensure proper synchronization between the banking platform and the application.

## Callback Request Parameters

| Field                       | Description                                                                                                                                                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AccountId                   | Receiving account Id                                                                                                                                                                                                                |
| TransactionId               | Associated transaction Id                                                                                                                                                                                                           |
| Reference                   | Deposit reference                                                                                                                                                                                                                   |
| SenderDetails.RoutingNumber | Sender routing number                                                                                                                                                                                                               |
| SenderDetails.AccountNumber | Sender account number                                                                                                                                                                                                               |
| SenderDetails.Name          | Sender name                                                                                                                                                                                                                         |
| SenderDetails.AddressLine1  | Sender address line 1                                                                                                                                                                                                               |
| SenderDetails.AddressLine2  | Sender address line 2                                                                                                                                                                                                               |
| SenderDetails.AddressLine3  | Sender address line 3                                                                                                                                                                                                               |
| Amount                      | Amount deposited                                                                                                                                                                                                                    |
| Imad                        | Transfer IMAD number                                                                                                                                                                                                                |
| Date                        | Transfer date                                                                                                                                                                                                                       |
| bReversal                   | True when a transaction is a refund for a existing transaction on the platform. In this case, **`OriginalTransactionsId`** will contain the ID of the original transaction                                                          |
| OriginalTransactionsId      | In cases where the fiat deposit represents a refund, this field will contain the ID of the original transaction.                                                                                                                    |
| bFlagged                    | True when a transaction is flagged. Inbound transactions may be flagged by our compliance system. If this value is true, you can expect to receive a TRANSACTION\_STATUS\_UPDATED regarding updated status once a decision is made. |

### Callback Example

**Standard Deposit Example**

```json
{
    "Id": "022afa7a-25e1-4a96-9273-eca3a5dd657f"
    "Type": "FIAT_DEPOSIT_RECEIVED"
    "Data":{
        "AccountsId": 1601,
        "TransactionsId": 13470,
        "OriginalTransactionsId": null,
        "Reference": "ExampleRef"
        "SenderDetails":{
            "RoutingNumber": "011000000",
            "AccountNumber": "0123456789",
            "Name": "Name Surname",
            "AddressLinel": "Address Line 1"
            "AddressLine2": "Address Line 2",
            "AddressLine3": null
        },
        "Amount": 25,
        "Imad": "7679117526335469481169"
        "Date": "2022-08-24713:39:37.72+00:00",
        "bReversal": false,
        "bFlagged": false
    }
}
```

**Refund Deposit Example**

```json
{
    "Id": "13590b4f-c190-4a5e-9438-16400aa3b53e",
    "Type": "FIAT_DEPOSIT_RECEIVED",
    "Data": {
        "AccountsId": 4116,
        "TransactionsId": 81878,
        "OriginalTransactionsId": 81877,
        "Reference": "Refund",
        "SenderDetails": null,
        "Amount": 1.230000000000000000,
        "Imad": null,
        "Date": "2024-08-02T16:28:12.0766667+00:00",
        "bReversal": true,
        "bFlagged": false
    }
}
```

### Retrieving Further Information

Once a Fiat Deposit has been received, you can utilize the [Get Transaction Details](/api-endpoints/accounts#get-transaction-details) endpoint to retrieve further information for a particular transaction. You can do so by utilizing the `Data.TransactionsId` value provided in this FIAT\_DEPOSIT\_RECIEVED callback.

You can also access account balances by accessing the [Get Asset Account by ID](/api-endpoints/accounts#get-asset-account-by-id) endpoint. This endpoint will accept the `Data.AccountsId` value, which corresponds to the ID of the account.


# Managee Card Approval Updated

## Overview

Sent when the top-up card assigned to a managee is approved or rejected by a manager or by a site admin.

## Data Object

<table><thead><tr><th width="260">Field</th><th>Description</th></tr></thead><tbody><tr><td>TopUpCardsId</td><td>Id of the updated card if the card has been created.</td></tr><tr><td>RequestedTopUpCardsId</td><td>Id of the updated card request if card creation was subject to deferred approval.</td></tr><tr><td>Status</td><td><p>Status of the card approval. One of</p><p>• “Approved”</p><p>• “Rejected”</p></td></tr><tr><td>bManuallyUpdated</td><td>Boolean. True if the approval/rejection was performed by manager or admin intervention, else false.</td></tr></tbody></table>

## Data Example

```json
{
        "Id": "2c58ed48-67d2-4d8e-bbb1-548864773d2c", 
        "Type": " MANAGEE_CARD_APPROVAL_UPDATED", 
        "Data": {
                "TopUpCardsId": 1000,
                "RequestedTopUpCardsId": 1000, 
                "Status": "Approved", 
                "bManuallyUpdated": true
        } 
}
```


# Managee KYC Updated

## Overview

Sent when the data submitted to create a managee is accepted or rejected. When the data provided is approved, the managee will be able to transact. Before this time most functionality will be disabled for the managee.

If managee data is rejected, they will not be allowed to transact. This is currently a final state, and you should check the data and retry by creating a new managee, or contact support.

## Data Object

<table><thead><tr><th width="260">Field</th><th>Description</th></tr></thead><tbody><tr><td>ManageesId</td><td>Id of the updated managee</td></tr><tr><td>VerificationStatus</td><td>New status: “Accepted” or “Rejected”</td></tr><tr><td>AcceptDate</td><td>Date of acceptance, or null</td></tr><tr><td>RejectDate</td><td>Date of rejection, or null</td></tr><tr><td>RejectReason</td><td>Reason for rejection, or null</td></tr></tbody></table>

## Data Example

```json
{
    "Id": "2c58ed48-67d2-4d8e-bbb1-548864773d2c", 
    "Type": "MANAGEE_KYC_UPDATED",
    "Data": {
        "ManageesId": 11049, 
        "VerificationStatus": "Accepted", 
        "AcceptDate": "2023-01-31T15:06:38.963", 
        "RejectReason": null,
        "RejectDate": null
    } 
}
```


# Transaction Status Updated

## Overview

Sent when an outbound transfer (Wire or ACH) status changed or when comply advantage approved a pending screening.

## Data Object

<table><thead><tr><th width="260">Field</th><th>Description</th></tr></thead><tbody><tr><td>Id</td><td>Transaction Id</td></tr><tr><td>AccountsId</td><td>Transaction account Id</td></tr><tr><td>FromTransactionsId</td><td>Nullable linked from transaction Id</td></tr><tr><td>FromAccountsId</td><td>Nullable linked from account Id</td></tr><tr><td>ToTransactionsId</td><td>Nullable linked to transaction Id</td></tr><tr><td>ToAccountsId</td><td>Nullable linked to account Id</td></tr><tr><td>RollbackTransactionsID</td><td>In cases where a transaction is rejected, failed, or refunded, this field will contain the ID of the refund transaction</td></tr><tr><td>Amount</td><td>Transaction amount</td></tr><tr><td>Description</td><td>Transaction description</td></tr><tr><td>DateTime</td><td>Transaction date</td></tr><tr><td>bPending</td><td>True when transaction is pending</td></tr><tr><td>bCompleted</td><td>True when the transaction is completed successfully</td></tr><tr><td>bRejected</td><td>True when a transaction is Rejected. When a transaction is rejected, it will be refunded. The transaction ID of the refund is found in <strong><code>RollbackTransactionsId</code></strong></td></tr></tbody></table>

## Data Example

#### Completed Example

```json
{
        "Id": "53105295-5905-41e6-ad16-b5dea5c0f2ad",
        "Type": "TRANSACTION_STATUS_UPDATED"
        "Data": {
                "Id": 19605,
                "AccountsId": 2001,
                "FromTransactionsId": null,
                "FromAccountsId": null,
                "ToTransactionsId": null,
                "ToAccountsId": null,
                "RollbackTransactionsId": null,
                "Amount": -100,
                "Description": "External transfer - Payment from Test Account",
                "DateTime": "2023-10-16T14:14:44.43+00:00",
                "bPending": false,
                "bCompleted": true,
                "bRejected": false
        }
}
```

#### Rejected Example

```json
{
        "Id": "53105295-5905-41e6-ad16-b5dea5c0f2ad",
        "Type": "TRANSACTION_STATUS_UPDATED"
        "Data": {
                "Id": 19605,
                "AccountsId": 2001,
                "FromTransactionsId": null,
                "FromAccountsId": null,
                "ToTransactionsId": null,
                "ToAccountsId": null,
                "RollbackTransactionsId": 10001,
                "Amount": -100,
                "Description": "External transfer - Payment from Test Account",
                "DateTime": "2023-10-16T14:14:44.43+00:00",
                "bPending": false,
                "bCompleted": false,
                "bRejected": true
        }
}
```


# Information Requests

## Information Requested Callback

#### Callback Request Parameters

* `Id:` is the unique identifier for the exchange transaction.
* `Type:`“INFORMATION\_REQUESTED” when more information is required
* `CustomerId:` int

#### Callback Example

```json
{
        "Id":"706fdb74-08cc-4954-a67c-17b4e2163419",
        "Type": "INFORMATION_REQUESTED",
        "Data": {
                "CustomersId":2464,
                "UpdatedInformationRequestIds": "1013"
          }
}
```

## Information Request Updated Callback

* `Id:` is the unique identifier for the exchange transaction.
* `Type:` “INFORMATION\_REQUEST\_UPDATED” when the information response is approved
* `CustomerId`: int

Callback Example:

```json
{
        "Id":"386cf6ed-e858-4bb9-b107-1bebfa82f980",
        "Type":"INFORMATION_REQUEST_UPDATED",
        "Data":{
                "CustomersId":2464,
                "UpdatedInformationRequestIds": "1013"
        }
} 
```


# QuickBuy

<figure><img src="https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-cd97de7650f7c0b7bc40891a990ed3c5d1bf9543%2FQuickBuyV2.png?alt=media" alt=""><figcaption><p>QuickBuy V2</p></figcaption></figure>

### Overview

Embedding the QuickBuy Widget into your site or app provides your customers with a convenient way to make payments to your crypto wallets, or their own, using their credit or debit cards.

### Integration steps

* When signing up to host the widget you should provide us with the URLs for the webhook detailed below and also the URL’s of the pages you wish to host the widget on for us to white list.
* You will be provided with an API key, and a shared secret, which you should store securely.
* Embed the widget Javascript in your page, and provide it with the required data when

  serving the page (including the API key, CustomerID, and a signature token for the

  transaction).
* In production you will also need to provide us with wallet addresses for the crypto assets

  you will be accepting or the widget can be configured so that the customers put in their own address at the point of purchase.

### Webhooks

You need to provide the following webhooks:

* An endpoint to receive the details of captured fiat payments.
* An endpoint to receive the details of cryptocurrency deposited into the customers wallet.

***

### Payment flow

The steps for a successful payment are as follows:

* Generate a signature for the transaction (see details below). Pass this to the page hosting the widget Javascript, along with your API key.
* The user will first select the assets they wish to exchange, and then be prompted to log in (Figures 2 & 3)
* If this is the first time the user has logged in, they will undergo a KYC check.
* The user is prompted to input a wallet address – we then check the wallet address is valid
* The user then chooses to pay with a new card or any of their saved cards if they are a

  returning customer.
* Once the payment is captured we will make a callback to your captured fiat payments

  webhook containing details of the transaction.
* Once the exchange has been completed, the amount of the crypto asset purchased will be

  paid to the nominated wallet address (less the network fees incurred during the exchange

  and transfer).
* Finally, we make the callback to the cryptocurrency webhook, containing the details of the

  transaction which deposits the cryptocurrency into the customers wallet.

***

## Sandbox Testing

### Test Cards

The following card details can be used for testing in the sandbox environment:

| Card Number      | Type       |
| ---------------- | ---------- |
| 4007400000000007 | Visa       |
| 4007410000000006 | Visa       |
| 4200000000000000 | Visa       |
| 5102420000000006 | MasterCard |
| 5555555555554444 | MasterCard |

When testing you should also set the CVV2 code to “555” and the postal/zip code to “AAAA”. Barring this, any name, future expiry date and address will work with these cards.

***

## API Details

### Client Signatures

Each instantiation of the widget requires a signature that is unique with respect to the customer. This needs to be passed to the page hosting the widget script. We do not impose any particular requirements on this string, we simply pass it back to you in the callbacks for you to verify. However:

* The signature must be between 10 and 2000 characters long.
* We recommend that an expiry is set for each signature, and your authentication webhook

  should not return successfully once the token has expired.

***


# QuickBuy Callback

## Overview

The body of this request contains details about the requested exchange and the captured payment once the exchange has been agreed.

## Completed fiat payment callback

The body of this request contains details about the requested exchange and the captured payment once the exchange has been agreed.

Key details:

* `transactionReference` is our reference for the transaction, for use in correspondence.
* `status` is currently always `SUCCESS` as this callback currently only occurs for captured payments. In future other status codes may be added.
* The `requestDetails` object contains:
  * client signature and user reference used to initiate the widget,
  * user selected asset, currency, and payment amount,
  * the estimate displayed to the user of the amount of crypto asset to purchase, and
  * other details about the widget instantiation like the timestamp and IP address.
* The `transactionDetails` object contains:
  * payment card details;
  * payment capture date;
  * confirmation of the amount charged to the user's card;
  * confirmation of the fee charged - the amount used to buy the crypto will be the charged amount less this fee;
  * the amount of the crypto asset to be purchased (note that there are several transactions to make before this reaches the nominated external wallet, and some fees may be incurred);
  * an estimated value in the selected fiat currency of this crypto amount; and
  * other details such as the card payment processor.
* The content type of the body is `application/json`.

### Callback Example

<pre class="language-json"><code class="lang-json">{
  "TransactionReference": "QBWE1001",
  "Status": "SUCCESS",
  "RequestDetails": {
    "UserReference": "TestWidgetUser1",
    "ClientSignature": "lafsao7y4v5q847yrjerocq32yroaerq398", 
    "CryptoAssetCode": "USDC",
    "FiatCurrencyCode": "USD",
<strong>    "FiatCurrencyAmount": 50,
</strong>    "CryptoAssetAmount": 49.95,
    "RequestDate": "2022-02-18T14:30:59.52",
    "RequestIp": "51.141.9.231"
  },
  "TransactionDetails": {
    "StatementDescriptor": null,
<strong>    "PaymentProcessor": "Processor 1", 
</strong><strong>    "CryptoAssetGrossAmount": 47, 
</strong><strong>    "CryptoAssetEstimatedFiatValue": 47.5, 
</strong><strong>    "FiatCurrencyChargedAmount": 50, 
</strong><strong>    "FiatCurrencyFeeAmount": 2.5, 
</strong><strong>    "PaymentCaptureDate": "2022-02-18T14:31:59.577", 
</strong><strong>    "PaymentCardLast4Digits": "1111"
</strong>  } 
}
</code></pre>

[**We will include a signing header with this request (see below).**](#callback-signing)

***

## Completed Cryptocurrency deposit callback

The body of this request contains details about transaction which deposits the cryptocurrency into the customers wallet.

Key details:

* `transactionReference` is our reference for the transaction, for use in correspondence.
* `status` is currently always `SUCCESS` as this callback currently only occurs for captured payments. In future other status codes may be added.
* The `requestDetails` object contains:
  * client signature and user reference used to initiate the widget,
  * user selected asset, currency, and payment amount,
  * the estimate displayed to the user of the amount of crypto asset to purchase, and
  * other details about the widget instantiation like the timestamp and IP address.
* The `transactionDetails` object contains:
  * payment card details;
  * payment capture date;
  * confirmation of the amount charged to the user's card;
  * confirmation of the fee charged - the amount used to buy the crypto will be the
  * charged amount less this fee;
  * the amount of the crypto asset to be purchased (note that there are several transactions to make before this reaches the nominated external wallet, and some fees may be incurred);
  * an estimated value in the selected fiat currency of this crypto amount;
  * **the transaction hash**; and
  * other details such as the card payment processor.
* The content type of the body is `application/json`.

### Completed cryptocurrency deposit callback body

<pre class="language-json"><code class="lang-json">{
  "TransactionReference": "QBWE1001",
  "Status": "SUCCESS",
  "RequestDetails": {
  "UserReference": "TestWidgetUser1",
  "ClientSignature": "lafsao7y4v5q847yrjerocq32yroaerq398", 
  "CryptoAssetCode": "USDC",
  "FiatCurrencyCode": "USD",
  "FiatCurrencyAmount": 50,
  "CryptoAssetAmount": 49.95,
  "RequestDate": "2022-02-18T14:30:59.52",
  "RequestIp": "51.141.9.231"
  },
  "TransactionDetails": {
    "StatementDescriptor": null,
    "PaymentProcessor": "Processor 1",
    "CryptoAssetGrossAmount": 47,
    "CryptoAssetEstimatedFiatValue": 47.5,
    "FiatCurrencyChargedAmount": 50,
    "FiatCurrencyFeeAmount": 2.5,
<strong>    "PaymentCaptureDate": "2022-02-18T14:31:59.577",
</strong>    "PaymentCardLast4Digits": "1111",
    "TransactionHash": "0x9ec48ce0653cc7b2bcaa463a92b3191ddee5275d897854f2d210d2b298828d00"
    } 
}
</code></pre>

[**We will include a signing header with this request (see below).**](#callback-signing)

***

## Callback Signing

In order for you to authenticate a call to your payment capture webhook we will sign it using the shared secret provided to you. To generate the signing header we:

* Append the shared secret (in UTF8 encoding) to the bytes of the request body.
* Perform a SHA256 hash on the result
* Provide the hash value in the QuickBuy-Signature header for the callback (encoded as a base64 string).

Note: This only applies to the payment capture callback, we currently do not sign the initial authentication callback.

### [See the code examples for checking the callback signature.](/quickbuy/validating-the-webhook-signature)


# QuickBuy Front End Implementation

## Embedding the QuickBuy Widget

#### Main steps

See the example HTML document included below. The key steps are as follows:

* Import the stylesheet for the widget (line 5)
* Override the stylesheet values with your own custom rules (if required).
* Create a `<div>` with `id="WidgetContainer"` and appropriate dataset (lines 22-33).
* Run the bundled index.js script (line 38).

#### Notes:

If the `clientSignature` used is invalid/expired, the widget will surface an error using `window.postMessage()`. In this case you should generate a new `clientSignature` and reload the widget javascript.

***

## Endpoints:

#### Sandbox:

* JavaScript: <https://fintech-phoenix-quickbuywidget-v2.uat.avamae.co.uk/index.js>
* CSS: <https://fintech-phoenix-quickbuywidget-v2.uat.avamae.co.uk/index.css>

#### Production:

* JavaScript: <https://quickbuy-v2.ibanera.com/index.js>
* CSS: <https://quickbuy-v2.ibanera.com/index.css>

***

### HTML Example:

{% code lineNumbers="true" fullWidth="true" %}

```html
<!DOCTYPE html>
<html lang="en">
<head>
<!-- This is the stylesheet for the widget -->
<link rel="stylesheet" href="https://quickbuy-v2.ibanera.com/index.css" /> <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div
      id="root"
      style="
>
    height: 100vh;
    width: 100vw;
    position: fixed;
    top: 0;
left: 0;
    overflow-y: auto;
"
<!-- This div is where the widget will be inserted. The data attributes are user- provided values that will be used to authenticate requests -->
      <div
        id="WidgetContainer"
        data-clientsignature="YOUR_GENERATED_SIGNATURE_HERE”
        data-quickbuykey="YOUR_QUICKBUY_KEY_HERE"
        style="
                    background-color: #fff;
                    max-width: 650px;
                    margin-left: auto;
                    margin-right: auto;
"
    <!-
- Import the index.js script below and it will insert the widget into the div it finds with
 id="WidgetContainer" -->
    <script src="https://quickbuy-v2.ibanera.com/index.js" id="QuickBuyScript"></script>
  </body>
</html>
```

{% endcode %}


# Validating the Webhook Signature

### JavaScript / NodeJS Example

```javascript
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/authenticate', async (req, res) => {
    const hashSecret = "your_secret_here"; // Replace with your secret
    const signatureHeaderKey = req.headers['quickbuy-signature'];

    const rawBody = JSON.stringify(req.body); // Assuming JSON body
    const rawSignature = rawBody + hashSecret;
    
    const sha256 = crypto.createHash('sha256');
    const keyToAccept = sha256.update(Buffer.from(rawSignature, 'utf8')).digest('base64');

    if (keyToAccept === signatureHeaderKey) {
        res.send("Authenticated");
    } else {
        res.status(401).send("Authentication failed");
    }
});
```

***

### Python Example

```python
import hashlib
import base64
import json

async def authenticate():
    hash_secret = "your_secret_here" # Replace with your secret
    signature_header_key = request.headers.get('QuickBuy-Signature')

    raw_body = json.dumps(request.json) # Assuming JSON body
    raw_signature = (raw_body + hash_secret).encode()

    sha256 = hashlib.sha256()
    sha256.update(raw_signature)
    key_to_accept = base64.b64encode(sha256.digest()).decode()

    if key_to_accept == signature_header_key:
        return "Authenticated"
    else:
        return "Authentication failed", 401

```

***

### C# ASP.NET Example

```csharp
using System;
using System.IO;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;

public class Authentication
{
    public async Task<bool> AuthenticateRequest(string hashSecret, HttpContext httpContext)
    {
        if (!httpContext.Request.Headers.TryGetValue("QuickBuy-Signature", out var headerKey))
        {
            return false;
        }

        using var ms = new MemoryStream();
        await httpContext.Request.Body.CopyToAsync(ms);
        var bodyBytes = ms.ToArray();

        var rawSignature = bodyBytes.Concat(Encoding.UTF8.GetBytes(hashSecret)).ToArray();
        using var sha256 = SHA256.Create();
        var keyToAccept = Convert.ToBase64String(sha256.ComputeHash(rawSignature));

        return keyToAccept == headerKey.FirstOrDefault();
    }
}

```

***

### Go Example

```go
package main

import (
	"crypto/sha256"
	"encoding/base64"
	"io"
	"io/ioutil"
	"net/http"
)

func authenticateRequest(w http.ResponseWriter, r *http.Request, hashSecret string) {
	headerKey := r.Header.Get("QuickBuy-Signature")
	if headerKey == "" {
		http.Error(w, "Unauthorized", http.StatusUnauthorized)
		return
	}

	body, err := ioutil.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Internal Server Error", http.StatusInternalServerError)
		return
	}
	defer r.Body.Close()

	rawSignature := append(body, []byte(hashSecret)...)
	hasher := sha256.New()
	hasher.Write(rawSignature)
	keyToAccept := base64.StdEncoding.EncodeToString(hasher.Sum(nil))

	if keyToAccept == headerKey {
		w.Write([]byte("Authenticated"))
	} else {
		http.Error(w, "Unauthorized", http.StatusUnauthorized)
	}
}

func main() {
	http.HandleFunc("/authenticate", func(w http.ResponseWriter, r *http.Request) {
		authenticateRequest(w, r, "your_secret_here") // Replace with your secret
	})

	http.ListenAndServe(":3000", nil)
}

```


# QuickBuy Pro

## **Introduction**

<figure><img src="https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-289ddd05a8ecfef9b07e3a0c6dd2efe6adb8c945%2FScreenshot%202024-04-22%20at%2012.28.37%E2%80%AFAM.png?alt=media" alt=""><figcaption></figcaption></figure>

**Welcome to QuickBuy Pro**, your ultimate gateway to simplifying customer transactions within the Ibanera Ecosystem. Designed specifically for merchants, QuickBuy Pro offers a robust and seamless platform for accepting payments. Whether your customers are paying with credit or debit cards, QuickBuy Pro facilitates smooth and secure transactions, enabling them to purchase cryptocurrency effortlessly. Dive into the world of QuickBuy technology, where convenience meets innovation, empowering you to enhance your customers' buying experience and expand your business within the thriving Ibanera Ecosystem.


# Visual Customization

**Tailor QuickBuy Pro to Reflect Your Brand**

QuickBuy Pro offers extensive customization options that allow you to align the look and feel of your payment gateway with your brand's visual identity. Modify logos, button colors, text styles, and more to create a seamless and engaging user experience that resonates with your clients.

<figure><img src="https://1042261367-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxYGT6bxbvntyOdsHjmeN%2Fuploads%2Fgit-blob-289ddd05a8ecfef9b07e3a0c6dd2efe6adb8c945%2FScreenshot%202024-04-22%20at%2012.28.37%E2%80%AFAM.png?alt=media" alt=""><figcaption></figcaption></figure>

**Two Flexible Ways to Customize:**

1. **Coordinate with Our Team:**
   * For personalized assistance, connect with a QuickBuy Pro representative who will guide you through the customization process. Our team is here to ensure that your payment interface meets your specific branding requirements.
2. **Direct CSS Customization:**
   * If you prefer hands-on control, QuickBuy Pro’s CSS classes are designed to be easily overridden. You can directly adjust the styling to match your company’s branding. This approach offers flexibility for those who have specific design needs or who wish to integrate the payment gateway seamlessly with their existing web design.

**Get Started with Customization**

Enhancing the visual aspects of your QuickBuy Pro interface not only enhances the aesthetics but also boosts user trust and engagement by providing a cohesive brand experience. Start customizing today by reaching out to a representative or dive into our detailed CSS documentation for in-depth guidance on direct modifications.


# Getting Started / Authentication

### Authentication Settings

In order to ensure security and service integrity, all API requests must be accompanied by a valid API key. This key must be included in the request header under the `x-api-key` field.

### Header Parameter Description

| Parameter     | Description                             |
| ------------- | --------------------------------------- |
| **x-api-key** | API Key provided by your representative |


# API Endpoints


# Create Payment

## Overview

The `/quickbuy/v1/create` endpoint is designed for merchants using QuickBuy Pro to initiate the payment process. When a payment order is created, it is accessible via the `PaymentURL` provided in the API response. This URL serves as a direct link for clients to process their payments.

Payments have a limited active period, which can be customized per order using the `timeoutMin` parameter. If this parameter is not specified, the payment will default to the merchant's predetermined timeout settings.

* **Endpoint**: `/quickbuy/v1/create`
* **Method:** `POST`
* **Content-Type**: `application/json`

#### Request Body Parameters

* **`client`** (Object): Contains client related data
  * **`reference`** (String, min 15 chars, max 75 chars, Optional): Customer reference field for a merchant to set. This enables a merchant to quickly associate a **CustomerReference** with their own database
  * **`first`** (String, min 2 chars, max 100 chars, Optional): Client first name
  * **`last`** (String, min 2 chars, max 100 chars, Optional): Client last name
  * **`email`** (String, Optional): Client email
  * **`phone`** (String, Optional): Client phone number
* **`payment`** (Object): Contains payment configuration
  * **`amount`** (Number, Required): The amount of the payment
  * **`currency`** (String, ISO 4217, Required): The currency for the payment. **(ONLY USD AVAILABLE)**
  * **`timeoutMin`** (Number, min 1, max 10080, optional): The number of minutes that a payment is active for. Minimum of 1 minute, maximum of 10,080 minutes (1 week). If no value is provided, this timeout value will default to the merchant default value.
* **`redirectURL`** (string, optional): URL of the webpage to be redirected to, 5 seconds after a card is processed. The URL must use HTTPS.

#### **Request Body Example**

```json
{
    "client": {
        "reference": "john-doe-1234-user" 
    },
    "payment": {
        "amount": 102.96,
        "currency": "USD",
        "timeoutMin": 1440 // 1 day
    },
    "redirectURL": "https://ibanera.com/"
}
```

#### Response

```json5
{
    "success": true,
    "details": {
        "id": "66251f21c12e178b83c2a3be",
        "UserReference": "john-doe-1234-user",
        "Amount": 102.96,
        "Currency": "USD",
        "PaymentURL": "https://quickpay.ibanera.com/v1/66251f21c12e178b83c2a3be",
        "ExpireDateUTC": "2024-04-22T14:13:53.739Z",
        "ExpireMinutesFromNow": 1440
    }
}
```

Once you've received a successful response, indicated by <mark style="color:blue;">`"success": true`</mark> you can host the **PaymentURL**.

#### Response Error Example (400 Bad Request)

```json
{
    "error": "payment.amount is a required field"
}
```


# Retrieve Payments

## Overview

There's two available endpoints to retrieve data on existing orders:

1. [**Get Payment By ID**](#get-payment-by-id) - Retrieves a single payment by utilizing it's ID as a query parameter
2. [**List Payments**](#list-payments) - Retrieves a list of payments with optional query parameters to filter results

***

### Possible Payment States

<table><thead><tr><th width="221">State</th><th>Description</th></tr></thead><tbody><tr><td><strong>NOT_STARTED</strong></td><td>Active payment that has not been started yet</td></tr><tr><td><mark style="color:red;"><strong>EXPIRED</strong></mark></td><td>Expired payment that is no longer active</td></tr><tr><td><mark style="color:orange;"><strong>PENDING</strong></mark></td><td>Active payment which has been accessed by a client</td></tr><tr><td><mark style="color:blue;"><strong>CAPTURED</strong></mark></td><td>Card payment successful, awaiting cryptocurrency transfer</td></tr><tr><td><mark style="color:green;"><strong>COMPLETE</strong></mark></td><td>Completed payment and cryptocurrency transfer</td></tr></tbody></table>

***

### Get Payment By ID

The `/quickbuy/v1/get` endpoint is designed to retrieve detailed information about a specific payment using its unique Payment ID. This allows merchants and clients to track the status and details of a transaction.

* **Endpoint**: `/quickbuy/v1/get`
* **Method:** `GET`

#### **Request Query**

* OrderID: ID of the order to be retrieved

#### Response Body

The response will provide comprehensive details about the payment associated with the specified Payment ID, including transaction status, payment details, client information, and any relevant timestamps.

This endpoint is crucial for monitoring individual transactions, providing a reliable method for both merchants and clients to access current and accurate payment information.

#### Example (200 OK)

```json5
{
    "success": true,
    "details": {
        "id": "662282ec1746ac93544cdd26",
        "status": "NOT_STARTED",
        "client": {
            "UserReference": "john-doe-1234-user"
        },
        "fiat": {
            "amount": 121.12,
            "currency": "USD"
        },
        "DateCreated": "2024-04-19T14:42:52.554Z"
    }
}
```

***

### List Payments

The `/quickbuy/v1/list` endpoint provides a mechanism for retrieving a list of payments, offering flexibility through various query parameters. This allows merchants to view multiple payments based on specified criteria such as date ranges, payment statuses, and more, making it easier to manage and analyze payment transactions.

* **Endpoint**: `/quickbuy/v1/list`
* **Method:** `GET`

#### Query Parameteres

* **`PageSize`** (optional, default = 10, max 1000): Number of results to be displayed
* **`HideExpired`** (optional, boolean, lowercase): When true, expired payments will be hidden
* **`State`** (optional): Filter by payment state, refer to [Possible Payment States](#possible-payment-states)

#### Response Body Example (200 OK)

```json5
{
    "success": true,
    "quantity": 3,
    "details": [
        {
            "id": "66251ea1b81def2bad344760",
            "status": "CAPTURED",
            "client": {
                "UserReference": "john-doe-1234-user"
            },
            "fiat": {
                "amount": 262.91,
                "currency": "USD"
            },
            "DateCreated": "2024-04-21T14:11:45.465Z",
            "ExpireDate": "2024-04-22T14:11:45.445Z",
            "CaptureDate": "2024-04-21T14:11:45.465Z"
        },
        {
            "id": "66251f21c12e178b83c2a3be",
            "status": "PENDING",
            "client": {
                "UserReference": "john-doe-1234-user"
            },
            "fiat": {
                "amount": 102.96,
                "currency": "USD"
            },
            "DateCreated": "2024-04-21T14:13:53.743Z",
            "ExpireDate": "2024-04-22T14:13:53.739Z"
        },
        {
            "id": "662528dccc21be7cb5e8aeb7",
            "status": "NOT_STARTED",
            "client": {
                "UserReference": "john-doe-1234-user"
            },
            "fiat": {
                "amount": 11.96,
                "currency": "USD"
            },
            "DateCreated": "2024-04-21T14:55:24.876Z",
            "ExpireDate": "2024-04-22T14:55:24.866Z"
        },
        
        /* ...more payments... */
    ]
}

```


# Delete Payment

## Overview

A QuickBuy Pro order can be deleted if it has a state of '`NOT_STARTED`'. This refers to a transaction that has been created, but no payment action has been made. Once a order is deleted, the payment's URL will no longer be accessible.

* **Endpoint**: `/quickbuy/v1/delete`
* **Method:** `DELETE`

#### Request Query Parameter

* **`OrderID`:** The OrderID, available when a payment is created, or via the retrieve payments endpoint.

#### Response Body Example (200 OK)

```json5
{
    "success": true,
    "message": "Order Deleted",
    "id": "66253fcf7788710a6063b66d"
}
```

Once you've received a successful response, indicated by <mark style="color:blue;">`"success": true`</mark><mark style="color:blue;">, the payment is deleted.</mark>

#### Response Error Example (404 Bad Request)

```json
{
    "success": false,
    "message": "Order not found."
}
```


# Callbacks


# Payment Captured

The Payment Captured callback is typically sent within 1-15 minutes from the time that a customer makes a card payment.

### Callback Example

```json
{
    "OrderID": "662d7681909539441bf6b1ee",
    "status": "CAPTURED",
    "client": {
        "UserReference": "joe-test-00001x",
        "email": "joe@doe.com"
    },
    "fiat": {
        "amount": 40.95,
        "currency": "USD",
        "PaymentCardLast4Digits": "0007"
    },
    "crypto": {
        "asset": "dUSD",
        "amount": 35.95
    },
    "DateCreated": "2024-04-27T22:04:49.423Z",
    "DateCaptured": "2024-04-28T02:15:20.977Z"
}
```

#### Callback Header

<table><thead><tr><th width="231">Parameter</th><th>Example Value</th></tr></thead><tbody><tr><td><strong>Quickbuy-Signature</strong></td><td>eO4HU1avkGpYpWf7eVzPYZGstCnnxdzytl3jUZ/tEiM="</td></tr></tbody></table>

[Click here to learn more about validating the webhook signature.](/quickbuy/validating-the-webhook-signature)


# Cryptocurrency Transferred

The Cryptocurrency Transferred callback is typically sent within 1-60 minutes from the time that a customer makes a card payment. This callback is triggered when the crypto currency purchase and transfer is completed, which finalizes a transaction.

### Callback Example

```json
{
    "OrderID": "662d7681909539441bf6b1ee",
    "status": "COMPLETED",
    "client": {
        "UserReference": "joe-test-00001x",
        "email": "joe@doe.com"
    },
    "fiat": {
        "amount": 40.95,
        "currency": "USD",
        "PaymentCardLast4Digits": "0007"
    },
    "crypto": {
        "asset": "dUSD",
        "amount": 35.95,
        "txHash": "4f3b365adb....."
    },
    "DateCreated": "2024-04-27T22:04:49.423Z",
    "DateCaptured": "2024-04-28T02:15:20.977Z",
    "DateTransfered": "2024-04-28T02:17:53.152Z"
}
```

#### Callback Header

<table><thead><tr><th width="231">Parameter</th><th>Example Value</th></tr></thead><tbody><tr><td><strong>Quickbuy-Signature</strong></td><td>eO4HU1avkGpYpWf7eVzPYZGstCnnxdzytl3jUZ/tEiM="</td></tr></tbody></table>

[Click here to learn more about validating the webhook signature.](/quickbuy/validating-the-webhook-signature)