# A Gentle Introduction for Developer

## **Welcome to the VelaFi API Documentation** 

Programmatically manage financial asset conversions and cross-currency transfers with VelaFi. Our API empowers you to seamlessly convert fiat to digital currencies and facilitate fiat-to-fiat transfers using stablecoins as intermediaries. Designed for enterprise developers, our solution prioritizes security, efficiency, and compliance, enabling you to build robust financial workflows for your business or customers. 

## **Integration Made Simple** 

The VelaFi API uses [RESTful](https://en.wikipedia.org/wiki/REST) architecture to organize resources. It employs basic access authentication over [HTTPS](https://en.wikipedia.org/wiki/HTTPS) for secure communication, accepts and returns JSON-encoded bodies, and utilizes standard [HTTP](https://en.wikipedia.org/wiki/HTTP) response codes for clarity. Our comprehensive guides and reference implementations ensure a smooth and efficient integration process.

## **What You’ll Find Here**

Explore detailed documentation and resources to address your payment and conversion needs:

{% content-ref url="/pages/EOdwnemFEXYcCD5xYT5k" %}
[📖  Guides](/velafi-1)
{% endcontent-ref %}

**Step-by-step instructions for managing transfers and conversions.**

{% content-ref url="/pages/nU8LdsvLdidgiEORkqE6" %}
[📗  API Reference](/velafi-1/api-reference/basic-configuration)
{% endcontent-ref %}

**Detailed descriptions of endpoints, parameters, and responses.**<br>

Start building with VelaFi today and unlock the power of seamless financial asset management.&#x20;

<br>


# Step-by-Step Guide

Guide

### Onboarding with **VelaFi**&#x20;

This section walks you through the complete onboarding process with VelaFi, including account registration, API key generation, merchant setup, compliance verification, and payment accout activation.

1. [**Creating VelaFi Account**](/velafi-1/guides/creating-velafi-account)\
   Begin by registering an account on the VelaFi platform. Upon successful registration, the system will assign a **unique user ID (UID)**, which will serve as the identifier for managing all your transactions, merchants, and account-level operations.<br>
2. [**Create a Merchant & Complete Compliance Verification (KYC/KYB)**](/velafi-1/guides/creating-your-merchant)

   To operate under VelaFi’s compliance framework, you must create a legal individual or business entity (Merchant).

   * Submit detailed merchant information to initiate the KYC/KYB verification process.
   * Once approved, the platform will assign a unique Merchant ID (MID) to you or your client.<br>
3. [**Create API Key**](/velafi-1/guides/creating-api-key)\
   Once your account is activated, you can log into the platform dashboard to generate your API Key.This key is required to authenticate your API requests and securely interact with VelaFi’s services.<br>
4. [**API Access**](https://share.hsforms.com/1QaOs6gjZQG2z_uHLEX9w9Ar8y9l)\
   Contact VelaFi Team for activation.<br>
5. [**Active Merchant Account**](/velafi-1/guides/activate-merchant-account)\
   Activate the required fiat payment channels (e.g., ARS, MXN, USD, EUR) for your merchant to enable seamless and efficient fund inflows and outflows.
   * Each merchant will be assigned a **dedicated payment account**, such as CVU and CUIT numbers for ARS (Argentina).
   * **Funds can be deposited** into the merchant's payment account via bank transfer. VelaFi will automatically reconcile the incoming payments and credit the corresponding balance to the merchant’s account.
   * Both **corporate and individual merchant accounts** are supported, allowing flexible fund management across different business scenarios.<br>
6. **Environment Selection**\
   [**Sandbox**](/velafi-1/guides/sandbox): Test transactions\
   Production: Real transactions

***

### On-Ramp Workflow (Fiat → Crypto)

Review the following Support articles to see our supported currencies and regions for on-ramp:

[View supported cryptocurrencies & fiat currencies](/velafi-1/guides/pair)<br>

#### 1. Ensure [Merchant Fiat Account Activation](/velafi-1/api-reference/merchant/activate-merchant-account)

Before initiating a transaction, please ensure that the merchant has successfully activated their fiat account.\
For example, if Merchant **Alice** wants to perform an **ARS → USDT** transaction, she must first activate her **ARS fiat account**.<br>

#### 2. [Create Fiat to Crypto Order](/velafi-1/api-reference/order/create-a-fiat-to-crypto-order)

When an order is created, the system will generate a unique `order_id` to track the transaction.

#### 3. [Retrieve a Specific Order](/velafi-1/api-reference/order/retrieve-a-specific-order)

To get the details of a specific order, use the `order_id` to query and retrieve comprehensive order information.

#### 4. Make a Payment

There are two payment methods available:

**A. Pending Fund Balance Payment**\
If you select **Merchant Account Pending Fund** and the account balance is sufficient, the system will automatically process the payment.

**B. Real-Time Manual Payment**\
If you opt for **real-time payment**, you must manually transfer the funds to the fiat account specified in the **order details**.

#### 5. System Confirms Order Completion

Once the payment is confirmed, your account will instantly receive the corresponding amount of **cryptocurrency**.

**Note:** Due to compliance requirements, certain transactions may require you to submit supporting documents after order creation via the **Upload Invoice Documents For a Specific Order** endpoint.

***

### Off-Ramp Workflow (Crypto → Fiat)

Review the following Support articles to see our supported currencies and regions for off-ramp:

[View supported cryptocurrencies & fiat currencies](/velafi-1/guides/pair)<br>

Before initiating a transaction, please ensure that the merchant has successfully activated their fiat account.\
For example, if Merchant Alice wants to perform an **USDT → ARS** transaction, she must first activate her **ARS fiat account And added** [**payment methods**](/velafi-1/api-reference/payment-method/add-payment-method)**.**\ <br>

#### 1.[ Create a Crypto to Fiat Order](/velafi-1/api-reference/order/create-a-crypto-to-fiat-order)

Initiate a transaction by creating a **Crypto to Fiat** order through the appropriate API endpoint.

#### 2. System Processes the Transaction

Once the order is submitted, the system will handle cryptocurrency validation, conversion, and fiat settlement instructions.

#### 3. Receive Fiat Funds

The fiat currency will be transferred to the beneficiary's account upon successful completion of the transaction.

***

### Global Payment Workflow

Review the following Support articles to see our supported currencies and regions for global payment:

[Supported cryptocurrencies & fiat currencies](/velafi-1/guides/pair)\
\
\
**Before initiating a transaction, please ensure that the merchant has successfully activated their fiat accounts.**\
For example, if merchant **Alice** intends to perform a **USD → ARS** transaction, she must first activate both her **USD** and **ARS** fiat accounts and add the required payment method.<br>

1. Confirm transfer details:
   * Sender fiat currency & amount
   * Recipient fiat currency & amount
2. Select sender [Merchant](/velafi-1/api-reference/merchant)
3. Retrieve [payment methods](/velafi-1/guides/payment-method-id)
4. Select recipient [Merchant](/velafi-1/api-reference/merchant)
5. Configure recipient [payment method](/velafi-1/api-reference/payment-method)
6. [Create fiat to fiat order via API](/velafi-1/api-reference/order/create-a-fiat-to-fiat-order)
7. Order execution completed
8. Recipient fiat funds received


# Creating VelaFi Account

Visit the [VelaFi Signup Page](https://www.velafi.com/signup).

<figure><img src="/files/5RBQSXxcAlrHSmeSGbyc" alt=""><figcaption></figcaption></figure>

* Follow the on-screen instructions to complete the registration process.
* Once the registration is complete, log in to your VelaFi account.&#x20;


# Creating Your Merchant

Create a legal individual or business entity (Merchant) to operate under VelaFi's compliance framework.

* Submit your detailed merchant information to initiate the KYC/KYB compliance verification process.
* Upon successful verification, the platform will assign a unique Merchant ID (MID) to you or your client.

Upon a successful API request, the response will include a unique URL that redirects the user to a secure KYC/KYB verification page. You may choose to:

* Redirect users directly to the provided URL to complete their verification process, or
* Embed the verification flow within your front-end application using an `<iframe>`, offering a seamless user experience.

Please ensure that the URL is used promptly, as it may be subject to expiration or session constraints depending on the configuration.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/v2/merchants`
* **Authorization Required**: Yes<br>

#### Request Parameters

The request body should include the following fields:\ <br>

**For New Merchant**

```json
{     
    "merchantName": "Tom", //(required, string: Merchant Name (Unique))
    "email": "tom@gmail.com", //(required, string: Email (Unique))
    "merchantType": "BUSINESS", //(required, string: Merchant Type [INDIVIDUAL, BUSINESS])
    "callbackUrl": "https://localhost", //(required, string: URL for KYC/KYB completion callback)
    "languageCode": "en", //(optional, string: Interface language (en(default)/es/pt/zh))
    "remark": "test" //(optional, string: Remark)
}
```

\
**For Unverified Merchant**

```json
{
    "merchantId": 15126673, //(required, number: id of the merchant)
    "callbackUrl": "https://localhost", //(required, string: URL for KYC/KYB completion callback)
    "languageCode": "en" //(optional, string: Interface language (en(default)/es/pt/zh))
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "merchantId": 15126673, //(number: id of the merchant)
        "kycLink": "https://www.velafi.com/verify?token=abc123" //(string: Link for conducting KYC/KYB verification)
    }
}
```

#### Example Requests

**Example Request (New Merchant)**

```json
{     
    "merchantName": "Tom", 
    "email": "tom@gmail.com", 
    "merchantType": "BUSINESS", 
    "callbackUrl": "https://localhost", 
    "languageCode": "en", 
    "remark": "add tom merchant"
}
```

**Example Request (Unverified Merchant)**

```json
{
    "merchantId": 15126673, 
    "callbackUrl": "https://localhost", 
    "languageCode": "en"
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "merchantId": 15126673,
        "kycLink": "https://www.velafi.com/business/token=_act-sbx-jwt-eyJhbGciOiJub25lIn0.eyJqdGkiOiJfYWN0LXNieC0xNGY3YWE4MS1kMTRjLTRmN2ItYTZmYy0xMzA4NWJiN2Y4MWUtdjIiLCJ1cmwiOiJodHRwczovL2FwaS5zdW1zdWIuY29tIn0.-v2&merchant_type=PERSONAL&callback_url=https%3A%2F%2F"
    }
}
```

**I. Multi-Merchant Management**

Once your **primary merchant account** has successfully passed KYB verification, you are eligible to create and manage **sub-merchant entities** (for individuals or businesses) under your account. This allows for **tiered merchant management** with flexible role and access controls.

**II. Reliance Mode Integration (Optional)**

If you are a **licensed financial institution**, you may apply to enable **Reliance Mode**, which grants greater autonomy over your merchant operations:

* You will be responsible for the **review, risk control, and ongoing compliance** of your sub-merchants. VelaFi will not intervene in the onboarding process.
* VelaFi provides the **technical infrastructure and operational support**, ensuring transaction security, efficiency, and regulatory compliance.
* Reliance Mode requires a **higher-tier compliance review** by the VelaFi compliance team.

> \
> 🔗 [Click here to learn more about the Reliance Mode application process](https://help.mexo.me/en/articles/10258575-process-guide-for-the-reliance-model-with-trubit)


# Creating API Key

* After logging in, navigate to the [API Management Page](https://www.velafi.com/user/interface).

<figure><img src="/files/0rySJjm6SpVnIgWbiyV8" alt=""><figcaption></figcaption></figure>

* Click the “**Creat**e **API Key**” button to generate your **API key**.&#x20;

<mark style="color:green;background-color:green;">**Note:**</mark> <mark style="color:green;background-color:green;"></mark><mark style="color:green;background-color:green;">If two-factor authentication (2FA) is not enabled on your account, the system will prompt you to enable it for enhanced security.</mark><br>

* Please enter Notes here, after verification is complete, click **"Continue"**

<figure><img src="/files/F2me8Q9stQ5uZ3Yj6tsV" alt=""><figcaption></figcaption></figure>


# Safely Store Your API Key

<figure><img src="/files/a6eNq0CsBADbUoOyLJ24" alt=""><figcaption></figcaption></figure>

Interface shows that the **API Key created**.&#x20;

## **⚠️Notes**

#### **Uniqueness:**

Each API key is unique and specifically designed for accessing VelaFi’s production environment.

#### **Storage Recommendations:**

<mark style="color:orange;background-color:orange;">Immediately store your API key in a secure location after generating it, as you will not be able to view it again once you leave the page.</mark>

<mark style="color:orange;background-color:orange;">Do not store your API key on public devices or in public locations, and avoid saving it in plaintext format.</mark>

<mark style="color:orange;background-color:orange;">Recommendation: Use encryption tools or a password manager to securely store your API key and prevent accidental exposure.</mark>


# Configure Whitelisted IPs

* Create a list of authorized IP addresses (IP whitelist) that are allowed to use your API keys.

<figure><img src="/files/NO0YdPvUb8zwV20STk1G" alt=""><figcaption></figcaption></figure>

## ⚠️**Important:** &#x20;

<mark style="color:orange;background-color:orange;">Whitelisting ensures that even if your API key is compromised, requests from unauthorized IPs will still be denied.</mark>


# Enable API Access

* Once your configuration is complete, contact the VelaFi team to finalize and activate your API access.<br>
* Submit your request via the [Contact Form](https://share.hsforms.com/1P1po-MZAThupnwug_qDEEAr8y9l).&#x20;


# Create API Token

This API allows you to generate a new API token for user authentication.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/token/generate`
* **Authorization Required**: Yes

#### Request Headers

* `X-BH-APIKEY`: Your API key.

#### Query Parameters

* `timestamp`: The current time in milliseconds since the epoch.
* `signature`: The HMAC signature for the request.

#### Response Structure

The response will include the following fields:

```json
{
  "code": 200,                      // (number: response code)
  "msg": "SUCCESS",                 // (string: message)
  "data": {                         // (object: token details)
    "token": "09ef3523-6242-4a8d-80e2-24cfbdb35851", // (string: generated token)
    "expireTime": "1740568725231"  // (string: timestamp of the expiration time in milliseconds)
  }
}
```

#### Signature Generation Process

To generate the signature, follow these steps:

1. **Prepare the Message**: Create a string with the current timestamp: `"timestamp=1740568725231"`.
2. **Prepare the Key**: Use your `API_SECRET` as the key.
3. **Generate the Signature**: Use HMAC-SHA256 to create a hex string signature from the message and the key.

#### Example Code for Signature Generation

**Python**

```python
import time
import hmac
import hashlib

API_SECRET = "xxxx"
message = "timestamp=" + str(int(time.time() * 1000))
signature = hmac.new(API_SECRET.encode('utf-8'), message.encode('utf-8'), hashlib.sha256).hexdigest()

print("Signature:", signature)
```

**Java**

```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class Signature {
    public static void main(String[] args) throws Exception {
        String API_SECRET = "xxxx";
        String message = "timestamp=" + System.currentTimeMillis();
        String signature = hmacSHA256(API_SECRET, message);

        System.out.println("Signature: " + signature);
    }

    public static String hmacSHA256(String secret, String message) throws Exception {
        Mac sha256HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256HMAC.init(secretKey);
        byte[] bytes = sha256HMAC.doFinal(message.getBytes(StandardCharsets.UTF_8));
        return bytesToHex(bytes);
    }

    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
}
```

**JavaScript (Node.js)**

```javascript
const crypto = require('crypto');

const API_SECRET = 'xxxx';
const message = 'timestamp=' + Date.now();
const signature = crypto.createHmac('sha256', API_SECRET).update(message).digest('hex');

console.log('Signature:', signature);
```

**Go**

```go
package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "time"
)

func main() {
    API_SECRET := "xxxx"
    message := "timestamp=" + fmt.Sprint(time.Now().UnixNano()/1e6)
    signature := generateHMAC(API_SECRET, message)

    fmt.Println("Signature:", signature)
}

func generateHMAC(secret, message string) string {
    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(message))
    return hex.EncodeToString(h.Sum(nil))
}
```

**Rust**

```rust
use hmac::{Hmac, Mac};
use sha2::Sha256;
use std::time::{SystemTime, UNIX_EPOCH};

fn main() {
    let api_secret = "xxxx";
    let start = SystemTime::now();
    let since_the_epoch = start.duration_since(UNIX_EPOCH).expect("Time went backwards");
    let message = format!("timestamp={}", since_the_epoch.as_millis());
    let signature = generate_hmac(api_secret, &message);

    println!("Signature: {}", signature);
}

fn generate_hmac(secret: &str, message: &str) -> String {
    let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes()).expect("HMAC can take key of any size");
    mac.update(message.as_bytes());
    let result = mac.finalize();
    hex::encode(result.into_bytes())
}
```

#### Notes

* Ensure that you replace `"xxxx"` with your actual `API_SECRET`.
* The generated token will have an expiration time, which is provided in the response.


# Sandbox

VelaFi offers a **sandbox environment** designed to facilitate rapid integration testing without the necessity of using real funds. The sandbox can be accessed at:

* **Sandbox URL**: \
  [`https://api-test.velafi.com`](< https://api-test.velafi.com>)

For instance, to retrieve information about fiat trading pairs, you can utilize the following endpoint:

* **Fiat Trading Pairs Endpoint**: \
  [`https://api-test.velafi.com/v2/base/fiat/symbols`](<https://api-test.velafi.com/v2/base/fiat/symbols&#xA;>)

#### Sandbox API Credentials

To access the sandbox environment, use the following credentials:

* **API Key**:

  ```
  Please contact the VelaFi team to get it.
  ```
* **API Secret**:

  ```
  Please contact the VelaFi team to get it.
  ```

#### Key Differences Between Sandbox and Production Environments

We recommend utilizing the sandbox environment exclusively for testing API request/response behaviors, while reserving the production environment for all other types of testing activities.

**Distinctions:**

1. **No KYC Registration or API Key Creation Required**:\
   The sandbox environment eliminates the need for actual identity verification and API key generation.
2. **Virtual User and Account Data**:\
   All user and account information within the sandbox is simulated and not linked to real individuals.
3. **No Actual Fund Transfers**:\
   The sandbox environment does not facilitate real financial transactions; all processes are entirely simulated.
4. **Webhook Callbacks Are Not Triggered**:\
   In the sandbox environment, webhooks will not initiate any callback events.

#### Conclusion

We encourage you to leverage the sandbox environment thoroughly to validate your integration before deploying it in the production environment. This ensures that your application functions as intended and minimizes the risk of issues in a live setting.


# Activate Merchant Account

This endpoint is used to activate a merchant's fiat currency payment account. Supported currencies include MXN, ARS, USD, and EUR. Once activated, merchants can send and receive funds through local banking channels with increased flexibility and efficiency.

* Each merchant will receive dedicated account details (e.g., ARS accounts include CVU number / CUIT for Argentina).
* Merchants can deposit funds via wire transfer; VelaFi will automatically reconcile the transaction and credit the merchant’s account balance.
* Both business and personal account types are supported, enabling broad use across various payment scenarios.
* Note: Once a EUR account is activated, it enables the merchant to operate with both EUR and USD currencies simultaneously.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/v2/merchant/accounts`
* **Authorization Required**: Yes

#### Request Parameters

The request body should include the following fields:

**For MXN Account (Mexico)**

```json
{    
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "MXN", // (required, string: name of the fiat currency [MXN/USD/EUR])
    "fieldList": { // List of channel fields
        "email": "rturo@gmail.com", // (optional, string: Email, if the merchant information is not provided, it must be filled in)
        "idNoType": "CURP", //(required, enum: type of identification document [CURP/RFC])
        "idNo": "MACM000502IR6",//(required, string: identity number)
        "cardIssueDate": "2019-06-01", // (required, string: Card Issue Date (yyyy-MM-dd))
        "cardExpireDate": "2029-06-01", // (required, string: Card Expiry Date (yyyy-MM-dd))
        "address": "Celle Lagu Wenner 50", // (required, string: Address)
        "city": "Ciudad de Mexico", // (required, string: City)
        "state": "CMX", // (required, string: State)
        "zipCode": "09060", // (required, string: Zip Code)
        "phone": "35580481683", // (required, string: Phone)
        
        "companyName": "Rrturo Tellez", // (string: Company Name, required if merchantType is COMPANY)
        "aliasName": "Rrturo", // (string: Alias Name, required if merchantType is COMPANY)
        "companyType": "SC", // (string: Company Type, required if merchantType is COMPANY)
        "incorporationDate": "2019-02-01", // (string: Incorporation Date (yyyy-MM-dd), required if merchantType is COMPANY)
    
        "birthday": "1988-07-02", // (string: Birthday (yyyy-MM-dd), required if merchantType is PERSONAL)
        "name": "Tellez", // (string: Name, required if merchantType is PERSONAL)
        "fatherSurname": "Rrturo", // (string: Father's Surname, required if merchantType is PERSONAL)
        "motherSurname": "" // (string: Mother's Surname, required if merchantType is PERSONAL)
    }
}
```

**For ARS Account (Argentina)**

```json
{
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "ARS", // (required, string: name of the fiat currency [MXN/USD/EUR])
    "fieldList": { // List of channel fields
        "email": "rturo@gmail.com", // (optional, string: Email, if the merchant information is not provided, it must be filled in)
        "cuit": "30708424478", // (required, string: CUIT)
        "name": "COCOS CAPITAL SA", // (required, string: Full Name)
        "alias": "soc.te" // (optional, string: Alias)
    }
}
```

**For EUR/USD Account**

After the EUR currency account is activated, it can be used for both EUR and USD transactions.

```json
{
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "EUR", // (required, string: name of the fiat currency [MXN/USD/EUR]) 
    "fieldList": { // List of channel fields
        "email": "rturo@gmail.com", // (optional, string: Email, if the merchant information is not provided, it must be filled in)
        "companyName": "CAPITAL SA COCOS", // (string: Company Name, required if merchantType is COMPANY)
        "firstName": "CAPITAL SA", // (string: First Name, required if merchantType is PERSONAL)
        "lastName": "COCOS" // (string: Last Name, required if merchantType is PERSONAL)
    }
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "MXN", // (string: name of the fiat currency [MXN/USD/EUR]) 
        "status": 1, // (enum: status of the channel [1: authenticating, 2: normal, 3: authentication failed, 4: incomplete])
        "failReason": "", //（string: cause of failure)
        "verifyLink": "" // (string: Verified link, only through the IBAN channel is it possible)
    }
}
```

#### Example Requests

**Example Request (MXN)**

```json
{    
    "fiat": "MXN",
    "merchantId": 15126673,
    "fieldList": { 
        "email": "rturo@gmail.com", 
        "idNoType": "CURP",
        "idNo": "MACM000502IR6",
        "cardIssueDate": "2019-06-01",
        "cardExpireDate": "2029-06-01",
        "address": "Celle Lagu Wenner 50", 
        "city": "Ciudad de Mexico",
        "state": "CMX",
        "zipCode": "09060",
        "phone": "35580481683",
        
        "companyName": "Rrturo Tellez",
        "aliasName": "Rrturo",
        "companyType": "SC",
        "incorporationDate": "2019-02-01",
    
        "birthday": "1988-07-02", 
        "name": "Tellez",
        "fatherSurname": "Rrturo",
        "motherSurname": ""
    }
}
```

**Example Request (ARS)**

```json
{
    "fiat": "ARS",
    "merchantId": 15126673,
    "fieldList": {
        "email": "rturo@gmail.com",
        "cuit": "30708424478",
        "name": "COCOS CAPITAL SA",
        "alias": "soc.te"
    }
}
```

**Example Request (EUR/USD)**

```json
{
    "fiat": "EUR",
    "merchantId": "15126673",
    "fieldList": {
        "email": "rturo@gmail.com",
        "companyName": "CAPITAL SA COCOS"       
    }
}
```

#### Example Responses

**Example Response (MXN)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "MXN",
        "status": 1,
        "failReason": ""        
    }
}
```

**Example Response (ARS)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "ARS",
        "status": 1,
        "failReason": ""        
    }
}
```

**Example Response (EUR/USD)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "EUR",
        "status": 4,
        "verifyLink": "https://www.VelaFi-test.com/business/channel/verify?token=12ceff08f9621808b5a573972cdfb10f",
        "failReason": ""        
    }
}
```

#### Notes

* Ensure that all fields in the request body are filled out correctly to facilitate the activation process.
* Merchants may need to provide additional documentation based on the type of account being activated.


# Creating Payment Method

This guide provides detailed information about managing payment methods, including how to retrieve payment method templates and add new payment methods.&#x20;

## **I. Get Payment Method Templates**

#### Endpoint Information

* **Request Method**: `GET`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Path**: `/v2/payments/templates`
* **Authorization Required**: Yes

#### Request Parameters

**Query Parameters**

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| paymentId | number | Yes      | ID of the payment method |

#### Response Structure

The response will contain the following fields:

```json
{
  "code": 0,
  "msg": "",
  "data": {
      [string]: [string]
  }
}
```

#### Example Responses

**Payment Type 1: Bank Information**

**Mexico Bank**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "CLABE number": "",
        "Account number/card": "",
        "Beneficiary Name": ""
    }
}
```

**Argentina Bank**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "CVU number": "",
        "cuit": "",
        "Bank name": ""
    }
}
```

**Payment Type 2: SEPA  Transfers**

**SEPA**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Bank Name": "",
        "Account Owner Name": "",
        "Account Owner Type": "",
        "Bank Country/Region": "",
        "Account Number": "",
        "Bic": "",
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}

Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.
Bank Country/Region is ISO 3166-1

```

**WIRE / ACH Transfers**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Bank Name": "",
        "Account Owner Name": "",
        "Account Owner Type": "",
        "Bank Country/Region": "",
        "Account Number": "",
        "Routing Number": "",
        "Street Line1": "",
        "Street Line2": "",
        "City": "",
        "State": "",
        "Postal Code": "",
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}

Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.
Bank Country/Region is ISO 3166-1
State is ISO 3166-2
```

**Payment Type 3: SWIFT / CHATS**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Account Owner Type": "",
        "IBAN": "",
        "Bank Name": "",
        "Bank Country/Region": "",
        "Bank Identifier": "",
        "Street": "",
        "City": "",
        "State": "",
        "Country/Region": "",
        "Postal Code": ""
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}

Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.

Bank Country/Region is ISO 3166-1

