跳转到主要内容

多币种与外汇报价

Quick Reference

What多币种定价与外汇汇率报价
Why以客户的本地货币显示价格，提升支付转化率
Reading Time10 分钟
Difficulty初级
Prerequisites身份验证 → 创建收费

为什么要提供多币种​

当客户在结账页面看到外币金额时，会因为不确定实际扣款金额而放弃付款。多币种定价消除了这种不确定性。

没有多币种使用 A55 多币种
客户看到 R$ 500.00，但不知道自己的卡会被扣多少钱客户看到 US$ 87.26——这就是卡片扣款的确切金额
客户不知道商户使用了什么汇率您展示银行间市场汇率，完全透明
客户收到账单后因金额不符发起争议价格与扣款金额一致，不会产生争议
跨境客户在结账环节流失国际访客看到自己货币的价格，完成支付

可衡量的业务影响：

  • 更高的转化率：客户看到自己货币的价格时更愿意购买。
  • 更少的 chargeback（拒付）：透明定价减少了"金额不符"的争议。
  • 竞争优势：提供与 Amazon、Shopify、Stripe 等全球平台相同的体验。
  • 拉美覆盖：8 种货币，7 个国家——USD、BRL、EUR、MXN、ARS、COP、CLP、PEN。
客户看到自己的货币

巴西商户可以为国际买家显示 USD、EUR 或 MXN 价格。SaaS（软件即服务）平台可以按客户所在地货币显示订阅费用。电商网站可以让买家在结账时切换货币。

工作原理——三个步骤​

多币种收费分为三步：获取汇率、展示价格、创建收费。

步骤 1——获取汇率​

调用 FX（外汇）端点，获取两种货币之间的当前银行间市场汇率。

端点： POST /api/v1/bank/wallet/fx/rate/

请求参数：

字段类型必填说明
from_currencystring是源货币，ISO 4217（国际标准货币代码）。示例：USD
to_currencystring是目标货币，ISO 4217 代码。示例：BRL

响应：

字段类型说明
pricefloat汇率，四舍五入到小数点后 2 位。含义：1 单位源货币 = price 单位目标货币
curl -X POST 'https://core-manager.a55.tech/api/v1/bank/wallet/fx/rate/' \
  -H 'Authorization: Bearer 您的_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "from_currency": "USD",
    "to_currency": "BRL"
  }'

响应示例：

{
  "price": 5.73
}

含义：此刻 1 USD = 5.73 BRL。

步骤 2——向客户展示转换后的价格​

用汇率计算目标货币的价格，在结账页面展示给客户。这一步在您的应用中完成，无需调用 A55 API（应用程序编程接口）。

示例（BRL——2 位小数）： 产品售价 US$ 100.00，汇率 5.73。

BRL 价格 = US$ 100.00 × 5.73 = R$ 573.00
客户看到的内容值
产品价格US$ 100.00
汇率1 USD = 5.73 BRL
应付金额R$ 573.00

示例（CLP——零小数货币）： 产品售价 US$ 100.00，汇率 950.73。

CLP 价格 = US$ 100.00 × 950.73 = CLP 95,073（四舍五入为整数）
客户看到的内容值
产品价格US$ 100.00
汇率1 USD = 950.73 CLP
应付金额CLP $95,073
CLP 和 COP：金额必须为整数

对于零小数货币，收费请求中的金额必须为整数。发送 95073，而非 95073.00。后端会截断小数部分。

同时展示两种货币

在结账页面同时显示原始价格和转换后的价格。客户能看到确切的汇率和卡片将被扣除的确切金额，这能显著提升信任度。Stripe、Wise、Adyen 等全球领先支付平台均采用此做法。

步骤 3——创建收费​

用结算货币（钱包的货币）创建收费。金额为步骤 2 中计算出的转换值。

