创建法币账户

POST
/openapi/v1/fiat-accounts

创建法币账户。请求格式按渠道区分:LEGEND 用 application/json,GLDB 用 multipart/form-data。

LEGEND

  • Idempotency-Key 必填。
  • 同步成功时直接返回标准账户,状态可为 ACTIVE。返回 PENDING 时再查账户详情。
  • 返回 fiat.account.channel.detail_unavailable 时,用消息里的账户 ID 查询,不要再次开户。
  • 请求体出现未定义字段会被拒绝。

GLDB

  • 不得传 Idempotency-Key。传了返回 fiat.account.idempotency_key.unsupported。
  • currency 只能填一个币种。不支持多币种申请。
  • 开户需要人工审核。创建返回 PENDING,accountId 是申请单号。用它轮询账户详情,审核通过后状态变为 ACTIVE。
  • 不推送状态变化的 Webhook。

传了另一渠道专属的字段,返回 fiat.account.field.unsupported。缺少本渠道必填字段,返回 fiat.account.field.required。

鉴权

bearerAuth
header鉴权Bearer <令牌>

通过 POST /oauth2/token 获取的 access_token。请求头格式为 Authorization: Bearer {accessToken}。

Header 参数

X-Channel-Provider*string

渠道提供商标识,如 GLDB

Idempotency-Key?string

唯一请求标识(建议使用 UUID)。LEGEND 必填,规则见 Payment 产品指南。GLDB 不得传,传了返回 fiat.account.idempotency_key.unsupported。

请求体

  1. body

LEGEND 开户请求(application/json)。

providerCustomerId?string

渠道侧客户标识,由调用方传入。LEGEND 必填,即 user_short_id。

currency*string

ISO 4217 货币代码,3 位大写字母。

bankCountry?string

ISO 3166-1 alpha-2 国家代码,2 位大写字母。

alias?string

账户别名。只允许字母、数字、空格、连字符,最长 50 字符。

openingOptionId?string

开户选项 ID,来自开户选项查询。不传则由渠道自行选择路由。

响应体

返回账户详情。LEGEND 同步成功时 status 可为 ACTIVE。GLDB 返回 PENDING,只带 accountId(申请单号)、currency、status、accountHolderName。

application/json
  1. response
code?integer

业务状态码

message?string
traceId?string

请求追踪 ID。联系技术支持时请提供

data?

法币账户详情。

请求示例
curl -X POST 'https://api.test.stabofx.com/openapi/v1/fiat-accounts' \  -H 'X-Channel-Provider: GLDB' \  -H 'Content-Type: application/json' \  -d '{  "providerCustomerId": "usr_user123",  "currency": "USD",  "bankCountry": "SG",  "alias": "Main USD Account",  "openingOptionId": "brt_abcdefghijklmnopqrstuvwxyz"}'
响应示例
{  "code": 200,  "message": "操作成功",  "traceId": "t_xxxxxxxx",  "data": {    "accountId": "bnk_abc123",    "providerCustomerId": "usr_user123",    "currency": "USD",    "status": "PENDING",    "alias": "Main USD Account",    "bankCountry": "SG",    "bankName": "DBS Bank",    "swiftBic": "DBSSSGSG",    "accountNumber": "072001234",    "routingCodes": [      {        "type": "ROUTING_NUMBER",        "value": "123456789"      }    ]  }}