```

## **II. Add Payment Method**

#### Endpoint Information

* **Request Method**: `POST`
* **Request Path**: `/v2/payments`
* **Request Header**: `X-BH-TOKEN: ******`
* **Authorization Required**: Yes

#### Request Parameters

**Request Body**

The request body should include the following parameters:

| Parameter  | Type   | Required | Description                                                         |
| ---------- | ------ | -------- | ------------------------------------------------------------------- |
| merchantId | number | Yes      | ID of the merchant id                                               |
| paymentId  | number | Yes      | ID of the payment method                                            |
| country    | string | Yes      | Name of the country                                                 |
| fiat       | string | Yes      | Name of the fiat currency                                           |
| realName   | string | No       | Real name of the account holder                                     |
| fieldJson  | object | Yes      | Field JSON of the payment template, format `{ [string]: [string] }` |
| remark     | string | No       | Additional remarks for the payment method                           |

**Request Example**

```json
{
  "merchantId": 0,
  "paymentId": 0,
  "country": "",
  "fiat": "",
  "realName": "",
  "fieldJson": {
      "fieldName": "value"
  },
  "remark": ""
}
```

#### Response Structure

The response will contain the following fields:

```json
{
  "code": 0,
  "msg": "",
  "data": {
      "id": 0,  // User payment ID
      "status": 0, // Status: [1: valid, 2: authenticating, 3: authentication failed]
      "failReason": "" // Reason for authentication failure
  }
}
```

### Notes

* Ensure to provide valid parameters for successful creation of payment methods.
* The `merchantId` and `paymentId` must correspond to existing configurations in the system.
* Pay attention to the status and failure reason in the response for troubleshooting.


# Payment Method ID

PaymentID

This section provides information about the various payment methods supported by the API, including a comprehensive mapping of payment method IDs to their respective names. The following table outlines the payment method IDs along with their corresponding payment method names. This reference is essential for developers and users to identify and utilize the appropriate payment methods in their transactions.

<table><thead><tr><th width="125.00006103515625">Payment ID</th><th width="268.1109619140625">Name</th><th width="109.5926513671875">Type</th><th>Trench</th></tr></thead><tbody><tr><td>105</td><td>SPEI (Finco Pay)</td><td>Automatic</td><td>CLABE - FINCO PAY</td></tr><tr><td>72</td><td>SPEI (Tesored)</td><td>Automatic</td><td>CLABE - TESORED</td></tr><tr><td>63</td><td>CBU/CVU (Momentum)</td><td>Automatic</td><td>CVU - Momentum</td></tr><tr><td>137</td><td>3.0 Transfer (QR)</td><td>Automatic</td><td>QR Argentina</td></tr><tr><td>81</td><td>ACH (Reference - Lead Bank)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>82</td><td>ACH (Virtual - Lead Bank)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>83</td><td>Wire (Reference - Lead Bank)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>84</td><td>Wire (Virtual - Lead Bank)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>85</td><td>SEPA (Bridge)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>90</td><td>Pix (Genial)</td><td>Automatic</td><td>BANCO GENIAL</td></tr><tr><td>135</td><td>Pix (a55)</td><td>Automatic</td><td>a55</td></tr><tr><td>95</td><td>Bank Transfer</td><td>Automatic</td><td>PEN Account</td></tr><tr><td>111</td><td>Wire (Virtual - CRB)</td><td>Automatic</td><td>Cross River Bank</td></tr><tr><td>113</td><td>ACH (Virtual - CRB)</td><td>Automatic</td><td>Cross River Bank</td></tr><tr><td>115</td><td>SWIFT Account_Cross River Bank</td><td>Automatic</td><td>Cross River Bank</td></tr><tr><td>120</td><td>Wire (CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>121</td><td>CIPS (CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>122</td><td>FPS (CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>123</td><td>CHATS (CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>124</td><td>SEPA(CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>125</td><td>BANK-TRANSFER(CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>126</td><td>PESONET(CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>127</td><td>FEDWIRE(CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>70</td><td>VelaFi Pending Fund</td><td>Automatic</td><td></td></tr><tr><td>19</td><td>Pix</td><td>Manual</td><td></td></tr><tr><td>27</td><td>Bank Transfer (Brazil)</td><td>Manual</td><td></td></tr><tr><td>28</td><td>Bank Transfer (Argentina)</td><td>Manual</td><td></td></tr><tr><td>29</td><td>Manual Bank Transfer (Mexico)</td><td>Manual</td><td></td></tr><tr><td>36</td><td>Mercantil</td><td>Manual</td><td></td></tr><tr><td>37</td><td>Bank Transfer (Venezuela)</td><td>Manual</td><td></td></tr><tr><td>38</td><td>Banco De Venezuela</td><td>Manual</td><td></td></tr><tr><td>39</td><td>Ubii Pagos</td><td>Manual</td><td></td></tr><tr><td>40</td><td>Banesco</td><td>Manual</td><td></td></tr><tr><td>41</td><td>Pago Movil</td><td>Manual</td><td></td></tr><tr><td>42</td><td>BNC Banco National De Credito</td><td>Manual</td><td></td></tr><tr><td>43</td><td>BBVA Provincial (Venezuela)</td><td>Manual</td><td></td></tr><tr><td>44</td><td>Bancamiga</td><td>Manual</td><td></td></tr><tr><td>45</td><td>Bancaribe</td><td>Manual</td><td></td></tr><tr><td>46</td><td>Banplus</td><td>Manual</td><td></td></tr><tr><td>47</td><td>Banco Activo</td><td>Manual</td><td></td></tr><tr><td>48</td><td>Bank Transfer (Colombia)</td><td>Manual</td><td></td></tr><tr><td>51</td><td>境內銀行轉賬 (台灣)</td><td>Manual</td><td></td></tr><tr><td>52</td><td>街口轉賬</td><td>Manual</td><td></td></tr><tr><td>53</td><td>LINE Pay</td><td>Manual</td><td></td></tr><tr><td>59</td><td>Bank Transfer (Perú)</td><td>Manual</td><td></td></tr><tr><td>60</td><td>Bank Transfer (Chile)</td><td>Manual</td><td></td></tr><tr><td>61</td><td>Manual USD Payments (CHATS)</td><td>Manual</td><td></td></tr><tr><td>64</td><td>Banque Msr UAE</td><td>Manual</td><td></td></tr><tr><td>67</td><td>Bank Transfer (Uruguay)</td><td>Manual</td><td></td></tr></tbody></table>

## Payment Method FAQ

| Payment method  | Region        | Currency | Direction                 | Account beneficiary         | Settlement time | Payin Conciliation Method              | Bank              | Features                    | Limits                                  | Tax                 | Status |
| --------------- | ------------- | -------- | ------------------------- | --------------------------- | --------------- | -------------------------------------- | ----------------- | --------------------------- | --------------------------------------- | ------------------- | ------ |
| ACH             | 🇺🇸US        | USD      | <p>Payin</p><p>Payout</p> | Partner                     | T+0 or +1       | Static Memo,Dynamic Memo               | Lead bank         |                             |                                         |                     | Live   |
| ACH             | 🇺🇸US        | USD      | Payin                     | User                        | T+0 or +1       | Virtual account/vIBAN                  | Lead bank         |                             |                                         |                     | Live   |
| Wire            | 🇺🇸US        | USD      | <p>Payin</p><p>Payout</p> | Partner                     | T+0             | Static Memo,Dynamic Memo               | Lead bank         |                             |                                         |                     | Live   |
| Wire            | 🇺🇸US        | USD      | Payin                     | User                        | T+0             | Virtual account/vIBAN                  | Lead bank         |                             |                                         |                     | Live   |
| CHATS           | 🇭🇰HK        | USD      | Payout                    | Partner                     | T+0             | N.A.                                   | DBS               | Ultimate remitter,Reference |                                         |                     | Live   |
| FPS             | 🇭🇰HK        | HKD      | Payout                    | Partner                     | T+0             | N.A.                                   | DBS               | Reference                   |                                         |                     | Live   |
| SWIFT           | 🇭🇰HK        | USD      | Payout                    | Partner                     | T+0 or +1       | N.A.                                   | DBS               | Ultimate remitter           |                                         |                     | Live   |
| SPEI            | 🇲🇽Mexico    | MXN      | <p>Payin</p><p>Payout</p> | User                        | Instant 24x7    | Virtual account/vIBAN                  | Arcus             | Reference                   |                                         |                     | Live   |
| CVU             | 🇦🇷Argentina | ARS      | <p>Payin</p><p>Payout</p> | User                        | Instant 24x7    | Virtual account/vIBAN                  | Momemtum Pagos    | Reference                   |                                         | IDC 60bps each side | Live   |
| PSE             | 🇨🇴Colombia  | COP      | Payin                     | Partner                     | Instant 24x7    | Dynamic Memo                           | N.A.              | Reference                   |                                         | GMF 40bps           | P1     |
| ACH             | 🇨🇴Colombia  | COP      | Payout                    | Velafi                      | T+0 or +1       | N.A.                                   | Banco Coopcentral | Reference                   |                                         | GMF Waived          | P1     |
| FastPay         | 🇨🇴Colombia  | COP      | Payout                    | <p>Partner</p><p>Velafi</p> | Instant 24x7    | N.A.                                   | Banco Coopcentral | Reference                   | 1 - 50,000,000 COP                      | GMF Waived          | P1     |
| Pix             | 🇧🇷Brazil    | BRL      | <p>Payin</p><p>Payout</p> | Velafi                      | Instant 24x7    | Static Memo,Dynamic Memo,Sender's info | Genial            | Reference                   |                                         |                     | P1     |
| Service Payment | 🇵🇪Peru      | PEN      | Payin                     | Partner                     | Instant 24x7    | Dynamic Memo                           | N.A.              | Reference                   | 1 - 50,000 PEN                          |                     | P1     |
| ACH             | 🇵🇪Peru      | PEN      | Payout                    | Partner                     | T+0 or +1       | N.A.                                   | N.A.              | Reference                   | SoF required for more than 10,000 soles |                     | P1     |


# Currencies

This section provides information about the various currencies supported by the API, including both cryptocurrencies and fiat currencies.&#x20;

### **Crypto Currencies**

| Currency Name  | Currency Code | Decimals | Protocol                     |
| -------------- | ------------- | -------- | ---------------------------- |
| Bitcoin        | BTC           | 8        | Bitcoin, Base                |
| Moneta Digital | MMXN          | 2        | ERC20, TRC20                 |
| USD Coin       | USDC          | 2        | ERC20, TRC20, BEP20, Polygon |
| Tether USD     | USDT          | 2        | ERC20, TRC20, BEP20, Polygon |

### **Fiat Currencies**

| Country            | Currency | Decimals |
| ------------------ | -------- | -------- |
| 🇦🇷 Argentina     | ARS      | 2        |
| 🇧🇷 Brazil        | BRL      | 2        |
| 🇨🇴 Colombia      | COP      | 2        |
| *🇭🇰* Hong Kong   | USD      | 2        |
| 🇲🇽 Mexico        | MXN      | 2        |
| 🇵🇪 Peru          | PEN      | 4        |
| 🇵🇪 Peru          | USD      | 2        |
| 🇺🇸 United States | EUR      | 2        |
| 🇺🇸 United States | USD      | 2        |


# Pair

This section provides information about the various trading pairs supported by the API, including block trade pairs and global payment pairs.

### **Block Trade Pair**

<table><thead><tr><th width="174">Country</th><th width="97">Fiat</th><th>Crypto</th><th width="103">Decimals</th><th>On-Ramp</th><th>Off-Ramp</th></tr></thead><tbody><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>BTC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇧🇷 Brazil</td><td>BRL</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇧🇷 Brazil</td><td>BRL</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇨🇴 Colombia</td><td>COP</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇨🇴 Colombia</td><td>COP</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇭🇰 Hong Kong</td><td>USD</td><td>MMXN</td><td>4</td><td>No</td><td>Yes</td></tr><tr><td>🇭🇰 Hong Kong</td><td>USD</td><td>USDC</td><td>4</td><td>No</td><td>Yes</td></tr><tr><td>🇭🇰 Hong Kong</td><td>USD</td><td>USDT</td><td>4</td><td>No</td><td>Yes</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>BTC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>MMXN</td><td>2</td><td>Yes</td><td>Yes</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇵🇪 Peru</td><td>PEN</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇵🇪 Peru</td><td>USD</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇺🇸 United States</td><td>EUR</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇺🇸 United States</td><td>EUR</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇺🇸 United States</td><td>USD</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇺🇸 United States</td><td>USD</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr></tbody></table>

### **Global Payment Pair**

<table><thead><tr><th width="167">Country From</th><th width="109">Fiat</th><th>Country To</th><th>Fiat</th><th>Decimals</th></tr></thead><tbody><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>🇲🇽 Mexico</td><td>MXN</td><td>4</td></tr><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>🇺🇸 United States</td><td>USD</td><td>8</td></tr><tr><td>🇧🇷 Brazil</td><td>BRL</td><td>🇦🇷 Argentina</td><td>ARS</td><td>4</td></tr><tr><td>🇧🇷 Brazil</td><td>BRL</td><td>🇭🇰 Hong Kong</td><td>USD</td><td>4</td></tr><tr><td>🇨🇴 Colombia</td><td>COP</td><td>🇲🇽 Mexico</td><td>MXN</td><td>2</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>🇦🇷 Argentina</td><td>ARS</td><td>4</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>🇨🇴 Colombia</td><td>COP</td><td>2</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>🇭🇰 Hong Kong</td><td>USD</td><td>4</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>🇺🇸 United States</td><td>USD</td><td>4</td></tr><tr><td>🇺🇸 United States</td><td>USD</td><td>🇦🇷 Argentina</td><td>ARS</td><td>4</td></tr><tr><td>🇺🇸 United States</td><td>USD</td><td>🇲🇽 Mexico</td><td>MXN</td><td>2</td></tr></tbody></table>


# Creating Webhook Listener

This interface is used to create a callback URL to receive notifications for specific events. Supported event types include order events and merchant trade events.&#x20;

### Interface Information

* **Request Header**: `Content-Type: application/json`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `POST`
* **Request Path**: `/openapi/v2/business/webhook`
* **Authorization Required**: Yes

### Request Parameters

| Parameter Name | Type   | Required | Description                                                                                                   |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| eventType      | string | Yes      | Event type, supported values: `ORDER_WEBHOOK` (order event), `MERCHANT_TRADE_WEBHOOK` (merchant trade event). |
| url            | string | Yes      | Callback URL for receiving event notifications.                                                               |

#### Request Example

```json
{
    "eventType": "ORDER_WEBHOOK",
    "url": "https://localhost/callback"
}
```

### Response Parameters

| Parameter Name | Type   | Description                                                                                      |
| -------------- | ------ | ------------------------------------------------------------------------------------------------ |
| code           | number | Response status code, `200` indicates success.                                                   |
| msg            | string | Response message, typically `SUCCESS`.                                                           |
| data           | object | Returned data object, containing the following fields:                                           |
| data.webhookId | string | Unique identifier for the callback URL.                                                          |
| data.eventType | string | Event type, confirming the event type specified in the request.                                  |
| data.url       | string | Merchant transfer callback URL.                                                                  |
| data.status    | number | Callback configuration status, supported values: `10` (active), `20` (disabled), `30` (deleted). |
| data.publicKey | string | (Optional) Public key of RSA-SHA256, used to verify push messages.                               |

#### Response Example

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
        "eventType": "ORDER_WEBHOOK",
        "url": "https://localhost/callback",
        "status": 1,
        "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGzXcqXbx6uA9PHQ3wGFgeBVEq0YpJxOSWpy4UmgBZ+fTOANiFyrODECWJoWIeJPOWkKR5VUseJTg57js3rgu/2Wn6Ihq1h+n6wCJEMCjK0Ia5brbQXtPcXCHK0J53hrt4YbxTzZuKUi7KIWO/Ply6xzYaTJeKzkaWlNDXF2VWBlutG+Pun3yXdWl7kTRENYA4mxXayaW0ELpnnLXF9qO01bAHPc2G8n0snqDiPMtz8Irw5MqlQ3YMjDiEDFLSb2aP9grae/o/LXZVNv0dJhV5IHgTJctDyFGz837BRiJZsBsodJK+3BTJhLsHqh6VAO8CSdQIDAQAB"
    }
}
```

### Notes

* Ensure that the provided callback URL is valid and capable of handling POST requests.
* The event type must be one of the supported types.
* The public key is an optional field, used only when verification of push messages is required.


# Fiat to Crypto (On-Ramp)

This section provides information about the fiat to crypto on-ramp process, allowing users to convert fiat currency into cryptocurrency through the API.

## **Create Order**

* **Request Header**: `Content-Type: application/json`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/fiat_to_crypto`
* **Authorization Required**: Yes

**Request Parameters**

The request body should include the following parameters:

| Parameter                                       | Type    | Required | Description                                                                      |
| ----------------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| country                                         | string  | Yes      | Name of the country (e.g., "Mexico")                                             |
| clientId                                        | string  | No       | An order ID that you may define and will be returned to you in a Get Order call. |
| merchantId                                      | number  | No       | ID of the merchant                                                               |
| crypto                                          | string  | Yes      | Name of the cryptocurrency (e.g., "USDT")                                        |
| fiat                                            | string  | Yes      | Name of the fiat currency (e.g., "MXN")                                          |
| fiatAmount                                      | decimal | Yes      | Amount of fiat currency to convert (e.g., 1000.00)                               |
| [paymentId](/velafi-1/guides/payment-method-id) | number  | Yes      | ID of the payment method                                                         |
| remark                                          | string  | No       | Additional remarks for the order                                                 |

**Request Example**

```json
{
    "country": "Mexico",
    "clientId": "xxxx",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "fiatAmount": 1000.00,
    "paymentId": 91,
    "remark": ""
}
```

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure that valid parameters are provided for successful order creation.
* The `merchantId` and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order, along with the order ID for tracking.


# Crypto to Fiat (Off-Ramp)

This section provides information about the crypto to fiat off-ramp process, allowing users to convert cryptocurrency into fiat currency through the API.&#x20;

## **Create Order**

* **Request Header**: `Content-Type: application/json`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/crypto_to_fiat`
* **Authorization Required**: Yes

**Request Parameters**

The request body should include the following parameters:

| Parameter                                                                  | Type    | Required | Description                                                                      |
| -------------------------------------------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| country                                                                    | string  | Yes      | Name of the country (e.g., "Mexico")                                             |
| clientId                                                                   | string  | No       | An order ID that you may define and will be returned to you in a Get Order call. |
| merchantId                                                                 | number  | No       | ID of the merchant                                                               |
| crypto                                                                     | string  | Yes      | Name of the cryptocurrency (e.g., "USDT")                                        |
| fiat                                                                       | string  | Yes      | Name of the fiat currency (e.g., "MXN")                                          |
| cryptoAmount                                                               | decimal | Yes      | Amount of fiat currency to convert (e.g., 1000.00)                               |
| [userPaymentId](/velafi-1/api-reference/payment-method/get-payment-method) | number  | Yes      | ID of the user payment method                                                    |
| remark                                                                     | string  | No       | Additional remarks for the order                                                 |

**Request Example**

```json
{
    "country": "Mexico",
    "clientId": "xxxx",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "cryptoAmount": 1000.00,
    "paymentId": 91,
    "remark": ""
}
```

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure that valid parameters are provided for successful order creation.
* The `merchantId` and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order, along with the order ID for tracking.


# Fiat to Fiat (Global Payment)

This section provides information about the fiat to fiat process, allowing users to convert fiat currency into cryptocurrency through the API.

## **Create Order**

* **Request Header**: `Content-Type: application/json`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/fiat_to_fiat`
* **Authorization Required**: Yes

**Request Parameters**

The request body should include the following parameters:

<table><thead><tr><th width="266">Parameter</th><th width="96">Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>clientId</td><td>string</td><td>No</td><td>Unique identifier for the client</td></tr><tr><td>onRampCountry</td><td>string</td><td>Yes</td><td>Name of the country (e.g., "Mexico")</td></tr><tr><td>onRampMerchantId</td><td>number</td><td>No</td><td>ID of the merchant</td></tr><tr><td>onRampFiat</td><td>string</td><td>Yes</td><td>Name of the fiat currency (e.g., "MXN")</td></tr><tr><td>onRampFiatAmount</td><td>decimal</td><td>Yes</td><td>Amount of fiat currency to convert (e.g., 1000.00)</td></tr><tr><td><a href="/pages/d6qFnm3pFqD22eQqFfoL">onRampPaymentId</a></td><td>number</td><td>Yes</td><td>ID of the payment method</td></tr><tr><td>offRampCountry</td><td>string</td><td>Yes</td><td>Name of the country (e.g., "Mexico")</td></tr><tr><td>offRampMerchantId</td><td>number</td><td>No</td><td>ID of the merchant</td></tr><tr><td>offRampFiat</td><td>decimal</td><td>Yes</td><td>Name of the fiat currency (e.g., "MXN")</td></tr><tr><td><a href="/pages/9Z3iWUBxVVRT9dUiaTQM">offRampPaymentId</a></td><td>number</td><td>Yes</td><td>ID of the payment method</td></tr><tr><td>remark</td><td>string</td><td>No</td><td>Additional remarks for the order</td></tr></tbody></table>

**Request Example**

```json

{
    "clientId": "xxxx",
    "onRampCountry": "Mexico",
    "onRampMerchantId": 12345,
    "onRampFiat": "MXN",
    "onRampFiatAmount": 1000.00,
    "onRampPaymentId": 91,
    "offRampCountry": "HONGKONG",
    "offRampMerchantId": 54321,
    "offRampFiat": "USD",
    "offRampPaymentId": 77,
    "remark": ""
}
```

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure to provide valid parameters for successful order creation.
* The `merchantId`  and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order along with the order ID for tracking.


# Basic Configuration


# API Endpoint

## **Production Environment**

<table><thead><tr><th width="191">Name</th><th width="289">Endpoint</th><th>Type</th></tr></thead><tbody><tr><td>Velafi</td><td><a href="https://api-business.trubit.com">https://api.velafi.com</a></td><td>rest-api</td></tr></tbody></table>

## **Sandbox**

<table><thead><tr><th>Name</th><th width="256">Endpoint</th><th>Type</th></tr></thead><tbody><tr><td>Velafi Sandbox</td><td><a href="https://api-test.velafi.com">https://api-test.velafi.com</a></td><td>rest-api</td></tr></tbody></table>


# Get List of Countries

This section details the API endpoint used to retrieve a list of countries. It provides options to filter the results based on their validity.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/countrys`

#### Request Parameters

**Query Parameters**

| Parameter  | Type    | Required | Description                                                                                                    |
| ---------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| hasFindAll | boolean | No       | Whether to query all countries (default is `false` for valid countries only). Use `true` to get all countries. |

#### Response Structure

The response will contain the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [{
        "country": "Mexico",  // Name of the country
        "abbr": "MX"          // ISO 3166-1 code of the country
    }]
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [
        {
            "country": "Mexico",
            "abbr": "MX"
        },
        {
            "country": "Argentina",
            "abbr": "AR"
        },
        {
            "country": "Brazil",
            "abbr": "BR"
        }
        // Additional countries may be included
    ]
}
```

### Notes

* By default, the API only returns valid countries unless `hasFindAll` is set to `true`.
* The response includes both the country name and its corresponding ISO 3166-1 code for easy reference.


# Get List of Fiat Currencies

This API retrieves a list of fiat currencies, along with their associated countries and trade accuracy.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/fiats`

#### Request Parameters

* **None**

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [{
        "country": "Mexico",  // (string: country of the currency)
        "fiat": "USD",        // (string: name of the currency)
        "accuracy": 6         // (number: accuracy of the trade)
    }]
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [
        {
            "country": "Mexico",
            "fiat": "MXN",
            "accuracy": 2
        },
        {
            "country": "United States",
            "fiat": "USD",
            "accuracy": 2
        }
        // Additional fiat currencies may be included
    ]
}
```

#### Notes

* The `country` field specifies the country associated with the fiat currency.
* The `fiat` field provides the name of the currency.
* The `accuracy` field indicates the precision of the currency's trade, typically representing the number of decimal places.


# Get List of Crypto Currencies

Crypto

This API retrieves a list of cryptocurrencies, along with their trade accuracy.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/cryptos`

#### Request Parameters

* **None**

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [{
        "crypto": "USDT",     // (string: name of the cryptocurrency)
        "accuracy": 6         // (number: accuracy of the trade)
    }]
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [
        {
            "crypto": "USDT",
            "accuracy": 6
        },
        {
            "crypto": "BTC",
            "accuracy": 8
        }
        // Additional cryptocurrencies may be included
    ]
}
```

#### Notes

* The `crypto` field specifies the name of the cryptocurrency.
* The `accuracy` field indicates the precision of the cryptocurrency's trade, typically representing the number of decimal places.


# Get Fiat/Crypto Pairs

This API retrieves a list of trading pairs that include both fiat currencies and cryptocurrencies, along with their trade accuracy.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/buy/symbols`

#### Request Parameters

* **None**

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [{
        "country": "Mexico",  // (string: country of the currency)
        "fiat": "USD",        // (string: name of the fiat currency)
        "crypto": "USDT",     // (string: name of the cryptocurrency)
        "accuracy": 2         // (number: accuracy of the trade)
    }]
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [
        {
            "country": "Mexico",
            "fiat": "MXN",
            "crypto": "BTC",
            "accuracy": 2
        },
        {
            "country": "United States",
            "fiat": "USD",
            "crypto": "ETH",
            "accuracy": 2
        }
        // Additional trading pairs may be included
    ]
}
```

#### Notes

* The `country` field specifies the country associated with the fiat currency.
* The `fiat` field provides the name of the fiat currency.
* The `crypto` field specifies the name of the cryptocurrency.
* The `accuracy` field indicates the precision of the trade, typically representing the number of decimal places.


# Get Crypto/Fiat Pairs

This API retrieves a list of trading pairs that include cryptocurrencies and fiat currencies, along with their trade accuracy.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/sell/symbols`

#### Request Parameters

* **None**

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [{
        "country": "Mexico",  // (string: country of the currency)
        "fiat": "USD",        // (string: name of the fiat currency)
        "crypto": "USDT",     // (string: name of the cryptocurrency)
        "accuracy": 2         // (number: accuracy of the trade)
    }]
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [
        {
            "country": "Mexico",
            "fiat": "MXN",
            "crypto": "USDT",
            "accuracy": 2
        },
        {
            "country": "United States",
            "fiat": "USD",
            "crypto": "USDT",
            "accuracy": 2
        }
        // Additional trading pairs may be included
    ]
}
```

#### Notes

* The `country` field specifies the country associated with the fiat currency.
* The `fiat` field provides the name of the fiat currency.
* The `crypto` field specifies the name of the cryptocurrency.
* The `accuracy` field indicates the precision of the trade, typically representing the number of decimal places.


# Get Fiat/Fiat Pairs

#### Get Fiat/Fiat Trading Pairs

This API retrieves a list of trading pairs that include fiat currencies, along with their trade accuracy.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/fiat/symbols`

#### Request Parameters

* **None**

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [{
        "onRampCountry": "Mexico",  // (string: Name of the country (e.g., "Mexico"))
        "onRampFiat": "MXN",        // (string: Name of the fiat currency (e.g., "MXN"))
        "offRampCountry": "HONG KONG",  // (string: Name of the country (e.g., "Mexico"))
        "offRampFiat": "USD",           // (string: Name of the fiat currency (e.g., "MXN"))
        "accuracy": 2              // (number: accuracy of the trade)
    }]
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [
        {
            "onRampCountry": "Mexico",  
            "onRampFiat": "MXN",       
            "offRampCountry": "Argentina", 
            "offRampFiat": "ARS",
            "accuracy": 2
        },
        {
            "onRampCountry": "United States",
            "onRampFiat": "USD",
            "offRampCountry": "Mexico",
            "offRampFiat": "MXN",
            "accuracy": 2
        }
        // Additional trading pairs may be included
    ]
}
```

#### Notes

* The `onRampCountry` field specifies the country associated with the originating fiat currency.
* The `onRampFiat` field provides the name of the originating fiat currency.
* The `offRampCountry` field specifies the country associated with the recipient fiat currency.
* The `offRampFiat` field provides the name of the recipient fiat currency.
* The `accuracy` field indicates the precision of the trade, typically representing the number of decimal places.


# Get Fiat/Crypto Payment Methods

This API retrieves the supported payment methods for a given fiat and cryptocurrency trading pair.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/buy/payments`

#### Request Parameters

The request should include the following fields:

```json
{
    "country": "Mexico",  // (string: country of the currency)
    "fiat": "USD",        // (string: name of the fiat currency)
    "crypto": "USDT"      // (string: name of the cryptocurrency)
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": { 
        "country": "Mexico",   // (string: country of the currency)
        "fiat": "USD",         // (string: name of the fiat currency)
        "crypto": "USDT",      // (string: name of the cryptocurrency)
        "paymentList": [
            { 
                "paymentId": 1,        // (string: Payment method template ID)
                "fiatFee": "2.00",     // (decimal: Fiat fee amount, unit is block)
                "paymentType": 1        // (enum: type of the payment method [0: manual, 1: automatic])
            }
        ]
    }
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "country": "Mexico",
        "fiat": "USD",
        "crypto": "USDT",
        "paymentList": [
            {
                "paymentId": 1,
                "fiatFee": "2.00",
                "paymentType": 1
            },
            {
                "paymentId": 2,
                "fiatFee": "1.50",
                "paymentType": 0
            }
            // Additional payment methods may be included
        ]
    }
}
```

#### Notes

* The `country` field specifies the country associated with the fiat currency.
* The `fiat` field provides the name of the fiat currency.
* The `crypto` field specifies the name of the cryptocurrency.
* The `paymentList` contains various payment methods supported for the specified trading pair.
* The `paymentId` is a unique identifier for each payment method.
* The `fiatFee` indicates the fee amount in fiat currency.
* The `paymentType` indicates whether the payment method is manual (0) or automatic (1).


# Get Crypto/Fiat Payment Methods

This API retrieves the supported payment methods for a given cryptocurrency and fiat trading pair.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/sell/payments`

#### Request Parameters

The request should include the following fields:

```json
{
    "country": "Mexico",  // (string: country of the currency)
    "fiat": "USD",        // (string: name of the fiat currency)
    "crypto": "USDT"      // (string: name of the cryptocurrency)
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": { 
        "country": "Mexico",   // (string: country of the currency)
        "fiat": "USD",         // (string: name of the fiat currency)
        "crypto": "USDT",      // (string: name of the cryptocurrency)
        "paymentList": [
            { 
                "paymentId": 1,        // (string: Payment method template ID)
                "fiatFee": "2.00",     // (decimal: Fiat fee amount, unit is block)
                "paymentType": 1        // (enum: type of the payment method [0: manual, 1: automatic])
            }
        ]
    }
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "country": "Mexico",
        "fiat": "USD",
        "crypto": "USDT",
        "paymentList": [
            {
                "paymentId": 1,
                "fiatFee": "2.00",
                "paymentType": 1
            },
            {
                "paymentId": 2,
                "fiatFee": "1.50",
                "paymentType": 0
            }
            // Additional payment methods may be included
        ]
    }
}
```

#### Notes

* The `country` field specifies the country associated with the fiat currency.
* The `fiat` field provides the name of the fiat currency.
* The `crypto` field specifies the name of the cryptocurrency.
* The `paymentList` contains various payment methods supported for the specified trading pair.
* The `paymentId` is a unique identifier for each payment method.
* The `fiatFee` indicates the fee amount in fiat currency.
* The `paymentType` indicates whether the payment method is manual (0) or automatic (1).


# Get Fiat/Fiat Payment Methods

This API retrieves the supported payment methods for converting one fiat currency to another, including the details for both the originating and recipient currencies.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/base/fiat/payments`

#### Request Parameters

The request should include the following fields:

```json
{
    "onRampCountry": "Mexico",  // (string: Name of the country (e.g., "Mexico"))
    "onRampFiat": "MXN",        // (string: Name of the fiat currency (e.g., "MXN"))
    "offRampCountry": "Argentina",  // (string: Name of the country (e.g., "Argentina"))
    "offRampFiat": "ARS"           // (string: Name of the fiat currency (e.g., "ARS"))
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": { 
        "onRampCountry": "Mexico",  // (string: Name of the country (e.g., "Mexico"))
        "onRampFiat": "MXN",        // (string: Name of the fiat currency (e.g., "MXN"))
        "offRampCountry": "Argentina",  // (string: Name of the country (e.g., "Argentina"))
        "offRampFiat": "ARS",           // (string: Name of the fiat currency (e.g., "ARS"))
        "paymentListFrom": [        // (array: list of supported payment methods for the originating currency)
            { 
                "paymentId": 1,        // (string: Payment method template ID)
                "fiatFee": "2",         // (decimal: Fiat fee amount, unit is block)
                "paymentType": 1        // (enum: type of the payment method [0: manual, 1: automatic])
            }
        ],
        "paymentListTo": [          // (array: list of supported payment methods for the recipient currency)
            { 
                "paymentId": 1,        // (string: Payment method template ID)
                "fiatFee": "2",         // (decimal: Fiat fee amount, unit is block)
                "paymentType": 1        // (enum: type of the payment method [0: manual, 1: automatic])
            }
        ]
    }
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "onRampCountry": "Mexico",
        "onRampFiat": "MXN",
        "offRampCountry": "Argentina",
        "offRampFiat": "ARS",
        "paymentListFrom": [
            {
                "paymentId": 1,
                "fiatFee": "2",
                "paymentType": 1
            },
            {
                "paymentId": 2,
                "fiatFee": "1.50",
                "paymentType": 0
            }
        ],
        "paymentListTo": [
            {
                "paymentId": 1,
                "fiatFee": "2",
                "paymentType": 1
            },
            {
                "paymentId": 3,
                "fiatFee": "1.75",
                "paymentType": 0
            }
        ]
    }
}
```

#### Notes

* The `countryFrom` field specifies the country associated with the originating fiat currency.
* The `fiatFrom` field provides the name of the originating fiat currency.
* The `countryTo` field specifies the country associated with the recipient fiat currency.
* The `fiatTo` field provides the name of the recipient fiat currency.
* The `paymentListFrom` contains various payment methods supported for the originating fiat currency.
* The `paymentListTo` contains various payment methods supported for the recipient fiat currency.
* The `paymentId` is a unique identifier for each payment method.
* The `fiatFee` indicates the fee amount in fiat currency.
* The `paymentType` indicates whether the payment method is manual (0) or automatic (1).


# Upload File

This API allows you to upload invoices for a specific merchant kyc/kyb file.

Request Header: `X-BH-TOKEN: ******`

* Request Header: `Content-Type: multipart/form-data`
* Request Method: `POST`
* Request Path: `/v2/base/file/upload`
* Authorization: Required

Form **Parameters**

* **businessType**: (Required, string) The type of business is currently fixed as FIAT\_ACCOUNT
* **files**: (Required, file) Upload multiple files. The maximum number of uploaded files is 5, with each file range (min 10KB - max 3M). Supported formats are \[jpg, png, jpeg, pdf].

**Response Structure**The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [
        {
            "fileName": "id-front.jpg", //The original name of the file
            "fileType": "jpg", //The type of the document
            "fileUrl": "1172300499489225472/f97d9f9b-641a-4245-8d99-aa4788015e38.jpg", //Relative file path
            "tempFileUrl": "https://chats-images-files.s3.ap.amazonaws.com/8d99-aa4788015e38.jpg?x-amz-security-token=IQoJb3JpZ2luX2VjE" //Temporary file path check
        }
    ]
}
```

**Notes**

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* Check that the uploaded files meet the specified requirements (number, size, and format).


# Account


# Get Account Details

Account

This API allows you to retrieve the details of a user's account.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/user/account`
* **Authorization Required**: Yes

#### Response Structure

The response will include the following fields:

```json
{
  "code": 200,                      // (number: response code)
  "msg": "SUCCESS",                 // (string: message)
  "data": {                         // (object: account details)
    "userId": 0,                    // (number: user ID)
    "country": "",                  // (string: name of the country)
    "companyName": "",              // (string: name of the company)
    "kycPassed": false,             // (boolean: whether the user passed KYC)
    "buyAmountLimit": 0.0,          // (number: buy amount limit)
    "buyAmountUsed": 0.0,           // (number: buy amount used)
    "sellAmountLimit": 0.0,         // (number: sell amount limit)
    "sellAmountUsed": 0.0            // (number: sell amount used)
  }
}
```

#### Example Response

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "userId": 1,
    "country": "Argentina",
    "companyName": "velafi",
    "kycPassed": true,
    "buyAmountLimit": 250000.0,
    "buyAmountUsed": 0.0,
    "sellAmountLimit": 250000.0,
    "sellAmountUsed": 0.0
  }
}
```

#### Notes

* Ensure that you include the necessary authorization tokens in the request headers for successful execution.
* The `kycPassed` field indicates whether the user has completed the KYC (Know Your Customer) process.


# Merchant


# Create Merchant

Create a legal individual or business entity (Merchant) to operate under Velafi's compliance framework.

* Submit your detailed merchant information to initiate the KYC/KYB compliance verification process.
* Upon successful verification, the platform will assign a unique Merchant ID (MID) to you or your client.

Upon a successful API request, the response will include a unique URL that redirects the user to a secure KYC/KYB verification page. You may choose to:

* Redirect users directly to the provided URL to complete their verification process, or
* Embed the verification flow within your front-end application using an `<iframe>`, offering a seamless user experience.

Please ensure that the URL is used promptly, as it may be subject to expiration or session constraints depending on the configuration.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/v2/merchants`
* **Authorization Required**: Yes

#### Request Parameters

The request body should include the following fields:

**For New Merchant**

```json
{     
    "merchantName": "Tom", //(required, string: Merchant Name (Unique))
    "email": "tom@gmail.com", //(required, string: Email (Unique))
    "merchantType": "INDIVIDUAL", //(required, string: Merchant Type [INDIVIDUAL, BUSINESS])
    "callbackUrl": "https://localhost", //(required, string: URL for KYC/KYB completion callback)
    "languageCode": "en", //(optional, string: Interface language (en(default)/es/pt/zh))
    "flow": "PROFESSIONALS", //(optional, string: The KYC process is applicable only to INDIVIDUAL. enum [PROFESSIONALS(default), CONSUMERS])
    "remark": "test" //(optional, string: Remark)
}
```

**For Unverified Merchant**

```json
{
    "merchantId": 15126673, //(required, number: id of the merchant)
    "callbackUrl": "https://localhost", //(required, string: URL for KYC/KYB completion callback)
    "languageCode": "en" //(optional, string: Interface language (en(default)/es/pt/zh))
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "merchantId": 15126673, //(number: id of the merchant)
        "kycLink": "https://www.velafi.com/verify?velafi_token=abc123" //(string: Link for conducting KYC/KYB verification)
    }
}
```

#### Example Requests

**Example Request (New Merchant)**

```json
{     
    "merchantName": "Tom", 
    "email": "tom@gmail.com", 
    "merchantType": "BUSINESS", 
    "callbackUrl": "https://localhost", 
    "languageCode": "en", 
    "remark": "add tom merchant"
}
```

**Example Request (Unverified Merchant)**

```json
{
    "merchantId": 15126673, 
    "callbackUrl": "https://localhost", 
    "languageCode": "en"
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "merchantId": 15126673,
        "kycLink": "https://www.velafi.com/business/token=_act-sbx-jwt-eyJhbGciOiJub25lIn0.eyJqdGkiOiJfYWN0LXNieC0xNGY3YWE4MS1kMTRjLTRmN2ItYTZmYy0xMzA4NWJiN2Y4MWUtdjIiLCJ1cmwiOiJodHRwczovL2FwaS5zdW1zdWIuY29tIn0.-v2&merchant_type=PERSONAL&callback_url=https%3A%2F%2F"
    }
}
```


# Get a List of Merchants

