用户开通RA流程

在调用 createTransfer 接口进行资金代发之前,您需要构建一个重定向URL来帮用户开通万里汇RA收款账户。用户点击URL后跳转万里汇门户进行授权登录并授权开通RA收款账户。本文介绍了RA开户整体流程、构建URL的步骤和验证RA账户的方法。

整体流程

image.png

图1. 用户开通RA流程

1. 用户首先在您的门户上发起账号绑定请求,要求绑定万里汇账户。

2. 通过构建重定向URL,引导用户跳转至万里汇门户。关于如何构建URL,详见步骤一:构建重定向URL

3. 在万里汇门户,用户需要输入账号密码进行登录,并授权万里汇开通与平台和币种绑定的RA收款账户。用户同意授权后,万里汇处理授权请求并创建一个WF RA账户。

4. 在用户完成授权后,您可以使用以下两种方式来检查RA开户情况:

- 用户完成授权绑定后,WorldFirst会向您发送URL,并返回开户结果。关于URL结果码的含义,详见步骤二:验证RA开户结果

- (可选步骤)您还可以通过调用 inquiryAccount 接口自行验证用户RA账户的状态。

具体步骤

步骤一:构建重定向URL

为引导用户跳转至万里汇门户完成登录、授权开户等操作,您需要按照以下几个步骤构建一个重定向URL。

万里汇支持两种构建重定向URL的技术方案,其中方案一构建出的URL安全级别更高,因此为首推方案,建议首次接入的集成商采纳。对于已接入的集成商而言,原来的方案(即现在的方案二)依旧兼容,您可以继续使用原方案或使用方案一重新集成。

方案一(推荐)

1. 构建待签名字符串

a. 字符串结构

使用以下参数构建字符串。

  • 按照如下顺序组装字符串,顺序不可变动,否则可能会失效;
  • 更换绑定万里汇RA账户时,必须修改 requestId 参数的取值,并保持其他参数取值不变。

clientId=clientId&redirectUrl=redirectUrl&referenceCustomerId=referenceCustomerId&storeUrl=storeUrl&storeName=storeName&currency=currency&requestId=requestId

字段名

数据类型

是否必传

描述

clientId

字符串

由万里汇指定给集成商的唯一ID。

redirectUrl

字符串

集成商用于接收RA开户结果的回传URL。

字符串最大值:512字符

referenceCustomerId

字符串

由集成商指定给用户的唯一ID。

字符串最大值:64字符

storeUrl

字符串

用户在集成商平台上的店铺URL地址。如:https://{domain_name}.com/seller/1/

字符串最大值:256字符

storeName

字符串

用户在集成商平台上注册的商铺名称。

字符串最大值:256字符

currency

字符串

由3个字母组成的 ISO4217 货币代码,代表RA账户的币种。比如美元为USD

注:

  • 当RA账户涉及多币种时,需用","将每个货币代码分隔开;
  • 在换绑万里汇RA账户时,必须传入所有原RA账户适用的币种。
  • 字符串最大值:256字符

requestId

字符串

有条件必传

集成商指定给每个跳转URL的唯一请求ID。

注:

  • 该请求ID仅在更换绑定RA账户时为必传
  • 该请求ID不能重复使用。
b. 字符串编码

对上一步构建出的字符串进行编码,关于编码规则,详见章节:编码标准

2. 使用RSA生成签名

使用上一步编码过的字符串以及 SHA256withRSA 混合加密算法来生成签名。

命令行示例:

copy
generatedSignature=sha256withrsa(<clientId=clientId&redirectUrl=redirectUrl&referenceCustomerId=referenceCustomerId&storeUrl=storeUrl&storeName=storeName&currency=currency&requestId=requestId>)

生成签名示例::

copy
KrwDE9tAPJYB...*****

3. 给URL加签和编码

URL结构

URL请求方式:GET

所含参数、域名以及参数排序如下。注意参数顺序不可变动,否则URL会失效:

https://{portal.worldfirst.com}.com/enterprise/auth?

clientId=clientId&redirectUrl=redirectUrl&referenceCustomerId=referenceCustomerId&storeUrl=storeUrl&storeName=storeName&currency=currency&requestId=requestId&signature=signature

构建URL的步骤
  1. 根据构建的待签名字符串在字符串末尾加上RSA签名,同时保持其他参数顺序不变。
  2. 在字符串开头添加万里汇域名:portal.worldfirst.com
  3. 对整个URL进行编码,关于编码规则,详见章节:编码标准

URL示例如下:

copy
https://{portal.worldfirst.com}.com/enterprise/auth?clientId=*****&redirectUrl=*****&referenceCustomerId=*****&storeUrl=*****&storeName=*****&currency=USD&requestId=*****&signature=KrwDE9tAPJYB...*****

方案二

1. 构建待签名字符串

a. 字符串结构

使用以下参数构建字符串。

  • 按照如下顺序组装字符串,顺序不可变动,否则可能会失效;
  • 更换绑定万里汇RA账户时,必须修改 requestId 参数的取值,并保持其他参数取值不变。

partnerId=partnerId&extBizPartnerId=extBizPartnerId&redirectUrl=redirectUrl&referenceCustomerId=referenceCustomerId&storeUrl=storeUrl&storeName=storeName&currency=currency&requestId=requestId&key=key

字段名

数据类型

是否必传

描述

partnerId

字符串

由万里汇指定给集成商的唯一ID。

注:

  • 该字段取值与extBizPartnerId 一致。
  • 字符串最大值:64字符

extBizPartnerId

字符串

由万里汇指定给集成商的唯一ID。

