← Blog & Resources

OnyxClearing API 入门 - 构建机构级外汇兑换工作流

EN only

大家好!我是 Thiskard 的开发者布道师。今天我们要深入探讨一个在集成发卡API时至关重要的功能模块:机构级外汇(FX)兑换工作流。 当你构建一个多币种发卡平台时,一个最常见的需求是如何优雅地处理资金在不同货币间的流转。比如,你的用户持有一张美元银行卡,却在巴黎的咖啡馆消费了欧元。作为发卡方,你需要实时或准实时地

Published July 24, 2026 · ThisKard team

大家好!我是 Thiskard 的开发者布道师。今天我们要深入探讨一个在集成发卡API时至关重要的功能模块:机构级外汇(FX)兑换工作流。

当你构建一个多币种发卡平台时,一个最常见的需求是如何优雅地处理资金在不同货币间的流转。比如,你的用户持有一张美元银行卡,却在巴黎的咖啡馆消费了欧元。作为发卡方,你需要实时或准实时地将用户账户中的美元兑换成欧元来结算这笔交易。

这就是 OnyxClearing API 大显身手的地方。它不仅提供了极具竞争力的机构级汇率,还为开发者提供了一套清晰、RESTful 的接口,让复杂的金融基础设施集成变得像调用普通 Web 服务一样简单。本教程将引导你完成从获取报价到执行兑换的全过程。

核心概念:OnyxClearing 的工作原理

在写代码之前,我们需要理解 OnyxClearing 的两个核心概念:

  1. 报价:这是外汇交易的意向书。它锁定了当前的汇率,并告诉你为了获得目标货币,你需要支付多少源货币。OnyxClearing 的报价通常有一个短暂的有效期(例如 15-30 秒),这保证了你不会因为市场波动而遭受滑点损失。
  2. 兑换:这是实际的交易动作。一旦你接受了报价,OnyxClearing 就会执行原子性的资金划转,借记你的源币种账户,贷记目标币种账户。

准备工作:环境配置

在开始编码之前,请确保你已经完成了以下准备工作:

  1. 注册开发者账户:访问 thiskard.com/developers 注册并获取你的 API Key 和 Secret。
  2. 获取沙盒凭证:我们的沙盒环境完全模拟了生产环境的行为,但使用的是虚拟资金。
  3. 配置环境变量:为了安全起见,永远不要将密钥硬编码在代码中。我们将假设你已经在环境中设置了 THISKARD_API_KEY 和 THISKARD_API_SECRET。

实战:构建 FX 兑换脚本

我们将使用 TypeScript (Node.js) 来构建这个工作流。我们选择 TypeScript 是因为它强大的类型系统能帮助我们更好地处理金融数据结构。

下面的代码示例将演示一个完整的流程:查询汇率 -> 锁定报价 -> 执行兑换。

import axios, { AxiosInstance, AxiosError } from 'axios';

// 1. 配置基础设置
const BASE_URL = 'https://api.thiskard.com/v1/onyxclearing';

// 定义接口类型,确保数据结构清晰
interface QuoteResponse {
  quote_id: string;
  base_currency: string;
  quote_currency: string;
  base_amount: string; // 金额通常以字符串形式传输以避免浮点数精度问题
  quote_amount: string;
  rate: string;
  expires_at: string; // ISO 8601 格式
}

interface ConversionResponse {
  conversion_id: string;
  status: 'PENDING' | 'SETTLED' | 'FAILED';
  source_account: string;
  dest_account: string;
  amount: string;
  settled_rate: string;
  timestamp: string;
}

class OnyxClearingClient {
  private client: AxiosInstance;

  constructor(apiKey: string, apiSecret: string) {
    this.client = axios.create({
      baseURL: BASE_URL,
      auth: {
        username: apiKey,
        password: apiSecret,
      },
      headers: {
        'Content-Type': 'application/json',
      },
      // 设置超时,防止因网络问题导致的长时间挂起
      timeout: 10000, 
    });
  }

