接入准备

所有支付相关 API 均需在请求中携带身份与签名信息，确保请求来自合法商户且未被篡改。

认证方式

采用 API Key + 商户 ID + 签名 方式：

• 请求头中携带 x-api-key：你的应用 API Key
• 请求头中携带 x-merchant-id：商户 ID
• 请求头中携带 x-signature：对请求体的签名（格式：sha256=<hex>）
• 请求头中携带 x-timestamp：Unix 秒级时间戳（单位：秒）；需在 5 分钟内有效，超出将被拒绝

签名流程概述

1. 取当前时间戳：取当前 Unix 秒级时间戳，作为 x-timestamp 请求头（单位：秒）。
2. 拼接待签名字符串：timestamp + "." + 请求体原文（Body 保持原始 JSON 字符串，不要重新格式化）。
3. 计算 HMAC-SHA256：以你的 appSecret 为密钥，对上述字符串做 HMAC-SHA256，结果转为十六进制小写。
4. 设置签名头：将签名以 sha256= 为前缀填入 x-signature（例如：sha256=a1b2c3...）。
5. 时间有效性：服务端会校验 x-timestamp 在 5 分钟 内有效，超出则拒绝。
6. 验签：服务端使用相同规则重新计算签名，并与请求头中的签名做时间安全的比较。

签名算法

签名内容

拼接规则：timestamp + "." + body

• timestamp：与请求头 x-timestamp 一致，为 秒级 Unix 时间戳
• body：请求体原始 JSON 字符串（不要重新格式化或增减空格）

签名计算

1. 对待签名字符串 timestamp + "." + body 使用 HMAC-SHA256（密钥为 appSecret），得到二进制摘要。
2. 将摘要转为 十六进制小写 字符串。
3. 在签名字符串前加前缀 sha256=，作为请求头 x-signature 的值。

示例（Node.js / TypeScript）

import * as crypto from 'crypto'

// const timestampS = Math.floor(Date.now() / 1000)
function generateSignature(timestamp: number, payload: string, secretKey: string) {
  const signData = `${timestamp}.${payload}`  // 签名字符串：timestamp.payload
  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(signData, 'utf8')
    .digest('hex')
  return `sha256=${signature}`
}


const timestampS = 1771912638
// 使用：请求体原文 + appSecret；请求时还需携带 x-api-key、x-merchant-id
const body = {"amount":100,"currency":"PHP"}
const str = JSON.stringify(body)
const secret = 'sk_live_xupsyzX1RxwUTQU2fjsZXUnOZboLciZfoSppBoiwkcA'
const signature = generateSignature(timestampS, body, secret)
console.log(signature)
// sha256=8535a7d16b35eb1d22822f0a6fc9432509ec07276b7b0dda5f0326e063c34c07

请求头规范

请求头	必填	说明
Content-Type	是	application/json
x-api-key	是	应用 API Key
x-merchant-id	是	商户 ID
x-timestamp	是	当前 Unix 秒级时间戳（单位：秒），需在 5 分钟内有效
x-signature	是	按上述算法得到的签名

加密货币场景

针对加密货币收款场景，接口请求头规范与其他支付相关接口保持一致，仍需按上述要求携带 x-api-key、x-merchant-id、x-timestamp 与 x-signature。

当前仅支持 USDT 和 USDC 代币。

加密货币收款流程如下：

1. 需要额外向 Velora 申请加密货币收款的资质信息，并开通加密货币收款权限
2. 需要在管理后台 API Key 板块配置接收回调的推送地址
3. 调用 获取钱包地址 获取商户用户专属的钱包地址
4. 用户向指定的钱包地址发起转账
5. 接收 Velora 的加密货币收款回调
6. 商户完成自身业务处理

环境说明

• 正式环境：https://api.veloraglobal.com
• 沙箱环境：https://api-dev.veloraglobal.com（仅用于联调，不产生真实资金）

建议先使用沙箱完成对接，再切换正式环境。

下一步

• 应答码说明：接口应答码说明
• 创建交易：发起支付