This API retrieves a list of merchants based on optional query parameters.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/merchants`
* **Authorization Required**: Yes

#### Query Parameters

* **merchantName**: (string) The name of the merchant (optional).
* **email**: (string) The email of the merchant (optional).
* **currentPage**: (int) The current page number (optional).
* **pageSize**: (int) The number of results per page (default is 10, maximum is 1000).

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "currentPage": 1,                  // (number: current page number)
        "size": 10,                         // (number: number of results per page)
        "total": 100,                       // (number: total number of results)
        "data": [                           // (array: list of merchants)
            {    
                "merchantId": 1,            // (number: id of the merchant)
                "country": "Mexico",        // (string: name of the country)
                "merchantName": "Rrturo Tellez", // (string: name of the merchant)
                "email": "tellez@gmail.com", // (string: email of the merchant)
                "merchantType": 1,          // (number: merchant type [1: INDIVIDUAL, 2: BUSINESS])
                "status": 1,                 // (enum: status of the merchant [1: authenticating, 2: normal, 3: authentication failed, 4: incomplete])
                "remark": "",                // (string: Remark)
                "createTime": "1737452292000", // (string: timestamp of the create time (milliseconds))
                "updateTime": "1737452344000" // (string: timestamp of the update time (milliseconds))
            }
        ]
    }
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "currentPage": 1,
        "size": 10,
        "total": 100,
        "data": [
            {
                "merchantId": 1,
                "country": "Mexico",
                "merchantName": "Rrturo Tellez",
                "email": "tellez@gmail.com",
                "merchantType": 2,
                "remark": "",
                "createTime": "1737452292000",
                "updateTime": "1737452344000"
            },
            {
                "merchantId": 2,
                "country": "Argentina",
                "merchantName": "Tom",
                "email": "tom@gmail.com",
                "merchantType": 1,
                "remark": "",
                "createTime": "1737452292001",
                "updateTime": "1737452344001"
            }
            // Additional merchants may be included
        ]
    }
}
```

#### Notes

* The `currentPage` field indicates the page of results currently being returned.
* The `size` field shows the number of results returned per page.
* The `total` field indicates the total number of merchants available based on the query.
* Each merchant object includes relevant details, such as ID, country, name, email, type, and timestamps for creation and updates.


# Activate Merchant Account

This endpoint is used to activate a merchant's fiat currency payment account. Supported currencies include MXN, ARS, COP, BRL,PEN,USD, and EUR. Once activated, merchants can send and receive funds through local banking channels with increased flexibility and efficiency.

* Each merchant will receive dedicated account details (e.g., ARS accounts include CVU number / CUIT for Argentina).
* Merchants can deposit funds via wire transfer; VelaFi will automatically reconcile the transaction and credit the merchant’s account balance.
* Both business and individual account types are supported, enabling broad use across various payment scenarios.
* Note: Once a EUR account is activated, it enables the merchant to operate with both EUR and USD currencies simultaneously.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/v2/merchant/accounts`
* **Authorization Required**: Yes

#### Request Parameters

The request body should include the following fields:

**For MXN Account (ARCUS FI)**

```json
{    
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "MXN", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/PEN/USD/EUR])   
    "trench": "ARCUS FI", //"trench": "Account_Lead Bank", //(required, string: trench [Account_Lead Bank/Wire - Standard Charted Bank]) 
    "fieldList": { // List of channel fields
        "email": "rturo@gmail.com", // (optional, string: Email, if the merchant information is not provided, it must be filled in)
        "idNoType": "CURP", //(required, enum: type of identification document [CURP/RFC])
        "idNo": "MACM000502IR6",//(required, string: identity number)
        "cardIssueDate": "2019-06-01", // (required, string: Card Issue Date (yyyy-MM-dd))
        "cardExpireDate": "2029-06-01", // (required, string: Card Expiry Date (yyyy-MM-dd))
        "address": "Celle Lagu Wenner 50", // (required, string: Address)
        "city": "Ciudad de Mexico", // (required, string: City)
        "state": "CMX", // (required, string: State)
        "zipCode": "09060", // (required, string: Zip Code)
        "phone": "35580481683", // (required, string: Phone)
        
        "companyName": "Rrturo Tellez", // (string: Company Name, required if merchantType is BUSINESS)
        "aliasName": "Rrturo", // (string: Alias Name, required if merchantType is BUSINESS)
        "companyType": "SC", // (string: Company Type, required if merchantType is BUSINESS)
        "incorporationDate": "2019-02-01", // (string: Incorporation Date (yyyy-MM-dd), required if merchantType is BUSINESS)
    
        "birthday": "1988-07-02", // (string: Birthday (yyyy-MM-dd), required if merchantType is INDIVIDUAL)
        "name": "Tellez", // (string: Name, required if merchantType is INDIVIDUAL)
        "fatherSurname": "Rrturo", // (string: Father's Surname, required if merchantType is INDIVIDUAL)
        "motherSurname": "" // (string: Mother's Surname, required if merchantType is INDIVIDUAL)
    }
}
```

**For MXN Account (FINCO PAY)**

```json
{    
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "MXN", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/PEN/USD/EUR])   
    "trench": "FINCO PAY", //(required, string: trench [FINCO PAY])     
    "fieldList": { // List of channel fields
        "alias": "rrturo_alias", // (required, string: alias)
    }
}
```

**For ARS Account (Argentina)**

```json
{
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "ARS", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/PEN/USD/EUR])
    "fieldList": { // List of channel fields
        "email": "rturo@gmail.com", // (optional, string: Email, if the merchant information is not provided, it must be filled in)
        "cuit": "30708424478", // (required, string: CUIT)
        "name": "COCOS CAPITAL SA", // (required, string: Full Name)
        "alias": "soc.te" // (optional, string: Alias)
    }
}
```

**For COP Account (Colombia)**

```json
{
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "COP", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/PEN/USD/EUR])
    "fieldList": { // List of channel fields
        "alias": "soc.te" // (required, string: Alias)
    }
}
```

**For BRL Account (Brazil)**

```json
{
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "BRL", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/PEN/USD/EUR])   
}
```

**For PEN Account (Peru)**

```json
{
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "PEN", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/PEN/USD/EUR])
    "fieldList": { // List of channel fields
        "customerIdentificationType": "00", // (required, string: identification type[00:CC (8 digits), 01:CE (>9 digits), 02:Tax ID (11 digits), 03:PAS (>9 digits), 04:PAR, 05:LMI])
        "customerIdentification": "12345678", // (required, string: identification number)
        "customerName": "Tom", // (required, string: name)
        "lastName": "", // (optional, string: surname, The merchant type must be selected as "Individual" for this field.)
        "customerEmail": "tom@gmai.com", // (required, string: email)
        "customerPhone": "975728895" // (required, string: phone number)       
    }
}
```

**For EUR/USD Account\_Lead Bank**

After the EUR currency account is activated, it can be used for both EUR and USD transactions.

```json
{
    "merchantId": "15126673", // (required, number: id of the merchant)
    "fiat": "EUR", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/USD/EUR]) 
    "trench": "Account_Lead Bank", //(required, string: trench [Account_Lead Bank/Wire - Standard Charted Bank]) 
    "fieldList": { // List of channel fields
        "email": "rturo@gmail.com", // (optional, string: Email, if the merchant information is not provided, it must be filled in)
        "companyName": "CAPITAL SA COCOS", // (string: Company Name, required if merchantType is BUSINESS)
        "firstName": "CAPITAL SA", // (string: First Name, required if merchantType is INDIVIDUAL)
        "lastName": "COCOS" // (string: Last Name, required if merchantType is INDIVIDUAL)
    }
}
```

**For USD Business Wire - Standard Charted Bank**

```json
{ 
  "merchantId": "15126673", // (required, number: id of the merchant)
  "fiat": "USD", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/USD/EUR])
  "trench": "Wire - Standard Charted Bank", //(required, string: trench [Account_Lead Bank/Wire - Standard Charted Bank]) 
  "callbackUri": "https://localhost/home", //(string: callback address after accepting the agreement)
  "fieldList": { // List of channel fields  
    "companyInfo": { // Company information (required when Merchant Type BUSINESS)
      "companyName": "Example Corp",         // Full company name (required)
      "companyDescription": "A fintech company providing payment solutions",  // Company description (required)
      "companyIndustry": "FINANCIAL_SERVICES",  // Industry type (Financial Services)(required)
      "email": "contact@example.com",        // Company contact email (required)
      "phoneNumber": "+15551234567",      // Company contact phone number (required)
      "incorporationDate": "2015-06-15",     // Company registration date (required)
      "taxType": "EIN",                      // Tax ID type [EIN/SSN/VAT/TIN/UTR](required)
      "taxId": "123456789",                // Tax ID (required)   
      "website": "https://www.example.com",  // Company website (required)
      "street1": "123 Main St",              // Street address 1 (required)
      "street2": "Suite 100",                // Street address 2
      "city": "New York",                    // City (required)
      "state": "NY",                         // State/Province (required)
      "postcode": "10001",                   // Postal code (required)
      "countryAbbr": "US",                   // Country code (required)
      "legalPresenceUrl": "example-corp/articles.pdf",  // Company registration document (required), size between 10KB - 3MB, Upload File endpoint: /v2/base/file/upload
      "ownershipStructure": "example-corp/ownership.pdf"  // Ownership structure proof (required), size between 10KB - 3MB, Upload File endpoint: /v2/base/file/upload
    },  
    "companyUbosInfo": [ // List of company Ultimate Beneficial Owners (UBO) (required when merchantType=2)
      {
        "personType": "UBO",                // Person type (UBO=Ultimate Beneficial Owner)(required)
        "firstName": "John",                // First name (required)
        "lastName": "Smith",                // Last name (required)
        "email": "john.smith@example.com",  // Email (required)
        "phone": "+15559876543",         // Contact phone number (required)
        "percentageOfOwnership": 0.65,       // Ownership percentage (65%)(required)
        "taxIdentificationNumber": "987654321",  // Personal tax ID (SSN)(required)
        "dateOfBirth": "1980-03-15",        // Date of birth (required), age must be between 18 and 120 years.
        "street": "456 Oak Ave",            // Street address (required)
        "street2": "",                      // Street address 2
        "city": "Brooklyn",                 // City (required)
        "state": "NY",                      // State/Province (required)
        "postcode": "11201",               // Postal code (required)
        "countryAbbr": "US",                // Country code (required)
        "idType": "3",                      // ID type [1:ID card, 2:Driver's license, 3:Passport/Residence permit](required)
        "idNumber": "P12345678",            // ID number (required)
        "govIdCountryAbbr": "US",           // ID issuing country (required)
        "govIdFrontUrl": "john-smith/passport-front.jpg",  // ID front side (required), size between 10KB - 3MB, Upload File endpoint: /v2/base/file/upload     
        "govIdBackUrl": "john-smith/passport-back.jpg",    // ID back side (required), size between 10KB - 3MB, Upload File endpoint: /v2/base/file/upload     
        "hasControl": true,                 // Has control rights (required)
        "hasOwnership": true,               // Has ownership rights (required)
        "hasSigner": true,                  // Is signatory (required), at least one must be true
        "relationshipEstablishedAt": "2015-06-15"  // Relationship establishment date (required)
      }
    ], 
    "companyQuestionnaireInfo": {  // Company questionnaire information (required when merchantType=2)
      "tradeName": "Example Payments",      // Trade name (required)
      "industryType": "cooperative",  // Industry subdivision (required)[cooperative/s_corporation/b_corporation/close_corporation/nonprofit_corporation/general_partnership/limited_partnership/limited_liability_company/other/sole_proprietorship/trust]
      "organizationalChartUrl": "example-corp/org-chart.pdf",  // Organizational chart (required), size between 10KB - 3MB, Upload File endpoint: /v2/base/file/upload
      "estimatedAnnualRevenueUsd": "100000_999999",  // Estimated annual revenue (USD)(required)[0_99999/100000_999999/1000000_9999999/10000000_49999999/50000000_249999999/250000000_plus]
      "expectedMonthlyPaymentsUsd": "500000",   // Expected monthly transaction volume (USD)(required)
      "highRiskActivities": "none_of_the_above",  // High-risk activities[none_of_the_above/adult_entertainment/gambling/hold_client_funds/investment_services/lending_banking/marijuana_or_related_services/money_services/operate_foreign_exchange_virtual_currencies_brokerage_otc/safe_deposit_box_rentals/third_party_payment_processing/weapons_firearms_and_explosives]
      "purposeOfAccount": "charitable_donations",    // Account purpose (required)[charitable_donations/ecommerce_retail_payments/investment_purposes/operating_a_company/other/payments_to_friends_or_family_abroad/personal_or_living_expenses/protect_wealth/purchase_goods_and_services/receive_payment_for_freelancing/receive_salary]
      "sourceOfFunds": "business_loans",       // Source of funds (required)[business_loans/grants/inter_company_funds/investment_proceeds/legal_settlement/owners_capital/pension_retirement/sale_of_assets/sales_of_goods_and_services/tax_refund/third_party_funds/treasury_reserves]
      "transmitsCustomerFunds": true,            // Handles customer funds (required)
      "transmitsCustomerFundsDescription": "We process payments for merchants"  // Funds handling description (required)
    }
  }
}
```

**For USD Individual Wire - Standard Charted Bank**

```json
{
  "merchantId": "15126673", // (required, number: id of the merchant)
  "fiat": "MXN", // (required, string: name of the fiat currency [MXN/ARS/COP/BRL/USD/EUR])
  "trench": "Account_Cross River Bank", //(required, string: trench [Account_Lead Bank/Wire - Standard Charted Bank]) 
  "callbackUri": "https://localhost/home", //(string: callback address after accepting the agreement)
  "fieldList": { // List of channel fields  
    "personalInfo": { // Personal information (required when when Merchant Type INDIVIDUAL)
      "firstName": "tom",                    // First name (pinyin or English)(required)
      "lastName": "fr",                     // Last name (pinyin or English)(required)
      "phone": "+12570000000",         // Personal phone number (with country code)(required)
      "email": "tom@example.com",      // Personal email (required)
      "taxIdentificationNumber": "31010119800000000",  // Personal tax ID/ID card number (required)
      "nationality": "US",                  // Nationality code (China)(required)
      "dateOfBirth": "1980-10-10",          // Date of birth (YYYY-MM-DD)(required), age must be between 18 and 120 years.
      "street1": "example street1",       // Street address (required)
      "street2": "",                       // Street address 2
      "city": "New City",                       // City (required)
      "state": "AZ",                        // Province/State code (required)
      "postcode": "901203",                 // Postal code (required)
      "countryAbbr": "US",                  // Country code (required)
      "idType": "1",                        // ID type [1:ID card, 2:Driver's license, 3:Passport/Residence permit](required)
      "idNumber": "31010119800000000",     // ID number (required)
      "govIdCountryAbbr": "US",             // ID issuing country (required)
      "govIdFrontUrl": "user-654321/id-front.jpg",  // ID front side (required), size between 10KB - 3MB, Upload File endpoint: /v2/base/file/upload   
      "govIdBackUrl": "user-654321/id-back.jpg"     // ID back side (required), size between 10KB - 3MB, Upload File endpoint: /v2/base/file/upload  
    },
    "personalQuestionnaireInfo": {   // Personal questionnaire information (required when merchantType=1)
      "actingAsIntermediary": false,        // Acting as intermediary (false=No)(required)
      "employmentStatus": "employed",      // Employment status (required)[employed/homemaker/retired/self_employed/student/unemployed]
      "expectedMonthlyPayments": "5000_9999",    // Expected monthly transaction volume (USD)(required)[0_4999/5000_9999/10000_49999/50000_plus]
      "purposeOfAccount": "charitable_donations",  // Account purpose (required)[charitable_donations/ecommerce_retail_payments/investment_purposes/operating_a_company/other/payments_to_friends_or_family_abroad/personal_or_living_expenses/protect_wealth/purchase_goods_and_services/receive_payment_for_freelancing/receive_salary]
      "occupation": "132011",   // Occupation (required), see list below: occupation codes
      "sourceOfFunds": "salary"   // Source of funds (required)[company_funds/ecommerce_reseller/gambling_proceeds/gifts/government_benefits/inheritance/investments_loans/pension_retirement/salary/sale_of_assets_real_estate/savings/someone_elses_funds]
    }
  }
}

occupation codes:
132011:Accountant and auditor
272011:Actor
152011:Actuary
172021:Agricultural engineer
132031:Budget analyst
412010:Cashier
172041:Chemical engineer
499091:Coin, vending, and amusement machine servicer and repairer
271021:Commercial and industrial designer
273041:Editor
472111:Electrician
434071:File clerk
131111:Management analyst
119199:Manager, other
191040:Medical scientist
195010:Occupational health and safety specialist and technician
27102X:Other designer
2912XX:Other physician
5191XX:Other production worker
519151:Photographic process worker and processing machine operator
211029:Social worker, other
132081:Tax examiner and collector, and revenue agent
151254:Web developer
515111:Prepress technician and worker
273042:Technical writer
172199:Engineer, other
433099:Financial clerk, other
1320XX:Other financial specialist
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "MXN", // (string: name of the fiat currency [MXN/USD/EUR]) 
        "status": 1, // (enum: status of the channel [1: authenticating, 2: normal, 3: authentication failed, 4: incomplete])
        "failReason": "", //（string: cause of failure)
        "verifyLink": "" // (string: Verified link, only through the IBAN channel is it possible)
    }
}
```

#### Example Requests

**Example Request (MXN)**

```json
{    
    "fiat": "MXN",
    "merchantId": 15126673,
    "fieldList": { 
        "email": "rturo@gmail.com", 
        "idNoType": "CURP",
        "idNo": "MACM000502IR6",
        "cardIssueDate": "2019-06-01",
        "cardExpireDate": "2029-06-01",
        "address": "Celle Lagu Wenner 50", 
        "city": "Ciudad de Mexico",
        "state": "CMX",
        "zipCode": "09060",
        "phone": "35580481683",
        
        "companyName": "Rrturo Tellez",
        "aliasName": "Rrturo",
        "companyType": "SC",
        "incorporationDate": "2019-02-01",
    
        "birthday": "1988-07-02", 
        "name": "Tellez",
        "fatherSurname": "Rrturo",
        "motherSurname": ""
    }
}
```

**Example Request (ARS)**

```json
{
    "fiat": "ARS",
    "merchantId": 15126673,
    "fieldList": {
        "email": "rturo@gmail.com",
        "cuit": "30708424478",
        "name": "COCOS CAPITAL SA",
        "alias": "soc.te"
    }
}
```

**Example Request (BRL)**

```json
{
    "merchantId": "15126673", 
    "fiat": "BRL"
}
```

**Example Request (COP )**

```json
{
    "merchantId": "15126673", 
    "fiat": "COP",
    "fieldList": { 
        "alias": "soc.te" 
    }
}
```

**Example Request (PEN)**

```json
{
    "merchantId": "15126673",
    "fiat": "PEN", 
    "fieldList": { 
        "customerIdentificationType": "00", 
        "customerIdentification": "12345678",
        "customerName": "Tom",
        "lastName": "", 
        "customerEmail": "tom@gmai.com",
        "customerPhone": "975728895"     
    }
}
```

**Example Request (USD)**

```json
{
    "fiat": "USD",
    "merchantId": "15126673",
    "fieldList": {
        "email": "rturo@gmail.com",
        "companyName": "CAPITAL SA COCOS"       
    }
}
```

#### Example Responses

**Example Response (MXN/ARS/COP/BRL/PEN)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "MXN",
        "status": 1,
        "failReason": ""        
    }
}
```

**Example Response (USD)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "USD",
        "status": 4,
        "verifyLink": "https://www.vealfi-test.com/business/channel/verify?token=12ceff08f9621808b5a573972cdfb10f",
        "failReason": ""        
    }
}
```

#### Notes

* Ensure that all fields in the request body are filled out correctly to facilitate the activation process.
* Merchants may need to provide additional documentation based on the type of account being activated.


# Get a List of Merchant Accounts

This API retrieves a list of accounts associated with merchants based on optional query parameters.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/merchant/accounts`
* **Authorization Required**: Yes

#### Query Parameters

* **merchantId**: (int) The ID (MID) associated with the Merchant (optional).
* **merchantName**: (string) The name of the merchant (optional).
* **email**: (string) The email of the merchant (optional).
* **fiat**: (string) The fiat currency (optional).
* **status**: (int) The status of the merchant \[1: authenticating, 2: normal, 3: authentication failed] (optional).
* **currentPage**: (int) The current page number (optional).
* **pageSize**: (int) The number of results per page (default is 10, maximum is 1000).

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "currentPage": 1,                  // (number: current page number)
        "size": 10,                         // (number: number of results per page)
        "total": 100,                       // (number: total number of results)
        "data": [                           // (array: list of merchant accounts)
            {   
                "merchantId": 1,            // (number: id of the merchant)
                "fiat": "MXN",               // (string: name of the fiat currency)
                "balance": "100.00",         // (decimal: amount of Merchant balance)
                "status": 1,                 // (enum: status of the merchant [1: authenticating, 2: normal, 3: authentication failed, 4: incomplete])
                "buyAmountLimit": "0",       // (number: from amount limit of the fiat currency)
                "buyAmountUsed": "2000.00",  // (number: from amount used of the fiat currency)
                "sellAmountLimit": "10000.00", // (number: to amount limit of the fiat currency)
                "sellAmountUsed": "0",       // (number: to amount used of the fiat currency)
                "paymentId": 58,             // (number: ID of the payment configuration)
                "paymentMethodName": "Automated SPEI - Arcus", // (string: name of the payment method)
                "createTime": "1737452292000", // (string: timestamp of the create time (milliseconds))
                "updateTime": "1737452344000" // (string: timestamp of the update time (milliseconds))
            }
        ]
    }
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "currentPage": 1,
        "size": 10,
        "total": 100,
        "data": [
            {
                "merchantId": 1,
                "fiat": "MXN",
                "balance": "100.00",
                "status": 2,
                "buyAmountLimit": "0",
                "buyAmountUsed": "2000.00",
                "sellAmountLimit": "10000.00",
                "sellAmountUsed": "0",
                "paymentId": 58, 
                "paymentMethodName": "Automated SPEI - Arcus",
                "createTime": "1737452292000",
                "updateTime": "1737452344000"
            },
            {
                "merchantId": 2,
                "fiat": "ARS",
                "balance": "500.00",
                "status": 1,
                "buyAmountLimit": "1000.00",
                "buyAmountUsed": "500.00",
                "sellAmountLimit": "20000.00",
                "sellAmountUsed": "1000.00",
                "paymentId": 63, 
                "paymentMethodName": "Automated Bank Transfer",
                "createTime": "1737452292001",
                "updateTime": "1737452344001"
            }
            // Additional merchant accounts may be included
        ]
    }
}
```

#### Notes

* The `currentPage` field indicates the page of results currently being returned.
* The `size` field shows the number of results returned per page.
* The `total` field indicates the total number of merchant accounts available based on the query.
* Each account object includes relevant details such as merchant ID, fiat currency, balance, status, limits, and timestamps for creation and updates.


# Get Pending Fund Account

This endpoint allows you to retrieve information about your VelaFi Pending Fund account,  With this information, you can pre-load funds into the Pending Fund account in advance. Pre-funding your account enables faster transactions, as you won't need to wait for external transfers to be confirmed at the time of trading.

**Endpoint Information**

* **Request Header:** `X-BH-TOKEN: ******`
* **Request Method:** GET
* **Request Path:** `/v2/merchant/addfunds`
* **Authorization Required:** Yes

**Query Parameters**

* **merchantId:** (int) The merchant ID.
* **paymentId:** (int) The payment ID. Currently supported payment IDs are：
  * 58 (Automated SPEI - Arcus) - MXN
  * 105 (SPEI - FINCO PAY) - MXN
  * 63 (Automated Bank Transfer (Argentina)) - ARS
  * 68 (PSE) - COP
  * 90 (Automated Pix) - BRL
  * 81/82/83/84 (ACH\_push/ACH\_Virtual Accoun/WIRE/WIRE\_Virtual Account) - USD
  * 85 (SEPA) - EUR
  * 95 (Automated Bank Transfer(Peru)) - PEN
* **fiat:** (string) Name of the fiat currency. Currently supported currencies are MXN/ARS/COP/BRL/PEN/USD/EUR.
* **amount**: (decimal) The deposit amount. When the currency is PEN, it is mandatory.

**Response Structure**

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {  
        "paymentMethodName": "Paypal",  // (string: name of the payment method)
        "fieldList": {                   // (object: list of fields related to the payment method)
            "fieldName1": ["value1", "value2"], // (string: array of values for fieldName1)
            "fieldName2": ["value1", "value2"]  // (string: array of values for fieldName2)
        }
    }
}
```

**Example Responses**

**Example for Payment ID 58:**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {  
        "fiat": "MXN",
        "paymentMethodName": "Automated SPEI - Arcus",
        "fieldList": {
             "Cuenta CLABE": "706180304649761358",          
             "Beneficiary Name": "Rrturo Tellez"
        }
    }
}
```

**Example for Payment ID 105:**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {  
        "fiat": "MXN",
        "paymentMethodName": "SPEI - FINCO PAY",
        "fieldList": {            
             "Cuenta CLABE": "706180304649761358",           
        }
    }
}
```

**Example for Payment ID 63:**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {  
        "fiat": "ARS",
        "paymentMethodName": "Automated Bank Transfer (Argentina)",
        "fieldList": {
             "CVU number": "0000775900000000000086",
             "CUIT": "20339698695"            
        }
    }
}
```

**Example for Payment ID 68:**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {   
        "fiat": "COP",
        "paymentMethodName": "PSE",       
        "fieldList": {
            "alias": "soc.ce",
            "paymentLink": "https://links.velaif.co/zAOCe"
        }
    }
}
```

**Example for Payment ID 81/82/83/84:**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "USD",
        "paymentMethodName": "ACH_push",
        "realName": "",
        "fieldList": {
            "Deposit Message": "BRGJT5PNSZX636P9EC2D",
            "Bank Account Number": "11223344556672",
            "Bank Routing Number": "123456790",
            "Bank Beneficiary Name": "Ventures Inc",
            "Bank Name": "Bank of Nowhere",
            "Bank Address": "1800 North Pole St., Orlando, FL 32803"
        }
    }
}
```

**Example for Payment ID 85:**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "fiat": "EUR",
        "paymentMethodName": "SEPA",
        "realName": "",
        "fieldList": {
            "Deposit Message": "BRGJT5PNSZX636P9EC2D",
            "BIC/Swift Code": "123456790",
            "IBAN": "11223344556672",
            "Bank Beneficiary Name": "Ventures Inc",
            "Bank Name": "Bank of Nowhere",
            "Bank Address": "1800 North Pole St., Orlando, FL 32803"
        }
    }
}
```

**Example for Payment ID 90:**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {   
        "fiat": "BRL",
        "paymentMethodName": "Automated Pix",       
        "fieldList": {  
            "Chave Pix - Random Pix": "09a3b1d1-49d6-4820-bd19-53e7f50ee13c",
            "Pix copia e cola": "00020101021126580014br.gov.bcb.pix013865755...",        
            "Pix QR Code": "https://links.qrcode.co/zAOCe/3471397f291c28d19.png"
        }
    }
}
```

**Example for Payment ID 95:**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {   
        "fiat": "PEN",
        "paymentMethodName": "Automated Bank Transfer(Peru)",       
        "fieldList": {                   
            "paymentLink": "https://links.velaif.co/zEOCb"
        }
    }
}
```

#### Notes

* The `paymentMethodName` field indicates the name of the payment method associated with the pending funds.
* The `fieldList` object contains various fields relevant to the payment method, where each key is a field name and the value is an array of associated values.


# Claim Pending Fund

This endpoint enables you to withdraw the available balance from your VelaFi Fund account to your specified payment method. Withdrawals can be initiated at any time, allowing for flexible and timely fund management.

**Endpoint Information**

* **Request Header:** `X-BH-TOKEN: ******`
* **Request Header:** `Content-Type: application/json`
* **Request Method:** POST
* **Request Path:** `/v2/merchant/claimfunds`
* **Authorization Required:** Yes

**Request Parameters**

The request body should include the following fields:

```json
{         
    "merchantId": 3,           // (number: ID of the merchant) required 
    "clientId": "1748536001",  // (string: An order ID that you may define and it is the only one) optional
    "fiat": "MXN",             // (string: name of the fiat currency; MXN and ARS are currently supported) required 
    "amount": 20.00,           // (decimal: fiat amount) required 
    "userPaymentId": 91        // (number: ID of the user payment method; obtainable via GET /v2/payments) required    
} 
```

**Response Structure**

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "txId": 1123123123,       // (number: ID of the fiat withdraw)        
        "merchantId": 3,          // (number: ID of the merchant)
        "clientId": "1748536001", // (string: ID of the client)
        "fiat": "MXN",            // (string: name of the fiat currency) 
        "totalAmount": 22.00,     // (decimal: total fiat amount)
        "amount": 20.00,          // (decimal: actual fiat amount)
        "fee": 2.00,              // (decimal: amount of the fee)
        "userPaymentId": 91,      // (number: ID of the user payment method) 
        "status": 1,              // (enum: status [1: pending, 2: completed, 3: canceled])       
        "createTime": "1737452292000" // (string: timestamp of the create time in milliseconds) 
    }
}
```

**Example Request**

```json
{         
    "merchantId": 3,
    "clientId": "1748536001",
    "fiat": "MXN", 
    "amount": 20.00, 
    "userPaymentId": 91
} 
```

**Example Response**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "txId": 1123123123,      
        "merchantId": 3,
        "clientId": "1748536001",
        "fiat": "MXN",
        "totalAmount": 22.00, 
        "amount": 20.00, 
        "fee": 2.00, 
        "userPaymentId": 91,
        "status": 1,    
        "createTime": "1737452292000"
    }
}
```

#### Notes

* Ensure to provide valid parameters for successful order creation.
* The response will confirm the successful creation of the order along with the `txId` for tracking.


# Get Transfer Pending Funds Fee

This endpoint can obtain the transaction fees for inter-merchant transfers. The fee models include fixed fee and percentage fee.

Endpoint Information

* Request Header: `X-BH-TOKEN: ******`
* Request Method: `GET`
* Request Path: `/v2/merchant/transfer_fee`
* Authorization Required: Yes

\
Parameters

* `fiat`: (Required, String) - Fiat currency, Currently supports MXN and ARS

#### Response Structure

The response will return the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {        
        "fiat": "MXN",     //string: Fiat currency         
        "feeType": 1,      //int: Transfer fee type [0: Fixed fee, 1: Percentage fee]
        "fee": 0.01,       //decimal: Transfer fee value (in percentage format, the range is from 0 to 1) 
    }
}
```

#### Example Response (Fixed)

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {        
        "fiat": "MXN",
        "feeType": 1, 
        "fee": 0.01,
    }
}
```

#### Example Response (Percentage)

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {        
        "fiat": "MXN",
        "feeType": 0,
        "fee": 5,
    }
}
```

#### Notes

* Supported Fiat Currencie&#x73;**:** Currently supports MXN (Mexican Peso) and ARS (Argentine Peso).
* The `feeType` There are two types of this:
  * Fixed Fee (`feeType=0`): A set flat rate applied to each transaction.
  * Percentage Fee (`feeType=1`): A variable fee calculated as a percentage of the transfer amount.


# Transfer Pending Funds

This endpoint allows merchants to transfer funds internally from one merchant account to another within the VelaFi system. It enables seamless movement of balance for operational or accounting purposes.

#### Endpoint Information

* **Request Header:** `X-BH-TOKEN: ******`
* **Request Header:** `Content-Type: application/json`
* **Request Method:** POST
* **Request Path:** `/v2/merchant/transfer`
* **Authorization Required:** Yes

#### Request Parameters

The request body must include the following fields:

<pre class="language-json"><code class="lang-json"><strong>{         
</strong>    "clientId": "test01",        // (string: custom client-defined ID for tracking) required  
    "fromMerchantId": 434,       // (number: ID of the sender merchant) required  
    "toMerchantId": 5,           // (number: ID of the recipient merchant) required  
    "fiat": "MXN",               // (string: Name of the fiat currency (e.g., "MXN","ARS")) required  
    "paymentId": 58,             // (number: Payment ID (e.g., 58,63,68,90,95)) required  
    "fiatAmount": 10             // (decimal: amount to transfer) required  
} 
</code></pre>

#### Response Structure

The response will return the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "clientId": "test01",             // (string: client-defined ID for the transaction)
        "fromId": 521006138624569344,     // (number: Funding Records ID)
        "toId": 521006138641346560,       // (number: Funding Records ID)
        "fiat": "MXN",                    // (string: token used in transfer)
        "fiatAmount": "10",               // (string: transferred amount)
        "totalFiatAmount": "12",          // (string: total transferred amount)
        "fee": "2",                       // (string: transferred fee amount)
        "createTime": 1746694343261       // (number: timestamp of transaction creation in milliseconds)
    }
}
```

#### Example Request （MXN）

```json
{         
    "clientId": "test-mxn",
    "fromMerchantId": 434,
    "toMerchantId": 5,
    "fiat": "MXN",
    "paymentId": 58,
    "fiatAmount": 10
} 
```

