Whalet Open API 接入指南

1. 介绍

1.1 概述

本文档旨在帮助合作伙伴快速接入易鲸的收款、收单、VCC、Payout等开放能力。

1.2 对接流程

1.3 对接参数

📌

在启动对接前，whalet跟合作伙伴需要交换的技术参数信息

参数	提供方	说明	示例值
partnerId	whalet	合作方ID	202506241658268
clientId	whalet	应用ID	budrOyt8X0qTCeyaDPMd2t5EI2DOUIii
secretKey	whalet	应用密钥	saBHKCCpWQXqEWRRFtSLmzStlVeXKBiE4p...
hmacKey	whalet	签名key	budrOyt8X0qTCeyaDPMd2t5EI2DOUIii
webhookUrl	合伙伙伴	通知地址	https://exaxple.com/webhook

1.4 技术支持

有关本接口对接、调试任何问题，可以在工作时间按以下方式联络相关技术支持人员。
product@whalet.com

2. 公共报文

2.1 接入方式

接口遵循REST规范，通过Outh2.0授权，使用HTTPS通信协议，通过POST方式提交。

环境	地址
测试环境	https://test-open.whalet.com
生产环境	https://open.whalet.com

2.2 注意事项

所有API请求必须使用HTTPS协议

建议使用TLS 1.2或更高版本

所有字符编码，请统一使用UTF-8

2.3 状态码说明

成功状态码

状态码	说明	使用场景
`SUCCESS`	操作成功	正常业务操作完成
`PROCESSING`	处理中	处理中

错误状态码

状态码	说明	解决方案
`FAILURE`	失败	查看错误原因
`TOO_MANY_REQUESTS`	请求频率过高	降低请求频率
`PARTNER_NOT_EXIST`	合作方不存在	检查请求头partnerId
`INTERNAL_ERROR`	内部错误	联系技术支持
`PARAMETER_ERROR`	参数错误	查看具体错误信息
`IDEMPOTENT_ERROR`	幂等错误	联系技术支持
`REQUEST_NO_NOT_UNIQUE`	请求号重复	检查请求号
`UNAUTHORIZED`	未授权	接口未授权,联系Whalet开通业务接口权限
`UNAUTHENTICATED_ERROR`	认证(签名)错误	检查签名
`INTERFACE_UNAUTHORIZED`	接口未授权	接口未授权,联系Whalet开通业务接口权限

3. 认证授权

3.1 获取访问令牌

接口信息

接口地址: POST /v1/auth/token

接口描述: 通过客户端ID和密钥获取访问令牌

认证要求: 无需认证

请求参数

参数类型	参数名	必填	类型	说明	示例值
Header	partnerId	是	string	合作方ID	202506241658268
Header	requestNo	是	string	请求流水号	REQ202312010001
Header	timestamp	是	long	时间戳（毫秒）	1753682997568
Body	clientId	是	string	客户端ID	budrOyt8X0qTCeyaDPMd2t5EI2DOUIii
Body	secretKey	是	string	密钥	saBHKCCpWQXqEWRRFtSLmzStlVeXK...

请求示例

响应参数