curl -X POST 'https://core-manager.a55.tech/api/v1/bank/wallet/charge/' \
  -H 'Authorization: Bearer 您的_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "张伟",
    "payer_email": "zhangwei@example.com",
    "payer_tax_id": "12345678909",
    "payer_cell_phone": "+5511999999999",
    "installment_value": 573.00,
    "currency": "BRL",
    "due_date": "2026-04-30",
    "description": "订单 #12345（US$ 100.00，汇率 5.73）",
    "type_charge": "credit_card",
    "installment_count": 1,
    "payer_address": {
      "street": "Av. Paulista",
      "address_number": "1000",
      "complement": "Sala 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR"
    }
  }'
在 description 中记录汇率

将汇率写入 description 字段（如 "订单 #12345（US$ 100.00，汇率 5.73）"）。这为对账和争议处理提供了审计记录。

收费响应包含自动多币种转换：

{
  "charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "local_currency": 573.00,
  "currency": "BRL",
  "usd_currency": 100.00,
  "eur_currency": 91.45,
  "type": "credit_card",
  "status": "confirmed",
  "installment_count": 1,
  "installments": [
    {
      "local_currency": 573.00,
      "currency": "BRL",
      "usd_currency": 100.00,
      "eur_currency": 91.45,
      "due_date": "2026-04-30",
      "status": "confirmed",
      "installment_number": 1
    }
  ]
}

每笔收费响应自动包含三种货币的金额：

字段说明示例
local_currency钱包结算货币的金额573.00（BRL）
usd_currency等值美元金额100.00（USD）
eur_currency等值欧元金额91.45（EUR）

这三个字段可直接用于多币种报告、对账和数据分析，无需再次调用汇率端点。

完整集成示例​

此示例演示完整流程——认证、获取汇率、计算价格、创建收费。

import requests

BASE = "https://core-manager.a55.tech/api/v1"
AUTH_URL = "https://smart-capital.auth.us-east-1.amazoncognito.com/oauth2/token"

# 认证——获取访问令牌
token_resp = requests.post(AUTH_URL, data={
    "grant_type": "client_credentials",
    "client_id": "您的_CLIENT_ID",
    "client_secret": "您的_CLIENT_SECRET",
}, headers={"Content-Type": "application/x-www-form-urlencoded"})
token = token_resp.json()["access_token"]
headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

# 步骤 1：获取最新汇率
fx_resp = requests.post(f"{BASE}/bank/wallet/fx/rate/", json={
    "from_currency": "USD",
    "to_currency": "BRL",
}, headers=headers)
rate = fx_resp.json()["price"]
print(f"汇率：1 USD = {rate} BRL")

# 步骤 2：计算转换后的价格
product_price_usd = 100.00
ZERO_DECIMAL_CURRENCIES = {"CLP", "COP"}
target_currency = "BRL"

if target_currency in ZERO_DECIMAL_CURRENCIES:
    charge_amount = round(product_price_usd * rate)       # 零小数货币：四舍五入为整数
else:
    charge_amount = round(product_price_usd * rate, 2)    # 其他货币：保留 2 位小数
print(f"收费金额：{charge_amount} {target_currency}")

# 步骤 3：以结算货币创建收费
charge_resp = requests.post(f"{BASE}/bank/wallet/charge/", json={
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "payer_name": "张伟",
    "payer_email": "zhangwei@example.com",
    "payer_tax_id": "12345678909",
    "payer_cell_phone": "+5511999999999",
    "installment_value": charge_amount,
    "currency": target_currency,
    "due_date": "2026-04-30",
    "description": f"订单 #12345（US$ {product_price_usd}，汇率 {rate}）",
    "type_charge": "credit_card",
    "installment_count": 1,
    "payer_address": {
        "street": "Av. Paulista", "address_number": "1000",
        "complement": "Sala 101", "neighborhood": "Bela Vista",
        "city": "São Paulo", "state": "SP",
        "postal_code": "01310-100", "country": "BR",
    },
}, headers=headers)

charge = charge_resp.json()
print(f"收费 UUID：{charge['charge_uuid']}")
print(f"本地货币（BRL）：R$ {charge['local_currency']}")
print(f"美元：US$ {charge['usd_currency']}")
print(f"欧元：€{charge['eur_currency']}")

支持的货币​

FX API（应用程序编程接口）支持 8 种货币，覆盖 7 个拉美国家加上 USD 和 EUR，共 56 个兑换货币对。

