# Stabo 开发者文档

- 指南
  - [概览](/docs/guide): Stabo 对外 API 的产品线、接入步骤和文档导航。
  - [快速开始](/docs/guide/quickstart): 接入准备、环境信息和第一个请求。
  - [鉴权](/docs/guide/authentication): 使用 OAuth2 Client Credentials 模式获取 Access Token。
  - [通用约定](/docs/guide/conventions): 协议、请求头、统一响应格式、数据格式和幂等性。
  - [Webhook](/docs/guide/webhooks): 通知机制、请求头、事件结构和签名验证。
  - [最佳实践](/docs/guide/best-practices): 幂等与重试、对账与补偿、安全建议，以及联调和上线检查清单。

  - **产品指南**
  - [Checkout 产品指南](/docs/guide/checkout): 托管收银台、Payment Intent、Refund、Webhook 事件和状态附录。接口细节见 API 参考。
  - Business Collection
    - [Business Collection](/docs/guide/business-collection): 用本地法币收款，资金以稳定币记入 Stabo 钱包。当前提供 On-Ramp。
    - [On-Ramp](/docs/guide/business-collection/on-ramp): 墨西哥 MXN 购买 USDT。收款账号开通与查询、报价、下单、查单、订单状态和 Webhook 事件。接口细节见 API 参考。
  - [Payment 产品指南](/docs/guide/payment): 余额查询、转账、交易查询、SWIFT 报文、法币账户和入账通知。接口细节见 API 参考。
  - [渠道 KYC 与开户](/docs/guide/provider-kyc): 通过 LEGEND 渠道为企业客户完成 KYB、RFI 补件和法币账户开户。每一步附请求与响应示例。
  - [Payment 附录](/docs/guide/payment-reference): 费用承担方式、汇款目的代码、交易类型代码和国家代码。
- API 参考
  - [开通收款账号](/docs/api/business-collection/on-ramp/createOnRampReceiveAccount): 为付款人开通专属收款 CLABE。开通需要几分钟。请在付款人注册或绑定时调用，不要等到付款时再开户。

本接口幂等。同一 `payerId` 重复调用，返回同一个收款账号的当前状态，不会重复开户。不需要 `Idempotency-Key`。

开户不需要付款人 KYC。KYC 在下单时提交。

本期不推送开户结果通知。请用查询收款账号接口查询，建议间隔 1 分钟以上。

收款账号长期有效。同一付款人以后的订单都使用这个 CLABE。
  - Business Collection
    - On Ramp: 本地法币收款并兑换为 USDT。查询报价、创建订单、查询订单、开通收款账号、查询收款账号。
      - [开通收款账号](/docs/api/business-collection/on-ramp/createOnRampReceiveAccount): 为付款人开通专属收款 CLABE。开通需要几分钟。请在付款人注册或绑定时调用，不要等到付款时再开户。

本接口幂等。同一 `payerId` 重复调用，返回同一个收款账号的当前状态，不会重复开户。不需要 `Idempotency-Key`。

开户不需要付款人 KYC。KYC 在下单时提交。

本期不推送开户结果通知。请用查询收款账号接口查询，建议间隔 1 分钟以上。

收款账号长期有效。同一付款人以后的订单都使用这个 CLABE。
      - [查询收款账号](/docs/api/business-collection/on-ramp/getOnRampReceiveAccount): 查询付款人收款账号的开通状态和 CLABE。响应结构与开通收款账号的响应相同。

只能查询本商户的付款人。没有开过户的 `payerId` 返回「收款账号不存在」。
      - [查询报价](/docs/api/business-collection/on-ramp/getOnRampQuote): 查询参考价。报价不锁价，最终价格以下单响应为准。

报价只支持按 MXN 金额查询。下单可以按 MXN（`fiatAmount`）或 USDT（`cryptoAmount`）金额。

报价不生成报价 ID。下单时不需要传报价信息。
      - [创建订单](/docs/api/business-collection/on-ramp/createOnRampOrder): 创建 On-Ramp 订单，返回付款指引。成功返回 HTTP 200，创建后 `status` 为 `AWAITING_PAYMENT`。

付款人必须在 `expiresAt` 之前，向 `paymentInfo.clabe` 转账 `fiatAmount` MXN。

下单价格由渠道实时确定，可能与报价不同。以下单响应为准。

`fiatAmount` 和 `cryptoAmount` 必须传且只传一个。

按 `fiatAmount` 下单时，到账 USDT 由渠道确认，记账金额以响应中的 `cryptoAmount` 为准。渠道确认前，`cryptoAmount` 可能为空。

`paymentInfo` 为空时，表示渠道收款还没确认。用同一 `Idempotency-Key` 重试下单，或稍后查单。

