接入指引

一、接入模式

平台支持商户模式、机构模式两种模式接入，可根据主体资质与业务需求选择。

1. 商户模式

适用对象：面向跨境电商卖家、海外广告主等跨境经营类商户。
核心开放能力：虚拟信用卡。

2. 机构模式

适用对象：面向持牌支付机构，助力其为旗下商户一站式提供 VA 账户开立、跨境收款、转账、付款等全流程跨境支付服务。
核心开放能力：商户准入入网、收款账户开通、收款、转账、付款等能力。

二、接入准备工作

1. 账号准备
注册商户平台/机构平台，若已有账号，可直接登录商户平台/机构平台。
2. 开发者配置
进入“开发者管理”模块，提交回调地址（用于接收异步回调通知的接口地址）、客户端Public Key，审核通过后系统会邮件发送：client_id、client_secret、服务端 RSA 公钥信息。
3. 密钥生成与录入
客户端需要自己生成适配 SHA256withRSA 算法的 RSA 公私钥，客户端公钥需录入平台（录入时删除 -----BEGIN PUBLIC KEY----- 开头和 -----END PUBLIC KEY----- 结尾，仅保留中间纯文本内容），否则服务端验签不能通过。
4. 接口调用说明
1）client_id，client_secret用于获取访问令牌。
2）服务端 RSA 公钥用于异步通知回调客户端，客户端采用 SHA256withRSA 算法进行验签。
3）客户端调用业务接口需要携带令牌，并对报文使用客户端私钥签名。

三、API 地址

测试：https://test-api.moneycomeon.com/
生产：https://api.falpay.com/

四、获取访问令牌（access_token）

1. 接口用途

获取调用业务接口的身份认证令牌，令牌有效期内可复用，过期需重新获取。

2. 调用说明

1）请求需携带我方分配的 client_id（客户端标识）、client_secret（客户端密钥）。
2）从接口返回结果中提取 access_token，作为后续业务接口的调用凭证。
3）具体接口文档请参考【认证-获取令牌】。

五、调用业务接口

调用我方各类业务接口完成具体业务操作，所有业务接口均遵循此调用规则。

1. 请求头必传参数

（4个核心参数，格式/规则严格遵循）

请求头名称	取值规则
Authorization	固定格式：`Bearer {{access_token}}`（`{{access_token}}`替换为实际获取的令牌，`Bearer`后必须加英文空格）
X-Signature	用客户端私钥，对完整的请求Body字符串原文做SHA256withRSA签名，签名结果经Base64编码后的值
X-Timestamp	当前系统毫秒级时间戳（13位纯数字），用于校验请求时效性
X-Nonce	32位唯一随机串，每次请求必须不同（推荐UUID去除`-`生成），用于防重放攻击

2. 请求体核心要求

请求Body必须为完整字符串（如JSON字符串），签名时需使用未做任何修改、与实际发送完全一致的Body字符串原文，包括字段顺序、空格、转义符等，否则会导致签名校验失败。

3. 调用顺序

先构造并确定请求Body字符串 → 生成X-Signature签名 → 携带请求头与Body发起请求。

4. 业务接口

具体接口文档请参考业务接口文档

5. 签名工具类

六、错误码

错误码	错误描述
PN000001	无接口访问权限
PN000002	缺少签名参数
PN000003	签名验证失败
PN000004	缺少防重参数
PN000005	防重校验失败
PN000006	IP 白名单校验失败
PN000007	读取请求体异常
PN000008	Token 无效 / 缺失
PN000009	RSA 秘钥生成失败
PN001001	客户端 ID 为空
PN001002	客户端不存在
PN001003	客户端已禁用
PN001004	客户端已过期
PN001005	客户端数据库查询异常
PN001006	客户端信息为空
PN001007	客户端密钥错误
PN001008	仅支持 client_credentials 授权类型
PN001009	client_id 和 client_secret 不能为空
PN003001	不支持的接口名
PN003002	业务服务不可用
PN003003	业务请求数据为空
PN003006	代理商或租户信息不存在
PN003007	获取代理商或商户信息失败
PN003009	业务接口返回空数据
PN003010	API 调用参数格式错误
PN004001	客户端必须审核通过后方可操作
PN004002	客户端必须提交资料后方可操作
PN004003	客户端资料已经提交过
PN999999	系统异常

一、接入模式#

1. 商户模式#

2. 机构模式#

二、接入准备工作#

三、API 地址#

四、获取访问令牌（access_token）#

1. 接口用途#

2. 调用说明#

五、调用业务接口#

1. 请求头必传参数#

2. 请求体核心要求#

3. 调用顺序#

4. 业务接口#

5. 签名工具类#

六、错误码#