代码货币国家 / 地区小数位支持钱包
USD美元美国2——
BRL巴西雷亚尔巴西2是
EUR欧元欧元区2——
MXN墨西哥比索墨西哥2是
ARS阿根廷比索阿根廷2是
COP哥伦比亚比索哥伦比亚0——
CLP智利比索智利0是
PEN秘鲁索尔秘鲁2——
零小数货币（CLP、COP）

转换为 CLP 或 COP 时，收费金额必须为整数。乘以汇率后使用 round() 四舍五入，不要使用 floor() 向下取整。示例：USD 100.00 × 950.73 = CLP 95,073。

主要跨境走廊​

货币对典型场景
USD → BRL美国企业向巴西客户销售
USD → MXN美国企业向墨西哥客户销售
EUR → BRL欧洲企业进入巴西市场
BRL → USD巴西 SaaS 企业、出口、跨境汇款
USD → CLP美国企业向智利客户销售
USD → ARS美国企业向阿根廷客户销售
USD → COP美国企业向哥伦比亚客户销售
USD → PEN美国企业向秘鲁客户销售

汇率来源与更新机制​

属性值
汇率来源银行间中间价（mid-market），即 Bid（买入价）与 Ask（卖出价）的中间值。由第三方数据源提供，A55 不加任何加价
缓存窗口约 17 分钟（1,000 秒）
数据源级联回退——系统依次查询多个外部数据源以确保汇率可用性
精度汇率四舍五入到小数点后 2 位
API 可用性24/7——端点全天候响应，包括周末和节假日
周末汇率外汇市场休市期间（周末、节假日），数据源返回最近一个交易时段的汇率
为什么使用银行间市场汇率

银行间市场汇率是全球银行之间买卖货币的中间价，不含任何加价。央行、金融监管机构和金融科技公司将其作为最公平的货币转换参考。全球外汇市场日均交易量超过 9.6 万亿美元（BIS（国际清算银行），2025 年数据）。如此庞大的交易量确保了汇率具有极高的流动性和准确性。

卡组织和发卡行如何在汇率基础上加收费用​

A55 的 FX 端点返回的是银行间市场汇率——零加价。但从 A55 到持卡人的信用卡账单之间，还有两个环节会加收费用。理解这个链条，能帮助您区分"正常的银行费用"和"集成错误"。

货币转换链路​

当一位美国持卡人在结算货币为 BRL 的商户网站上付款。账单金额由五个步骤决定：

步骤参与方发生了什么
1A55 FX 端点返回银行间汇率（例如 1 USD = 5.50 BRL）
2商户以 BRL 创建收费 R$ 550.00（结算货币）
3卡组织（Visa 或 Mastercard）按其每日公布的汇率将 R$ 550.00 换算为 USD——银行间汇率加上卡组织加价（约 1%）
4发卡行加收外币交易手续费（0%–3%，大多数信用卡收取 1%–2%）
5持卡人账单显示最终金额：约 US$ 101–104

各环节费用明细​

环节含义由谁承担典型范围
A55 汇率报价银行间汇率，零加价——0%
卡组织跨境评估费Visa ISA（国际服务评估费）或 Mastercard 跨境评估费商户（通过支付处理商传递）0.6%–1.4%
卡组织货币转换加价内嵌在卡组织公布的汇率中持卡人约 1%
发卡行外币交易手续费发卡行对外币交易收取的费用持卡人0%–3%
持卡人合计影响银行间汇率与账单金额的差异持卡人约 1.6%–4.4%

Visa 与 Mastercard 费用对比​

VisaMastercard
跨境评估费（商户侧）ISA：1.00%（USD 结算）/ 1.40%（非 USD）0.60%（USD 结算）/ 1.00%（非 USD）
货币转换加价（持卡人侧）银行间汇率基础上约 1%银行间汇率基础上约 1%
汇率适用时间通常在结算时（授权后 1–2 个工作日）在授权时（交易发生时）
官方汇率查询Visa 汇率计算器Mastercard 货币转换器