#### Example Response (MXN)

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "clientId": "test-mxn",
        "fromId": 521006138624569344,
        "toId": 521006138641346560,
        "fiat": "MXN",
        "fiatAmount": "10",
        "totalFiatAmount": "10",
        "fee": "0",
        "createTime": 1746694343261
    }
}
```

#### Example Request （ARS）

```json
{         
    "clientId": "test-ars",
    "fromMerchantId": 434,
    "toMerchantId": 5,
    "fiat": "ARS",
    "paymentId": 63,
    "fiatAmount": 10
} 
```

#### Example Response (ARS)

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "clientId": "test-ars",
        "fromId": 521006138624569345,
        "toId": 521006138641346561,
        "fiat": "ARS",
        "fiatAmount": "10",
        "totalFiatAmount": "10",
        "fee": "0",
        "createTime": 1746694343261
    }
}
```

#### Example Request （COP）

```json
{         
    "clientId": "test-cop",
    "fromMerchantId": 15127301,
    "toMerchantId": 15127302,
    "fiat": "COP",
    "paymentId": 68,
    "fiatAmount": 10
} 
```

#### Example Response (COP)

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "clientId": "test-cop",
        "fromId": 521006138624569346,
        "toId": 521006138624569347,
        "fiat": "COP",
        "fiatAmount": "10",
        "totalFiatAmount": "10",
        "fee": "0",
        "createTime": 1746694343261
    }
}
```

#### Example Request （BRL）

```json
{         
    "clientId": "test-brl",
    "fromMerchantId": 15127301,
    "toMerchantId": 15127302,
    "fiat": "BRL",
    "paymentId": 90,
    "fiatAmount": 10
} 
```

#### Example Response (BRL)

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "clientId": "test-brl",
        "fromId": 521006138624569348,
        "toId": 521006138624569349,
        "fiat": "BRL",
        "fiatAmount": "10",
        "totalFiatAmount": "10",
        "fee": "0",
        "createTime": 1746694343261
    }
}
```

#### Example Request （PEN）

```json
{         
    "clientId": "test-pen",
    "fromMerchantId": 15127301,
    "toMerchantId": 15127302,
    "fiat": "PEN",
    "paymentId": 95,
    "fiatAmount": 10
} 
```

#### Example Response (PEN)

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "clientId": "test-pen",
        "fromId": 521006138624569350,
        "toId": 521006138624569351,
        "fiat": "PEN",
        "fiatAmount": "10",
        "totalFiatAmount": "10",
        "fee": "0",
        "createTime": 1746694343261
    }
}
```

#### Notes

* Ensure that all provided IDs (merchantId, paymentId) are valid and active.
* The `clientId` can be used by clients to trace or de-duplicate requests.
* This operation is only valid for merchant accounts with sufficient balance.
* Supported fiat currency are:
  * `MXN` (Mexican Peso): use `paymentId = 58`
  * `ARS` (Argentine Peso): use `paymentId = 63`
  * `COP` (Colombia Peso): use `paymentId = 68`
  * `BRL` (Brazil Peso): use `paymentId = 90`
  * `PEN` (Peru Peso): use `paymentId = 95`


# Retrieve Funding Records

This endpoint provides a detailed history of your Pending Fund activity, including deposits, usage, and withdrawals. It helps you maintain full transparency and traceability over your fund operations.

**Endpoint Information**

* **Request Header:** `X-BH-TOKEN: ******`
* **Request Method:** GET
* **Request Path:** `/v2/merchant/funding/records`
* **Authorization Required:** Yes

**Query Parameters**

The following query parameters can be used:

* **startTime:** (long) The start time (in milliseconds).
* **endTime:** (long) The end time (in milliseconds).
* **merchantId:** (int) The ID of the merchant.
* **fiat:** (string) The fiat currency.
* **type:** (string) The transaction type. Options include:
  * `ALL` (default)
  * `DEPOSIT`: The addition of the funding record
  * `WITHDRAW`: The claim of the funding record
  * `BUY_CRYPTO`: The purchase of cryptocurrency
  * `REFUND`: The refund of the funding record
  * `TRANSFER_IN`: The internal transfer of funds between merchants into the account
  * `TRANSFER_OUT`: The internal transfer of funds between merchants out of the account
* **status:** (int) The status. Options include:
  * `0` (all, default)
  * `1`: pending
  * `2`: completed
  * `3`: canceled
* **clientId:** (string) The ID of the client.
* **currentPage:** (int) The current page number (default is 1).
* **pageSize:** (int) The number of results per page (default is 10, maximum is 1000).

**Response Structure**

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "currentPage": 1,         // (number: current page number)
        "size": 10,               // (number: number of results per page)
        "total": 100,             // (number: total number of results)   
        "data": [                 // (array: list of funding records)
            {
                "txId": 1123123123,   // (number: ID of the fiat withdraw)               
                "merchantId": 3,      // (number: ID of the merchant)
                "merchantName": "Rrturo Tellez", // (string: name of the merchant)
                "fiat": "MXN",         // (string: name of the fiat currency) 
                "totalAmount": 22.00,  // (decimal: total fiat amount)
                "amount": 20.00,       // (decimal: actual fiat amount)
                "fee": 2.00,           // (decimal: amount of the fee)
                "userPaymentId": 91,   // (number: ID of the user payment method) 
                "type": "DEPOSIT",     // (enum: transaction type)
                "status": 1,           // (enum: status [1: pending, 2: completed, 3: canceled])               
                "createTime": "1737452292000", // (string: timestamp of creation in milliseconds)
                "updateTime": "1737452344000"  // (string: timestamp of update in milliseconds)
            }
            // Additional funding records may be included
        ]
    }
}
```

**Example Response**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "currentPage": 1,
        "size": 10,
        "total": 100,
        "data": [
           {
                "txId": 1123123123,         
                "merchantId": 3,
                "merchantName": "Rrturo Tellez",
                "fiat": "MXN", 
                "totalAmount": 22.00, 
                "amount": 20.00, 
                "fee": 2.00,
                "userPaymentId": 91,
                "type": "DEPOSIT",
                "status": 1, 
                "createTime": "1737452292000", 
                "updateTime": "1737452344000"
            }
            // Additional funding records may be included
        ]
    }
}
```

#### Notes

* The `currentPage` field indicates the page of results currently being returned.
* The `size` field shows the number of results returned per page.
* The `total` field indicates the total number of funding records available based on the query.
* Each transaction object includes relevant details such as transaction ID, merchant ID, merchant name, fiat currency, total amount, actual amount, fee, type, status, and timestamps for creation and updates.


# Get Crypto Assets Balance

This API allows you to retrieve the balances of cryptocurrency assets in a user's account.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/assets/account/assets`
* **Authorization Required**: Yes

#### Query Parameters

* **merchantId**: (int) The ID of the merchant. If `0`, the API will return the **aggregated balances** across all merchants linked to this user.

#### Response Structure

The response will include the following fields:

```json
{
  "code": 200,                      // (number: response code)
  "msg": "SUCCESS",                 // (string: message)
  "data": {                         // (object: account asset details)
    "canDeposit": false,            // (boolean: whether the account can deposit)
    "balances": [                   // (array: list of asset balances)
      {
        "asset": "",                // (string: name of the asset)
        "assetId": "",              // (string: ID of the asset)
        "assetName": "",            // (string: display name of the asset)
        "total": "",                // (string: total amount of the asset)
        "free": "",                 // (string: free amount of the asset)
        "locked": ""                // (string: locked amount of the asset)
      }
    ]
  }
}
```

#### **Example Response (Specific Merchant)**

**Request:**

```
GET /v2/assets/account/assets?merchantId=12345
X-BH-TOKEN: ******
```

**Response:**

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "canDeposit": true,
    "balances": [
      {
        "asset": "USDT",
        "assetId": "USDT",
        "assetName": "USDT",
        "total": "1000",
        "free": "800",
        "locked": "200"
      },
      {
        "asset": "BTC",
        "assetId": "BTC",
        "assetName": "BTC",
        "total": "0.5",
        "free": "0.3",
        "locked": "0.2"
      }
    ]
  }
}
```

***

#### **Example Response (Aggregated Across All Merchants)**

**Request:**

```
GET /v2/assets/account/assets?merchantId=0
X-BH-TOKEN: ******
```

**Response:**

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "canDeposit": true,
    "balances": [
      {
        "asset": "USDT",
        "assetId": "USDT",
        "assetName": "USDT",
        "total": "5000",
        "free": "4000",
        "locked": "1000"
      },
      {
        "asset": "BTC",
        "assetId": "BTC",
        "assetName": "BTC",
        "total": "2",
        "free": "1.5",
        "locked": "0.5"
      }
    ]
  }
}
```

***

#### **Notes**

&#x20;**`canDeposit` field:**\
Indicates whether the account supports deposits at this time.

&#x20;**`merchantId=0` special case:**\
When `merchantId` is `0`, the API aggregates balances across **all merchants** bound to the same account and returns the combined amounts for each asset.


# Get Crypto Deposit Address

This API allows you to retrieve the balances of cryptocurrency assets in a user's account.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/assets/depositAddress`
* **Authorization Required**: Yes

#### Query Parameters

* **tokenId**: (String) - ID of the token
* **chainType** (String) - Type of the blockchain (default: "")
* **merchantId**: (int) The ID of the merchant.

| tokenId | ChainType | Chain Full Name |
| ------- | --------- | --------------- |
| USDT    | TRC20     | Tron            |
| USDT    | ERC20     | Ethereum        |
| USDT    | BEP20     | BNB Smart Chain |
| USDT    | POL       | Polygon         |

#### Response Structure

The response will include the following fields:

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "allowDeposit": false, (boolean: whether the deposit is allowed)
    "address": "", (string: address of the deposit)
    "addressExt": "", (string: address tag)
    "minQuantity": "", (string: minimum amount of the deposit)
    "needAddressTag": false, (boolean: whether the address tag is required)
    "requiredConfirmNum": 0, (number: required confirmation number)
    "canWithdrawConfirmNum": 0, (number: maximum confirmation number)
    "tokenType": "" (string: type of the token)
  }
}
```

#### Example Response

tokenId: USDT\
chainType: TRC20

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "allowDeposit": true,
    "address": "TT5PSvrhxXjw2NZNu1S8L5ybwYVxCkQRKC",
    "addressExt": "",
    "minQuantity": "5",
    "needAddressTag": false,
    "requiredConfirmNum": 12,
    "canWithdrawConfirmNum": 20,
    "tokenType": "TRX_TOKEN"
  }
}
```

####


# Crypto Transfer

### This API allows you to transfer crypto assets internally between merchants.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/v2/assets/internalTransfer`
* **Authorization Required**: Yes

#### **Request Body Parameters**

The request body should include the following fields:

```json
{
  "fromMerchantId": 0,   // (number: ID of the sender merchant)
  "toMerchantId": 0,     // (number: ID of the recipient merchant)
  "tokenId": "",           // (string: token symbol, e.g., USDT,USDC,BTC,MMXN)
  "amount": 0,           // (number: amount to transfer)
  "clientId": ""         // (string: client ID for tracking, optional)
}
```

***

#### **Authorization**

This request requires valid authorization via `X-BH-TOKEN`.

***

#### **Response Structure**

The response will include the following fields:

```json
{
  "code": 0,                // (number: response code)
  "msg": "",                // (string: response message)
  "data": {
    "id": "",               // (string: unique ID of the transfer record)
    "tokenId": "",           // (string: token symbol)
    "amount": "",     // (string: transferred amount, negative means debit)
    "clientId": "",         // (string: client ID)
    "merchantId": "",       // (string: ID of the sender merchant)
    "fromMerchantId": "",   // (string: same as merchantId, sender)
    "toMerchantId": ""      // (string: recipient merchant ID)
  }
}
```

***

#### **Example Request**

```json
{
  "fromMerchantId": 246,
  "toMerchantId": 61,
  "tokenId": "USDT",
  "amount": 10,
  "clientId": "1"
}
```

***

#### **Example Response**

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "id": "4352",
    "tokenId": "USDT",
    "amount": "-10",
    "clientId": "1",
    "merchantId": "246",
    "fromMerchantId": "246",
    "toMerchantId": "61"
  }
}
```

***

✅ **Note:**

* The `amount` is negative on the sender side, indicating a debit.


# Query Crypto Transfers

### This API allows you to query internal transfer orders between merchants.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `GET`
* **Request Path**: `/v2/assets/internalTransferOrders`
* **Authorization Required**: Yes

***

#### **Query Parameters**

The request URL may include the following query parameters:

<table><thead><tr><th>Parameter</th><th width="216">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>tokenId</code></td><td>string</td><td>(optional) Token symbol, e.g., <code>USDT</code>.</td></tr><tr><td><code>clientId</code></td><td>string</td><td>(optional) Client ID for filtering.</td></tr><tr><td><code>startTime</code></td><td>number</td><td>(optional) Start timestamp (in ms).</td></tr><tr><td><code>endTime</code></td><td>number</td><td>(optional) End timestamp (in ms).</td></tr><tr><td><code>pageSize</code></td><td>number</td><td>(optional) Number of records per page.</td></tr><tr><td><code>merchantId</code></td><td>number</td><td>(optional) Merchant ID to query records for.</td></tr></tbody></table>

***

#### **Authorization**

This request requires valid authorization via `X-BH-TOKEN`.

***

#### **Response Structure**

The response will include the following fields:

```json
{
  "code": 0,             // (number: response code)
  "msg": "",             // (string: response message)
  "data": [              // (array: list of transfer records)
    {
      "id": "",             // (string: unique ID of the transfer record)
      "tokenId": "",         // (string: token symbol)
      "amount": "",   // (string: transferred amount)
      "clientId": "",       // (string: client ID)
      "merchantId": "",     // (string: merchant ID of this record)
      "fromMerchantId": "", // (string: sender merchant ID)
      "toMerchantId": ""    // (string: recipient merchant ID)
    }
  ]
}
```

***

#### **Example Request**

```
GET /v2/assets/internalTransferOrders?tokenId=&clientId=&startTime=0&endTime=0&pageSize=10&merchantId=
```

***

#### **Example Response**

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "id": "4355",
      "tokenId": "USDT",
      "amount": "10",
      "clientId": "1",
      "merchantId": "61",
      "fromMerchantId": "246",
      "toMerchantId": "61"
    },
    {
      "id": "4354",
      "tokenId": "USDT",
      "amount": "-10",
      "clientId": "1",
      "merchantId": "246",
      "fromMerchantId": "246",
      "toMerchantId": "61"
    }
  ]
}
```

***

✅ **Note:**

* Positive `amount` indicates credit to the receiving merchant.
* Negative `amount` indicates debit from the sending merchant.
* `merchantId` indicates which merchant the current record belongs to.


# Quote


# Get User Quote for Crypto/Fiat

This API retrieves the current price quote for a specific cryptocurrency to fiat currency conversion.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/user/crypto-quote`
* **Authorization Required**: Yes

#### Query Parameters

* **country**: (string) The country for which the quote is requested.
* **from**: (string) The cryptocurrency token symbol (e.g., USDT).
* **to**: (string) The fiat currency symbol (e.g., MXN).

#### Authorization

This request requires authorization.

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "price": "0.0"  // (string: price of the cryptocurrency in the specified fiat currency)
    }
}
```

#### Example Request

For example, to get the price of USDT in Mexican Pesos (MXN):

* **country**: Mexico
* **from**: USDT
* **to**: MXN

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "price": "21.3707"
    }
}
```

#### Example Request

For example, to get the price of Mexican Pesos (MXN) in USDT:

* **country**: Mexico
* **from**: MXN
* **to**: USDT

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "price": "0.05"
    }
}
```

####

#### Notes

* The `price` field represents the current conversion rate from the specified cryptocurrency to the fiat currency.
* Ensure that valid authorization tokens are included in the request headers for successful execution.
* This `price` is for reference only and does not guarantee consistency with the order price.

  <br>


# Get User Quote for Fiat/Fiat

This API retrieves the current exchange rate for converting one fiat currency to another.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/user/fiat-quote`
* **Authorization Required**: Yes

#### Query Parameters

* **onRampCountry**: (string) Name of the country (e.g., "Mexico"))
* **onRampFiat**: (string) Name of the fiat currency (e.g., "MXN"))
* **offRampCountry**: (string) Name of the country (e.g., "Argentina"))
* **offRampFiat**: (string) Name of the fiat currency (e.g., "ARS"))

#### Authorization

This request requires authorization.

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "price": "0.0"  // (string: price of the first fiat currency in terms of the second fiat currency)
    }
}
```

#### Example Request

For example, to get the exchange rate from Mexican Pesos (MXN) to Argentine Pesos (ARS):

* **onRampCountry**: Mexico
* **onRampFiat**: MXN
* **offRampCountry**: Argentina
* **offRampFiat**: ARS

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "price": "56.14266017"
    }
}
```

#### Example Request

For example, to get the exchange rate from Argentine Pesos (ARS) to Mexican Pesos (MXN):

* **onRampCountry**: Argentina
* **onRampFiat**: ARS
* **offRampCountry**: Mexico
* **offRampFiat**: MXN

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "price": "0.0160686"
    }
}
```

#### Notes

* The `price` field represents the current exchange rate from the specified first fiat currency to the second fiat currency.
* Ensure that valid authorization tokens are included in the request headers for successful execution.
* This `price` is for reference only and does not guarantee consistency with the order price.

  <br>


# Payment Method


# Get Payment Templates

#### Get Payment Method Templates

This API retrieves the template details for various payment methods based on the provided payment method ID.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/payments/templates`
* **Authorization Required**: Yes

#### Query Parameters

* **paymentId**: (int) The ID of the payment method.

#### Authorization

This request requires authorization.

#### Payment ID Lists

| Payment ID | Name                                | Type      |
| ---------- | ----------------------------------- | --------- |
| 58         | Automated SPEI - Arcus              | Automatic |
| 105        | SPEI - FINCO PAY                    | Automatic |
| 63         | Automated Bank Transfer (Argentina) | Automatic |
| 68         | PSE/ACH                             | Automatic |
| 77         | SWIFT (HK)                          | Automatic |
| 78         | CHATS                               | Automatic |
| 79         | FPS                                 | Automatic |
| 81         | ACH\_push                           | Automatic |
| 82         | ACH\_Virtual Account                | Automatic |
| 83         | WIRE                                | Automatic |
| 84         | WIRE\_Virtual Account               | Automatic |
| 90         | Automated Pix                       | Automatic |
| 95         | Automated Bank Transfer(Peru)       | Automatic |
| 111        | ACH Account\_Cross River Bank       | Automatic |
| 113        | WIRE Account\_Cross River Bank      | Automatic |
| 115        | SWIFT Account\_Cross River Bank     | Automatic |
| 19         | Pix                                 | Manual    |
| 27         | Bank Transfer (Brazil)              | Manual    |
| 28         | Bank Transfer (Argentina)           | Manual    |
| 29         | Manual Bank Transfer (Mexico)       | Manual    |
| 36         | Mercantil                           | Manual    |
| 37         | Bank Transfer (Venezuela)           | Manual    |
| 38         | Banco De Venezuela                  | Manual    |
| 39         | Ubii Pagos                          | Manual    |
| 40         | Banesco                             | Manual    |
| 41         | Pago Movil                          | Manual    |
| 42         | BNC Banco National De Credito       | Manual    |
| 43         | BBVA Provincial (Venezuela)         | Manual    |
| 44         | Bancamiga                           | Manual    |
| 45         | Bancaribe                           | Manual    |
| 46         | Banplus                             | Manual    |
| 47         | Banco Activo                        | Manual    |
| 48         | Bank Transfer (Colombia)            | Manual    |
| 51         | 境內銀行轉賬 (台灣)                         | Manual    |
| 52         | 街口轉賬                                | Manual    |
| 53         | LINE Pay                            | Manual    |
| 59         | Bank Transfer (Perú)                | Manual    |
| 60         | Bank Transfer (Chile)               | Manual    |
| 61         | Manual USD Payments (CHATS)         | Manual    |
| 64         | Banque Msr UAE                      | Manual    |
| 67         | Bank Transfer (Uruguay)             | Manual    |

#### Response Structure

The response will include the following fields:

```json
{
    "code": 0,                            // (number: response code)
    "msg": "",                            // (string: message)
    "data": {                             // (object: template fields)
        [string]: [string]                // (key-value pairs of template fields)
    }
}
```

#### Example Responses

**Example:**

**Mexico Bank (58: Automated SPEI - Arcus)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "CLABE number": "",
        "Account number/card": "",
        "Beneficiary Name": ""
    }
}
```

**Mexico Bank (105: SPEI - FINCO PAY)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Account Type": "",
	"Account Number": "",
	"Beneficiary Name": "",
	"Bank Code": ""     
    }
}

Account Type: enum [clabe: VA account, debit: card account]
Bank Code: Bank code is required to be filled in only when the account type is "debit". See Mexico FINCO PAY Bank Codes.
```

**Argentina Bank (63: Automated Bank Transfer (Argentina))**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "CVU number": "",
        "cuit": "",
        "Bank name": ""
    }
}
```

**SEPA (Payment Type 2)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Bank Name": "",
        "Account Owner Name": "",
        "Account Owner Type": "",
        "Bank Country/Region": "",
        "Account Number": "",
        "Bic": "",
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}
Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.

Bank Country/Region is ISO 3166-1
```

**WIRE/ACH/SWIFT (ES) (Payment Type 2)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Bank Name": "",
        "Account Owner Name": "",
        "Account Owner Type": "",
        "Bank Country/Region": "",
        "Account Number": "",
        "Routing Number": "",
        "Street Line1": "",
        "Street Line2": "",
        "City": "",
        "State": "",
        "Postal Code": "",
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}
Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.

Bank Country/Region is ISO 3166-1
State is ISO 3166-2
```

**SWIFT (HK) / CHATS (Payment Type 3)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Account Owner Type": "",
        "IBAN": "",
        "Bank Name": "",
        "Bank Country/Region": "",
        "Bank Identifier": "",
        "Street": "",
        "City": "",
        "State": "",
        "Country/Region": "",
        "Postal Code": ""
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}

Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.

Bank Country/Region is ISO 3166-1

```

**Colombia Bank (68: PSE/ACH)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Account Type": "",
        "Full Name": "",
        "ID Document Type": "",
        "ID Document Number": "", 
        "Bank Code": "",
        "Bank Account Number": ""
    }
}

Account Type: enum [cc: Checking Account, ch: Savings Account, dp:Electronic deposit]
ID Document Type: enum [cc: Citizenship ID, nit: Tax Identification Number, ce: Foreigner ID,  pa: Pasaporte (Passport),  ppt: Temporary Protection Permit,  ti: Identity Card, rc: Civil Registry, te: Foreigner Card, die: Foreign Identification Document, nd: No Document]
Bank Code: See Colombian Bank Codes, The bank code filled in must be one that is supported by the corresponding Account Type.
```

**Brazil Bank (90: Automated Pix)**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Pix Type": "",
        "Pix Key": ""
    }
}

Pix Type: enum [CPF:11 digits, CNPJ:14 digits, EMAIL:email, PHONE: 10-11 digits, RANDOM_KEY: with "-"]
```

**Peru Bank (95: Automated Bank Transfer(Peru))**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
       "Bank Name": "",
       "Account Type": "",
       "Account Number": "",
       "CCI Number": "",
       "Email": "",
       "Identification Type": "",
       "Identification Number": "",
       "Name": "",
       "Phone Number": ""
    }
}
```

## Colombia Bank Codes <a href="#colombian-bank-codes" id="colombian-bank-codes"></a>

<table><thead><tr><th width="98">Code</th><th width="474">Bank</th><th width="204">Type</th></tr></thead><tbody><tr><td>1001</td><td>BANCO DE BOGOTA</td><td>cc, ch, dp</td></tr><tr><td>1002</td><td>BANCO POPULAR</td><td>cc, ch, dp</td></tr><tr><td>1006</td><td>ITAU</td><td>cc, ch</td></tr><tr><td>1007</td><td>BANCOLOMBIA</td><td>cc, ch, dp</td></tr><tr><td>1009</td><td>CITIBANK</td><td>cc, ch</td></tr><tr><td>1012</td><td>BANCO GNB SUDAMERIS</td><td>cc, ch</td></tr><tr><td>1013</td><td>BBVA COLOMBIA</td><td>cc, ch, dp</td></tr><tr><td>1019</td><td>SCOTIABANK COLPATRIA S.A</td><td>cc, ch</td></tr><tr><td>1023</td><td>BANCO DE OCCIDENTE</td><td>cc, ch</td></tr><tr><td>1032</td><td>BANCO CAJA SOCIAL BCSC SA</td><td>cc, ch</td></tr><tr><td>1040</td><td>BANCO AGRARIO</td><td>cc, ch, dp</td></tr><tr><td>1047</td><td>BANCO MUNDO MUJER</td><td>ch</td></tr><tr><td>1051</td><td>BANCO DAVIVIENDA SA</td><td>cc, ch, dp</td></tr><tr><td>1052</td><td>BANCO AV VILLAS</td><td>cc, ch, dp</td></tr><tr><td>1053</td><td>BANCO W</td><td>cc, ch</td></tr><tr><td>1059</td><td>BANCO DE LAS MICROFINANZAS - BANCAMIA S.A.</td><td>cc, ch</td></tr><tr><td>1060</td><td>BANCO PICHINCHA</td><td>cc, ch</td></tr><tr><td>1061</td><td>BANCOOMEVA</td><td>cc, ch, dp</td></tr><tr><td>1062</td><td>BANCO FALABELLA S.A.</td><td>cc, ch</td></tr><tr><td>1063</td><td>BANCO FINANDINA S.A.</td><td>cc, ch</td></tr><tr><td>1065</td><td>BANCO SANTANDER DE NEGOCIOS COLOMBIA S.A</td><td>ch</td></tr><tr><td>1066</td><td>BANCO COOPERATIVO COOPCENTRAL</td><td>cc, ch, dp</td></tr><tr><td>1067</td><td>MIBANCO S.A.</td><td>cc, ch, dp</td></tr><tr><td>1069</td><td>BANCO SERFINANZA S.A</td><td>cc, ch, dp</td></tr><tr><td>1070</td><td>LULO BANK S.A.</td><td>ch</td></tr><tr><td>1071</td><td>BANCO J.P. MORGAN COLOMBIA S.A.</td><td>cc, ch</td></tr><tr><td>1097</td><td>Dale</td><td>dp</td></tr><tr><td>1121</td><td>FINANCIERA JURISCOOP S.A. COMPAÑIA DE FINANCIAMIENTO</td><td>ch</td></tr><tr><td>1283</td><td>COOPERATIVA FINANCIERA DE ANTIOQUIA</td><td>ch, dp</td></tr><tr><td>1286</td><td>JFK COOPERATIVA FINANCIERA</td><td>ch</td></tr><tr><td>1289</td><td>COOTRAFA COOPERATIVA FINANCIERA</td><td>ch</td></tr><tr><td>1292</td><td>CONFIAR COOPERATIVA FINANCIERA</td><td>ch</td></tr><tr><td>1303</td><td>BANCO UNION S.A</td><td>ch</td></tr><tr><td>1370</td><td>COLTEFINANCIERA S.A</td><td>ch</td></tr><tr><td>1507</td><td>NEQUI</td><td>ch, dp</td></tr><tr><td>1551</td><td>DAVIPLATA</td><td>dp</td></tr><tr><td>1558</td><td>BAN100 S.A</td><td>cc, ch</td></tr><tr><td>1637</td><td>IRIS</td><td>ch</td></tr><tr><td>1801</td><td>MOVII</td><td>dp</td></tr><tr><td>1802</td><td>DING TECNIPAGOS SA</td><td>dp</td></tr><tr><td>1803</td><td>POWWI</td><td>dp</td></tr><tr><td>1804</td><td>UALA</td><td>ch</td></tr><tr><td>1805</td><td>BANCO BTG PACTUAL</td><td>cc</td></tr><tr><td>1808</td><td>BOLD CF</td><td>dp</td></tr><tr><td>1809</td><td>NU COLOMBIA</td><td>ch</td></tr><tr><td>1811</td><td>RAPPIPAY</td><td>ch, dp</td></tr><tr><td>1812</td><td>COINK</td><td>dp</td></tr><tr><td>1814</td><td>GLOBAL66</td><td>dp</td></tr><tr><td>1815</td><td>Alianza fiduciaria</td><td>ch</td></tr><tr><td>1816</td><td>Crezcamos</td><td>cc, ch</td></tr></tbody></table>

## Peru Bank Codes

<table><thead><tr><th width="98">Code</th><th width="691">Bank</th></tr></thead><tbody><tr><td>01</td><td>BCP</td></tr><tr><td>02</td><td>Interbank</td></tr><tr><td>03</td><td>BBVA</td></tr><tr><td>04</td><td>Scotiabank</td></tr><tr><td>05</td><td>Banco de Comercio</td></tr><tr><td>06</td><td>BanBif (Banco Interamericano de Finanzas)</td></tr><tr><td>07</td><td>Banco Pichincha</td></tr><tr><td>08</td><td>Citibank</td></tr><tr><td>09</td><td>Banco GNB</td></tr><tr><td>10</td><td>Banco Santander</td></tr><tr><td>11</td><td>Banco Azteca</td></tr><tr><td>12</td><td>Banco Cencosud</td></tr><tr><td>13</td><td>ICBC PERU BANK</td></tr><tr><td>14</td><td>Banco de la Nación</td></tr><tr><td>15</td><td>Caja Cusco</td></tr><tr><td>16</td><td>Caja Huancayo</td></tr><tr><td>17</td><td>Caja Maynas</td></tr><tr><td>18</td><td>Caja Metropolitana</td></tr><tr><td>19</td><td>Caja Municipal Ica</td></tr><tr><td>20</td><td>Caja Sullana</td></tr><tr><td>21</td><td>Caja Tacna</td></tr><tr><td>22</td><td>Caja Trujillo</td></tr></tbody></table>

## Mexico FINCO PAY Bank Codes