  /**
   * 第一步:获取实时报价
   * 这是一个 "Not for Payment" 的查询,仅用于展示汇率。
   */
  async getIndicativeRate(base: string, quote: string, amount: number): Promise<void> {
    try {
      console.log(`正在查询 ${base}/${quote} 的指示性汇率...`);
      const response = await this.client.get('/rates', {
        params: { base_currency: base, quote_currency: quote, amount: amount }
      });
      console.log(`当前市场汇率: ${response.data.rate}`);
      console.log(`预估可得金额: ${response.data.quote_amount}`);
    } catch (error) {
      this.handleError(error);
    }
  }

  /**
   * 第二步 & 第三步:锁定报价并执行兑换
   * 在生产环境中,这通常是两个步骤,但为了流程顺畅,我们在这里合并展示逻辑。
   */
  async executeConversion(
    baseCurrency: string, 
    quoteCurrency: string, 
    amount: number,
    idempotencyKey: string // 幂等性Key,防止重复扣款
  ): Promise<void> {
    try {
      console.log('\n--- 开始 FX 兑换流程 ---');
      
      // Step 2.1: 创建报价请求
      // 这里的报价是可执行的,包含 quote_id
      console.log('正在请求可执行报价...');
      const quoteResponse = await this.client.post<QuoteResponse>('/quotes', {
        base_currency: baseCurrency,
        quote_currency: quoteCurrency,
        base_amount: amount.toString(),
        action: 'CONVERSION' // 明确意图为兑换
      });

      const quote = quoteResponse.data;
      console.log(`报价锁定成功! Quote ID: ${quote.quote_id}`);
      console.log(`锁定汇率: ${quote.rate}, 将于 ${quote.expires_at} 过期`);

      // Step 2.2: 执行兑换
      // 在实际应用中,你可能会在这里校验汇率是否符合预期阈值
      console.log('正在提交兑换请求...');
      
      const conversionResponse = await this.client.post<ConversionResponse>('/conversions', {
        quote_id: quote.quote_id,
        // 可选:指定资金来源账户ID,如果不指定则使用默认清算账户
        source_account_id: 'acc_fx_liquidty_usd', 
        dest_account_id: 'acc_settlement_eur'
      }, {
        headers: {
          'Idempotency-Key': idempotencyKey // 关键头部:保证请求幂等性
        }
      });

      const result = conversionResponse.data;
      
      if (result.status === 'SETTLED') {
        console.log(`✅ 兑换成功! 交易ID: ${result.conversion_id}`);
        console.log(`最终汇率: ${result.settled_rate}`);
        console.log(`到账金额: ${result.amount}`);
      } else {
        console.log(`⚠️ 兑换状态: ${result.status}`);
      }

    } catch (error) {
      this.handleError(error);
    }
  }

  private handleError(error: unknown) {
    const err = error as AxiosError;
    if (err.response) {
      // API 返回的业务错误
      console.error(`❌ API 错误: ${err.response.status}`);
      console.error(`错误详情: ${JSON.stringify(err.response.data, null, 2)}`);
    } else if (err.request) {
      // 请求已发出但无响应
      console.error('❌ 网络错误:无法连接到 Thiskard API 网关。');
    } else {
      // 其他错误
      console.error('❌ 未知错误:', err.message);
    }
  }
}

// --- 运行示例 ---

// 注意:实际运行时请替换环境变量获取方式
const API_KEY = process.env.THISKARD_API_KEY || 'sk_test_your_api_key';
const API_SECRET = process.env.THISKARD_API_SECRET || 'your_secret_here';

const client = new OnyxClearingClient(API_KEY, API_SECRET);

// 场景:为了结算一笔 Visa 欧元交易,我们需要卖出 10,000 美元
const runWorkflow = async () => {
  await client.getIndicativeRate('USD', 'EUR', 10000);
  
  // 使用 UUID 作为幂等键,确保即使网络中断重试也不会重复扣款
  await client.executeConversion('USD', 'EUR', 10000, 'uuid-v4-12345-abcde');
};

runWorkflow();

代码解析:分步工作流详解

让我们拆解上面的代码,看看它是如何映射到实际业务流程的。

第一步:身份验证与实例化

我们使用 axios 创建了一个实例,并配置了 HTTP Basic Auth。api.thiskard.com 端点强制要求使用 HTTPS,所有未加密的请求都会被拒绝。我们在 constructor 中注入凭证,确保了凭证管理的灵活性。

第二步:获取报价 (POST /quotes)