持卡人可通过上述链接输入交易日期和货币对，查询 Visa 或 Mastercard 当日实际使用的汇率。

商户能控制什么，不能控制什么​

您能控制的您无法控制的
何时获取汇率（时效性）卡组织公布的每日汇率
提交收费的 BRL 金额发卡行收取的外币交易手续费（0%–3%）
向客户展示的价格和汇率持卡人的信用卡是收 0% 还是 3% 的外汇手续费
为争议处理保存的审计记录卡组织适用汇率的具体日期

实际场景对照表​

场景持卡人账单预期金额拒付风险
最新汇率 + 0% 外汇手续费的卡约 US$ 101.00无
最新汇率 + 2% 外汇手续费的卡约 US$ 103.00无
最新汇率 + 3% 外汇手续费的卡约 US$ 104.00无——在预期范围内
过期汇率（45 分钟前）+ 2% 手续费约 US$ 106–108高——可触发 Mastercard 4834 拒付

前三行是银行费用导致的正常、可预期差异，不会引发争议。最后一行是过期汇率叠加银行费用——这种组合才会导致拒付。

汇率适用时间与周末交易​

Mastercard 在授权时（持卡人付款的时刻）适用汇率。Visa 通常在结算时（授权后 1–2 个工作日）适用汇率。这意味着：

  • Mastercard 交易：适用的汇率与交易时刻非常接近。
  • Visa 交易：汇率可能在授权和结算之间发生偏移。在汇率波动剧烈的市场中，这会产生额外差异。

周末交易：外汇市场于纽约时间周五 17:00 EST 收盘，周日晚间重新开盘。在此期间，Visa 和 Mastercard 均使用周五的收盘汇率。如果周末期间市场出现大幅波动，周末交易的汇率偏差风险更高。

汇率使用最佳实践​

全球领先的支付平台（Stripe、Wise、Adyen）将汇率用途分为两个场景。A55 的 FX 端点同时适用于这两种场景，但刷新策略不同。

展示定价——产品页面和目录​

在产品列表页或定价页展示多币种价格时，可以在服务端缓存汇率并定期刷新。

建议说明
刷新频率每 10–15 分钟调用一次 FX 端点
缓存策略在服务端缓存汇率，避免每次页面加载都调用 API
价格标注标注"价格按参考汇率折算，最终金额以结账时为准"

交易结账——创建实际收费​

在客户确认付款、创建收费时，需要使用最新汇率以确保展示金额与扣款金额一致。

建议说明
刷新时机在客户点击"确认支付"时重新调用 FX 端点
展示汇率在支付确认页同时展示原始金额、汇率和转换后的金额
记录汇率将汇率存入收费的 description 字段，并保存到您的数据库
金额一致确保展示给客户的金额与请求中的 installment_value 完全一致
使用最新汇率创建收费

汇率在缓存窗口内（约 17 分钟）保持不变。如果客户在结账页面停留较长时间，请在创建收费前重新调用 FX 端点获取最新汇率。使用过期汇率可能导致客户实际被扣金额与页面展示金额不符。

过期汇率如何导致拒付——以真实场景说明​

如果您刚接触跨境支付集成，这一节将帮助您理解为什么汇率时效性至关重要。下面是一个真实的拒付场景：

场景： 您的产品售价 US$ 100.00，客户使用美元信用卡支付，您的钱包结算货币为 BRL。

时间事件汇率金额
10:00您获取汇率并展示价格1 USD = 5.73 BRL页面显示"R$ 573.00"
10:45客户点击"确认支付"，您用 10:00 的旧汇率创建收费实际汇率已变为 5.50您提交 R$ 573.00
10:45发卡行按当前汇率将 R$ 573.00 换算回 USD发卡行使用 5.50持卡人账单显示 US$ 104.18
次日持卡人查看账单——"我只同意支付 US$ 100.00，为什么扣了 US$ 104.18？"
3 天后持卡人向发卡行发起争议——Mastercard 拒付码 4834："交易金额不符"

发生了什么： 您用 45 分钟前的旧汇率（5.73）计算了 BRL 金额。但持卡人的发卡行按当前汇率（5.50）将 BRL 换算回 USD，得到 US$ 104.18 而非 US$ 100.00。差额 US$ 4.18 导致了拒付。