渠道拒绝时，订单置为 `FAILED`。用同一 `Idempotency-Key` 重放会返回该 `FAILED` 订单。

付款人 KYC 只用于转发给渠道。Stabo 不保存，也不在响应中返回证件号和联系方式。

付款人的收款账号必须已开通，见开通收款账号接口。未开通时，下单返回「收款账号开通中」，不建单。
      - [查询订单](/docs/api/business-collection/on-ramp/getOnRampOrder): 按 Stabo 订单号查询订单。响应结构与创建订单的响应相同。

只能查询本商户的 On-Ramp 订单。其他订单返回「订单不存在」。

建议以 Webhook 为主、查单为辅。轮询时建议间隔 30 秒以上，到达终态后停止。

Webhook 与查单结果不一致时，以查单结果为准。
  - Checkout
    - Payment Intent: 创建支付意图、查询支付详情、分页查询支付列表。
      - [查询 Payment Intent 列表](/docs/api/checkout/payment-intent/listPaymentIntents): 分页查询 Payment Intent。筛选条件通过 Query Parameters 传入。
      - [创建 Payment Intent](/docs/api/checkout/payment-intent/createPaymentIntent): 创建 Payment Intent，生成托管收银台链接。创建成功后，把客户跳转到响应中的 `checkoutUrl` 完成支付。

成功返回 HTTP 200。创建后 `status` 为 `AWAITING_PAYMENT`。
      - [查询 Payment Intent 详情](/docs/api/checkout/payment-intent/getPaymentIntent): 按 Payment Intent ID 查询支付详情。
    - Refund: 创建退款、查询退款列表和退款详情。
      - [查询 Refund 列表](/docs/api/checkout/refund/listRefunds): 分页查询指定 Payment Intent 下的退款。
      - [创建 Refund](/docs/api/checkout/refund/createRefund): 为指定 Payment Intent 创建退款。支持部分退款和全额退款。不传 `amount` 时，退还剩余可退金额。退款先进入 `PENDING_APPROVAL`，运营确认后执行。

成功返回 HTTP 200。
      - [查询 Refund 详情](/docs/api/checkout/refund/getRefund): 按 Refund ID 查询退款详情。退款必须属于路径中的 Payment Intent，否则按"不存在"返回。
  - Payment
    - Balance: 查询账户可用余额。
      - [余额查询](/docs/api/payment/balance/queryBalance): 查询账户可用余额。
    - Transfer: 行内转账、MEPS+ 转账、跨境汇款，及各自的结果查询。
      - [行内转账](/docs/api/payment/transfer/createIntraBankTransfer): 账户之间的行内转账，支持所有币种。适用于同一银行内不同账户间的资金调拨。

**注意事项**

- `remarks` 仅支持字母数字、空格及特殊字符 `/ - ? : ( ) . , ' +`
- 当返回 `PROCESSING` 状态时，请在 5 分钟后调用结果查询接口确认最终状态
- 走 POBO 出账的订单，响应会返回 `poboAccountNo` / `poboAccountName`；调用结果查询接口时建议传入 `accountNumber=poboAccountNo`，以明确指定 POBO 出账账号。未传 `accountNumber` 时，系统将根据 `referenceNo` 自动匹配对应的 POBO 出账账号。
      - [行内转账结果查询](/docs/api/payment/transfer/queryIntraBankTransfer): 查询行内转账的结果状态。当转账返回 `PROCESSING` 状态时，请调用此接口查询最终结果。
      - [MEPS+ 转账](/docs/api/payment/transfer/createMepsTransfer): 通过 MEPS+（MAS Electronic Payment System）进行新加坡本地实时转账。

特点：

- 仅支持 SGD 币种
- 实时到账
- 适用于大额本地转账

**注意事项**

- `beneficiaryName`、`beneficiaryAddress`、`remarks` 仅支持字母数字、空格及特殊字符 `/ - ? : ( ) . , ' +`
- 如收款银行非 MEPS+ 参与行，需提供中间行信息
- 走 POBO 出账的订单，响应会返回 `poboAccountNo` / `poboAccountName`；调用结果查询接口时建议传入 `accountNumber=poboAccountNo`，以明确指定 POBO 出账账号。未传 `accountNumber` 时，系统将根据 `referenceNo` 自动匹配对应的 POBO 出账账号。
      - [MEPS+ 转账结果查询](/docs/api/payment/transfer/queryMepsTransfer): 查询 MEPS+ 转账的结果状态。
      - [跨境汇款](/docs/api/payment/transfer/createSwiftTransfer): 通过 SWIFT 网络进行跨境汇款。**注意**：GLDB 渠道不支持 SGD 币种的跨境汇款。