参数名	类型	说明	示例值
code	string	响应状态码	SUCCESS
message	string	响应消息	success
data.token	string	访问令牌	eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
data.expire	number	过期时间(秒）	3600
data.tokenType	string	令牌类型	Bearer

成功响应示例

{
    "message": "success",
    "code": "SUCCESS",
    "data": {
        "token": "S5laCM1hbNZxcWqp7l8xBTtDKopQtE7wfRy4fxyzyQIHbvJJ76bW6UkJvVAmakZS",
        "expire": 3600,
        "tokenType": "Bearer"
    }
}

3.2 Token 失效与刷新机制

token 有效期（单位：秒）由 expire 字段指定（单位：秒），如 3600 表示 1 小时。

建议调用方本地缓存token，如果 token有效期小于5分钟（300秒），重新获取新的新的token，原token将失效。

4.业务接口

3.1 概述

请确保您已经完成授权（获取token），所有的业务接口都需要授权。

3.2 请求格式

请求头 (HTTP Headers)

所有API请求都需要在请求头中携带以下信息：

参数名	必填	类型	说明	示例值
`partnerId`	是	string	合作方ID，用于标识请求来源	partner_001
`requestNo`	是	string	请求流水号，建议使用唯一标识便于问题排查	REQ202312010001
`Authorization`	是	string	访问令牌，从 `/v1/auth/token` 接口获取	Bearer eyJhbGciO...
`timestamp`	是	long	请求时间戳（毫秒）	1753682997568
`Content-Type`	是	string	内容类型，固定为 `application/json`	application/json

注意: Authorization 在所有接口中都需要传递

请求头示例

{
  "partnerId": "partner_001",
  "requestNo": "REQ202312010001",
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "timestamp": "1753682997568",
  "Content-Type": "application/json"
}

curl示例

请求体 (HTTP Body)

请求体使用JSON格式，具体参数根据各接口文档定义。

{
  "param1": "value1",
  "param2": "value2",
  "param3": {
    "nestedParam": "nestedValue"
  }
}

3.3 响应格式

响应头 (HTTP Headers)

服务器响应时会返回以下头信息：

参数名	类型	说明	示例值
`Content-Type`	string	固定为 `application/json`	`application/json`

响应头示例

{
  "Content-Type": application/json
}

响应体 (HTTP Body)

所有API响应都遵循统一的JSON格式：

{
  "code": "SUCCESS",
  "message": "响应描述",
  "data": "接口文档数据定义"
}

响应字段说明

字段名	类型	必填	说明	示例值
`code`	string	是	响应状态码	`SUCCESS`
`message`	string	是	响应描述信息	操作成功
`data`	object/array/null	是	响应数据，具体结构见各接口文档	`{}`

成功响应示例

{
  "code": "SUCCESS",
  "message": "success",
  "data": {
    "id": "12345",
    "name": "示例数据",
    "status": "active"
  }
}

错误响应示例

{
    "message": "clientId length must be 32",
    "code": "PARAMETER_ERROR",
    "data": null
}

4.通知(webhook)

webhook用于向合作伙伴推送通知，例如入账通知或者各类业务结果通知。

4.1 通知方式

重试机制: 最多5次间隔时间依次为1s、2s、4s、8s、16s

响应要求: 30秒内返回结果，如果5次仍然无法成功，将线下通知合作伙伴

通知成功判定、以响应的httpStatus = 200 作为判断依据

4.2 请求信息

请求方法： POST

请求地址： 由合作伙伴提供

通知 Header

参数名	必填	类型	说明
Content-Type	是	string	application/json
signature	是	string	签名，见下方签名规则

通知 Body 参数

字段名	类型	必填	说明
type	string	是	业务类型(详见各个通知type定义)
data	object	是	业务数据体(详见各个通知接口的请求参数定义)
requestNo	string	是	请求流水号
version	string	是	接口版本号
timestamp	long	是	时间戳（毫秒）

curl示例

4.3 验签

验签规则

验签内容： 请求体的原始 JSON 字符串（即 HTTP payload，不要做任何格式化或空格处理）

验签算法： HMAC-SHA256

验签密钥： 由whalet提供给合作伙伴

验签过程：

使用签名密钥对请求体（payload）进行运算，得到签名结果

将签名结果进行 Base64 编码，得到最终签名字符串

将最终签名字符串和通知HTTPHeader的signature字段进行equal比较

示例代码

java

php

python

5. 文件上传

5.1 上传接口

接口信息

接口地址: POST /v1/upload

接口描述: 文件（证件/附件/证明等）上传

认证要求: 需要认证

请求参数

参数类型	参数名	必填	类型	说明	示例值
Header	partnerId	是	string	合作方ID	202506241658268
Header	requestNo	是	string	请求流水号	REQ202312010001
Header	timestamp	是	long	时间戳（毫秒）	1740995200123
Header	Content-Type	是	string	固定请求头	multipart/form-data
Header	Authorization	是	string	请求令牌	Bearer eyJhbGciOiU...
Body	file	是	file	文件	上传文件

请求示例

5.2 支持格式

图片: jpeg, jpg, png, gif, bmp

文档: pdf, doc, docx, xls, xlsx, csv, txt

压缩: zip, rar

5.3 大小限制

10MB以内

5.4 Body 响应参数

响应参数

参数名	类型	说明	示例值
code	string	响应状态码	SUCCESS
message	string	响应消息	success
data.fileId	string	文件id	202507301610248867670001
data.fileName	string	文件名称	图片1.jpg
data.fileUrl	string	文件url	https://test-file.whalet.com/2025-07-30/demo.jpg

成功响应示例

{
    "message": "success",
    "code": "SUCCESS",
    "data": {
        "fileId": "202507301610248867670001",
        "fileName": "demo.png",
        "fileUrl": "https://test-file.whalet.com/2025-07-30/demo.jpg"
    }
}

6. 主要接口分类

用户入网

用户入网申请，用户入网-补充资料。

收款

开通VA并收款。

收单

国际信用卡收单+本地支付。

VCC

Virtual Credit Card.

出金

Fund payout.

钱包

Wallet and Balance.

接入指南

Whalet Open API 接入指南#

1. 介绍#

1.1 概述#

1.2 对接流程#

1.3 对接参数#

1.4 技术支持#

2. 公共报文#

2.1 接入方式#

2.2 注意事项#

2.3 状态码说明#

成功状态码#

错误状态码#

3. 认证授权#

3.1 获取访问令牌#

3.2 Token 失效与刷新机制#

4.业务接口#

3.1 概述#

3.2 请求格式#

请求头 (HTTP Headers)#

请求体 (HTTP Body)#

3.3 响应格式#

响应头 (HTTP Headers)#

响应体 (HTTP Body)#

4.通知(webhook)#

4.1 通知方式#

4.2 请求信息#

通知 Header#

通知 Body 参数#

4.3 验签#

验签规则#

示例代码#

5. 文件上传#

5.1 上传接口#

5.2 支持格式#

5.3 大小限制#

5.4 Body 响应参数#

6. 主要接口分类#

Whalet Open API 接入指南

1. 介绍

1.1 概述

1.2 对接流程

1.3 对接参数

1.4 技术支持

2. 公共报文

2.1 接入方式

2.2 注意事项

2.3 状态码说明

成功状态码

错误状态码

3. 认证授权

3.1 获取访问令牌

3.2 Token 失效与刷新机制

4.业务接口

3.1 概述

3.2 请求格式

请求头 (HTTP Headers)

请求体 (HTTP Body)

3.3 响应格式

响应头 (HTTP Headers)

响应体 (HTTP Body)

4.通知(webhook)

4.1 通知方式

4.2 请求信息

通知 Header

通知 Body 参数

4.3 验签

验签规则

示例代码

5. 文件上传

5.1 上传接口

5.2 支持格式

5.3 大小限制

5.4 Body 响应参数

6. 主要接口分类