正确做法： 在客户点击"确认支付"时（10:45）重新调用 FX 端点获取最新汇率 5.50，计算 R$ 550.00，提交 R$ 550.00。发卡行换算后约为 US$ 100.00，账单金额与展示金额一致，不会产生争议。

发卡行汇率加价——为什么账单金额仍可能略有差异

即使汇率完全实时，持卡人的发卡行也会在银行间汇率基础上加收自身的外汇加价（通常为 1%–3%）。这是 Visa 和 Mastercard 网络的行业惯例，在持卡人与银行的协议中已披露。以银行间汇率换算恰好为 US$ 100.00 的收费，在持卡人账单上可能显示为 US$ 101.00–103.00。这种小幅、可预期的差异很少引发争议。真正导致 Mastercard 4834 拒付的是使用过期汇率造成的大额差异，如上述场景所示。

关键规则

在创建收费前的最后一刻获取汇率。获取汇率和创建收费之间的时间间隔越短，持卡人账单金额与展示金额的差异越小。

为什么"确认时重新获取汇率"是最佳方案​

跨境支付中防止汇率相关拒付的策略有三种：

策略原理A55 是否支持
确认时重新获取汇率在创建收费前获取最新的银行间汇率，最大程度缩小汇率偏移支持——在最后一刻调用 FX 端点
DCC（动态货币转换）以持卡人的本国货币收费，发卡行无需再次换算不支持——需要 DCC 认证和多币种结算能力
锁定汇率将报价汇率锁定一段时间，保证有效期内不变不支持——FX 端点返回实时报价，不锁定汇率

确认时重新获取汇率能最大程度减少汇率偏移（拒付的最主要原因）。结合透明的信息披露和完整的审计记录，这是 Stripe、Adyen、Wise 等全球领先支付平台为单一结算货币商户推荐的行业标准方案。

拒付防范清单​

在每笔跨境收费中，请确认以下各项：

  • 在创建收费前立即调用 FX 端点获取最新汇率
  • 在支付确认页同时展示原始货币金额、汇率和转换后金额
  • 在支付确认页注明："最终账单金额可能因发卡行汇率略有差异"
  • 将汇率和原始金额写入收费的 description 字段
  • 确保 installment_value 与页面展示给客户的金额完全一致
  • 在您的数据库中记录：汇率值、获取时间、展示金额、收费金额
  • 对于零小数货币（CLP、COP），确保金额为整数

使用场景​

场景如何使用 FX 端点
跨境结账在客户确认支付前获取汇率，展示转换后的价格
动态定价定期刷新汇率，更新网站上的多币种产品价格
多币种仪表板将所有交易金额转换为 USD 或 EUR，用于合并报告
财务对账记录交易时汇率与结算时汇率，进行差异分析
订阅定价按客户所在地货币显示月费金额
发票生成在发票上注明汇率和两种货币的金额

重要说明​

FX 端点为报价端点，不锁定汇率

FX 端点返回当前银行间市场汇率，供展示和计算使用。它不会锁定汇率。实际收费使用的汇率取决于 acquirer 在处理交易时的汇率。acquirer 即收单机构，与商户签约并处理交易。为将差异降到最低，请在创建收费前立即获取最新报价。

资本管制货币（ARS）

阿根廷比索（ARS）存在资本管制。本端点返回的银行间汇率可能与阿根廷国内的官方汇率或平行市场汇率不同。涉及 ARS 的交易，请确认与客户沟通时使用的汇率口径一致。

建立汇率审计记录

在每笔跨境收费中记录以下信息：获取汇率的时间、使用的汇率值、展示给客户的金额、实际收费金额。将汇率写入收费的 description 字段（如 "订单 #12345（US$ 100.00，汇率 5.73）"），并在您的系统中保存完整记录。这些数据在对账和争议处理时不可或缺。

创建收费 →使用转换后的金额创建收费提供商能力 →查看每个国家可用的货币和支付方式状态生命周期 →从创建到结算跟踪收费状态