<table><thead><tr><th width="442">Code</th><th width="400">Bank</th></tr></thead><tbody><tr><td>14b392f6-5dd9-4cd9-ac51-d13c5547c137</td><td>FINCO_PAY</td></tr><tr><td>99d3c26a-bf2c-494e-9a39-c3359a692c38</td><td>ALBO</td></tr><tr><td>1d792ab5-95f3-44ba-944f-9da198f68c2e</td><td>CASHI</td></tr><tr><td>af8250bd-f169-480f-9dc5-0fafeb89c21b</td><td>KAPITAL</td></tr><tr><td>05409c64-a872-4e5e-9bac-c2a16261aea1</td><td>NAFIN</td></tr><tr><td>6ec6bbd5-94fa-47c4-a2c6-8ed8c3f3457b</td><td>HIPOTECARIAFED</td></tr><tr><td>8e04b055-b6cf-4e66-abfb-fc845d69a1bc</td><td>ACCENDOBANCO</td></tr><tr><td>810c88e2-8fdb-4ecd-9747-eda708b5ebe7</td><td>AMERICANEXPRES</td></tr><tr><td>2218cd20-0fdf-4f81-ab5c-90587b91057a</td><td>BANKOFAMERICA</td></tr><tr><td>6bb38026-7386-4992-8fdf-946b17b1d16c</td><td>MUFG</td></tr><tr><td>c4d942d0-c102-48ef-9756-532266183856</td><td>JPMORGAN</td></tr><tr><td>9d989796-0be4-4466-a213-61a27cdfcfaf</td><td>BMONEX</td></tr><tr><td>b9eae957-344c-4169-8c41-e189d3f2c74a</td><td>VEPORMAS</td></tr><tr><td>b2438e53-33bd-456e-937a-24e59b65fb35</td><td>DEUTSCHE</td></tr><tr><td>fe025a91-37ea-4869-bd68-687fd63ab6a3</td><td>CREDITSUISSE</td></tr><tr><td>a832542e-5eb2-49ae-b01e-b441f0d4d1ec</td><td>AZTECA</td></tr><tr><td>b835e788-b8c0-497a-9ce2-f5dfeac607bd</td><td>BARCLAYS</td></tr><tr><td>ef51659d-6b84-4f29-a92e-e435648be5b5</td><td>COMPARTAMOS</td></tr><tr><td>fc9a2874-2a07-416b-ac97-cf0d8eb68101</td><td>MULTIVABANCO</td></tr><tr><td>a72ff745-6094-4fb0-96ae-ea86847cf9b7</td><td>ACTINVER</td></tr><tr><td>5dcd3410-a88a-4c7a-8c4f-390f666836f4</td><td>INTERCAMBANCO</td></tr><tr><td>a4f9d274-2407-4295-8136-ccd0135192d7</td><td>BANCOPPEL</td></tr><tr><td>522333da-cff6-40b9-943e-71da34879815</td><td>ABCCAPITAL</td></tr><tr><td>ce134175-ad5d-4a6b-b429-deb0f4040166</td><td>CONSUBANCO</td></tr><tr><td>4583c80e-f7ad-4d62-bc2f-09b1aab598b9</td><td>VOLKSWAGEN</td></tr><tr><td>e10fb312-0538-48f6-ab9a-fc0184563d37</td><td>CIBANCO</td></tr><tr><td>92acfe76-0a74-4817-83e1-3fdabe2cc89c</td><td>BBASE</td></tr><tr><td>505292b9-41bc-4cf8-8765-1fb75fc0a264</td><td>BANKAOOL</td></tr><tr><td>d2ea27c8-0b41-4ca8-b5f4-e62f97d46909</td><td>PAGATODO</td></tr><tr><td>082a3ea6-12a9-42ce-9716-59d98e080a0e</td><td>INMOBILIARIO</td></tr><tr><td>95d541a3-9000-4d43-a3b2-be3dc08e5964</td><td>DONDE</td></tr><tr><td>13f54258-ae13-4d1d-b470-113c66db84f6</td><td>BANCREA</td></tr><tr><td>50b78495-f60b-475c-be1d-5f31588f9a1b</td><td>PROGRESO</td></tr><tr><td>688d032b-fc6f-43b7-97a1-e75a5b718597</td><td>BANCOFINTERRA</td></tr><tr><td>a27f9214-00d4-4826-8e59-832daf7f41aa</td><td>ICBC</td></tr><tr><td>0eff7474-046f-4ea7-9cdf-4ef56427919b</td><td>SABADELL</td></tr><tr><td>5e80e573-7e55-474f-80e0-b2424713b2a1</td><td>BANXICO</td></tr><tr><td>a12c354f-d2e0-462f-8b95-49d08a5aa376</td><td>BANCOMEXT</td></tr><tr><td>04a2c4e7-2e1c-4235-bb0b-599215f60560</td><td>BANOBRAS</td></tr><tr><td>cc1cdae0-3091-40b7-80af-681fdf6a9bfd</td><td>BANAMEX</td></tr><tr><td>6fe813b9-3daf-4fc4-9398-82dc75e26cd0</td><td>BaBien</td></tr><tr><td>e01d0e74-c95e-4cfd-89bb-e664bf86e4f3</td><td>SHINHAN</td></tr><tr><td>3387b78c-92a2-4636-94d3-a949dcbabd00</td><td>MIZUHOBANK</td></tr><tr><td>4b25af05-9f6f-4d5e-aaa8-5cce5059c280</td><td>BANKOFCHINA</td></tr><tr><td>368ad8e9-5f7a-49c5-93b3-be799dadacd8</td><td>BANCOS</td></tr><tr><td>9ded667d-ad5c-4da8-aa85-acf56a14adb7</td><td>NU_MEXICO</td></tr><tr><td>2ab903aa-e32c-4e40-a811-684050fd5476</td><td>FOMPED</td></tr><tr><td>d94ebc8d-6675-4158-8dca-0937b0cff6b9</td><td>MONEXCB</td></tr><tr><td>ead338fc-35c6-4436-b062-b87df217a152</td><td>GBM</td></tr><tr><td>4354277f-e083-48ff-981f-24dae6124027</td><td>MASARI</td></tr><tr><td>af3a5d5d-b052-4e73-8411-69db92cab98d</td><td>VALUE</td></tr><tr><td>10997d0a-3ac5-494d-80b5-cede1f6cc2e4</td><td>ESTRUCTURADORES</td></tr><tr><td>728550ff-2c76-4cbf-8969-e488081ecdfe</td><td>VECTOR</td></tr><tr><td>7cbc1932-b402-406f-82e7-39ddc41246d9</td><td>MULTIVACBOLSA</td></tr><tr><td>4cb562f8-0a9a-4df5-8451-d01a971a2944</td><td>FINAMEX</td></tr><tr><td>8cf9ad29-b0db-40a5-82f4-7e3e19af8400</td><td>VALMEX</td></tr><tr><td>4c469adf-4e07-4a3b-8ea2-955e69516e88</td><td>PROFUTURO</td></tr><tr><td>a930ac56-0d84-4ca5-9340-8cf3ff93de7f</td><td>CBINTERCAM</td></tr><tr><td>4b62d90c-8db7-4d50-a229-265786a643f0</td><td>CIBOLSA</td></tr><tr><td>52c1e083-309e-4bb8-ba1f-779b6493a9ce</td><td>FINCOMUN</td></tr><tr><td>15d56a15-86a9-48a0-8222-34c9b482cd29</td><td>HDISEGUROS</td></tr><tr><td>fd852c62-0ebc-470b-a9dc-bdc2d71b174e</td><td>REFORMA</td></tr><tr><td>033f8743-3bc4-45d7-8bc9-7805ccedb2f9</td><td>STP</td></tr><tr><td>0a01916c-e09d-4834-84bd-35ce27de404f</td><td>EVERCORE</td></tr><tr><td>6dad109e-5163-49d2-8557-7af8b35cad2b</td><td>CREDICAPITAL</td></tr><tr><td>8c9f8509-2989-4a97-aeee-bc55bdea330e</td><td>KUSPIT</td></tr><tr><td>163a12e4-e463-45cc-a684-7f986d5f1fae</td><td>UNAGRA</td></tr><tr><td>4e18dd45-d4a4-491b-af9e-cb086c69f4c2</td><td>ASPINTEGRAOPC</td></tr><tr><td>97bce569-8fc0-4025-9c04-9860592f77fd</td><td>LIBERTAD</td></tr><tr><td>ea38aef5-dbe0-42ec-8870-6844cf77ba30</td><td>C.B.INBURSA</td></tr><tr><td>16a4f525-ef02-4018-b0ef-88a98530c2c8</td><td>CAJAPOPMEXICA</td></tr><tr><td>a03aa6d1-0aa2-48ad-8b7d-b4dfeeed51cb</td><td>CRISTOBALCOLON</td></tr><tr><td>2459cecf-7841-4cf1-a98a-af9bf6984f92</td><td>CAJATELEFONIST</td></tr><tr><td>c9bff5ba-8f00-4743-83ec-f62af901a1d9</td><td>TRANSFER</td></tr><tr><td>0f0ab913-cfdb-4b11-b0c7-4c2b2bac9024</td><td>FONDO(FIRA</td></tr><tr><td>31e3cec1-d95c-4849-92ff-36c9944f91cc</td><td>CREDICLUB</td></tr><tr><td>d028742d-5cbe-4add-8518-718b840d023a</td><td>XXI-BANORTE</td></tr><tr><td>429d2ddc-e369-4438-a393-dbfb44e4d635</td><td>TECREEMOS</td></tr><tr><td>55196e15-c27f-40cd-a824-c28fdc0ed49a</td><td>SCPROMYOP</td></tr><tr><td>7dbf5a21-9dfd-4a71-8dd5-7832681dd6a0</td><td>CAPITALACTIVO</td></tr><tr><td>cf3d6099-5bdd-4738-b3a5-2bf7f127d33e</td><td>BURSAMETRICA</td></tr><tr><td>48a881e1-95ab-44bb-9f69-fd1ae6ade6ad</td><td>ARCUS</td></tr><tr><td>0b0e321e-fd89-4af9-a5c9-e3f030874646</td><td>FND</td></tr><tr><td>71db3f6f-0da8-4455-8e6f-1caea04223c0</td><td>CLSBANK</td></tr><tr><td>86107256-75dc-4429-ba6c-de5ae71e75fb</td><td>INDEVAL</td></tr><tr><td>5e02554c-4471-4d21-9f6e-5c7b0d754443</td><td>BanCobro_R</td></tr><tr><td>b9133baa-8e87-4162-bcf9-223ec4d297a5</td><td>BanCobro</td></tr><tr><td>481bdbde-7e47-43d9-8a30-bdd0968c40b1</td><td>BanCobro</td></tr><tr><td>e1adef4c-5368-41bb-92f2-7dc6ec2a6465</td><td>Validador</td></tr><tr><td>912f9702-f480-4f10-acec-788119e01d88</td><td>BANAMEX</td></tr><tr><td>e4e7f75c-4f61-4bce-b411-a5509347d755</td><td>BBVABANCOMER</td></tr><tr><td>0997b675-5230-4752-ae14-cff991d9f6c3</td><td>SANTANDER</td></tr><tr><td>89bfe0b7-ccd2-4f2d-93ef-472a62a1da45</td><td>HSBC</td></tr><tr><td>ec7f37e2-4a5d-4df7-9a0d-17200497a603</td><td>BANORTE</td></tr><tr><td>daa62e35-19e4-4b39-a99c-2ea611cf0476</td><td>AZTECA</td></tr><tr><td>67ee7fff-258f-4bd6-888c-7ff4d4c2477a</td><td>BANJERCITO</td></tr><tr><td>5ad49c1d-bff3-4b00-8bc5-32df6cb1cd2c</td><td>BBVABANCOMER</td></tr><tr><td>93e25084-52b2-4c4e-bfd3-39b531f9fae1</td><td>SANTANDER</td></tr><tr><td>1aa2cc10-84ba-453e-adae-9edcd9232847</td><td>HSBC</td></tr><tr><td>bbc556be-0cae-4907-aff8-9851774949f3</td><td>BAJIO</td></tr><tr><td>538aeb53-f5f7-4eea-9747-035c6fc80e3a</td><td>INBURSA</td></tr><tr><td>bdb58e56-a7d4-4fcd-b32c-ed780a9a23d0</td><td>MIFEL</td></tr><tr><td>631b3a6a-71fc-43dc-a483-7ea6ca46a7ed</td><td>SCOTIABANK</td></tr><tr><td>a9151de7-393f-4ea1-a897-92dd158f3e25</td><td>BANREGIO</td></tr><tr><td>2ef06d9b-0739-40fe-81c2-4a88bdd7e939</td><td>INVEX</td></tr><tr><td>9bdd8ac7-b628-41c7-b93a-123d09378878</td><td>BANSI</td></tr><tr><td>223ae9ee-47ff-4b4f-a48d-60f1c9893dfe</td><td>AFIRME</td></tr><tr><td>1ffb6b3b-1e93-407a-b5ec-cbb1139c1898</td><td>BANORTE</td></tr><tr><td>d3f867b9-9f59-46f8-b937-050d30d311bb</td><td>FONDEADORA</td></tr><tr><td>f34c6d1c-5204-41a4-adc0-7440cd1e8ea9</td><td>TESORED</td></tr><tr><td>cdf6384e-a8bc-423a-b42a-b7b488aeee83</td><td>NVIO</td></tr><tr><td>5d4208e6-8c5b-4654-a98a-5e35fef74c2b</td><td>MERCADO_PAGO_W</td></tr><tr><td>e96d092b-cc4e-4602-8665-d91bed1210f1</td><td>CUENCA</td></tr><tr><td>23eafe0c-833c-41ff-89c3-5dfefbe376fd</td><td>SPIN_BY_OXXO</td></tr><tr><td>84e4e446-f7ed-4551-9360-ad39e5a2bf06</td><td>KLAR</td></tr></tbody></table>

#### Notes

* The `data` object contains key-value pairs representing the required fields for the specified payment method.
* Ensure that valid authorization tokens are included in the request headers for successful execution.


# Add Payment Method

This API allows you to add a new payment method for a merchant.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/v2/payments`
* **Authorization Required**: Yes

#### Request Body Parameters

The request body should include the following fields:

```json
{
  "merchantId": 0,         // (number: id of the merchant id)
  "paymentId": 0,          // (number: payment ID)
  "country": "",            // (string: name of the country)
  "fiat": "",               // (string: name of the fiat currency)
  "realName": "",           // (string: real name of the account holder)
  "fieldJson": {            // (object: field JSON of the payment template)
       [string]: [string]   // (key-value pairs as per the payment template)
  },
  "remark": ""              // (string: remark about the payment method)
}
```

#### Authorization

This request requires authorization.

#### Response Structure

The response will include the following fields:

```json
{
  "code": 0,                            // (number: response code)
  "msg": "",                             // (string: message)
  "data": {                              // (object: result data)
      "id": 0,                           // (number: user payment ID)
      "status": 0,                       // (number: status [1: valid, 2: authenticating, 3: authentication failed])
      "failReason": ""                   // (string: reason for authentication failure)
  }
}
```

#### Example Request (Mexico - MXN)  58: Automated SPEI - Arcus

```json
{
  "merchantId": 123,
  "paymentId": 58,
  "country": "Mexico",
  "fiat": "MXN",
  "realName": "John Doe",
  "fieldJson": {
      "Cuenta CLABE": "123456789012345678", //clabe number
      "Banco": "Banamex", //bank name
      "Beneficiary Name": "John Doe" //beneficiary name
  },
  "remark": "Preferred payment method"
}
```

#### Example Request (Mexico - MXN)  105: SPEI - FINCO PAY

```json
{
  "merchantId": 123,
  "paymentId": 105,
  "country": "Mexico",
  "fiat": "MXN",
  "realName": "John Doe",
  "fieldJson": {
      "Account Type":"clabe", //account type enum [clabe: VA account, debit: card account]
      "Account Number": "123456789012345678", //account number   
      "Beneficiary Name": "John Doe", //beneficiary name
      "Bank Code": "" //bank code, Only fill in when the account type is "debit", The list is shown in https://docs.velafi.com/api-reference/payment-method/get-payment-templates#mexico-finco-pay-bank-codes
  },
  "remark": "Preferred payment method"
}
```

#### Example Request (Argentina - ARS)

```json
{
  "merchantId": 123,
  "paymentId": 63,
  "country": "Argentina",
  "fiat": "ARS",
  "realName": "John Doe",
  "fieldJson": {
      "Bank Name": "Banco Galicia",
      "CVU Number": "0000775900000000000041",
      "CUIT": "20339698693"
  },
  "remark": "Preferred payment method"
}
```

**Example Request (Colombia - COP)**

```json
{
    "merchantId": 15123,
    "paymentId": 58,
    "country": "Colombia",
    "fiat": "COP",
    "realName": "Tom",
    "fieldJson": {
        "Account Type": "cc", //enum: account type[cc: Checking Account, ch: Savings Account, dp:Electronic deposit]
        "Full Name": "Tom", //full name
        "ID Document Type": "cc", //enum: Type of identification document[cc: Citizenship ID, nit: Tax Identification Number, ce: Foreigner ID,  pa: Pasaporte (Passport),  ppt: Temporary Protection Permit,  ti: Identity Card, rc: Civil Registry, te: Foreigner Card, die: Foreign Identification Document, nd: No Document]
        "ID Document Number": "123456789", //Identification number
        "Bank Code": "1007", //Bank Code, The list is shown in https://docs.velafi.com/api-reference/payment-method/get-payment-templates#colombian-bank-codes
        "Bank Account Number": "9876543210" //Bank Account Number
    },
    "remark": "Preferred payment method"
}
```

**Example Request (Brazil - BRL)**

```json
{
    "merchantId": 15123,
    "paymentId": 90,
    "country": "Brazil",
    "fiat": "BRL",
    "realName": "Tom",
    "fieldJson": {
        "Pix Type": "EMAIL", //pix type[CPF:11 digits, CNPJ:14 digits, EMAIL:email, PHONE: 10-11 digits, RANDOM_KEY: with "-"]
        "Pix Key": "tom@gmail.com" //pix key      
    },
    "remark": "Preferred payment method"
}
```

**Example Request (Peru - PEN)**

```json
{
    "merchantId": 15123,
    "paymentId": 90,
    "country": "Peru",
    "fiat": "PEN",
    "realName": "Tom",
    "fieldJson": {       
        "Bank Name": "01", //bank code, The list is shown in https://docs.velafi.com/api-reference/payment-method/get-payment-templates#peru-bank-codes
        "Account Type": "00", //account type[00:CORRIENTE, 01:AHORROS]
        "Account Number": "1110333710152", //account number
        "CCI Number": "", //Payer's intermediary account(20 digits), When the Bank Name is not one of the four major banks(01-BCP, 02-Interbank, 03-BBVA, 04-Scotiabank), it must be filled in.
        "Email": "tom@gmai.com", //email
        "Identification Type": "00", //identification type[00:CC (8 digits), 01:CE (>9 digits), 02:Tax ID (11 digits), 03:PAS (>9 digits), 04:PAR, 05:LMI]
        "Identification Number": "12345678", //identification number
        "Name": "Tom", //user name
        "Phone Number": "975728895" //user phone number (9 digits)
    },
    "remark": "Preferred payment method"
}
```

**Example Request (United States - USD)**

```json
{
    "merchantId": 15123,
    "paymentId": 111,
    "country": "United States",
    "fiat": "USD",
    "realName": "Tom",        
    "fieldJson": {       
        "Account Owner Type": "individual", //account type[individual/business]
        "Bank Name": "Bank of Nowhere", //bank name
        "Beneficiary Name": "Tom", //name
        "Email": "tom@gmail.com", //emial
        "National code": "1", //International area code for mobile phones
        "Phone Number": "123456", //phone number
        "Account Number": "11223344556663", //account number
        "Routing Number": "123456795", //routing Number
        "Street Line1": "street example", //street
        "City": "New City", //city
        "State": "AL", //state code
        "Postal Code": "123456", //postal code
        "Purpose Of Payment": "invoice_payments" //purpose of payment[invoice_payments/payment_for_services/payment_for_imported_goods/travel_services/transfer_to_own_account/repayment_of_loans/payroll/payment_of_property_rental/information_service_charges/advertising_and_public_relations/royalty_and_ip_fees/financial_service_fees/advisory_and_consulting_fees/representative_office_expenses/tax_payment/transportation_fees/construction_costs/insurance_premium/offline_goods_trade/insurance_claims/remittance_to_family_or_friends/education_expenses/medical_treatment/donations/currency_exchange/advance_payment_for_goods/merchant_settlement/repatriation_fund_settlement]
    },
    "remark": "Preferred payment method"
}
```

**Example Request (Hong Kong - USD)**

```json
{
    "merchantId": 15123,
    "paymentId": 115,
    "country": "Hong Kong",
    "fiat": "USD",
    "realName": "Tom",
    "fieldJson": {       
        "Account Owner Type": "individual", //account type[individual/business]
        "Bank Name": "Bank of Nowhere", //bank name
        "Beneficiary Name": "Tom", //name
        "Date of birth or formation": "2020-01-01", //date of birth or formation
        "Id Number": "123456", //id number
        "Account Number": "123456789", //account number
        "Swift Code": "ICEKHKHK001", //swift code
        "Street Line1": "789 street", //street
        "City": "Hong Kong", //city
        "State": "HK", //state code
        "Postal Code": "999077", //postal code
        "Purpose Of Payment": "invoice_payments" ////purpose of payment[invoice_payments/payment_for_services/payment_for_imported_goods/travel_services/transfer_to_own_account/repayment_of_loans/payroll/payment_of_property_rental/information_service_charges/advertising_and_public_relations/royalty_and_ip_fees/financial_service_fees/advisory_and_consulting_fees/representative_office_expenses/tax_payment/transportation_fees/construction_costs/insurance_premium/offline_goods_trade/insurance_claims/remittance_to_family_or_friends/education_expenses/medical_treatment/donations/currency_exchange/advance_payment_for_goods/merchant_settlement/repatriation_fund_settlement]
    },
    "remark": "Preferred payment method"
}
```

#### Example Response

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
      "id": 456,
      "status": 1,
      "failReason": ""
  }
}
```

#### Notes

* The `fieldJson` object should match the required fields for the specified payment method template.
* Ensure that valid authorization tokens are included in the request headers for successful execution.


# Get Payment Method

This API retrieves payment methods based on various query parameters.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/payments`
* **Authorization Required**: Yes

#### Query Parameters

* **country**: (string) The country for which to retrieve payment methods.
* **status**: (int) The status of the payment method \[0: all (default), 1: valid, 2: authenticating, 3: authentication failed].
* **fiat**: (string) The fiat currency.
* **merchantId**: (int) The ID of the merchant id.
* **currentPage**: (int) The current page number.
* **pageSize**: (int) The number of results per page.

#### Authorization

This request requires authorization.

#### Response Structure

The response will include the following fields:

```json
{
    "code": 0,                            // (number: response code)
    "msg": "",                             // (string: message)
    "data": {                              // (object: result data)
        "currentPage": 1,                 // (number: current page number)
        "size": 10,                        // (number: number of results per page)
        "total": 100,                      // (number: total number of results)
        "record": [                        // (array: list of payment methods)
            {
                "id": 1,                  // (number: user payment ID)
                "merchantId": 1,           // (number: ID of the merchant id)
                "country": "Mexico",       // (string: name of the country)
                "fiat": "USD",             // (string: name of the fiat currency)
                "paymentId": 1,            // (number: ID of the payment configuration)
                "paymentMethodName": "Paypal", // (string: name of the payment method)
                "realName": "Bob",         // (string: real name of the account holder)
                "status": 1,                // (number: status of the payment method)
                "hasRefundAccount": 0,     // (number: indicates if a refund account exists)
                "fieldList": {             // (object: field JSON of the payment template)
                    [string]: [string]
                },
                "remark": "",               // (string: remark about the payment method)
                "createTime": 111          // (number: creation time)
            }
        ]
    }
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "record": [
            {
                "id": 228,
                "merchantId": 67,
                "country": "Hong Kong",
                "fiat": "USD",
                "paymentId": 529,
                "paymentMethodName": "CHATS",
                "realName": "test",
                "remark": "11",
                "createTime": 0,
                "fieldList": {
                    "Account Owner Type": "Business",
                    "Account Number": "390202731",
                    "Bank Name": "Citibank, N.A., Hong Kong Branch",
                    "Bank Country/Region": "HK",
                    "Bank Identifier": "CITIHKHX",
                    "Remarks": "111",
                    "Street": "UNIT E, 36/F., E-TRADE PLAZA, 24 LEE CHUNG STREET, CHAIWAN, HONG KONG",
                    "City": "Hong Kong",
                    "State": "HK-HK",
                    "Country/Region": "HK",
                    "Postal Code": "00000"
                },
                "status": 1,
                "hasRefundAccount": 0
            }
        ],
        "size": 10,
        "currentPage": 1,
        "total": 1
    }
}
```

#### Notes

* The `record` array contains details about each payment method that matches the query parameters.
* Ensure that valid authorization tokens are included in the request headers for successful execution.


# Delete Payment Method

This API allows you to delete a specific payment method using its user payment ID.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `DELETE`
* **Request Path**: `/v2/payments/{userPaymentId}`
* **Authorization Required**: Yes

#### Path Parameters

* **userPaymentId**: (int) The ID of the user payment method you want to delete.

#### Authorization

This request requires authorization.

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,                        // (number: response code)
    "msg": "SUCCESS",                   // (string: message)
    "data": true                        // (boolean: indicates if the deletion was successful)
}
```

#### Example Request

To delete a payment method with `userPaymentId` of `123`:

```
DELETE /v2/payments/123
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": true
}
```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* Confirm that the specified `userPaymentId` exists and is eligible for deletion.


# Set Refund Account

This API allows you to set a refund account for a specific payment method.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/openapi/v2/payment/refund_account`
* **Authorization Required**: Yes

#### Request Body Parameters

The request body should include the following fields:

```json
{
  "userPaymentId": 0,  (int) The ID of the user payment method.
  "merchantId": 0 (int) The ID of the merchant id.
}
```

#### Request Body Parameters

The request body should include the following fields:

```
{
  "userPaymentId": 2,         // (number: The ID of the user payment method)
  "merchantId": 6          // (number: The ID of the merchant id)  
}
```

#### Authorization

This request requires authorization.

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,                        // (number: response code)
    "msg": "SUCCESS",                   // (string: message)
    "data": true                        // (boolean: indicates if the operation was successful)
}
```

#### Example Request

To set a refund account for a payment method with `userPaymentId` of `123` and `settingsId` of `456`:

#### Example Request

```json
{
  "merchantId": 456,
  "userPaymentId": 123 
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": true
}
```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* Confirm that the specified `userPaymentId` and `settingsId` are valid and that the payment method is eligible for setting a refund account.


# Order


# Create a Fiat to Crypto Order

This section provides information about the fiat to crypto on-ramp process, allowing users to convert fiat currency into cryptocurrency through the API.

## **Create Order**

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/fiat_to_crypto`
* **Authorization**: Required

**Request Parameters**

The request body should include the following parameters:

| Parameter                                       | Type    | Required | Description                                                                      |
| ----------------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| country                                         | string  | Yes      | Name of the country (e.g., "Mexico")                                             |
| clientId                                        | string  | No       | An order ID that you may define and will be returned to you in a Get Order call. |
| merchantId                                      | number  | No       | ID of the merchant                                                               |
| crypto                                          | string  | Yes      | Name of the cryptocurrency (e.g., "USDT")                                        |
| fiat                                            | string  | Yes      | Name of the fiat currency (e.g., "MXN")                                          |
| fiatAmount                                      | decimal | Yes      | Amount of fiat currency to convert (e.g., 1000.00)                               |
| [paymentId](/velafi-1/guides/payment-method-id) | number  | Yes      | ID of the payment method                                                         |
| remark                                          | string  | No       | Additional remarks for the order                                                 |

**Request Example**

```json
{
    "country": "Mexico",
    "clientId": "xxxx",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "fiatAmount": 1000.00,
    "paymentId": 91,
    "remark": ""
}
```

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure to provide valid parameters for successful order creation.
* The `settingsId` and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order along with the order ID for tracking.


# Create a Crypto to Fiat  Order

This section provides information about the crypto to fiat off-ramp process, allowing users to convert cryptocurrency into fiat currency through the API.

## **Create Order**

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/crypto_to_fiat`
* **Authorization**: Required

**Request Parameters**

The request body should include the following parameters:

| Parameter                                           | Type    | Required | Description                                                                      |
| --------------------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| country                                             | string  | Yes      | Name of the country (e.g., "Mexico")                                             |
| clientId                                            | string  | No       | An order ID that you may define and will be returned to you in a Get Order call. |
| merchantId                                          | number  | No       | ID of the merchant                                                               |
| crypto                                              | string  | Yes      | Name of the cryptocurrency (e.g., "USDT")                                        |
| fiat                                                | string  | Yes      | Name of the fiat currency (e.g., "MXN")                                          |
| cryptoAmount                                        | decimal | Yes      | Amount of fiat currency to convert (e.g., 1000.00)                               |
| [userPaymentId](/velafi-1/guides/payment-method-id) | number  | Yes      | ID of the user payment method                                                    |
| remark                                              | string  | No       | Additional remarks for the order                                                 |

**Request Example**

```json
{
    "country": "Mexico",
    "clientId": "xxxx",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "cryptoAmount": 1000.00,
    "userPaymentId": 91,
    "remark": ""
}
```

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure to provide valid parameters for successful order creation.
* The `settingsId` and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order along with the order ID for tracking.


# Create a Fiat to Fiat Order

## **Create Order**

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/fiat_to_fiat`
* **Authorization**: Required

**Request Parameters**

The request body should include the following parameters:

<table><thead><tr><th width="266">Parameter</th><th width="96">Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>clientId</td><td>string</td><td>No</td><td>Unique identifier for the client</td></tr><tr><td>onRampCountry</td><td>string</td><td>Yes</td><td>Name of the country (e.g., "Mexico")</td></tr><tr><td>onRampMerchantId</td><td>number</td><td>No</td><td>ID of the merchant</td></tr><tr><td>onRampFiat</td><td>string</td><td>Yes</td><td>Name of the fiat currency (e.g., "MXN")</td></tr><tr><td>onRampFiatAmount</td><td>decimal</td><td>Yes</td><td>Amount of fiat currency to convert (e.g., 1000.00)</td></tr><tr><td><a href="/pages/d6qFnm3pFqD22eQqFfoL">onRampPaymentId</a></td><td>number</td><td>Yes</td><td>ID of the payment method</td></tr><tr><td>offRampCountry</td><td>string</td><td>Yes</td><td>Name of the country (e.g., "Mexico")</td></tr><tr><td>offRampMerchantId</td><td>number</td><td>No</td><td>ID of the merchant</td></tr><tr><td>offRampFiat</td><td>decimal</td><td>Yes</td><td>Name of the fiat currency (e.g., "MXN")</td></tr><tr><td><a href="/pages/d6qFnm3pFqD22eQqFfoL">offRampPaymentId</a></td><td>number</td><td>Yes</td><td>ID of the payment method</td></tr><tr><td>remark</td><td>string</td><td>No</td><td>Additional remarks for the order</td></tr></tbody></table>

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure to provide valid parameters for successful order creation.
* The `merchantId`  and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order along with the order ID for tracking.


# Confirm a Specific Order

This API allows you to confirm a specific order using its order ID.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/v2/order/confirm`
* **Authorization**: Required

**Body Parameters**

* **orderId:** (int)  The id of the order
* **orderType**: (string) The type of the order, `fiat_to_crypto crypto_to_fiat fiat_to_fiat`
* **direction:** (string)   Mark the flow direction, when the order type is fiat\_to\_fiat, this field must be filled in as `on_ramp` `off_ramp` (optional)

```json
{
    "orderId": 493829236956962817,
    "orderType": "fiat_to_fiat",
    "direction": "on_ramp"
}
```

#### Response Structure

The response will include the following fields:

* **code:** (number)  response code
* **msg**: (string) message
* data: (boolean) indicates if the confirmation was successful

```json
{
    "code": 200,        
    "msg": "SUCCESS",
    "data": true 
}
```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* Confirm that the specified `orderId` is valid and that the order is eligible for confirmation.


# Retrieve a Specific Order

This API retrieves the detail of a specific order using its order ID.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/order/detail`
* **Authorization**: Required

**Query Parameters**

* **orderId:** (int)  The id of the order
* **orderType**: (string) The type of the order, `fiat_to_crypto crypto_to_fiat fiat_to_fiat`

<pre class="language-url"><code class="lang-url"><strong>/v2/order/detail?orderId=493829236956962816&#x26;orderType=fiat_to_crypto
</strong></code></pre>

#### Response Structure

When the order type is `fiat_to_crypto` and `crypto_to_fiat`, the response will include the following fields:

* cod&#x65;**:** (number)  response code
* msg: (string) message
* data: (object) order info
* orderId: (int) id of the order
* clientId: (string) a id defined by client
* merchantId: (int)  id of the merchant settings
* paymentId: (int)  id of paymenyId (`fiat_to_crypto`)
* userPaymentId: (int)  id of user paymenyId (`crypto_to_fiat`)
* country: (string) name of the country
* crypto: (string) name of the crypto currency&#x20;
* fiat: (string) name of the fiat currency&#x20;
* orderType: (string) type of the order
* orderPrice: (string) exchange rate when create orden
* cryptoAmount: (string) amount of crypto currency
* fiatAmount: (string) amount of fiat currency
* fiatFee: (string) fee of the order
* orderStatus: (int) status of the order(10: pending, 11: request for information, 12: uploaded RFI Information, 30: approved, 31: support documents pending, 40: pending payment, 50: paid, 60: released, 70: canceled)
* traceNumber: (string) id of the national central bank order
* paymentInfo: (object) info of the payment
* createTime: (string) create time of the order
* completedTime: (string) completed time of the order

<pre class="language-json"><code class="lang-json">{
<strong>    "code": 200,
</strong>    "msg": "SUCCESS",
    "data": {
        "orderId": "493829236956962816",
        "clientId": "f_c_0250222004",
        "merchantId": 3,
        "paymentId": 0,
        "userPaymentId": 0,
        "country": "Mexico",
        "crypto": "USDT",
        "fiat": "MXN",
        "orderType": "fiat_to_crypto",
        "orderPrice": "21.4104",
        "cryptoAmount": "5.1376",
        "fiatAmount": "110",
        "fiatFee": "0",
        "orderStatus": 60,
        "hasRefund": 0,
        "traceNumber": "20241223907069062e51744c4f0e57",
        "paymentInfo": {
            "CLABE number": "",
            "Account number/card": "706180304649761358",
            "Beneficiary Name": ""
        },
        "createTime": "1740214865000",
        "completedTime": "1740214866000"
    }
}
</code></pre>

When the order type is `fiat_to_fiat`, the response will include the following fields:

* cod&#x65;**:** (number)  response code
* msg: (string) message
* data: (object) order info
* orderId: (int) id of the order
* clientId: (string) a id defined by client
* onRampMerchantId: (int)  id of the merchant
* onRampPaymentId: (int)  id of user paymenyId
* onRampCountry: (string) name of the country
* onRampFiat: (string) name of the fiat currency
* onRampFiatAmount: (string) amount of fiat currency
* onRampFiatFee: (string) fee of the order
* offRampMerchantId: (int)  id of the merchant
* offRampPaymentId: (int)  id of user paymenyId
* offRampCountry: (string) name of the country
* offRampFiat: (string) name of the fiat currency
* offRampFiatAmount: (string) amount of fiat currency
* offArriveRampFiatAmount: (string) arrive amount of fiat currency
* offRampFiatFee: (string) fee of the order
* orderPrice: (string) exchange rate when create order
* orderStatus: (int) status of the order(10: pending, 11: request for information, 12: uploaded RFI Information, 30: approved, 31: support documents pending, 41: payin pending, 51: payout pending, 60: released, 71: payin canceled, 72: payout canceled)
* onRampPaymentInfo: (object) info of the payment
* offRampPaymentInfo: (object) info of the payment
* createTime: (string) create time of the order
* completedTime: (string) completed time of the order

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": "494541042692263936",
        "clientId": "c_f_0250224003",
        "onRampMerchantId": 3,
        "onRampPaymentId": 17,
        "onRampCountry": "Mexico",
        "onRampFiat": "MXN",
        "onRampFiatAmount": "110",
        "onRampFiatFee": "1",
        "offRampCountry": "Argentina",
        "offRampMerchantId": 4,
        "offRampPaymentId": 134,
        "offRampFiat": "ARS",
        "offRampFiatAmount": "6156.3",
        "offArriveRampFiatAmount": "6155.3",
        "offRampFiatFee": "1",
        "orderPrice": "55.9664",
        "orderStatus": 31,
        "onRampPaymentInfo": {
            "CLABE number": "",
            "Account number/card": "706180304649761358",
            "Beneficiary Name": ""
        },
        "offRampPaymentInfo": {
            "CLABE number": "",
            "Account number/card": "706180304649761359",
            "Beneficiary Name": ""
        }
        "createTime": "1740384573000",
        "completedTime": "1740384573000"
    }
}
```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* The `paymentInfo` object will vary based on the country and payment method used.