**注意事项（GLDB 渠道）**

- 不支持 SGD 币种
- BIC 代码不足 11 位需补充 `X`
- `beneficiaryName`、`beneficiaryAddress`、`remarks` 仅支持字母数字、空格及特殊字符 `/ - ? : ( ) . , ' +`
- 走 POBO 出账的订单，响应会返回 `poboAccountNo` / `poboAccountName`；调用结果查询接口时建议传入 `accountNumber=poboAccountNo`，以明确指定 POBO 出账账号。未传 `accountNumber` 时，系统将根据 `referenceNo` 自动匹配对应的 POBO 出账账号。
      - [跨境汇款结果查询](/docs/api/payment/transfer/querySwiftTransfer): 查询跨境汇款的结果状态。
    - Transaction: 交易历史查询和 MT/MX 报文查询。
      - [交易历史查询](/docs/api/payment/transaction/queryTransactionHistory): 查询账户的交易历史记录，支持分页查询。适用于对账和财务报表生成。
      - [MT/MX 报文查询](/docs/api/payment/transaction/queryMtMxMessage): 查询转账交易关联的 MT/MX SWIFT 报文原文。适用于合规审计和问题排查。

各场景下 `messageContent` 的内容示例见 [Payment 产品指南](/docs/guide/payment#swift-报文示例)。
    - Fee: 查询转账预估手续费。
      - [查询转账预估手续费](/docs/api/payment/fee/estimateFee): 根据转账类型和金额，计算产生的预估手续费。
    - Provider K Y C: 渠道侧 KYC：提交要求、企业 KYB 提交与状态查询、RFI 补件。当前只支持 LEGEND。
      - [查询 KYC 提交要求](/docs/api/payment/provider-kyc/getProviderKycRequirements): 返回向渠道提交企业 KYC（KYB）所需的国家、选项和文件要求。

- `label` 按请求语言返回，只用于展示。提交时用 `code`。
- 不传 `customerUid` 时，`options` 有 8 个键。
- `options["documents[].category"]` 是文件分类的参考值，不是完整列表。其他值原样转给渠道，由渠道判定。
- 带 `customerUid` 时，已在渠道建档的客户额外返回 `questionnaire.purposes`。新客户返回的结果不含 `questionnaire.purposes`。
- 新客户首次提交时，`questionnaire.purposes` 可以填参考值 `invest_trade`、`crypto_fiat`。这不是完整列表，取值由渠道校验。
- 首次调用约 10 秒，之后命中缓存会更快。客户端超时建议不低于 60 秒。

完整流程见 [渠道 KYC 与开户](/docs/guide/provider-kyc)。
      - [查询 KYC 状态](/docs/api/payment/provider-kyc/getProviderKyc): 查询客户在渠道的 KYC 状态。不是 Stabo 平台的 KYC 状态。

- `providerCustomerId` 在 `SUBMITTED` 阶段可能为空，`APPROVED` 后才返回。开户要用它。
- `failureReason` 只在 `REJECTED` 时返回。
      - [提交 KYB](/docs/api/payment/provider-kyc/submitProviderKyc): 向渠道提交或重新提交客户的企业 KYC。首次提交时在渠道建档。

请求为 `multipart/form-data`：`data` 部分是 JSON 资料，其余每个部分是一个文件，部分名等于 `documents[].clientFileId`。文件部分与 `clientFileId` 必须一一对应。

- 渠道已受理（`SUBMITTED` 或 `APPROVED`）时，返回当前状态，不写资料，不带 `submittedAt`。
- `Idempotency-Key` 必填，用于审计关联。超时后用同一份资料和原键重试。
- 耗时视文件数量，可能超过 30 秒。客户端超时建议不低于 60 秒。
- 本地只做组装和安全所需的最小校验：必需字段非空、`data` 无未知字段、`personId` 与 `clientFileId` 不重复、文件对应关系、单文件不超过 2 MB、文件头为 PDF、PNG 或 JPEG。
- 字段格式、取值、人员角色数量、必备文件等规则由渠道判定，不符合时返回 `openapi.channel.rejected`。

字段说明里的长度和取值是渠道规则，由渠道校验。完整示例见 [渠道 KYC 与开户](/docs/guide/provider-kyc#提交-kyb)。
      - [查询 RFI 列表](/docs/api/payment/provider-kyc/listProviderKycRfis): 查询渠道为客户发起的补件请求（RFI）。列表不返回题目，查详情才返回。
      - [查询 RFI 详情](/docs/api/payment/provider-kyc/getProviderKycRfi): 查询一张 RFI 及其题目。
      - [创建 IDV 会话](/docs/api/payment/provider-kyc/createProviderKycIdvSession): 为待作答 RFI 中的 IDV 题创建身份核验会话。

- RFI 不是 `ACTION_REQUIRED` 时返回 `provider_kyc.rfi.not_actionable`。题目不是本 RFI 的 IDV 题时返回 `provider_kyc.rfi.question_not_idv`。
- `url` 是一次性会话链接。只交给完成核验的人员，不要记录或转发。
- 核验完成后，仍要随整张 RFI 提交这道题。
      - [提交 RFI 答案](/docs/api/payment/provider-kyc/submitProviderKycRfiAnswers): 一次提交待作答 RFI 全部题目的答案。

请求为 `multipart/form-data`：`data` 部分是 JSON 答案，其余每个部分是一个文件，部分名等于 `answers[].clientFileIds` 中的值。

- RFI 已在审核中（`UNDER_REVIEW`）时，返回当前状态，不写入，不带 `submittedAt`。
- `Idempotency-Key` 必填。重试同一次提交时复用原键，渠道不会受理两次。
- 受理不等于审核通过，也不解除 `restrictions`。
- 本地只校验必需字段非空、`clientFileId` 安全字符、文件对应关系、文件大小和类型。题目归属、必答、长度、文件数、勾选值由渠道判定，不符合时返回 `openapi.channel.rejected`。

各题型的答案写法见 [渠道 KYC 与开户](/docs/guide/provider-kyc#提交-rfi-答案)。
    - Fiat Account: 标准法币账户开户、开户选项与账户详情查询。
      - [创建法币账户](/docs/api/payment/fiat-account/createFiatAccount): 创建法币账户。请求格式按渠道区分：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`。
      - [查询开户选项](/docs/api/payment/fiat-account/listFiatAccountOpeningOptions): 查询指定客户的可选开户路由与费用。`currency` 和 `bankCountry` 都可选，都不传时返回该客户的全部选项。`partnerBanks` 只是候选银行，实际开户银行以账户详情为准。仅适用于 LEGEND。GLDB 不支持，返回 `openapi.channel.unsupported`。
      - [查询账户详情](/docs/api/payment/fiat-account/getFiatAccount): 按账户 ID 查询账户详情。

**GLDB**

- `accountId` 是创建时返回的申请单号。
- 不得传 `providerCustomerId`。
- 审核中为 `PENDING`。审核通过后为 `ACTIVE`。账户之后停用或关闭时为 `INACTIVE` 或 `CLOSED`。审核拒绝或申请取消时为 `FAILED`。
- 开户后返回 `accountNumber`、`bankName`、`bankAddress`、`swiftBic`、`iban`、`bankCountry`、`accountHolderName`。`openedAt` 只在 `ACTIVE` 时返回。
- 不推送状态变化的 Webhook。请轮询本接口。
- 账户不存在时返回 `fiat.account.not_found`。只支持单币种账户，查询多币种账户返回 `fiat.account.multi_currency_unsupported`。
    - Digital Wallet: 数币钱包资产、钱包创建、详情与充值地址。
      - [查询支持的资产与网络](/docs/api/payment/digital-wallet/listDigitalWalletAssets): 返回渠道支持的数币资产与网络列表。生成地址时需把 `assetCode` 原样传回。
      - [创建数币钱包](/docs/api/payment/digital-wallet/createDigitalWallet): 创建数币钱包。数币钱包是多资产容器，创建时不传币种和网络。

幂等键走 `Idempotency-Key` 请求头。创建成功返回 `ACTIVE`，若渠道仍在创建中返回 `PENDING`。
      - [查询钱包详情](/docs/api/payment/digital-wallet/getDigitalWallet): 按钱包 ID 查询钱包详情，含已生成的充值地址。
      - [查询充值地址列表](/docs/api/payment/digital-wallet/listDigitalWalletAddresses): 返回钱包下已生成的充值地址与余额。复用钱包详情里的 `addresses`，不另发渠道请求。
      - [生成充值地址](/docs/api/payment/digital-wallet/generateDigitalWalletAddress): 为已开通的数币钱包生成充值地址。钱包必须为 `ACTIVE`。渠道已有该资产地址时返回同一个 `addressId`。

幂等键走 `Idempotency-Key` 请求头。`assetCode` 来自资产列表查询，原样传回。
- 帮助
  - [错误码](/docs/help/errors): 错误响应的格式、HTTP 状态码与响应体 code 的对应关系，以及处理方式。
  - [常见问题](/docs/help/faq): 接入中的常见问题，以及技术支持联系方式。
  - [变更记录](/docs/help/changelog): 对外 API 文档的版本变更记录。