跳转到主要内容

​
什么是账户？

账户代表 ramp 交易中资金的来源或目的地。用户可以拥有多个不同类型的账户，以支持各种支付方式和用例。
每个账户都链接到特定用户，在交易中使用前必须经过验证。

​
账户类型

银行账户

PSE, SPEI, ACH, Wire用于接收本地货币的传统法币银行账户。用于：Off-ramps（加密货币 → 法币）

加密货币钱包

多个网络上的 USDC/USDT用于接收加密货币的区块链钱包地址。用于：On-ramps（法币 → 加密货币）

​
快速开始

1

创建用户

在添加账户之前，用户必须存在
POST /api/v2/users
2

选择账户类型

Off-ramps 使用银行账户，on-ramps 使用钱包
3

创建账户

提交账户详情
POST /api/v2/accounts
4

等待验证

验证后，账户状态变为 ACTIVE
5

在 Ramps 中使用

创建 ramps 时引用账户 ID

​
创建账户

​
银行账户示例

{
  "type": "PSE",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "bank-account-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
钱包账户示例

{
  "type": "WALLET",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "wallet-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
查询账户

​
获取所有用户账户

GET /api/v2/accounts/userId/{userId}

const getUserAccounts = async (userId) => {
  const response = await fetch(
    `https://teste-94u93qnn.uc.gateway.dev/api/v2/accounts/userId/${userId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return await response.json();
};

​
搜索账户

GET /api/v2/accounts?userId=user-id&type=WALLET
过滤器：
  • ids - 特定账户 ID（逗号分隔）
  • userId - 按用户过滤
  • type - 账户类型
  • accountNumber - 银行账户号码
  • address - 钱包地址
  • limit, page - 分页

​
按 ID 获取账户

GET /api/v2/accounts/{accountId}

​
更新账户

创建后只能更新有限字段： 
PATCH /api/v2/accounts/{accountId}

{
  "type": "PSE",
  "data": {
    "accountNumber": "9876543210",
    "bankCode": "0002",
    "type": "checking"
  }
}
更新某些字段可能需要重新验证，并将账户状态设置回 PENDING。

​
删除账户

DELETE /api/v2/accounts/{accountId}

const deleteAccount = async (accountId) => {
  const response = await fetch(
    `https://teste-94u93qnn.uc.gateway.dev/api/v2/accounts/${accountId}`,
    {
      method: 'DELETE',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  if (response.ok) {
    console.log('Account deleted');
  }
};
在待处理或处理中的 ramps 中使用的账户无法删除。

​
账户验证

账户经过验证流程： 状态：
  • ACTIVE - 可用于交易
  • PENDING - 验证中
  • REJECTED - 验证失败
  • INACTIVE - 已禁用

​
多个账户

用户可以拥有多个账户： 
const userAccounts = await getUserAccounts(userId);

// 按类型分组
const groupedAccounts = {
  banks: userAccounts.filter(a => ['PSE', 'SPEI', 'ACH'].includes(a.type)),
  wallets: userAccounts.filter(a => a.type === 'WALLET')
};

// 查找默认账户
const defaultWallet = userAccounts.find(a => 
  a.type === 'WALLET' && 
  a.data.network === 'POLYGON' &&
  a.data.currency === 'USDC'
);

​
最佳实践

// 验证银行代码是否存在
const banks = await getBanks('CO');
const validBank = banks.find(b => b.code === bankCode);

// 验证钱包地址格式
const isValidAddress = /^0x[a-fA-F0-9]{40}$/.test(address);

// 检查重复
const existing = await findAccount({ userId, address });

{
  "externalId": `${yourUserId}-wallet-polygon-usdc`,
  // 使查找变得容易并防止重复
}

if (account.status === 'PENDING') {
  showMessage('账户验证进行中');
  // 1 小时后检查或等待 webhook
}

// 帮助用户识别账户
const accountLabel = account.type === 'WALLET'
  ? `${account.data.currency} on ${account.data.network}`
  : `${account.data.bankCode} - ${account.data.accountNumber.slice(-4)}`;

​
下一步

银行账户

为不同国家设置银行账户

加密货币钱包

配置加密货币钱包账户

预充值账户

启用即时结算

API 参考

完整的账户 API 文档