# Retrieve a List of Orders

This API retrieves a list of orders based on specified query parameters.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/orders`
* **Authorization**: Required

Query **Parameters**

* **currentPage**: (number) The current page number (optional, default is 1).
* **pageSize**: (number) The number of results per page (optional, default is 10, max is 100).
* **startTime**: (string) The start time for filtering orders (optional).
* **endTime**: (string) The end time for filtering orders (optional).
* **orderType:** (string)The type of the orders to filter by, `fiat_to_crypto crypto_to_fiat fiat_to_fiat` .
* **orderStatus**: (number) The status of the orders to filter by (optional), status of the `fiat_to_crypto` `crypto_to_fiat` order (10: pending, 30: approved, 31: support documents pending, 40: pending payment, 50: paid, 60: released, 70: canceled); status of the fiat\_to\_fiat order (10: pending, 30: approved, 31: support documents pending, 41: payin pending, 51: payout pending, 60: released, 71: payin canceled, 72: payout canceled).

```url
/v2/orders?currentPage=1&pageSize=10&startTime=100000&endTime=200000
&orderStatus=10&orderType=fiat_to_crypto
```

#### Response Structure

When the order type is `fiat_to_crypto` and `crypto_to_fiat`, the response will include the following fields:

* cod&#x65;**:** (number)  response code
* msg: (string) message
* data: (object) order info
* orderId: (int) id of the order
* clientId: (string) a id defined by client
* merchantId: (int)  id of the merchant
* paymentId: (int)  id of user paymenyId
* country: (string) name of the country
* crypto: (string) name of the crypto currency&#x20;
* fiat: (string) name of the fiat currency&#x20;
* orderType: (string) type of the order
* orderPrice: (string) exchange rate when create orden
* cryptoAmount: (string) amount of crypto currency
* fiatAmount: (string) amount of fiat currency
* fiatFee: (string) fee of the order
* orderStatus: (int) status of the order(10: pending, 30: approved, 31: support documents pending, 40: pending payment, 50: paid, 60: released, 70: canceled)
* createTime: (string) create time of the order
* completedTime: (string) completed time of the order

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "size": 10,
        "currentPage":1,
        "total": 1,
        "record":[
            {
            "orderId": "493829236956962816",
            "clientId": "f_c_0250222004",
            "merchantId": 3,
            "paymentId": 0,
            "country": "Mexico",
            "crypto": "USDT",
            "fiat": "MXN",
            "orderType": "fiat_to_crypto",
            "orderPrice": "21.4104",
            "cryptoAmount": "5.1376",
            "fiatAmount": "110",
            "fiatFee": "0",
            "orderStatus": 60,
            "hasRefund": 0,
            "createTime": "1740214865000",
            "completedTime": "1740214866000"
            }
        ]
    }
}
```

When the order type is `fiat_to_fiat`, the response will include the following fields:

* cod&#x65;**:** (number)  response code
* msg: (string) message
* data: (object) order info
* orderId: (int) id of the order
* clientId: (string) a id defined by client
* onRampMerchantId: (int)  id of the merchant settings
* onRampPaymentId: (int)  id of user paymenyId
* onRampCountry: (string) name of the country
* onRampFiat: (string) name of the fiat currency
* onRampFiatAmount: (string) amount of fiat currency
* onRampFiatFee: (string) fee of the order
* offRampMerchantId: (int)  id of the merchant settings
* offRampPaymentId: (int)  id of user paymenyId
* offRampCountry: (string) name of the country
* offRampFiat: (string) name of the fiat currency
* offRampFiatAmount: (string) amount of fiat currency
* offRampFiatFee: (string) fee of the order
* orderPrice: (string) exchange rate when create order
* orderStatus: (int) status of the order(10: pending, 30: approved, 31: support documents pending, 41: payin pending, 51: payout pending, 60: released, 71: payin canceled, 72: payout canceled)
* onRampPaymentInfo: (object) info of the payment
* offRampPaymentInfo: (object) info of the payment
* createTime: (string) create time of the order
* completedTime: (string) completed time of the order

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "size": 10,
        "currentPage":1,
        "total": 1,
        "record":[
            {
                "orderId": "494541042692263936",
                "clientId": "c_f_0250224003",
                "onRampMerchantId": 3,
                "onRampPaymentId": 17,
                "onRampCountry": "Mexico",
                "onRampFiat": "MXN",
                "onRampFiatAmount": "110",
                "onRampFiatFee": "1",
                "offRampCountry": "Argentina",
                "offRampMerchantId": 4,
                "offRampPaymentId": 134,
                "offRampFiat": "ARS",
                "offRampFiatAmount": "6156.3",
                "offRampFiatFee": "1",
                "orderPrice": "55.9664",
                "orderStatus": 31,
                "createTime": "1740384573000",
                "completedTime": "1740384573000"
            }
        ]
    }
}
```

Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* The `record` array contains details about each order that matches the query parameters.


# Upload Invoice Documents For a Specific Order

This API allows you to upload invoices for a specific order.

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: multipart/form-data`
* **Request Method**: `POST`
* **Request Path**: `v2/order/invoice`
* **Authorization**: Required

Form **Parameters**

* **orderId**: (number) The ID of the order for which the invoice is being uploaded.
* **files**: (file) Upload multiple files. The maximum number of uploaded files is 5, with each file limited to 5 MB in size. Supported formats are \[jpg, png, jpeg, pdf].

**Response Structure**

The response will include the following fields:

* **code:** (number)  response code
* **msg**: (string) message
* data: (boolean) indicates if the confirmation was successful

```json
{
    "code": 200,        
    "msg": "SUCCESS",
    "data": true 
}

```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* Check that the uploaded files meet the specified requirements (number, size, and format).


# Webhooks


# Webhook Setup

**Receiving Webhook Events**

TruBit Business API will send webhooks to your designated URL as a HTTP POST request with a JSON payload. You can provide your URLs via the webhook subscription endpoint, and retrieve, modify, or delete later them as you wish.

**Validation**

TruBit Business signs the webhook payload that is sent to your endpoint, and you can validate it by verifying the `signature` attached in the request header:

1. Extract the `signature` from the header, uses hexadecimal encoding.
2. Compute the hash with `RSA-SHA256` using the payload and the public key.
3. Compare the hash with the reap-signature and make sure they match.

**For Java Code**

```java
import java.security.*;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import javax.servlet.http.HttpServletRequest;

public class CallbackController {

    //Place your public key according to the environment
    private String publicKey = "PUBLIC KEY";

    public String callbackNotice(HttpServletRequest request, @RequestBody String param) {
        //extract the signature
        String signature = request.getHeader("signature");
    
        //Use RSA-SHA256 to verify the signature, This signature uses hexadecimal encoding.
        boolean verified = verifyRSASHA256(param, signature, publicKey);
        System.out.println(String.format("verified:%s", verified));
    
        return String.format("{\"callbackStatus\":\"%s\"}", (verified ? "SUCCESS" : "FAIL"));  
    }
    
    public static boolean verifyRSASHA256(String data, String signature, String publicKeyStr) {
        try {
            // 1. Decode the Base64-encoded public key
            byte[] publicKeyBytes = Base64.getDecoder().decode(publicKeyStr);
            X509EncodedKeySpec keySpec = new X509EncodedKeySpec(publicKeyBytes);  
                      
            // 2. Generate RSA public key
            KeyFactory keyFactory = KeyFactory.getInstance("RSA");
            PublicKey publicKey = keyFactory.generatePublic(keySpec);
                        
            // 3. Initialize Signature object
            Signature sig = Signature.getInstance("SHA256withRSA");
            sig.initVerify(publicKey);
            
            // 4. Update the data to be verified
            sig.update(data.getBytes("UTF-8"));
            
            // 5. Decode the hexadecimal encoding signature
            byte[] signatureBytes = decodeHex(signature);
            
            // 6. Verify the signature
            return sig.verify(signatureBytes);
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
    }
    
    public static byte[] decodeHex(String value) {
        int len = value.length();
        byte[] data = new byte[len / 2];

        for (int i = 0; i < len; i += 2) {
            data[i / 2] = (byte) ((Character.digit(value.charAt(i), 16) << 4)
                    + Character.digit(value.charAt(i+1), 16));
        }
        return data;
    }
    
}
```

**For Python Code**

```python
import json
from flask import request

# Place your public key according to the environment
public_key = "PUBLIC KEY"

def callback_notice():
    # Extract the parameter and signature
    param = request.get_data(as_text=True)
    signature = request.headers.get('signature')
    
    # Use RSA-SHA256 to verify the signature, This signature uses hexadecimal encoding.
    # Note: You'll need to implement or import a similar verify function
    verified = sha256_rsa_verify(param, signature, public_key)
    print(f"verified:{verified}")
    
    return json.dumps({"callbackStatus": "SUCCESS" if verified else "FAIL"})
    
def sha256_rsa_verify(data, signature, public_key):
    """
    Verify RSA-SHA256 signature
    :param data: The data that was signed
    :param signature: The signature to verify
    :param public_key: The public key to use for verification
    :return: Boolean indicating if verification succeeded
    """
    pass
```

**For JavaScript Code**

```javascript
// Place your public key according to the environment
const publicKey = "PUBLIC KEY";

async function callbackNotice(req, param) {
    // Extract the signature
    const signature = req.headers['signature'];

    // Use RSA-SHA256 to verify the signature, This signature uses hexadecimal encoding.
    const verified = await verifyRSASHA256(param, signature, publicKey);
    console.log(`verified: ${verified}`);

    return JSON.stringify({
        callbackStatus: verified ? "SUCCESS" : "FAIL"
    });
}

// RSA-SHA256 verification function (example using crypto module)
async function verifyRSASHA256(data, signature, publicKey) {
    const crypto = require('crypto');
    const verify = crypto.createVerify('RSA-SHA256');
    verify.update(data);
    return verify.verify(publicKey, signature, 'base64');
}
```


# Create Webhook Endpoints

This API allows you to create a callback URL for receiving event notifications.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `POST`
* **Request Path**: `/v2/webhook`
* **Authorization Required**: Yes

#### Request Body Parameters

The request body should include the following fields:

```json
{
    "eventType": "ORDER_WEBHOOK",     // (string: required, event type [ORDER_WEBHOOK, GLOBAL_PAYMENT_WEBHOOK, FUNDING_WEBHOOK])
    "url": "https://localhost/callback"        // (string: required, callback URL)
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,                        // (number: response code)
    "msg": "SUCCESS",                   // (string: message)
    "data": {                           // (object: webhook data)
        "webhookId": "ebab8a9663704e7cbbebe672c7c67912", // (string: webhook ID)
        "eventType": "ORDER_WEBHOOK",  // (string: event type)
        "url": "https://localhost/callback", // (string: Merchant Transfer callback URL)
        "status": 1,                    // (number: webhook config status [10: active, 20: disabled, 30: deleted])
        "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGzXcqXbx6uA9PHQ3wGFgeBVEq0YpJxOSWpy4UmgBZ+fTOANiFyrODECWJoWIeJPOWkKR5VUseJTg57js3rgu/2Wn6Ihq1h+n6wCJEMCjK0Ia5brbQXtPcXCHK0J53hrt4YbxTzZuKUi7KIWO/Ply6xzYaTJeKzkaWlNDXF2VWBlutG+Pun3yXdWl7kTRENYA4mxXayaW0ELpnnLXF9qO01bAHPc2G8n0snqDiPMtz8Irw5MqlQ3YMjDiEDFLSb2aP9grae/o/LXZVNv0dJhV5IHgTJctDyFGz837BRiJZsBsodJK+3BTJhLsHqh6VAO8CSdQIDAQAB" // (string: optional, public key for verifying messages)
    }
}
```

#### Example Request

To create a webhook for order events:

```json
{
    "eventType": "ORDER_WEBHOOK",
    "url": "https://localhost/callback"
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
        "eventType": "ORDER_WEBHOOK",
        "url": "https://localhost/callback",
        "status": 1,
        "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGzXcqXbx6uA9PHQ3wGFgeBVEq0YpJxOSWpy4UmgBZ+fTOANiFyrODECWJoWIeJPOWkKR5VUseJTg57js3rgu/2Wn6Ihq1h+n6wCJEMCjK0Ia5brbQXtPcXCHK0J53hrt4YbxTzZuKUi7KIWO/Ply6xzYaTJeKzkaWlNDXF2VWBlutG+Pun3yXdWl7kTRENYA4mxXayaW0ELpnnLXF9qO01bAHPc2G8n0snqDiPMtz8Irw5MqlQ3YMjDiEDFLSb2aP9grae/o/LXZVNv0dJhV5IHgTJctDyFGz837BRiJZsBsodJK+3BTJhLsHqh6VAO8CSdQIDAQAB"
    }
}
```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* The `publicKey` can be used to verify the integrity of the messages received at the callback URL.


# Get Webhook Endpoints

This API allows you to retrieve a list of webhook configurations based on their status.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `GET`
* **Request Path**: `/v2/webhooks`
* **Authorization Required**: Yes

#### Query Parameter

* **status**: (int) The status of the webhooks to filter by:
  * `10`: active
  * `20`: disabled
  * `30`: deleted

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,                        // (number: response code)
    "msg": "SUCCESS",                   // (string: message)
    "data": [                           // (array: list of webhooks)
        {  
            "webhookId": "ebab8a9663704e7cbbebe672c7c67912", // (string: webhook ID)
            "eventType": "ORDER_WEBHOOK", // (string: event type)
            "url": "https://localhost/callback", // (string: Merchant Transfer callback URL)
            "status": 1,                // (number: webhook config status)
            "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGzXcqXbx6uA9PHQ3wGFgeBVEq0YpJxOSWpy4UmgBZ+fTOANiFyrODECWJoWIeJPOWkKR5VUseJTg57js3rgu/2Wn6Ihq1h+n6wCJEMCjK0Ia5brbQXtPcXCHK0J53hrt4YbxTzZuKUi7KIWO/Ply6xzYaTJeKzkaWlNDXF2VWBlutG+Pun3yXdWl7kTRENYA4mxXayaW0ELpnnLXF9qO01bAHPc2G8n0snqDiPMtz8Irw5MqlQ3YMjDiEDFLSb2aP9grae/o/LXZVNv0dJhV5IHgTJctDyFGz837BRiJZsBsodJK+3BTJhLsHqh6VAO8CSdQIDAQAB" // (string: optional, public key for verifying messages)
        }
    ]
}
```

#### Example Request

To query active webhooks:

```
GET /v2/webhooks?status=10
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": [
        {  
            "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
            "eventType": "ORDER_WEBHOOK",
            "url": "https://localhost/callback",
            "status": 1,
            "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGzXcqXbx6uA9PHQ3wGFgeBVEq0YpJxOSWpy4UmgBZ+fTOANiFyrODECWJoWIeJPOWkKR5VUseJTg57js3rgu/2Wn6Ihq1h+n6wCJEMCjK0Ia5brbQXtPcXCHK0J53hrt4YbxTzZuKUi7KIWO/Ply6xzYaTJeKzkaWlNDXF2VWBlutG+Pun3yXdWl7kTRENYA4mxXayaW0ELpnnLXF9qO01bAHPc2G8n0snqDiPMtz8Irw5MqlQ3YMjDiEDFLSb2aP9grae/o/LXZVNv0dJhV5IHgTJctDyFGz837BRiJZsBsodJK+3BTJhLsHqh6VAO8CSdQIDAQAB"
        }
    ]
}
```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* The `publicKey` can be used to verify the integrity of the messages received at the webhook URL.


# Update a Webhook

This API allows you to update an existing webhook configuration.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Header**: `Content-Type: application/json`
* **Request Method**: `PUT`
* **Request Path**: `/v2/webhook/{webhookId}`
* **Authorization Required**: Yes

#### Request Body Parameters

The request body should include the following fields:

```json
{
    "url": "https://localhost/callback", // (string: required, callback URL)
    "status": 1                           // (number: webhook config status [10: active, 20: disabled])
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,                         // (number: response code)
    "msg": "SUCCESS",                    // (string: message)
    "data": {                            // (object: webhook data)
        "webhookId": "ebab8a9663704e7cbbebe672c7c67912", // (string: webhook ID)
        "eventType": "ORDER_WEBHOOK",    // (string: event type)
        "url": "https://localhost/callback", // (string: Merchant Transfer callback URL)
        "status": 1,                     // (number: webhook config status [10: active, 20: disabled, 30: deleted])
        "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGzXcqXbx6uA9PHQ3wGFgeBVEq0YpJxOSWpy4UmgBZ+fTOANiFyrODECWJoWIeJPOWkKR5VUseJTg57js3rgu/2Wn6Ihq1h+n6wCJEMCjK0Ia5brbQXtPcXCHK0J53hrt4YbxTzZuKUi7KIWO/Ply6xzYaTJeKzkaWlNDXF2VWBlutG+Pun3yXdWl7kTRENYA4mxXayaW0ELpnnLXF9qO01bAHPc2G8n0snqDiPMtz8Irw5MqlQ3YMjDiEDFLSb2aP9grae/o/LXZVNv0dJhV5IHgTJctDyFGz837BRiJZsBsodJK+3BTJhLsHqh6VAO8CSdQIDAQAB" // (string: optional, public key for verifying messages)
    }
}
```

#### Example Request

To update a webhook with a specific `webhookId`:

```json
{
    "url": "https://localhost/callback",
    "status": 1
}
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
        "eventType": "ORDER_WEBHOOK",
        "url": "https://localhost/callback",
        "status": 1,
        "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGzXcqXbx6uA9PHQ3wGFgeBVEq0YpJxOSWpy4UmgBZ+fTOANiFyrODECWJoWIeJPOWkKR5VUseJTg57js3rgu/2Wn6Ihq1h+n6wCJEMCjK0Ia5brbQXtPcXCHK0J53hrt4YbxTzZuKUi7KIWO/Ply6xzYaTJeKzkaWlNDXF2VWBlutG+Pun3yXdWl7kTRENYA4mxXayaW0ELpnnLXF9qO01bAHPc2G8n0snqDiPMtz8Irw5MqlQ3YMjDiEDFLSb2aP9grae/o/LXZVNv0dJhV5IHgTJctDyFGz837BRiJZsBsodJK+3BTJhLsHqh6VAO8CSdQIDAQAB"
    }
}
```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* The `publicKey` can be used to verify the integrity of the messages received at the callback URL.


# Delete a Webhook

This API allows you to delete an existing webhook configuration.

#### Endpoint Information

* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `DELETE`
* **Request Path**: `/v2/webhook/{webhookId}`
* **Authorization Required**: Yes

#### Path Parameter

* **webhookId**: (string) The ID of the webhook you want to delete.

#### Response Structure

The response will include the following fields:

```json
{
    "code": 200,                        // (number: response code)
    "msg": "SUCCESS",                   // (string: message)
    "data": {                           // (object: deletion result)
        "result": true                  // (boolean: indicates if the deletion was successful)
    }
}
```

#### Example Request

To delete a webhook with a specific `webhookId`:

```
DELETE /v2/webhook/ebab8a9663704e7cbbebe672c7c67912
```

#### Example Response

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "result": true
    }
}
```

#### Notes

* Ensure that valid authorization tokens are included in the request headers for successful execution.
* Once deleted, the webhook configuration cannot be recovered.


# Fiat/Crypto Order Message Push

This API allows you to push order notifications to a specified webhook.

#### Endpoint Information

* **Request Method**: `POST`
* **Request Path**: (Specify the appropriate path for your webhook notifications)
* **Requesst** **Headers**: Requires signature
  * `signature` (string: To verify that a webhook request is coming from trubit, you can use the signature header. The value of the header is a RSA-SHA256 signature of the request body, Use hexadecimal encoding.)

#### Request Body Parameters

The request body should include the following fields:

```json
{
    "webhookId": "ebab8a9663704e7cbbebe672c7c67912",  // (string: ID of the webhook)
    "eventType": "ORDER_WEBHOOK",                    // (string: event type [ORDER_WEBHOOK])
    "orderId": "473130522693193728",                 // (string: ID of the order)
    "clientId": "W658784738723",                     // (string: ID of the client)
    "userId": "455472",                              // (string: ID of the user)
    "merchantId": 4,                                 // (number: ID of the merchant)   
    "orderType": "SELL",                             // (string: order type [BUY or SELL])
    "fiat": "MXN",                                   // (string: name of the fiat currency)
    "fiatAmount": "99",                             // (decimal: amount of fiat currency)
    "fiatFee": "0",                                  // (decimal: fiat fee)
    "crypto": "USDT",                                // (string: name of the crypto currency)
    "cryptoAmount": "5.00",                          // (decimal: amount of crypto currency)
    "orderPrice": "19.8158",                         // (decimal: order price)
    "orderStatus": "60",                             // (string: order status [10, 30, 40, 50, 60, 70])
    "createTime": "1735279907000",                  // (string: timestamp of the create time in milliseconds)
    "updateTime": "1735280582000"                   // (string: timestamp of the update time in milliseconds)
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "callbackStatus": "SUCCESS"                      // (string: callback status, indicates if the message was successfully notified)
}
```

#### Example Request

```json
{
    "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
    "eventType": "ORDER_WEBHOOK",
    "orderId": "473130522693193728",
    "clientId": "W658784738723",
    "userId": "455472",
    "merchantId": 4,    
    "orderType": "SELL",
    "fiat": "MXN",
    "orderAmount": "99",
    "fiatFee": "0",
    "crypto": "USDT",
    "quantity": "5",
    "orderPrice": "19.8158",
    "orderStatus": "60",
    "createTime": "1735279907000",
    "updateTime": "1735280582000"
}
```

#### Example Response

```json
{
    "callbackStatus": "SUCCESS"
}
```

#### Notes

* Ensure that the webhook URL is properly configured to receive and process the notification.
* The `callbackStatus` indicates whether the message was successfully sent to the webhook. If it shows `SUCCESS`, the notification was sent without issues.


# Fiat/Fiat Order Message Push

This API allows you to push global payment order notifications to a specified webhook.

#### Endpoint Information

* **Request Method**: `POST`
* **Request Path**: (Specify the appropriate path for your webhook notifications)
* **Requesst** **Headers**: Requires signature
  * `signature` (string: To verify that a webhook request is coming from trubit, you can use the signature header. The value of the header is a RSA-SHA256 signature of the request body, Use hexadecimal encoding.)

#### Request Body Parameters

The request body should include the following fields:

```json
{
    "webhookId": "ebab8a9663704e7cbbebe672c7c67912",  // (string: ID of the webhook)
    "eventType": "GLOBAL_PAYMENT_WEBHOOK",            // (string: event type [GLOBAL_PAYMENT_WEBHOOK])
    "orderId": "473130522693193728",                  // (string: ID of the order)
    "clientId": "W658784738723",                      // (string: ID of the client)
    "userId": "455472",                               // (string: ID of the user)        
    "onRampCountry": "Mexico",                        // (string: name of the on-ramp country)
    "onRampMerchantId": 3,                            // (number: ID of the on-ramp merchant id)
    "onRampFiat": "MXN",                              // (string: name of the on-ramp fiat currency)
    "onRampFiatAmount": "100.00",                     // (decimal: amount of on-ramp fiat currency)
    "onRampFiatFee": "0",                             // (decimal: amount of on-ramp fiat fee)    
    "offRampCountry": "Hong Kong",                    // (string: name of the off-ramp country)
    "offRampMerchantId": 4,                           // (number: ID of the off-ramp merchant id)
    "offRampFiat": "USD",                             // (string: name of the off-ramp fiat currency)
    "offRampFiatAmount": "18.00",                     // (decimal: amount of off-ramp fiat currency)
    "offRampFiatFee": "2.00",                         // (decimal: amount of off-ramp fiat fee)    
    "orderPrice": "20.00",                            // (decimal: price of the order)
    "orderStatus": "41",                              // (string: order status [10, 30, 31, 41, 51, 60, 71, 72])
    "createTime": "1735279907000",                    // (string: timestamp of the create time in milliseconds)
    "updateTime": "1735280582000"                     // (string: timestamp of the update time in milliseconds)
}
```

#### Response Structure

The response will include the following fields:

```json
{
    "callbackStatus": "SUCCESS"                       // (string: callback status, indicates if the message was successfully notified)
}
```

#### Example Request

```json
{
    "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
    "eventType": "GLOBAL_PAYMENT_WEBHOOK",
    "orderId": "473130522693193728",
    "clientId": "W658784738723",
    "userId": "455472",
    "onRampCountry": "Mexico",
    "onRampMerchantId": 3,
    "onRampFiat": "MXN",
    "onRampFiatAmount": "100.00",
    "onRampFiatFee": "0",
    "offRampCountry": "Hong Kong",
    "offRampMerchantId": 4,
    "offRampFiat": "USD",
    "offRampFiatAmount": "18.00",
    "offRampFiatFee": "2.00",
    "orderPrice": "20.00",
    "orderStatus": "41",
    "createTime": "1735279907000",
    "updateTime": "1735280582000"
}
```

#### Example Response

```json
{
    "callbackStatus": "SUCCESS"
}
```

#### Notes

* Ensure that the webhook URL is properly configured to receive and process the notification.
* The `callbackStatus` indicates whether the message was successfully sent to the webhook. If it shows `SUCCESS`, the notification was sent without issues.


# Funding Records Message Push

TruBit uses webhooks to notify merchants of funding-related events in real time, such as deposits, withdrawals, crypto purchases, and refunds. When triggered, a POST request with detailed transaction data is sent to your configured webhook URL.

**Endpoint Information**

* **Request Method:** POST
* **Request Path:** *(Specify the appropriate path for your webhook notifications)*
* **Requesst** **Headers**: Requires signature
  * `signature` (string: To verify that a webhook request is coming from trubit, you can use the signature header. The value of the header is a RSA-SHA256 signature of the request body, Use hexadecimal encoding.)

**Request Body Parameters**

The request body should include the following fields:

```json
{
    "webhookId": "ebab8a9663704e7cbbebe672c7c67912",  // (number: ID of the webhook)
    "eventType": "FUNDING_WEBHOOK",                  // (string: event type [FUNDING_WEBHOOK: merchant funding event])
    "txId": "1123123123",                            // (number: ID of the fiat claim)
    "merchantId": "3",                               // (number: ID of the merchant)
    "merchantName": "Rrturo Tellez",                 // (string: name of the merchant)
    "fiat": "ARS",                                   // (string: name of the fiat currency)
    "totalAmount": "22.00",                          // (decimal: total fiat amount)
    "amount": "20.00",                               // (decimal: actual fiat amount)
    "fee": "2.00",                                   // (decimal: amount of the fee)
    "userPaymentId": "91",                           // (number: ID of the user payment method)
    "type": "DEPOSIT",                               // (enum: type [DEPOSIT: The add of the funding record, WITHDRAW: The claim of the funding record, BUY_CRYPTO: The buy crypto of the funding record, REFUND: The refund of the funding record])
    "status": "1",                                   // (enum: status [1: pending, 2: completed, 3: canceled])
    "createTime": "1737452292000",                   // (string: timestamp of the create time in milliseconds)
    "updateTime": "1737452344000",                   // (string: timestamp of the update time in milliseconds)
    "cardNo": "3067212321",                          // (string: id of the entity sending ID number)
    "taxId": "5269328432",                           // (string: id of the entity sending tax)
    "payerName": "Matias Alva",                      // (string: name of the entity sending funds)
    "payerAccount": "CH8508843132556121020",         // (string: bank account of the entity sending funds)
    "bankWebhookInfo": "{}"                          // (json: bank webhook info of the entity sending funds, see Bank Webhook Info Detaials)
}
```

**Response Structure**

The response will include the following fields:

```json
{
    "callbackStatus": "SUCCESS"                      // (string: callback status; if SUCCESS is returned, the message is successfully notified)
}
```

**Example Request**

```json
{
    "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
    "eventType": "FUNDING_WEBHOOK",
    "txId": "1123123123",
    "merchantId": "3",
    "merchantName": "Rrturo Tellez",
    "fiat": "ARS",
    "totalAmount": "22.00",
    "amount": "20.00",
    "fee": "2.00",
    "userPaymentId": "91",
    "type": "DEPOSIT",
    "status": "1",
    "createTime": "1737452292000",
    "updateTime": "1737452344000",
    "cardNo": "3067212321",
    "taxId": "5269328432", 
    "payerName": "Matias Alva",
    "payerAccount": "CH8508843132556121020" 
}
```

**Example Response**

```json
{
    "callbackStatus": "SUCCESS"
}
```

**Bank Webhook Info Detaials**

MXN Detail

```json
{
    "sender_account_number": "684180168000000000",  //(the payer cable)
    "description": "Payment",                       //(the description)
    "sender_name": "CENTAURE S.A. DE C.V.",         //(the payer name)
    "tracking_id": "DO1755784299100",               //(the bank tracking id)
    "sender_id": "CCN2203099WA"                     //(the identity id)
}
```

ARS Detail

```json
{	
    "id": "98569107",                                 //id
    "idCoelsa": "86VRPQ2GVJEQE70M2GLY0M",             //bank order id
    "titularOriginante": "Alejandro Samuel Alvarez",  //payer name
    "cuitCvu": "20391896357",                         //payer cuit
    "cuitOriginante": "20391896357",                  //payer cuit
    "cuentaOriginante": "0000003100158708912546",     //payer cvu/cbu
    "titularCvu": "ALVAREZ ALEJANDRO SAMUEL42911|61", //receiver name
    "cuitPsp": "30717909751",                         //receiver cuit
    "cvu": "0000278500000000540634",                  //receiver cvu
    "descripcion": "",                                //remark
    "fechaNegocio": "2025-08-28T00:00:00Z"            //time of payment   
}
```

COP Detail

```json
{
    "sender_name": "SUPEFINE SAS",      //(the payer name)
    "sender_id": "9017343700",          //(the identity id)
    "sender_bank_code": "1013",         //(the bank code)
    "description": "Payment In",        //(the description)
    "r2p_method": "pse",                //(the method)
    "tracking_key": "1714319140"        //(the bank tracking key)
}
```

BRL Detail

```json
{
    "payer_tax_id": "51799311002001",           //(the payer tax id)
    "payer_name": "Tom",                        //(the payer name)
    "payer_bank_account": "570302",             //(the bank last account number)
    "payer_bank_name": "BCO DO BRASIL S.A."     //(the bank name)
}
```

#### Notes

* Ensure that the webhook URL is properly configured to receive and process the notification.
* The `callbackStatus` indicates whether the message was successfully sent to the webhook. If it shows `SUCCESS`, the notification was sent without issues.


# Error and Warning Dictionary

***

\
**Parameter Errors**

| Code  | Message                           | Description                                        |
| ----- | --------------------------------- | -------------------------------------------------- |
| -4010 | PARAM\_IS\_INVALID                | Parameter {0} is invalid                           |
| -4011 | PARAM\_EXCEEDS\_LIMIT\_LENGTH     | Parameter {0} exceeds the limit length of {1}      |
| -4012 | PARAM\_EXCEEDS\_LIMIT\_QUANTITY   | Parameter {0} exceeds the limit quantity of {1}    |
| -4013 | PARAM\_MUST\_LENGTH\_CHAR         | The length of parameter {0} must be {1} characters |
| -4014 | PARAM\_MUST\_LENGTH\_LETTERS      | The length of parameter {0} must be {1} letters    |
| -4015 | PARAM\_MUST\_LENGTH\_NUMERIC      | The length of parameter {0} must be {1} digits     |
| -4016 | PARAM\_MUST\_POSITION             | The parameter {0} must be {1} at position {2}      |
| -4021 | PARAM\_NOT\_IS\_NUMERIC           | Parameter {0} is not numeric type                  |
| -4022 | PARAM\_NOT\_IS\_ALPHABETIC        | Parameter {0} is not alphabetic type               |
| -4023 | PARAM\_NOT\_IS\_ALPHANUMERIC      | Parameter {0} is not alphanumeric type             |
| -4024 | PARAM\_IS\_INVALID\_ISO1          | Parameter {0} is an invalid ISO 3166-1 code        |
| -4025 | PARAM\_IS\_INVALID\_ISO2          | Parameter {0} is an invalid ISO 3166-2 code        |
| -4026 | PARAM\_IS\_INVALID\_ACCOUNT\_TYPE | Parameter {0} is an invalid account owner type     |
| -4040 | COMMON\_ERROR\_CODE               | fill with unknown errors                           |
| -4041 | COMMON\_TRAN\_CODE                | fill with unknown errors                           |
| -1174 | REPEATED\_SUBMIT\_REQUEST         | Repeated submit request                            |

#### **Payment Method Errors**

