结论

BlueSnap 的 Payment API 通常是用于创建支付、查询交易和退款等操作的核心支付接口。Extended Payment API 则多见于 BlueSnap 的旧版或特定账户体系，可能支持更完整的结账流程控制，以及更多订单字段和附加操作。

不能只根据名称把两者理解成”基础版”和”高级版”，也不能混用 endpoint、认证方式或请求参数。BlueSnap 曾调整过产品命名和文档结构，具体使用哪个 API，应根据以下信息判断：

• 商户后台提供的集成文档
• 当前账户已启用的产品和 API 权限
• 文档列出的 endpoint、认证方式和发布日期
• BlueSnap 技术支持对账户集成类型的确认

主要区别

两者的常见区别如下：

“Extended”不一定意味着它是 Payment API 的完全兼容超集。即使两套接口都可以完成收款，其认证信息、请求模型、交易状态和错误码也可能不同。

如何确认应该使用哪个 API

1. 检查现有 endpoint

先检查项目配置中的 BlueSnap 请求地址。类名和代码注释可能不准确，实际调用的 URL 才是判断依据。

例如：

curl --request POST \
  "${BLUESNAP_BASE_URL}/<payment-endpoint>" \
  --user "${BLUESNAP_USERNAME}:${BLUESNAP_PASSWORD}" \
  --header "Content-Type: application/json" \
  --data @request.json

<payment-endpoint>必须来自当前账户对应的官方文档，不要参照其他项目或社区示例自行拼接。

2. 核对认证方式和请求模型

确认当前集成采用哪种认证方式，并检查请求体包含的对象：

{
  "amount": 49.99,
  "currency": "USD",
  "cardTransactionType": "AUTH_CAPTURE",
  "paymentSource": {
    "...": "..."
  }
}

这段内容只用于展示请求结构，不是可以直接提交的完整 BlueSnap 请求。字段名称、必填项和支付来源对象，都应以相应 API 版本的 schema 为准。

如果 Extended Payment API 要求先创建结账上下文、购物者或订单，再执行付款，就不能直接使用 Payment API 的单次交易请求。

3. 查看账户后台的开发者入口

登录 BlueSnap Merchant Portal，在开发者、API 或集成相关页面中确认：

• 可用的 API 产品
• Sandbox 和 Production 地址
• API 凭据
• Webhook/IPN 配置
• 当前账户支持的支付方式
• 是否带有 legacy 或 deprecated 标记

如果后台只显示一种集成方式，另一种接口可能没有对该账户开放。

4. 向 BlueSnap 支持提供明确信息

如果仍然无法确定文档与账户的对应关系，联系 BlueSnap 技术支持时应一并提供：

• Merchant ID
• 当前使用的 endpoint
• 文档页面名称或链接
• Sandbox 或 Production 环境
• 准备实现的操作，例如支付、授权、捕获、退款或订阅
• 是否正在迁移旧系统

可以直接询问：

Is Extended Payment API enabled for this merchant account, and is it still the recommended integration for new development? Which API documentation and endpoint family should this account use?

与单纯询问两个名称有什么区别相比，这种问法更容易得到符合当前账户情况的答复。

集成时的注意事项

不要混用文档

Payment API 和 Extended Payment API 的示例可能属于不同年代或产品线。以下内容不能直接跨接口复制：

• endpoint
• 请求字段
• HTTP 方法
• 认证头
• 错误码
• Webhook/IPN 事件
• 交易状态
• Sandbox 凭据

关注 PCI DSS 范围

如果支付卡信息会经过商户自己的服务器，通常会扩大 PCI DSS 合规范围。应优先确认 BlueSnap 是否提供 Hosted Payment Fields、托管结账页或 tokenization 方案，避免敏感卡数据直接进入商户服务器。

先确认新项目推荐方案

新集成不能因为 Extended Payment API 的名称中含有”Extended”就默认选择它。如果该接口属于旧版体系，BlueSnap 可能只会继续为已有商户提供支持。新项目应优先使用 BlueSnap 当前官方文档明确推荐的 API 或 SDK。

迁移前建立字段映射

从 Extended Payment API 迁移到 Payment API 时，需要逐项核对：

旧请求字段 → 新请求字段
旧交易状态 → 新交易状态
旧错误码   → 新错误码
旧通知事件 → 新 Webhook/IPN 事件

授权、捕获、撤销、退款、重复请求和超时重试也要分别验证，不能只测试一次成功付款。

在哪里查阅信息

应优先查阅 BlueSnap 官方开发者文档，以及 Merchant Portal 中与账户绑定的集成说明，同时检查相关页面是否标记为 legacy、deprecated 或 archived。BlueSnap 的接口名称可能随产品迭代发生变化。如果公开文档与后台信息不一致，应以当前账户配置和 BlueSnap 技术支持的书面确认为准。

备注：内容仅供参考。