注:

  • 该字段取值与partnerId 一致。
  • 字符串最大值:64字符

redirectUrl

字符串

集成商用于接收RA开户结果的回传URL。

字符串最大值:512字符

referenceCustomerId

字符串

由集成商指定给用户的唯一ID。

字符串最大值:64字符

storeUrl

字符串

用户在集成商平台上的店铺URL地址。如:https://{domain_name}.com/seller/1/

字符串最大值:256字符

storeName

字符串

用户在集成商平台上注册的商铺名称。

字符串最大值:256字符

currency

字符串

由3个字母组成的 ISO4217 货币代码,代表RA账户的币种。比如美元为USD

注:

  • 当RA账户涉及多币种时,需用","将每个货币代码分隔开;
  • 在换绑万里汇RA账户时,必须传入所有原RA账户适用的币种。
  • 字符串最大值:256字符

requestId

字符串

有条件必传

集成商指定给每个跳转URL的唯一请求ID。

注:

  • 该请求ID仅在更换绑定RA账户时为必传
  • 该请求ID不能重复使用。

key

字符串

集成商密钥。

注:

  • 确保在进行下一步之前和万里汇技术支持交换此密钥。
b. 字符串编码

对上一步构建出的字符串进行编码,关于编码规则,详见章节:编码标准

2. 使用MD5生成签名

使用上一步编码过的字符串以及MD5加密算法来生成签名。

Linux命令行或任意一种编程语言都可以用来计算MD5签名。

关于代码实例和使用方法,参考章节:工具

生成签名例如: f4bfcde6a3e9edab347ae849e54*****.

3. 给URL加签和编码

URL结构

URL请求方式:GET

所含参数、域名以及参数排序如下。注意参数顺序不可变动,否则URL会失效:

https://{portal.worldfirst.com}.com/enterprise/auth?partnerId=partnerId&extBizPartnerId=extBizPartnerId&redirectUrl=redirectUrl&referenceCustomerId=referenceCustomerId&storeUrl=storeUrl&storeName=storeName&currency=currency&requestId=requestId&signature=signature

构建URL的步骤
  1. 根据构建的待签名字符串。将 key 替换为MD5算法生成的signature,同时保持其他参数顺序不变。
  2. 在字符串开头添加万里汇域名:portal.worldfirst.com
  3. 对整个URL进行编码,关于编码规则,详见章节:编码标准

URL示例如下:

copy
https://{portal.worldfirst.com}.com/enterprise/auth?partnerId=*****&extBizPartnerId=*****&redirectUrl=*****&referenceCustomerId=*****&storeUrl=*****&storeName=*****&currency=USD&requestId=*****&signature=f4bfcde6a3e9edab347ae849e54*****

步骤二:验证RA开户结果

用户授权万里汇开通RA账户后,有两种方式来验证授权是否成功:

  • 万里汇通过URL向您返回授权结果;
  • (可选步骤)您也可以自行调用 inquiryAccount 接口来验证RA的状态。

接收万里汇返回的授权结果

URL结构

当用户在万里汇门户授权开通RA账户之后,您会收到万里汇向您发送的重定向URL,其中包括如下参数:

https://{domain_name}.com?partnerId=partnerId&referenceCustomerId=referenceCustomerId&resultMsg=resultMsg

字段说明:

字段名

数据类型

是否必传

描述

partnerId

字符串

由万里汇指定给集成商的唯一ID。

更多信息:

  • 字符串最大值:64字符

referenceCustomerId

字符串

由集成商指定给用户的唯一ID。

更多信息:

  • 字符串最大值:64字符

resultMsg

字符串

结果码,代表OAuth授权结果。

注:

  • 只有当结果码为SUCCESS时,代表OAuth验证成功。
  • 关于OAuth失败时返回的结果码,详见表格:resultMsg

更多信息:

  • 字符串最大值:512字符

返回URL示例:

copy
https://{domain_name}.com?partnerId=*****&referenceCustomerId=*****&resultMsg=SUCCESS

resultMsg

resultMsg

结果状态

描述

处理建议

SUCCESS

S

Success

RA账户开通成功。

PARAM_ILLEGAL

F

Illegal parameter

因传入非法参数导致RA开户失败,确认字段正确后重试。

CURRENCY_ALREADY_EXISTS

F

Currency already exists

因重复传入相同的币种导致RA开户失败,确认币种正确后重试。

CURRENCY_OUT_OF_SUPPORTED_RANGE

F

Currency is not supported

因传入不支持的币种导致RA开户失败,确认币种正确后重试。

SYSTEM_BUSY

U

System is busy

重试,若问题依旧,联系技术支持。

SIGNATURE_VERIFICATION_FAILED

F

Invalid signature

因URL签名无法验证导致RA开户失败,确认签名正确后重试。

REQUEST_ID_IDEMPOTENT

F

Repeated requestId

因传入重复的requestId导致RA换绑失败,更换requestId后重试

REFERENCE_CUSTOMER_ID_OPENED_RA

F

User already has an RA

referenceCustomerId指定的用户已开通万里汇RA账户,更换用户ID后重试

(可选)调用inquiryAccount API

建议调用inquiryAccount API确保用户的RA账户已激活,具体步骤详见章节:账户管理

当API调用失败时

若响应体的 resultCode 取值为PARAM_ILLEGAL,建议检查传入的referenCustomerId 是否正确。

当API调用成功时

  • 万里汇向您返回已成功开通的RA账户信息(RA账户可以是一个,也可以是多个,取决于指定的币种数量),代表RA开户成功。
  • 万里汇向您返回的响应体为空,代表RA账户不存在。

@2024 WorldFirst