| Code  | Message                               | Description                                                                   |
| ----- | ------------------------------------- | ----------------------------------------------------------------------------- |
| -4027 | PAYMENT\_NOT\_EXIST                   | The payment method doesn't exist                                              |
| -5001 | PAYMENT\_SELECT\_AUTO                 | Please select automatic payment method                                        |
| -5002 | PAYMENT\_NOT\_ACCOUNT\_INFO           | Payment method has no bank account information                                |
| -5003 | PAYMENT\_NOT\_EDIT                    | Payment method cannot be modified temporarily                                 |
| -5004 | PAYMENT\_NOT\_CONFIG\_AUTO\_API       | Payment method does not have automatic bank API configured                    |
| -5014 | PAYMENT\_ACCOUNT\_INFO\_AND\_MC\_SAME | Bank card information matches merchant's card information                     |
| -5017 | PAYMENT\_INVALID                      | Invalid payment method                                                        |
| -5018 | PAYMENT\_AND\_PLATFORM\_NOT\_MATCH    | Payment method does not match the platform configuration, please choose again |
| -5048 | PAYMENT\_TYPE\_INVALID                | The payment type is invalid                                                   |
| -5053 | PAYMENT\_ACCOUNT\_ALREADY\_EXISTS     | Account already exists                                                        |
| -5054 | PAYMENT\_ADD\_FAIL                    | Failed to add a payment method; please edit and resubmit                      |
| -2017 | EMAIL\_EXIST                          | The email already exists                                                      |

***

#### **Merchant Errors**

| Code  | Message                                | Description                                                       |
| ----- | -------------------------------------- | ----------------------------------------------------------------- |
| -5005 | MC\_EXIST                              | Merchant already exists                                           |
| -5006 | MC\_NOT\_EXIST                         | Merchant does not exist                                           |
| -5007 | MC\_INVALID                            | Invalid merchant information                                      |
| -5015 | CUIT\_AND\_MC\_NOT\_MATCH              | The CUIT does not match with your selected merchant               |
| -5038 | MC\_ACCOUNT\_NOT\_EXIST                | The merchant account does not exist                               |
| -5039 | MC\_SETTINGS\_EXIST                    | The merchant settings do not exist                                |
| -5056 | PAYMENT\_AND\_MC\_SETTINGS\_NOT\_MATCH | Payment information doesn't match merchant configuration          |
| -5059 | MC\_REGISTER\_FAIL                     | Merchant registration failed                                      |
| -5064 | EXCEEDED\_MC\_NUMBER                   | Exceeded the maximum number of merchants (max: {0})               |
| -5065 | MC\_ACCOUNT\_INVALID                   | The merchant channel is invalid                                   |
| -5066 | MC\_ACCOUNT\_REVIEWING                 | The merchant's account is under verification                      |
| -5067 | MC\_ACCOUNT\_END                       | The merchant account certification process has ended              |
| -5069 | MC\_NAME\_EXIST                        | The merchant name already exists                                  |
| -5070 | MC\_NOT\_OPEN\_ACCOUNT                 | The merchant has not activated the automatic mode account for {0} |
| -5071 | MC\_CHANNEL\_INVALID                   | Merchant channel is invalid                                       |

***

#### **Order Errors**

| Code  | Message                              | Description                                                                 |
| ----- | ------------------------------------ | --------------------------------------------------------------------------- |
| -5008 | ORDER\_REFUND\_NOT\_OP               | Refund orders cannot be processed                                           |
| -5009 | ORDER\_PAYING                        | Order is in payment process; current operation unavailable                  |
| -5010 | ORDER\_AUTO\_NOT\_MANUAL\_COMPLETE   | Automated orders cannot be completed manually                               |
| -5011 | ORDER\_AUTO\_NOT\_CURRENT\_OPERATION | Automated orders cannot perform current operation                           |
| -5034 | ORDER\_END                           | The order process is over                                                   |
| -5035 | ORDER\_NOT\_FINISH                   | Orders cannot be filled at present                                          |
| -5041 | ORDER\_UNPAID\_CAN\_UPLOAD           | Only non-payment or pending-document orders can upload supporting documents |
| -5050 | ORDER\_MIN\_AMOUNT                   | Order does not meet the minimum limit (min {0} {1})                         |
| -5060 | ORDER\_MAX\_AMOUNT                   | Order does not meet the maximum limit (max {0} {1})                         |

***

#### **Trading Pair Errors**

| Code  | Message                               | Description                                               |
| ----- | ------------------------------------- | --------------------------------------------------------- |
| -5019 | SYMBOL\_INVALID                       | Invalid trading pair                                      |
| -5020 | SYMBOL\_BUY\_CLOSED                   | BUY direction is closed                                   |
| -5021 | SYMBOL\_SELL\_CLOSED                  | SELL direction is closed                                  |
| -5045 | FIAT\_INVALID                         | Invalid fiat                                              |
| -5047 | SYMBOL\_AND\_PAYMENT\_NOT\_MATCH      | The symbol does not match the payment method              |
| -5051 | PAYMENT\_FIAT\_AND\_ORDER\_NOT\_MATCH | Fiat currency in payment method does not match order fiat |
| -5057 | COUNTRY\_AND\_FIAT\_NOT\_SUPPORT      | The selected country and fiat currency are not supported  |
| -5058 | TOKEN\_NOT\_SUPPORT                   | The selected crypto is not supported                      |

***

#### **Risk Control Errors**

| Code  | Message                     | Description                                            |
| ----- | --------------------------- | ------------------------------------------------------ |
| -5022 | PRICE\_BELOW\_SAFE          | Price is below the trade line                          |
| -5023 | BASE\_RATE\_CONFIG\_INVALID | The current coin pair is not supported                 |
| -5024 | USER\_RATE\_CONFIG\_INVALID | Invalid user rate configuration; contact admin         |
| -5025 | RISK\_RATE\_CONFIG\_INVALID | Invalid risk control rate configuration; contact admin |
| -5027 | RATE\_INVALID               | Current exchange rate is invalid                       |

***

#### **KYC/KYB Errors**

| Code  | Message                                | Description                                         |
| ----- | -------------------------------------- | --------------------------------------------------- |
| -5032 | NOT\_WHITELIST\_USER                   | Not an OTC whitelist user; contact customer service |
| -5033 | NOT\_API\_USER                         | Not an API user; contact customer service           |
| -5037 | NEED\_UPLOAD\_DOCUMENTS                | You need to upload supporting documents             |
| -5042 | USER\_NOT\_UPLOAD\_DOCUMENTS           | No supporting documents were uploaded               |
| -5043 | NEED\_PASS\_KYC\_OR\_KYB               | You must pass KYC/KYB to perform this operation     |
| -5044 | PAYMENT\_ADD\_NEED\_PASS\_KYC\_OR\_KYB | You must pass KYC/KYB to add this payment method    |
| -5055 | KYC\_OR\_KYB\_REGISTER\_FAIL           | KYC/KYB registration failed                         |
| -5061 | MAX\_DOCUMENT                          | Exceeded maximum uploadable documents (max {0})     |
| -5062 | MC\_KYC\_REVIEWING                     | Merchant KYC is under verification                  |
| -5063 | MC\_KYC\_END                           | Merchant KYC certification process has ended        |

***

#### **Compliance Errors**

| Code  | Message                                    | Description                                                           |
| ----- | ------------------------------------------ | --------------------------------------------------------------------- |
| -5012 | BANK\_NOT\_SUPPORT                         | Bank not supported                                                    |
| -5013 | MC\_COUNTRY\_NOT\_SUPPORT                  | Automatic API is not supported in this country                        |
| -5016 | FIAT\_NOT\_MATCH                           | The fiat currency does not match the merchant                         |
| -5026 | PEND\_ORDER\_NUM\_LIMIT                    | Too many pending orders (current: {0}); wait before creating new ones |
| -5028 | SELF\_ORDER\_CLOSE                         | Self-service ordering is temporarily closed                           |
| -5029 | ORDER\_UID\_EXCEED\_LIMIT                  | Order exceeds user's monthly transaction limit                        |
| -5030 | ORDER\_MC\_EXCEED\_LIMIT                   | Order exceeds user's monthly limit with the merchant                  |
| -5031 | TRADE\_TEMP\_NOT\_PROCEED                  | Transaction temporarily unavailable; contact support                  |
| -5036 | PAYMENT\_FEE\_INVALID                      | Fee config invalid; contact support                                   |
| -5046 | COMMON\_ERROR                              | Please try again or contact customer service                          |
| -5049 | CONFIG\_INVALID                            | Invalid config                                                        |
| -5052 | DESELECT\_MC                               | Merchant selection is not available for manual payment methods        |
| -5068 | NOT\_RELIANCE\_MODE                        | You are not a Reliance model user; function unavailable               |
| -5072 | ACCOUNT\_TYPE\_AND\_BANK\_CODE\_NOT\_MATCH | Account type \[{0}] does not support bank code \[{1}]                 |

<br>


# Changelog

***

### VelaFi API Documentation V2

**Release Date: 2025-06-13**

#### 1. Workflow Update: Merchant Creation Process

[Guides – Creating Your Merchant](/velafi-1/guides/creating-your-merchant)\
The merchant creation process has been updated to adopt the KYC/KYB model.

> **Note:** Endpoints prior to 2025-06-13 will remain functional for the time being, but support will be deprecated at a later date. Users are encouraged to migrate to the new flow promptly.

#### 2. API Update: Create Merchant Endpoint

[API Reference – Create Merchant](/velafi-1/api-reference/merchant/create-merchant)\
The `create merchants` API endpoint has been updated to align with the new KYC/KYB process.

> **Note:** Existing endpoint versions released before 2025-06-13 will continue to work temporarily, but deprecation is planned.

#### 3. New Feature: Activate Merchant Account (Guide)

[Guides – Activate a Merchant Account](/velafi-1/api-reference/merchant/activate-merchant-account)\
A new step has been added to allow users to **activate fiat accounts** once a merchant entity is successfully created. This ensures the merchant is fully operational in terms of fiat transactions.

#### 4. New API Endpoint: Activate Merchant Account

[API Reference – Activate Merchant Account<br>](/velafi-1/api-reference/merchant/activate-merchant-account)Introduces a new API endpoint that enables merchants to **activate their fiat account** after the initial merchant setup is complete. This ensures the merchant is fully operational in terms of fiat transactions.

***

**Release Date: 2025-05-08**

***

**1.Funding Records Message Push Webhook**\
This update aims to provide more detailed funding record information for better tracking and management of fund sources.

* **Request Body Parameters**:
  * **New Fields**:
    * `payerName`: string: name of the entity sending funds
    * `payerAccount`: string: bank account of the entity sending funds

**2.** **Added API endpoint** `/v2/merchant/transfer` for internal fund transfers.

***

**Release Date: 2025-04-14**

This version introduces new API endpoints and webhook functionality related to the Pending Fund system, as well as updates to available payment methods.

***

#### 1. Payment Method Update in Guides

* **New Payment ID: 70 – VelaFi Pending Fund**\
  When creating an order via API, users can now select **VelaFi Pending Fund** as the payment or receiving method. This enables faster transaction processing by utilizing preloaded funds.

***

#### 2. New API Endpoint: Retrieve Pending Fund

**Location**: API Reference > Merchant

* Allows users to query their **Pending Fund account** via API.
* Enables users to preload funds into the account, avoiding delays from external transfer confirmation during transactions.

***

#### 3. New API Endpoint: Claim Pending Fund

**Location**: API Reference > Merchant

* Enables withdrawal of available balances from the **Pending Fund account** to a specified payment method.
* Withdrawals are available at any time, allowing flexible fund management.

***

#### 4. New API Endpoint: Retrieve Funding Records

**Location**: API Reference > Merchant

* Provides detailed records of all **Pending Fund-related activities**, including deposits, withdrawals, usage, and refunds.
* Supports full traceability and financial transparency.

***

#### 5. New Webhook: Funding Records Message Push

**Location**: Webhooks

* Introduces webhook notifications for **Pending Fund events**.
* Merchants receive real-time updates with structured transaction data, improving operational automation and monitoring.

***


# A Gentle Introduction for Developer

## **Welcome to the VelaFi API Documentation**&#x20;

Programmatically manage financial asset conversions and cross-currency transfers with VelaFi. Our API empowers you to seamlessly convert fiat to digital currencies and facilitate fiat-to-fiat transfers using stablecoins as intermediaries. Designed for enterprise developers, our solution prioritizes security, efficiency, and compliance, enabling you to build robust financial workflows for your business or customers.&#x20;

## **Integration Made Simple**&#x20;

