创建商户

每个通过 VelaFi 收付款的实体都必须注册为商户并通过身份验证。VelaFi 通过此流程遵守了解你的客户 (KYC) 和了解你的企业 (KYB) 法规。验证完成后，平台会为该实体分配一个唯一的商户 ID (MID)。在后续所有与交易、账户管理和结算相关的 API 调用中，您都必须包含此 MID。

为什么需要商户

VelaFi 在受监管的金融生态系统中运营。每条商户记录都将现实中的个人或企业与其入金 (On-Ramp)、出金 (Off-Ramp) 和全球支付活动关联起来。合规审查可确保在任何资金流动之前，所有参与方都符合反洗钱 (AML) 和反恐怖融资 (CFT) 标准。

向 /v2/merchants 发送 POST 请求，以注册新的个人或企业商户并启动验证流程。端点

POST https://api.velafi.com/v2/merchants

请求头

X-BH-TOKEN: <your-token>
Content-Type: application/json

请求参数

string

必填

商户的全名或企业名称。在您的账户中必须唯一。

string

必填

商户的电子邮件地址。在您的账户中必须唯一。

string

必填

商户实体类型。可接受的值：INDIVIDUAL、BUSINESS。

string

必填

KYC/KYB 流程完成（成功或失败）后 VelaFi 调用的 URL。VelaFi 会向此 URL 发送 POST 通知。

string

商户所属行业。当 merchantType 为 BUSINESS 时必填。 可接受的值：payment_psp、fintech、lending、fx_or_otc、e-commerce、gaming_or_entertainment、crypto_or_web3、supply_chain、import_or_export、payroll_or_hr、media_or_advertising、remittance_or_money_transfer、treasury_or_asset_management、wholesale_or_b2b_marketplace、logistics_and_courier、digital_content_or_streaming、travel_or_booking、online_marketplace、investment_and_crowdfunding、real_estate_and_proptech、accounting_or_billing、freelancer_platform、saas_or_api、online_education、outsourcing_agency、other。

string

KYC 流程，仅适用于 INDIVIDUAL 商户。可接受的值：PROFESSIONALS（默认）、CONSUMERS。

string

KYC/KYB 验证界面的语言。可接受的值：en（默认）、es、pt、zh。

string

可选的自由文本备注，附加到此商户记录。

string

当 industryType 设置为 other 时必填。请简要描述商户的实际行业。

请求示例

curl -X POST https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantName": "Acme Payments Ltd",
    "email": "payments@acme.com",
    "merchantType": "BUSINESS",
    "callbackUrl": "https://acme.com/webhooks/kyc",
    "languageCode": "en",
    "industryType": "fintech",
    "remark": "Primary merchant account"
  }'

{
  "merchantName": "Acme Payments Ltd",
  "email": "payments@acme.com",
  "merchantType": "BUSINESS",
  "callbackUrl": "https://acme.com/webhooks/kyc",
  "languageCode": "en",
  "industryType": "fintech",
  "remark": "Primary merchant account"
}

响应字段

number

响应码。200 表示成功。

string

人类可读的结果消息，例如 SUCCESS。

object

显示 data 字段

number

分配给此商户的唯一商户 ID (MID)。请保存此值——后续所有 API 调用都需要用到它。

string

指向 VelaFi 安全 KYC/KYB 验证页面的 URL。请将用户重定向到此 URL，或将其嵌入 iframe 中。

Example Response

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "merchantId": 100001,
    "kycLink": "https://www.velafi.com/verify?velafi_token=abc123"
  }
}

完成 KYC/KYB 验证

成功调用 POST /v2/merchants 后，请引导用户访问 kycLink URL 以完成身份验证。您有两种集成方式：

重定向模式
嵌入 (iframe) 模式

将用户的浏览器直接重定向到 kycLink URL。这是最简单的集成方式——用户在 VelaFi 托管的页面上完成验证，完成后将返回到您的 callbackUrl。

window.location.href = data.kycLink;

在您的应用中将 kycLink URL 嵌入 <iframe>，以提供无缝的应用内体验。

<iframe
  src="https://www.velafi.com/verify?velafi_token=abc123"
  width="100%"
  height="700"
  title="Identity Verification"
/>

在 MDX 页面中只能使用与 Mintlify 兼容的组件。上面的 iframe 代码片段用于您应用的前端代码，而非本文档页面。

根据会话和配置设置，kycLink URL 可能会在短时间后过期。请确保用户在 API 调用后及时访问。

为未验证的商户重新请求 KYC 链接

如果商户未在初始会话中完成验证——例如链接已过期或用户关闭了浏览器——您可以请求新的 kycLink，而无需创建重复的商户记录。请传入现有的 merchantId，而不是完整的商户信息：

{
  "merchantId": 100001,
  "callbackUrl": "https://acme.com/webhooks/kyc",
  "languageCode": "en"
}

响应中会包含新的 kycLink，您可以再次将用户重定向到该链接。

商户管理模式

多商户管理

当您的主商户账户通过 KYB 验证后，您可以在您的账户下创建和管理子商户——个人或企业均可。这样即可实现分层商户管理，并支持基于角色的访问控制和按商户配置。常见用例包括：

聚合商代表多个客户管理支付
平台为其自有商户提供支付基础设施
市场运营方在商户层面处理合规和结算

每个子商户都会经过各自的 KYC/KYB 流程，并获得各自的 MID。

依赖模式（持牌金融机构）

如果您的组织是持牌金融机构，可以申请启用依赖模式 (Reliance Mode)。在此模式下：

您负责商户入驻、持续审查和合规监控。
VelaFi 不会干预您的商户入驻流程。
VelaFi 继续提供技术基础设施、结算通道和监管支持。

依赖模式需要 VelaFi 合规团队进行额外的合规审查。了解有关依赖模式申请流程的更多信息。

快速入门

核心概念

指南

参考

创建商户

为什么需要商户

创建商户

请求参数

请求示例

响应字段

完成 KYC/KYB 验证

为未验证的商户重新请求 KYC 链接

商户管理模式

​为什么需要商户

​创建商户

​请求参数

​请求示例

​响应字段

​完成 KYC/KYB 验证

​为未验证的商户重新请求 KYC 链接

​商户管理模式

为什么需要商户

创建商户

请求参数

请求示例

响应字段

完成 KYC/KYB 验证

为未验证的商户重新请求 KYC 链接

商户管理模式