结论

调用 BlueSnap Payment API 时，请求头通常包含以下属性：

某些支付、风控、幂等或平台业务还需要额外的请求头。它们并非所有 Payment API 接口都适用，具体要求应以对应端点的官方文档为准。

各请求头的作用

Authorization

BlueSnap API 通常使用 HTTP Basic Authentication，格式如下：

Authorization: Basic <Base64(username:password)>

<Base64(username:password)> 是把 API 用户名和密码用冒号连接，再进行 Base64 编码后得到的值。

例如，原始凭据为：

api_user:api_password

对应的请求头为：

Authorization: Basic YXBpX3VzZXI6YXBpX3Bhc3N3b3Jk

Base64 只是编码，并不提供加密保护，因此请求必须通过 HTTPS 发送。用户名、密码和编码后的凭据都不应写入前端代码、公开仓库或应用日志。

Content-Type

请求包含 JSON 请求体时，应设置：

Content-Type: application/json

BlueSnap 会根据该属性解析请求体。如果请求体是 JSON，但 Content-Type 设置错误，服务端可能无法解析参数，并返回 400 Bad Request 或 415 Unsupported Media Type。

没有请求体的 GET 请求通常不需要该请求头，不过统一设置一般也不会造成问题。

Accept

REST JSON 接口通常使用：

Accept: application/json

该属性表示客户端希望收到 JSON 格式的响应。部分接口即使没有提供 Accept 也会默认返回 JSON，但明确声明可以避免内容协商出现歧义。

bluesnap-version

部分 BlueSnap API 请求需要通过该请求头指定 API 版本，例如：

bluesnap-version: 3.0

不要直接照搬示例中的版本值。不同接口、账户配置或不同时期的 BlueSnap 文档可能有不同要求，应使用目标端点文档中明确指定的版本。

cURL 示例

下面是一个典型的 JSON 请求头配置。URL、API 版本和请求体仅用于展示结构，实际使用时应按照目标端点的要求替换。

curl --request POST \
  'https://sandbox.bluesnap.com/services/2/transactions' \
  --user 'API_USERNAME:API_PASSWORD' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'bluesnap-version: 3.0' \
  --data '{
    "amount": 10.00,
    "currency": "USD"
  }'

--user 会自动生成 HTTP Basic Authentication 所需的 Authorization 请求头。

如需手动传递认证信息，可以使用：

curl --request POST \
  'https://sandbox.bluesnap.com/services/2/transactions' \
  --header 'Authorization: Basic BASE64_ENCODED_CREDENTIALS' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'bluesnap-version: 3.0' \
  --data '{
    "amount": 10.00,
    "currency": "USD"
  }'

JavaScript 服务端示例

支付接口应由服务端调用，避免在浏览器中暴露 BlueSnap API 凭据。

const credentials = Buffer.from(
  `${process.env.BLUESNAP_API_USERNAME}:${process.env.BLUESNAP_API_PASSWORD}`
).toString("base64");

const response = await fetch(
  "https://sandbox.bluesnap.com/services/2/transactions",
  {
    method: "POST",
    headers: {
      Authorization: `Basic ${credentials}`,
      Accept: "application/json",
      "Content-Type": "application/json",
      "bluesnap-version": "3.0"
    },
    body: JSON.stringify({
      amount: 10.0,
      currency: "USD"
    })
  }
);

const responseText = await response.text();

if (!response.ok) {
  throw new Error(`BlueSnap request failed: ${response.status} ${responseText}`);
}

const result = responseText ? JSON.parse(responseText) : null;

注意事项

• Sandbox 和 Production 通常使用不同的地址与凭据，不能混用。
• bluesnap-version 的具体值应以所调用端点的官方文档为准。
• 不要把 API 用户名、密码或完整的 Authorization 请求头写入日志。
• Content-Type 必须与实际请求体格式一致。
• 某些端点可能还会用到幂等、风控、商户代理或客户端 IP 等专用请求头。只有对应接口文档明确要求时才应添加。
• 不要自行伪造 X-Forwarded-For 等来源信息。如果业务需要传递客户端 IP，应从可信代理链中提取，并按照 BlueSnap 的接口要求处理。
• 收到 401 Unauthorized 时，先检查凭据、认证格式和运行环境是否匹配。收到 415 Unsupported Media Type 时，先检查 Content-Type。遇到版本相关错误时，则应检查 bluesnap-version。

备注：内容仅供参考。