The VelaFi API uses [RESTful](https://en.wikipedia.org/wiki/REST) architecture to organize resources. It employs basic access authentication over [HTTPS](https://en.wikipedia.org/wiki/HTTPS) for secure communication, accepts and returns JSON-encoded bodies, and utilizes standard [HTTP](https://en.wikipedia.org/wiki/HTTP) response codes for clarity. Our comprehensive guides and reference implementations ensure a smooth and efficient integration process.

## **What You’ll Find Here**

Explore detailed documentation and resources to address your payment and conversion needs:

{% content-ref url="/pages/EOdwnemFEXYcCD5xYT5k" %}
[📖  Guides](/)
{% endcontent-ref %}

**Step-by-step instructions for managing transfers and conversions.**

{% content-ref url="/pages/nU8LdsvLdidgiEORkqE6" %}
[📗  API Reference](/api-reference/basic-configuration)
{% endcontent-ref %}

**Detailed descriptions of endpoints, parameters, and responses.**<br>

Start building with VelaFi today and unlock the power of seamless financial asset management.&#x20;

<br>


# Step-by-Step Guide

Guide

### Onboarding with **VelaFi**&#x20;

This section walks you through the complete onboarding process with VelaFi, including account registration, API key generation, merchant setup, compliance verification, and payment accout activation.

1. [**Creating VelaFi Account**](/guides/creating-velafi-account)\
   Begin by registering an account on the VelaFi Platform. Upon successful registration, the system will assign a unique **User ID (UID)**, which serves as the identifier for managing all your transactions, merchants, API, and account-level operations.<br>

2. [**Create a Merchant & Complete Compliance Verification (KYC/KYB)**](/guides/creating-your-merchant)

   To operate under VelaFi’s compliance framework, you must create a legal individual or business entity (Merchant).

   * Submit detailed merchant information to initiate the KYC/KYB verification process.
   * Once approved, the platform will assign a unique **Merchant ID (MID)** to you or your client.
   * Upon successful creation, a **crypto custody wallet** will be automatically provisioned for the merchant with an initial monthly withdrawal limit of **USD 10,000,000,000.**

3. [**Create API Key**](/guides/creating-api-key)\
   Once your account is activated, log in to the VelaFi dashboard to generate your **API Key**. This key is required to authenticate your API requests and securely interact with VelaFi’s services.\
   \
   **Environment Selection**

   | Environment | Base URL                      | Description                                 |
   | ----------- | ----------------------------- | ------------------------------------------- |
   | Sandbox     | <https://api-test.velafi.com> | Test environment for simulated transactions |
   | Production  | <https://api.velafi.com>      | Live environment for real transactions      |

4. [**API Access Activation**](https://share.hsforms.com/10CFW-gfVR3GvDmNX6r8M6wr8y9l)

After generating your API key, please contact the **VelaFi Support Team** to enable API access for your account.

> **Email:** <contact@velafi.com>

5\. [**Activate Merchant Payment Account**](/guides/activate-merchant-account)

Submit the required documents and information for the target countries where your merchant will operate to activate fiat channels (e.g., ARS, MXN, BRL, PEN, COP, USD, etc.).

> [**Activate Merchant Account (For Individual)**](/api-reference/merchant/activate-merchant-account-for-individual)\
> \
> [**Activate Merchant Account (For Business)**](/api-reference/merchant/activate-merchant-account-for-business)

* Each merchant will be assigned a **dedicated payment account**, such as **CVU** and **CUIT** numbers for ARS (Argentina).
* Funds can be deposited into the merchant’s payment account via **bank transfer**.
* VelaFi automatically reconciles incoming payments and credits the corresponding balance to the merchant’s wallet.
* Once activation is complete, you will receive your **monthly transaction limit** for each fiat channel.

[View limits.](/guides/limits)

> **Need higher limits?** [Click here](/api-reference/merchant/upgrade-merchant-limit)

***

### On-Ramp Workflow (Fiat → Crypto)

Review the following Support articles to see our supported currencies and regions for on-ramp:

[View supported cryptocurrencies & fiat currencies](/guides/pair)<br>

#### 1. Ensure [Merchant Fiat Account Activation](/api-reference/merchant/activate-merchant-account-for-individual)

Before initiating a transaction, please ensure that the merchant has successfully activated their fiat account.\
For example, if Merchant **Alice** wants to perform an **ARS → USDT** transaction, she must first activate her **ARS fiat account**.<br>

#### 2. [Create Fiat to Crypto Order](/api-reference/order/create-a-fiat-to-crypto-order)

When an order is created, the system will generate a unique `order_id` to track the transaction.

#### 3. [Retrieve a Specific Order](/api-reference/order/retrieve-a-specific-order)

To get the details of a specific order, use the `order_id` to query and retrieve comprehensive order information.

#### 4. Make a Payment

There are two payment methods available:

**A. Pending Fund Balance Payment**\
If you select **Merchant Account Pending Fund** and the account balance is sufficient, the system will automatically process the payment.

**B. Real-Time Manual Payment**\
If you opt for **real-time payment**, you must manually transfer the funds to the fiat account specified in the **order details**.

#### 5. System Confirms Order Completion

Once the payment is confirmed, your account will instantly receive the corresponding amount of **cryptocurrency**.

**Note:** Due to compliance requirements, certain transactions may require you to submit supporting documents after order creation via the **Upload Invoice Documents For a Specific Order** endpoint.

***

### Off-Ramp Workflow (Crypto → Fiat)

Review the following Support articles to see our supported currencies and regions for off-ramp:

[View supported cryptocurrencies & fiat currencies](/guides/pair)<br>

Before initiating a transaction, please ensure that the merchant has successfully activated their fiat account.\
For example, if Merchant Alice wants to perform an **USDT → ARS** transaction, she must first activate her **ARS fiat account And added** [**payment methods**](/api-reference/payment-method/add-payment-method)**.**\ <br>

#### 1.[ Create a Crypto to Fiat Order](/api-reference/order/create-a-crypto-to-fiat-order)

Initiate a transaction by creating a **Crypto to Fiat** order through the appropriate API endpoint.

#### 2. System Processes the Transaction

Once the order is submitted, the system will handle cryptocurrency validation, conversion, and fiat settlement instructions.

#### 3. Receive Fiat Funds

The fiat currency will be transferred to the beneficiary's account upon successful completion of the transaction.

***

### Global Payment Workflow

Review the following Support articles to see our supported currencies and regions for global payment:

[Supported cryptocurrencies & fiat currencies](/guides/pair)\
\
\
**Before initiating a transaction, please ensure that the merchant has successfully activated their fiat accounts.**\
For example, if merchant **Alice** intends to perform a **USD → ARS** transaction, she must first activate both her **USD** and **ARS** fiat accounts and add the required payment method.<br>

1. Confirm transfer details:
   * Sender fiat currency & amount
   * Recipient fiat currency & amount
2. Select sender [Merchant](/api-reference/merchant)
3. Retrieve [payment methods](/guides/payment-method-id)
4. Select recipient [Merchant](/api-reference/merchant)
5. Configure recipient [payment method](/api-reference/payment-method)
6. [Create fiat to fiat order via API](/api-reference/order/create-a-fiat-to-fiat-order)
7. Order execution completed
8. Recipient fiat funds received


# Creating VelaFi Account

Visit the [VelaFi Signup Page](https://www.velafi.com/signup).

<figure><img src="/files/5RBQSXxcAlrHSmeSGbyc" alt=""><figcaption></figcaption></figure>

* Follow the on-screen instructions to complete the registration process.
* Once the registration is complete, log in to your VelaFi account.&#x20;


# Creating Your Merchant

This section describes how to create a compliant individual or business entity (Merchant) under the **VelaFi compliance framework**. You will initiate the **KYC/KYB verification process**, receive a redirect URL for user verification, and learn about the available merchant management modes.

### Overview

To operate within VelaFi’s regulated ecosystem, every merchant must complete **Know Your Customer (KYC)** or **Know Your Business (KYB)** verification.When creating a merchant via API, you must submit detailed business or personal information to initiate the compliance review\.Once the verification is successful, the platform will assign a **unique Merchant ID (MID)** to you or your client. This `MID` is required for all subsequent API calls related to transactions, account management, and settlements.

***

### KYC/KYB Verification Flow

When the API request for merchant creation is successful, the response will include a **unique redirect URL**. This URL leads to VelaFi’s secure KYC/KYB verification page.You can choose between two integration options:

* **Redirect Mode** — Directly redirect your user to the provided URL to complete the verification process.
* **Embedded Mode** — Embed the verification page into your front-end application using an `<iframe>` for a seamless user experience.

> ⚠️ **Important:** The verification URL may expire or become invalid after a specific period, depending on session and configuration settings. Ensure it is used promptly.

***

### Merchant Management Modes

VelaFi provides two operational models for merchant creation and management:

#### 1.Multi-Merchant Management

Once your **primary merchant account** has successfully passed KYB verification, you can create and manage **sub-merchants** (either individuals or entities) under your account. This enables **hierarchical merchant management**, along with flexible **role-based access control** and configuration.Typical use cases include:

* Aggregators managing multiple clients
* Platforms offering payment infrastructure to sub-merchants
* Marketplace operators handling merchant-level compliance separately

***

#### 2.Reliance Mode (Optional)

If you are a **licensed financial institution**, you can apply to enable **Reliance Mode**. This mode grants you greater autonomy over merchant operations and compliance.In Reliance Mode:

* You are responsible for merchant onboarding, review, and ongoing compliance monitoring.
* VelaFi does **not** intervene in your merchant onboarding workflow.
* VelaFi provides the **technical infrastructure**, **settlement rails**, and **regulatory support** to ensure transactions remain secure, efficient, and compliant.

> 🛡️ Reliance Mode requires an additional compliance review by the VelaFi Compliance Team.

[Click here ](https://velafi.notion.site/Reliance-Model-Onboarding-Guide-With-TruBit-2944850302de80619bb8daa72f3a8841)to learn more about the Reliance Mode application process.


# Creating API Key

* After logging in, navigate to the [API Management Page](https://www.velafi.com/user/interface).

<figure><img src="/files/0rySJjm6SpVnIgWbiyV8" alt=""><figcaption></figcaption></figure>

* Click the “**Creat**e **API Key**” button to generate your **API key**.&#x20;

<mark style="color:green;background-color:green;">**Note:**</mark> <mark style="color:green;background-color:green;"></mark><mark style="color:green;background-color:green;">If two-factor authentication (2FA) is not enabled on your account, the system will prompt you to enable it for enhanced security.</mark><br>

* Please enter Notes here, after verification is complete, click **"Continue"**

<figure><img src="/files/F2me8Q9stQ5uZ3Yj6tsV" alt=""><figcaption></figcaption></figure>


# Safely Store Your API Key

<figure><img src="/files/a6eNq0CsBADbUoOyLJ24" alt=""><figcaption></figcaption></figure>

Interface shows that the **API Key created**.&#x20;

## **⚠️Notes**

#### **Uniqueness:**

Each API key is unique and specifically designed for accessing VelaFi’s production environment.

#### **Storage Recommendations:**

<mark style="color:orange;background-color:orange;">Immediately store your API key in a secure location after generating it, as you will not be able to view it again once you leave the page.</mark>

<mark style="color:orange;background-color:orange;">Do not store your API key on public devices or in public locations, and avoid saving it in plaintext format.</mark>

<mark style="color:orange;background-color:orange;">Recommendation: Use encryption tools or a password manager to securely store your API key and prevent accidental exposure.</mark>


# Configure Whitelisted IPs

* Create a list of authorized IP addresses (IP whitelist) that are allowed to use your API keys.

<figure><img src="/files/NO0YdPvUb8zwV20STk1G" alt=""><figcaption></figcaption></figure>

## ⚠️**Important:** &#x20;

<mark style="color:orange;background-color:orange;">Whitelisting ensures that even if your API key is compromised, requests from unauthorized IPs will still be denied.</mark>


# Enable API Access

* Once your configuration is complete, contact the VelaFi team to finalize and activate your API access.<br>
* Submit your request via the [Contact Form](https://share.hsforms.com/1P1po-MZAThupnwug_qDEEAr8y9l).&#x20;


# Create API Token

This API allows you to generate a new API token for user authentication.

#### Endpoint Information

* **Request Method**: `GET`
* **Request Path**: `/v2/token/generate`
* **Authorization Required**: Yes

#### Request Headers

* `X-BH-APIKEY`: Your API key.

#### Query Parameters

* `timestamp`: The current time in milliseconds since the epoch.
* `signature`: The HMAC signature for the request.

#### Response Structure

The response will include the following fields:

```json
{
  "code": 200,                      // (number: response code)
  "msg": "SUCCESS",                 // (string: message)
  "data": {                         // (object: token details)
    "token": "09ef3523-6242-4a8d-80e2-24cfbdb35851", // (string: generated token)
    "expireTime": "1740568725231"  // (string: timestamp of the expiration time in milliseconds)
  }
}
```

#### Signature Generation Process

To generate the signature, follow these steps:

1. **Prepare the Message**: Create a string with the current timestamp: `"timestamp=1740568725231"`.
2. **Prepare the Key**: Use your `API_SECRET` as the key.
3. **Generate the Signature**: Use HMAC-SHA256 to create a hex string signature from the message and the key.

#### Example Code for Signature Generation

**Python**

```python
import time
import hmac
import hashlib

API_SECRET = "xxxx"
message = "timestamp=" + str(int(time.time() * 1000))
signature = hmac.new(API_SECRET.encode('utf-8'), message.encode('utf-8'), hashlib.sha256).hexdigest()

print("Signature:", signature)
```

**Java**

```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;

public class Signature {
    public static void main(String[] args) throws Exception {
        String API_SECRET = "xxxx";
        String message = "timestamp=" + System.currentTimeMillis();
        String signature = hmacSHA256(API_SECRET, message);

        System.out.println("Signature: " + signature);
    }

    public static String hmacSHA256(String secret, String message) throws Exception {
        Mac sha256HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256HMAC.init(secretKey);
        byte[] bytes = sha256HMAC.doFinal(message.getBytes(StandardCharsets.UTF_8));
        return bytesToHex(bytes);
    }

    private static String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
}
```

**JavaScript (Node.js)**

```javascript
const crypto = require('crypto');

const API_SECRET = 'xxxx';
const message = 'timestamp=' + Date.now();
const signature = crypto.createHmac('sha256', API_SECRET).update(message).digest('hex');

console.log('Signature:', signature);
```

**Go**

```go
package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "time"
)

func main() {
    API_SECRET := "xxxx"
    message := "timestamp=" + fmt.Sprint(time.Now().UnixNano()/1e6)
    signature := generateHMAC(API_SECRET, message)

    fmt.Println("Signature:", signature)
}

func generateHMAC(secret, message string) string {
    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(message))
    return hex.EncodeToString(h.Sum(nil))
}
```

**Rust**

```rust
use hmac::{Hmac, Mac};
use sha2::Sha256;
use std::time::{SystemTime, UNIX_EPOCH};

fn main() {
    let api_secret = "xxxx";
    let start = SystemTime::now();
    let since_the_epoch = start.duration_since(UNIX_EPOCH).expect("Time went backwards");
    let message = format!("timestamp={}", since_the_epoch.as_millis());
    let signature = generate_hmac(api_secret, &message);

    println!("Signature: {}", signature);
}

fn generate_hmac(secret: &str, message: &str) -> String {
    let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes()).expect("HMAC can take key of any size");
    mac.update(message.as_bytes());
    let result = mac.finalize();
    hex::encode(result.into_bytes())
}
```

#### Notes

* Ensure that you replace `"xxxx"` with your actual `API_SECRET`.
* The generated token will have an expiration time, which is provided in the response.


# Sandbox

VelaFi offers a **sandbox environment** designed to facilitate rapid integration testing without the necessity of using real funds. The sandbox can be accessed at:

* **Sandbox URL**: \
  [`https://api-test.velafi.com`](< https://api-test.velafi.com>)

For instance, to retrieve information about fiat trading pairs, you can utilize the following endpoint:

* **Fiat Trading Pairs Endpoint**: \
  [`https://api-test.velafi.com/v2/base/fiat/symbols`](<https://api-test.velafi.com/v2/base/fiat/symbols&#xA;>)

#### Sandbox API Credentials

To access the sandbox environment, use the following credentials:

* **API Key**:

  ```
  Please contact the VelaFi team to get it.
  ```
* **API Secret**:

  ```
  Please contact the VelaFi team to get it.
  ```

#### Key Differences Between Sandbox and Production Environments

We recommend utilizing the sandbox environment exclusively for testing API request/response behaviors, while reserving the production environment for all other types of testing activities.

**Distinctions:**

1. **No KYC Registration or API Key Creation Required**:\
   The sandbox environment eliminates the need for actual identity verification and API key generation.
2. **Virtual User and Account Data**:\
   All user and account information within the sandbox is simulated and not linked to real individuals.
3. **No Actual Fund Transfers**:\
   The sandbox environment does not facilitate real financial transactions; all processes are entirely simulated.
4. **Webhook Callbacks Are Not Triggered**:\
   In the sandbox environment, webhooks will not initiate any callback events.

#### Conclusion

We encourage you to leverage the sandbox environment thoroughly to validate your integration before deploying it in the production environment. This ensures that your application functions as intended and minimizes the risk of issues in a live setting.


# Activate Merchant Account

This endpoint is used to activate a merchant's fiat currency payment account. Supported currencies include MXN, ARS, BRL, COP, PEN, USD, and EUR. Once activated, merchants can send and receive funds through local banking channels with increased flexibility and efficiency.

* Each merchant will receive dedicated account details (e.g., ARS accounts include CVU number / CUIT for Argentina).
* Merchants can deposit funds via wire transfer; VelaFi will automatically reconcile the transaction and credit the merchant’s account balance.
* Both business and personal account types are supported, enabling broad use across various payment scenarios.

> [**Activate Merchant Account (For Individual)**](/api-reference/merchant/activate-merchant-account-for-individual)\
> \
> [**Activate Merchant Account (For Business)**](/api-reference/merchant/activate-merchant-account-for-business)


# Creating Payment Method

This guide provides detailed information about managing payment methods, including how to retrieve payment method templates and add new payment methods.&#x20;

## **I. Get Payment Method Templates**

#### Endpoint Information

* **Request Method**: `GET`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Path**: `/v2/payments/templates`
* **Authorization Required**: Yes

#### Request Parameters

**Query Parameters**

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| paymentId | number | Yes      | ID of the payment method |

#### Response Structure

The response will contain the following fields:

```json
{
  "code": 0,
  "msg": "",
  "data": {
      [string]: [string]
  }
}
```

#### Example Responses

**Payment Type 1: Bank Information**

**Mexico Bank**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "CLABE number": "",
        "Account number/card": "",
        "Beneficiary Name": ""
    }
}
```

**Argentina Bank**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "CVU number": "",
        "cuit": "",
        "Bank name": ""
    }
}
```

**Payment Type 2: SEPA  Transfers**

**SEPA**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Bank Name": "",
        "Account Owner Name": "",
        "Account Owner Type": "",
        "Bank Country/Region": "",
        "Account Number": "",
        "Bic": "",
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}

Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.
Bank Country/Region is ISO 3166-1

```

**WIRE / ACH Transfers**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Bank Name": "",
        "Account Owner Name": "",
        "Account Owner Type": "",
        "Bank Country/Region": "",
        "Account Number": "",
        "Routing Number": "",
        "Street Line1": "",
        "Street Line2": "",
        "City": "",
        "State": "",
        "Postal Code": "",
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}

Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.
Bank Country/Region is ISO 3166-1
State is ISO 3166-2
```

**Payment Type 3: SWIFT / CHATS**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "Account Owner Type": "",
        "IBAN": "",
        "Bank Name": "",
        "Bank Country/Region": "",
        "Bank Identifier": "",
        "Street": "",
        "City": "",
        "State": "",
        "Country/Region": "",
        "Postal Code": ""
        "firstName": "",
        "lastName": "",
        "businessName": ""
    }
}

Account Owner Type must be either Business or Individual.
If Account Owner Type is Business, businessName is required.
If Account Owner Type is Individual, firstName and lastName are required.

Bank Country/Region is ISO 3166-1

```

## **II. Add Payment Method**

#### Endpoint Information

* **Request Method**: `POST`
* **Request Path**: `/v2/payments`
* **Request Header**: `X-BH-TOKEN: ******`
* **Authorization Required**: Yes

#### Request Parameters

**Request Body**

The request body should include the following parameters:

| Parameter  | Type   | Required | Description                                                         |
| ---------- | ------ | -------- | ------------------------------------------------------------------- |
| merchantId | number | Yes      | ID of the merchant id                                               |
| paymentId  | number | Yes      | ID of the payment method                                            |
| country    | string | Yes      | Name of the country                                                 |
| fiat       | string | Yes      | Name of the fiat currency                                           |
| realName   | string | No       | Real name of the account holder                                     |
| fieldJson  | object | Yes      | Field JSON of the payment template, format `{ [string]: [string] }` |
| remark     | string | No       | Additional remarks for the payment method                           |

**Request Example**

```json
{
  "merchantId": 0,
  "paymentId": 0,
  "country": "",
  "fiat": "",
  "realName": "",
  "fieldJson": {
      "fieldName": "value"
  },
  "remark": ""
}
```

#### Response Structure

The response will contain the following fields:

```json
{
  "code": 0,
  "msg": "",
  "data": {
      "id": 0,  // User payment ID
      "status": 0, // Status: [1: valid, 2: authenticating, 3: authentication failed]
      "failReason": "" // Reason for authentication failure
  }
}
```

### Notes

* Ensure to provide valid parameters for successful creation of payment methods.
* The `merchantId` and `paymentId` must correspond to existing configurations in the system.
* Pay attention to the status and failure reason in the response for troubleshooting.


# Payment Method ID

PaymentID

This section provides information about the various payment methods supported by the API, including a comprehensive mapping of payment method IDs to their respective names. The following table outlines the payment method IDs along with their corresponding payment method names. This reference is essential for developers and users to identify and utilize the appropriate payment methods in their transactions.

<table><thead><tr><th width="123.5184326171875">Payment ID</th><th width="281.8519287109375">Name</th><th width="119.5924072265625">Type</th><th>Trench</th></tr></thead><tbody><tr><td>105</td><td>SPEI (Finco Pay)</td><td>Automatic</td><td>CLABE - FINCO PAY</td></tr><tr><td>72</td><td>SPEI (Tesored)</td><td>Automatic</td><td>CLABE - TESORED</td></tr><tr><td>63</td><td>CBU/CVU (Momentum)</td><td>Automatic</td><td>CVU - Momentum</td></tr><tr><td>137</td><td>3.0 Transfer (QR)</td><td>Automatic</td><td>QR Argentina</td></tr><tr><td>81</td><td>ACH (Reference - Lead Bank)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>82</td><td>ACH (Virtual - Lead Bank)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>83</td><td>Wire (Reference - Lead Bank)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>84</td><td>Wire (Virtual - Lead Bank)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>85</td><td>SEPA (Bridge)</td><td>Automatic</td><td>Lead Bank</td></tr><tr><td>90</td><td>Pix (Genial)</td><td>Automatic</td><td>BANCO GENIAL</td></tr><tr><td>95</td><td>Bank Transfer</td><td>Automatic</td><td>PEN Account</td></tr><tr><td>111</td><td>Wire (Virtual - CRB)</td><td>Automatic</td><td>Cross River Bank</td></tr><tr><td>113</td><td>ACH (Virtual - CRB)</td><td>Automatic</td><td>Cross River Bank</td></tr><tr><td>115</td><td>SWIFT Account_Cross River Bank</td><td>Automatic</td><td>Cross River Bank</td></tr><tr><td>120</td><td>Wire (CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>121</td><td>CIPS (CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>122</td><td>FPS (CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>123</td><td>CHATS (CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>124</td><td>SEPA(CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>125</td><td>BANK-TRANSFER(CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>126</td><td>PESONET(CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>127</td><td>FEDWIRE(CPN)</td><td>Automatic</td><td>Circle Payment Network</td></tr><tr><td>68</td><td>PSE/ACH</td><td>Automatic</td><td>COP Account</td></tr><tr><td>69</td><td>Bre-B</td><td>Automatic</td><td>COP Account</td></tr><tr><td>70</td><td>VelaFi Pending Fund</td><td>Automatic</td><td></td></tr><tr><td>19</td><td>Pix</td><td>Manual</td><td></td></tr><tr><td>27</td><td>Bank Transfer (Brazil)</td><td>Manual</td><td></td></tr><tr><td>28</td><td>Bank Transfer (Argentina)</td><td>Manual</td><td></td></tr><tr><td>29</td><td>Manual Bank Transfer (Mexico)</td><td>Manual</td><td></td></tr><tr><td>48</td><td>Bank Transfer (Colombia)</td><td>Manual</td><td></td></tr><tr><td>56</td><td>Manual ACH/WIRE</td><td>Manual</td><td></td></tr><tr><td>59</td><td>Manual ACH - Perú</td><td>Manual</td><td></td></tr><tr><td>60</td><td>Bank Transfer (Chile)</td><td>Manual</td><td></td></tr><tr><td>61</td><td>Manual USD Payments (CHATS)</td><td>Manual</td><td></td></tr><tr><td>62</td><td>Bridge</td><td>Manual</td><td></td></tr><tr><td>87</td><td>SWIFT (US)</td><td>Manual</td><td></td></tr><tr><td>89</td><td>SEPA</td><td>Manual</td><td></td></tr><tr><td>102</td><td>SWIFT (SGP）</td><td>Manual</td><td></td></tr><tr><td>500</td><td>Bank Tansfer (Bolivia Manual)</td><td>Manual</td><td></td></tr><tr><td>501</td><td>WIRE (HK TRADE PAYIN)</td><td>Manual</td><td></td></tr><tr><td>503</td><td>Manual CNY Payout</td><td>Manual</td><td></td></tr><tr><td>504</td><td>Manual Global USD Payout</td><td>Manual</td><td></td></tr></tbody></table>

## Payment Method FAQ

| Payment method  | Region        | Currency | Direction                 | Account beneficiary         | Settlement time | Payin Conciliation Method              | Bank              | Features                    | Limits                                  | Tax                 | Status |
| --------------- | ------------- | -------- | ------------------------- | --------------------------- | --------------- | -------------------------------------- | ----------------- | --------------------------- | --------------------------------------- | ------------------- | ------ |
| ACH             | 🇺🇸US        | USD      | <p>Payin</p><p>Payout</p> | Partner                     | T+0 or +1       | Static Memo,Dynamic Memo               | Lead bank         |                             |                                         |                     | Live   |
| ACH             | 🇺🇸US        | USD      | Payin                     | User                        | T+0 or +1       | Virtual account/vIBAN                  | Lead bank         |                             |                                         |                     | Live   |
| Wire            | 🇺🇸US        | USD      | <p>Payin</p><p>Payout</p> | Partner                     | T+0             | Static Memo,Dynamic Memo               | Lead bank         |                             |                                         |                     | Live   |
| Wire            | 🇺🇸US        | USD      | Payin                     | User                        | T+0             | Virtual account/vIBAN                  | Lead bank         |                             |                                         |                     | Live   |
| CHATS           | 🇭🇰HK        | USD      | Payout                    | Partner                     | T+0             | N.A.                                   | DBS               | Ultimate remitter,Reference |                                         |                     | Live   |
| FPS             | 🇭🇰HK        | HKD      | Payout                    | Partner                     | T+0             | N.A.                                   | DBS               | Reference                   |                                         |                     | Live   |
| SWIFT           | 🇭🇰HK        | USD      | Payout                    | Partner                     | T+0 or +1       | N.A.                                   | DBS               | Ultimate remitter           |                                         |                     | Live   |
| SPEI            | 🇲🇽Mexico    | MXN      | <p>Payin</p><p>Payout</p> | User                        | Instant 24x7    | Virtual account/vIBAN                  | Arcus             | Reference                   |                                         |                     | Live   |
| CVU             | 🇦🇷Argentina | ARS      | <p>Payin</p><p>Payout</p> | User                        | Instant 24x7    | Virtual account/vIBAN                  | Momemtum Pagos    | Reference                   |                                         | IDC 60bps each side | Live   |
| PSE             | 🇨🇴Colombia  | COP      | Payin                     | Partner                     | Instant 24x7    | Dynamic Memo                           | N.A.              | Reference                   |                                         | GMF 40bps           | P1     |
| ACH             | 🇨🇴Colombia  | COP      | Payout                    | Velafi                      | T+0 or +1       | N.A.                                   | Banco Coopcentral | Reference                   |                                         | GMF Waived          | P1     |
| FastPay         | 🇨🇴Colombia  | COP      | Payout                    | <p>Partner</p><p>Velafi</p> | Instant 24x7    | N.A.                                   | Banco Coopcentral | Reference                   | 1 - 50,000,000 COP                      | GMF Waived          | P1     |
| Pix             | 🇧🇷Brazil    | BRL      | <p>Payin</p><p>Payout</p> | Velafi                      | Instant 24x7    | Static Memo,Dynamic Memo,Sender's info | Genial            | Reference                   |                                         |                     | P1     |
| Service Payment | 🇵🇪Peru      | PEN      | Payin                     | Partner                     | Instant 24x7    | Dynamic Memo                           | N.A.              | Reference                   | 1 - 50,000 PEN                          |                     | P1     |
| ACH             | 🇵🇪Peru      | PEN      | Payout                    | Partner                     | T+0 or +1       | N.A.                                   | N.A.              | Reference                   | SoF required for more than 10,000 soles |                     | P1     |


# Currencies

This section provides information about the various currencies supported by the API, including both cryptocurrencies and fiat currencies.&#x20;

### **Crypto Currencies**

| Currency Name             | Currency Code | Decimals | Protocol                        |
| ------------------------- | ------------- | -------- | ------------------------------- |
| Bitcoin                   | BTC           | 8        | BTC                             |
| Moneta Digital            | MMXN          | 2        | ERC20, TRC20                    |
| USD Coin                  | USDC          | 2        | ERC20, POL, SPL20               |
| Tether USD                | USDT          | 2        | BEP20, ERC20, POL, SPL20, TRC20 |
| BRL1                      | BRL1          | 4        | POL                             |
| CAD Coin                  | CADC          | 5        | Base                            |
| MXNB                      | MXNB          | 5        | Arbitrum                        |
| Colombian Peso Stablecoin | COPM          | 4        | POL                             |

### **Fiat Currencies**

| Country            | Currency | Decimals |
| ------------------ | -------- | -------- |
| 🇦🇷 Argentina     | ARS      | 2        |
| 🇧🇷 Brazil        | BRL      | 2        |
| 🇨🇴 Colombia      | COP      | 2        |
| *🇭🇰* Hong Kong   | USD      | 2        |
| 🇲🇽 Mexico        | MXN      | 2        |
| 🇵🇪 Peru          | PEN      | 4        |
| 🇵🇪 Peru          | USD      | 2        |
| 🇺🇸 United States | EUR      | 2        |
| 🇺🇸 United States | USD      | 2        |


# Pair

This section provides information about the various trading pairs supported by the API, including on/off ramp and global payment pairs.

### **On/Off Ramp Pair**

<table><thead><tr><th width="174">Country</th><th width="97">Fiat</th><th>Crypto</th><th width="103">Decimals</th><th>On-Ramp</th><th>Off-Ramp</th></tr></thead><tbody><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>BTC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇧🇷 Brazil</td><td>BRL</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇧🇷 Brazil</td><td>BRL</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇨🇴 Colombia</td><td>COP</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇨🇴 Colombia</td><td>COP</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇭🇰 Hong Kong</td><td>USD</td><td>MMXN</td><td>4</td><td>No</td><td>Yes</td></tr><tr><td>🇭🇰 Hong Kong</td><td>USD</td><td>USDC</td><td>4</td><td>No</td><td>Yes</td></tr><tr><td>🇭🇰 Hong Kong</td><td>USD</td><td>USDT</td><td>4</td><td>No</td><td>Yes</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>BTC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>MMXN</td><td>2</td><td>Yes</td><td>Yes</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇵🇪 Peru</td><td>PEN</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇵🇪 Peru</td><td>USD</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇺🇸 United States</td><td>EUR</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇺🇸 United States</td><td>EUR</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇺🇸 United States</td><td>USD</td><td>USDC</td><td>4</td><td>Yes</td><td>Yes</td></tr><tr><td>🇺🇸 United States</td><td>USD</td><td>USDT</td><td>4</td><td>Yes</td><td>Yes</td></tr></tbody></table>

### **Global Payment Pair**

<table><thead><tr><th width="167">Country From</th><th width="109">Fiat</th><th>Country To</th><th>Fiat</th><th>Decimals</th></tr></thead><tbody><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>🇲🇽 Mexico</td><td>MXN</td><td>4</td></tr><tr><td>🇦🇷 Argentina</td><td>ARS</td><td>🇺🇸 United States</td><td>USD</td><td>8</td></tr><tr><td>🇧🇷 Brazil</td><td>BRL</td><td>🇦🇷 Argentina</td><td>ARS</td><td>4</td></tr><tr><td>🇧🇷 Brazil</td><td>BRL</td><td>🇭🇰 Hong Kong</td><td>USD</td><td>4</td></tr><tr><td>🇨🇴 Colombia</td><td>COP</td><td>🇲🇽 Mexico</td><td>MXN</td><td>2</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>🇦🇷 Argentina</td><td>ARS</td><td>4</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>🇨🇴 Colombia</td><td>COP</td><td>2</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>🇭🇰 Hong Kong</td><td>USD</td><td>4</td></tr><tr><td>🇲🇽 Mexico</td><td>MXN</td><td>🇺🇸 United States</td><td>USD</td><td>4</td></tr><tr><td>🇺🇸 United States</td><td>USD</td><td>🇦🇷 Argentina</td><td>ARS</td><td>4</td></tr><tr><td>🇺🇸 United States</td><td>USD</td><td>🇲🇽 Mexico</td><td>MXN</td><td>2</td></tr></tbody></table>


# Limits

To meet compliance requirements, **VelaFi** applies different transaction and withdrawal limits based on the user’s region and verification level. This ensures that all users operate within the regulatory framework of their respective jurisdictions.

### 1. Default Merchant Wallet Limit

After successfully creating a **Merchant**, VelaFi automatically provisions a **crypto custody wallet** for that merchant.

* The wallet is activated upon creation.
* The default **monthly withdrawal limit** is **USD 10,000,000,000**.

### 2. Individual Users

VelaFi classifies individual users into two categories — **Consumers** and **Professionals**, each with different verification requirements and transaction limits.

#### Consumers

* Requires minimal documentation for verification.
* Quick review process, with lower transaction limits.
* Suitable for low-frequency or small-value payment use cases.

| Country       | Monthly Trade Limit (USD) |
| ------------- | ------------------------- |
| 🇲🇽Mexico    | 10,000,000,000            |
| 🇧🇷Brazil    | 10,000,000,000            |
| 🇨🇴Colombia  | 10,000,000,000            |
| 🇵🇪Peru      | 10,000,000,000            |
| 🇦🇷Argentina | 10,000,000,000            |

#### Professionals

* Requires more comprehensive identity and business documentation.
* Subject to enhanced compliance review.
* Suitable for high-volume merchants or users requiring higher operational limits.

(Limits vary by jurisdiction and are subject to approval by the VelaFi compliance team.)

### 3. Business Users (After Channel Activation)

For business merchants, limits are applied per country once the corresponding fiat payment channels are activated.

| Country           | Monthly Limit (USD) |
| ----------------- | ------------------- |
| 🇲🇽Mexico        | 10,000,000,000      |
| 🇨🇴Colombia      | 10,000,000,000      |
| 🇦🇷Argentina     | 10,000,000,000      |
| 🇧🇷Brazil        | 10,000,000,000      |
| 🇵🇪Peru          | 10,000,000,000      |
| 🇺🇸United States | 10,000,000,000      |
| 🇭🇰Hong Kong     | 10,000,000,000      |

***

### 4. Increasing Your Limit

If your business or operational needs exceed the default limit, you can request a **limit increase** by submitting additional compliance documentation (e.g., proof of source of funds, business licenses, or audited statements).\
\
[Upgrade Merchant Limit](https://app.gitbook.com/o/eeU0trgBle4zqs7IuQir/s/kcqCFfOVAdQbR1YyMZUY/~/changes/5/api-reference/merchant/upgrade-merchant-limit)\
\
or\
\
Contact Us to learn more about the limit upgrade process.

> **Email:** <contact@velafi.com>


# Creating Webhook Listener

This interface is used to create a callback URL to receive notifications for specific events. Supported event types include order events and merchant trade events.&#x20;

### Interface Information

* **Request Header**: `Content-Type: application/json`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `POST`
* **Request Path**: `/openapi/v2/business/webhook`
* **Authorization Required**: Yes

### Request Parameters

| Parameter Name | Type   | Required | Description                                                                                                   |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| eventType      | string | Yes      | Event type, supported values: `ORDER_WEBHOOK` (order event), `MERCHANT_TRADE_WEBHOOK` (merchant trade event). |
| url            | string | Yes      | Callback URL for receiving event notifications.                                                               |

#### Request Example

```json
{
    "eventType": "ORDER_WEBHOOK",
    "url": "https://localhost/callback"
}
```

### Response Parameters

| Parameter Name | Type   | Description                                                                                      |
| -------------- | ------ | ------------------------------------------------------------------------------------------------ |
| code           | number | Response status code, `200` indicates success.                                                   |
| msg            | string | Response message, typically `SUCCESS`.                                                           |
| data           | object | Returned data object, containing the following fields:                                           |
| data.webhookId | string | Unique identifier for the callback URL.                                                          |
| data.eventType | string | Event type, confirming the event type specified in the request.                                  |
| data.url       | string | Merchant transfer callback URL.                                                                  |
| data.status    | number | Callback configuration status, supported values: `10` (active), `20` (disabled), `30` (deleted). |
| data.publicKey | string | (Optional) Public key of RSA-SHA256, used to verify push messages.                               |

#### Response Example

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
        "eventType": "ORDER_WEBHOOK",
        "url": "https://localhost/callback",
        "status": 1,
        "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGzXcqXbx6uA9PHQ3wGFgeBVEq0YpJxOSWpy4UmgBZ+fTOANiFyrODECWJoWIeJPOWkKR5VUseJTg57js3rgu/2Wn6Ihq1h+n6wCJEMCjK0Ia5brbQXtPcXCHK0J53hrt4YbxTzZuKUi7KIWO/Ply6xzYaTJeKzkaWlNDXF2VWBlutG+Pun3yXdWl7kTRENYA4mxXayaW0ELpnnLXF9qO01bAHPc2G8n0snqDiPMtz8Irw5MqlQ3YMjDiEDFLSb2aP9grae/o/LXZVNv0dJhV5IHgTJctDyFGz837BRiJZsBsodJK+3BTJhLsHqh6VAO8CSdQIDAQAB"
    }
}
```

### Notes

* Ensure that the provided callback URL is valid and capable of handling POST requests.
* The event type must be one of the supported types.
* The public key is an optional field, used only when verification of push messages is required.


# Fiat to Crypto (On-Ramp)

This section provides information about the fiat to crypto on-ramp process, allowing users to convert fiat currency into cryptocurrency through the API.

## **Create Order**

* **Request Header**: `Content-Type: application/json`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/fiat_to_crypto`
* **Authorization Required**: Yes

**Request Parameters**

The request body should include the following parameters:

| Parameter                              | Type    | Required | Description                                                                      |
| -------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| country                                | string  | Yes      | Name of the country (e.g., "Mexico")                                             |
| clientId                               | string  | No       | An order ID that you may define and will be returned to you in a Get Order call. |
| merchantId                             | number  | No       | ID of the merchant                                                               |
| crypto                                 | string  | Yes      | Name of the cryptocurrency (e.g., "USDT")                                        |
| fiat                                   | string  | Yes      | Name of the fiat currency (e.g., "MXN")                                          |
| fiatAmount                             | decimal | Yes      | Amount of fiat currency to convert (e.g., 1000.00)                               |
| [paymentId](/guides/payment-method-id) | number  | Yes      | ID of the payment method                                                         |
| remark                                 | string  | No       | Additional remarks for the order                                                 |

**Request Example**

```json
{
    "country": "Mexico",
    "clientId": "xxxx",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "fiatAmount": 1000.00,
    "paymentId": 91,
    "remark": ""
}
```

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure that valid parameters are provided for successful order creation.
* The `merchantId` and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order, along with the order ID for tracking.


# Crypto to Fiat (Off-Ramp)

This section provides information about the crypto to fiat off-ramp process, allowing users to convert cryptocurrency into fiat currency through the API.&#x20;

## **Create Order**

* **Request Header**: `Content-Type: application/json`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/crypto_to_fiat`
* **Authorization Required**: Yes

**Request Parameters**

The request body should include the following parameters:

| Parameter                                                         | Type    | Required | Description                                                                      |
| ----------------------------------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| country                                                           | string  | Yes      | Name of the country (e.g., "Mexico")                                             |
| clientId                                                          | string  | No       | An order ID that you may define and will be returned to you in a Get Order call. |
| merchantId                                                        | number  | No       | ID of the merchant                                                               |
| crypto                                                            | string  | Yes      | Name of the cryptocurrency (e.g., "USDT")                                        |
| fiat                                                              | string  | Yes      | Name of the fiat currency (e.g., "MXN")                                          |
| cryptoAmount                                                      | decimal | Yes      | Amount of fiat currency to convert (e.g., 1000.00)                               |
| [userPaymentId](/api-reference/payment-method/get-payment-method) | number  | Yes      | ID of the user payment method                                                    |
| remark                                                            | string  | No       | Additional remarks for the order                                                 |

**Request Example**

```json
{
    "country": "Mexico",
    "clientId": "xxxx",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "cryptoAmount": 1000.00,
    "paymentId": 91,
    "remark": ""
}
```

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure that valid parameters are provided for successful order creation.
* The `merchantId` and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order, along with the order ID for tracking.


# Fiat to Fiat (Global Payment)

This section provides information about the fiat to fiat process, allowing users to convert fiat currency into cryptocurrency through the API.

## **Create Order**

* **Request Header**: `Content-Type: application/json`
* **Request Header**: `X-BH-TOKEN: ******`
* **Request Method**: `POST`
* **Request Path:** `/v2/order/fiat_to_fiat`
* **Authorization Required**: Yes

**Request Parameters**

The request body should include the following parameters:

<table><thead><tr><th width="266">Parameter</th><th width="96">Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>clientId</td><td>string</td><td>No</td><td>Unique identifier for the client</td></tr><tr><td>onRampCountry</td><td>string</td><td>Yes</td><td>Name of the country (e.g., "Mexico")</td></tr><tr><td>onRampMerchantId</td><td>number</td><td>No</td><td>ID of the merchant</td></tr><tr><td>onRampFiat</td><td>string</td><td>Yes</td><td>Name of the fiat currency (e.g., "MXN")</td></tr><tr><td>onRampFiatAmount</td><td>decimal</td><td>Yes</td><td>Amount of fiat currency to convert (e.g., 1000.00)</td></tr><tr><td><a href="/pages/d6qFnm3pFqD22eQqFfoL">onRampPaymentId</a></td><td>number</td><td>Yes</td><td>ID of the payment method</td></tr><tr><td>offRampCountry</td><td>string</td><td>Yes</td><td>Name of the country (e.g., "Mexico")</td></tr><tr><td>offRampMerchantId</td><td>number</td><td>No</td><td>ID of the merchant</td></tr><tr><td>offRampFiat</td><td>decimal</td><td>Yes</td><td>Name of the fiat currency (e.g., "MXN")</td></tr><tr><td><a href="/pages/9Z3iWUBxVVRT9dUiaTQM">offRampPaymentId</a></td><td>number</td><td>Yes</td><td>ID of the payment method</td></tr><tr><td>remark</td><td>string</td><td>No</td><td>Additional remarks for the order</td></tr></tbody></table>

**Request Example**

```json

{
    "clientId": "xxxx",
    "onRampCountry": "Mexico",
    "onRampMerchantId": 12345,
    "onRampFiat": "MXN",
    "onRampFiatAmount": 1000.00,
    "onRampPaymentId": 91,
    "offRampCountry": "HONGKONG",
    "offRampMerchantId": 54321,
    "offRampFiat": "USD",
    "offRampPaymentId": 77,
    "remark": ""
}
```

**Response Parameters**

The response will contain the following parameters:

| Parameter    | Type   | Description                        |
| ------------ | ------ | ---------------------------------- |
| code         | number | Response status code (e.g., 200)   |
| msg          | string | Response message (e.g., "SUCCESS") |
| data         | object | Contains order details             |
| data.orderId | number | ID of the created order            |

**Response Example**

```json
{
    "code": 200,
    "msg": "SUCCESS",
    "data": {
        "orderId": 1123123123
    }
}
```

### Notes

* Ensure to provide valid parameters for successful order creation.
* The `merchantId`  and `paymentId` must correspond to existing merchant and payment method configurations.
* The response will confirm the successful creation of the order along with the order ID for tracking.


# Stablecoin Payments


# Get Wallet List

This API is used to retrieve a list of available stablecoin wallets under a specific merchant account.\
Merchants can use this interface to obtain wallet information before creating payment links or performing fund management operations.

Typical use cases include:

* Selecting a wallet prior to initiating a payment flow
* Wallet configuration and validation
* Managing multiple wallets under a merchant account

#### Endpoint Information

* **Request Header:** `X-BH-TOKEN: ******`
* **Request Header: `Content-Type:`**` ``application/json`
* **Request Method:** `GET`
* **Request Path:** `/v2/payments/wallets`
* **Authorization Required:** Yes

### Request Parameters

The request query should include the following parameters:

* merchantId: The merchant ID.

### Request Example

```
GET /openapi/v2/payments/wallets?merchantId=3
```

### Response Parameters

The response will contain the following parameters:

* wallets: List of wallets under the merchant account.
* walletId: Wallet identifier.
* walletName: Wallet name.

### Response Example

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "wallets": [
      {
        "walletId": 1,
        "walletName": "Primary Wallet"
      }
    ]
  }
}
```

### Notes

* The `merchantId` must correspond to a valid merchant account.
* If multiple wallets are configured for the merchant, all available wallets will be returned in the `wallets` list.
* The returned `walletId` can be used when creating payment links or performing wallet-related operations.


# Create a Sub-Wallet

This API is used to create a new stablecoin wallet for a specific merchant.\
Once successfully created, the wallet can receive on-chain stablecoin transfers and can be associated with payment links or payment orders.

The platform distinguishes between a **Primary Wallet** and a **Sub Wallet**, which differ in functionality and intended usage.

#### Wallet Types

**Primary Wallet**

* Provides full fund management capabilities, including:
  * Stablecoin on-chain deposits
  * Stablecoin withdrawals
* Typically used for the merchant’s main settlement and fund management purposes

**Sub Wallet**

* Intended for internal accounting and bookkeeping purposes only
* Does not support independent on-chain deposits or withdrawals
* Commonly used for:
  * Business line segregation
  * Financial accounting
  * Payment data tracking and reconciliation

#### Usage Notes

* Each merchant has at least one **Primary Wallet** by default
* Creating sub wallets does not affect the ownership of the merchant’s actual on-chain assets
* Payment links may be associated with sub wallets for accounting categorization purposes, while all on-chain funds are credited to the merchant’s **Primary Wallet**

***

## Create Sub-Wallet

* **Request Header:** `X-BH-TOKEN: ******`
* **Request Header:** `Content-Type: application/json`
* **Request Method:** `POST`
* **Request Path:** `/v2/payments/wallet`
* **Authorization Required:** Yes

***

### Request Parameters

The request body should include the following parameters:

* merchantId: Merchant ID.
* walletName: Name of the sub wallet to be created.

***

### Request Example

```json
{
  "merchantId": 1,
  "walletName": "subwallet"
}
```

***

### Response Parameters

The response will contain the following parameters:

* walletId: The identifier of the created wallet.
* walletName: The name of the created wallet.

***

### Response Example

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "walletId": 1,
    "walletName": "New Wallet"
  }
}
```

***

### Notes

* Each merchant must have at least one **Primary Wallet** before creating sub wallets.
* Sub wallets are used for internal accounting purposes and cannot independently receive or withdraw on-chain funds.
* The returned `walletId` can be used for payment link creation, payment order association, and financial categorization.


# Create a Payment Link

This API is used to create a stablecoin payment link that can be shared with users to facilitate on-chain stablecoin payments.\
A payment link includes key information such as the payment amount, currency, wallet, and expiration time. Users can initiate payments through the link within its validity period.

* Once the user completes the on-chain transfer, a corresponding payment order is automatically generated
* Payment links are strictly bound to the merchant and wallet
* Expired payment links are no longer usable

📌 For the currently supported blockchain networks and cryptocurrencies, please refer to the following list.

<table data-header-hidden><thead><tr><th valign="top"></th><th valign="top"></th><th valign="top"></th></tr></thead><tbody><tr><td valign="top">Currency</td><td valign="top">Coin ID</td><td valign="top">Network / Standard</td></tr><tr><td valign="top">USDT</td><td valign="top">2</td><td valign="top">Binance Smart Chain (BEP20)</td></tr><tr><td valign="top">USDT</td><td valign="top">2</td><td valign="top">Ethereum (ERC20)</td></tr><tr><td valign="top">USDT</td><td valign="top">2</td><td valign="top">Polygon (POS)</td></tr><tr><td valign="top">USDT</td><td valign="top">2</td><td valign="top">Solana (Mainnet)</td></tr><tr><td valign="top">USDT</td><td valign="top">2</td><td valign="top">TRON (TRC20)</td></tr><tr><td valign="top">USDC</td><td valign="top">3</td><td valign="top">Ethereum (ERC20)</td></tr><tr><td valign="top">USDC</td><td valign="top">3</td><td valign="top">Polygon (POS)</td></tr><tr><td valign="top">USDC</td><td valign="top">3</td><td valign="top">Solana (Mainnet)</td></tr></tbody></table>

***

* **Request Header: X-BH-TOKEN: `******`**
* **Request Header: Content-Type: `application/json`**
* **Request Method: `POST`**
* **Request Path: `/v2/payments/link`**
* **Authorization Required:** Yes

***

### Request Parameters

The request body should include the following parameters:

* userId: User identifier.
* merchantId: Merchant ID (required).
* amount: Payment amount (required).
* currency: Payment currency (required).
* walletId: Wallet ID (required).
* reference: Reference number for order tracking (required).
* expireSeconds: Expiration time in seconds (default: 1).

***

### Request Example

```json
{
  "userId": 1,
  "merchantId": 1,
  "amount": 100.00,
  "currency": "USDT",
  "walletId": 1,
  "reference": "INV-123456",
  "expireSeconds": 123
}
```

***

### Response Parameters

The response will contain the following parameters:

* linkId: Payment link identifier.
* paymentLink: Generated payment URL.

***

### Response Example

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "linkId": 1,
    "paymentLink": "https://example.com/pay/123456"
  }
}
```

***

### Notes

* The `walletId` must belong to the specified merchant.
* The generated `paymentLink` can be shared with users to initiate on-chain stablecoin payments.
* Once the payment is completed on-chain, a corresponding payment order will be automatically generated by the system.
* Expired payment links cannot be used to initiate new payments.


# Retrieve Payment Links

This API is used to retrieve a list of stablecoin payment links created by a merchant, with support for filtering by various conditions.\
The query results are returned in a paginated format, allowing merchants to efficiently manage and analyze payment links.

Typical use cases include:

* Reviewing historical payment links
* Checking payment link status
* Analyzing payment link usage

***

* **Request Header:** X-BH-TOKEN: `******`
* **Request Header:** Content-Type: `application/json`
* **Request Method:** `POST`
* **Request Path:** `/v2/payments/page/links`
* **Authorization:** `Required`

***

### Request Parameters

The request body should include the following parameters:

* currentPage: Current page number (default: 1).
* pageSize: Number of results per page (default: 10, maximum: 1000).
* merchantId: Merchant ID.
* reference: Reference number used for filtering.
* currency: Payment currency.
* status: Link status filter. Possible values: `0` (Active), `1` (Expired).
* startTime: Start time timestamp (Unix milliseconds).
* endTime: End time timestamp (Unix milliseconds).

***

### Request Example

```json
{
  "currentPage": 1,
  "pageSize": 10,
  "merchantId": 1,
  "reference": "INV-123456",
  "currency": "USDT",
  "status": 0,
  "startTime": 1737452292000,
  "endTime": 1737538692000
}
```

***

### Response Parameters

The response will contain the following parameters:

* record: List of payment links.
* linkId: Payment link identifier.
* reference: Reference number.
* paymentLink: Payment URL.
* walletId: Wallet identifier.
* walletName: Wallet name.
* currency: Currency type.
* depositAmount: Deposit amount configured for the link.
* feeAmount: Transaction fee.
* totalDepositAmount: Total deposited amount through this link.
* totalConfirmedOrders: Total number of confirmed orders associated with this link.
* status: Link status (`ACTIVE` or `EXPIRED`).
* createTime: Creation timestamp.
* size: Page size.
* currentPage: Current page number.
* total: Total number of records.

***

### Response Example

```json
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "record": [
      {
        "linkId": 1,
        "reference": "INV-123456",
        "paymentLink": "https://example.com/pay/123456",
        "walletId": 1,
        "walletName": "Primary Wallet",
        "currency": "USDT",
        "depositAmount": 100.00,
        "feeAmount": 0.50,
        "totalDepositAmount": 1000.00,
        "totalConfirmedOrders": 10,
        "status": "ACTIVE",
        "createTime": 1737452292000
      }
    ],
    "size": 10,
    "currentPage": 1,
    "total": 100
  }
}
```

***

### Notes

* This API supports **paginated queries** to efficiently retrieve large numbers of payment links.
* The `reference`, `currency`, and `status` parameters can be used to filter specific payment links.
* Time filters (`startTime`, `endTime`) use **Unix timestamp in milliseconds**.
* The `totalDepositAmount` and `totalConfirmedOrders` fields provide aggregated statistics for each payment link.




---

[Next Page](/llms-full.txt/1)