这是整个流程的核心。我们在代码中发送了一个 JSON 对象,指定了 base_currency(我们要卖出的币种)、quote_currency(我们要买入的币种)和金额。 OnyxClearing API 会返回一个包含 quote_id 的对象。这个 ID 是下一步执行兑换的关键凭证。请注意,报价是有时效性的,如果 expires_at 时间已过,该 Quote ID 将失效,你需要重新请求。

第三步:执行兑换 (POST /conversions)

拿到报价 ID 后,我们立即调用 /conversions 端点。这里有一个非常关键的 HTTP 头部:Idempotency-Key。 为什么这很重要? 在分布式系统中,网络超时是常态。如果你发起请求,API 处理成功了,但响应包在网络传输中丢失,你的客户端可能会因为超时而重试。如果没有幂等性机制,重复的请求可能会导致用户被扣款两次。Thiskard API 支持幂等性,使用相同的 Key 重试,系统只会返回原始的成功结果,而不会产生新交易。

错误处理与异常管理

在金融系统集成中,如何处理错误甚至比成功流程更重要。OnyxClearing API 遵循标准的 HTTP 状态码规范:

  • 400 Bad Request: 通常意味着参数错误,比如金额为负数或货币代码格式不对。你需要检查请求体。
  • 401 Unauthorized: API Key 或 Secret 错误,或者 Key 已被禁用。
  • 409 Conflict / 422 Unprocessable Entity: 这在 FX 场景下很常见。可能报价已过期,或者你的账户流动性不足。
  • 429 Too Many Requests: 你触发了速率限制。Our API has strict rate limits to ensure fairness. 如果遇到此错误,应实施指数退避重试机制。
  • 5xx Server Errors: 服务端错误。虽然罕见,但建议配置重试逻辑(Jitter Retry)。

最佳实践: 在我们的代码示例中,handleError 函数对错误进行了分类。在生产环境,你应该将这些错误日志记录到你的 APM(如 Datadog 或 Sentry)系统中,并为运营团队配置警报。特别是 INSUFFICIENT_FUNDS 错误,这可能意味着你的清算账户需要注资了。

集成到发卡生命周期

你可能会问:“我应该在什么时候调用这个 API?”

这取决于你的发卡模式:

  1. 预付卡充值模式:用户发起充值时,你可以实时调用 OnyxClearing API 将资金兑换为卡内货币。这通常发生在用户交互的 UI 线程中,需要快速响应。
  2. 后台批量清算:对于信用卡或借记卡交易,你通常不需要在每一笔刷卡时都调用 FX API。Visa/Mastercard 会先进行授权,然后在晚间进行批量清算。
    • 你可以编写一个批处理脚本,汇总所有需要结算的跨币种交易。
    • 计算总金额,调用 OnyxClearing 进行一次大额兑换(通常大额兑换能获得更好的汇率点差)。
    • 兑换完成后,在内部记账系统中分配资金。

安全性与最佳实践

作为开发者布道师,我有责任提醒你注意以下安全事项:

  1. API Key 安全:永远不要在客户端代码(React, iOS, Android)中存储 Secret Key。所有的 API 调用都应从你的服务端发起。OnyxClearing API 旨在服务端之间通信。
  2. IP 白名单:在 Thiskard 开发者后台,你可以配置 IP 白名单。强烈建议配置此项,这样即使 Key 泄露,攻击者也无法从不在此名单的服务器发起请求。
  3. Webhook 集成:虽然我们的示例使用了同步请求响应模式,但对于大额交易或非即时清算,建议使用 Webhook。你可以提供一个 HTTPS 回调地址,当交易状态变为 SETTLED 或 FAILED 时,我们会主动推送消息,这样你就不需要轮询接口了。
  4. 日志脱敏:在记录请求日志时,请务必屏蔽掉 API Secret 和敏感的用户数据,符合 PCI-DSS 和 GDPR 合规要求。

结语

通过 OnyxClearing API,我们将复杂的机构级外汇交易简化为几个简单的 RESTful 调用。从获取实时报价到幂等性执行,这套工作流旨在帮助开发者快速构建稳健的跨币种发卡应用。

上述代码示例不仅可以直接运行(只需替换凭证),也为你处理并发、超时和幂等性提供了标准的模板。

准备好开始构建了吗?访问 thiskard.com/developers 获取API文档、SDK和沙盒环境。