用户开通RA流程
在调用createTransfer进行资金代发之前，您需要构建一个重定向URL来帮用户开通万里汇RA收款账户。用户点击URL后跳转万里汇门户进行授权登录并授权开通RA收款账户。本文介绍了RA开户整体流程、构建URL的步骤和验证RA账户的方法。
整体流程
图一：用户开通RA流程
1. 用户首先在您的门户上发起账号绑定请求，要求绑定万里汇账户。
2. 通过构建重定向URL，引导用户跳转至万里汇门户。关于如何构建URL，详见步骤1：构建重定向URL。
3. 在万里汇门户，用户需要输入账号密码进行登录，并授权万里汇开通与平台和币种绑定的RA收款账户。用户同意授权后，万里汇处理授权请求并创建一个WF RA账户。
4. 在用户完成授权后，您可以使用以下两种方式来检查RA开户情况：
- 用户完成授权绑定后，WorldFirst会向您发送URL，并返回开户结果。关于URL结果码的含义，详见步骤2：验证RA开户结果。
- （可选步骤）您还可以通过调用inquiryAccount API自行验证用户RA账户的状态。
具体步骤
步骤1：构建重定向URL
为引导用户跳转至万里汇门户完成登录、授权开户等操作，您需要按照以下几个步骤构建一个重定向URL。
万里汇支持两种构建重定向URL的技术方案，其中方案一构建出的URL安全级别更高，因此为首推方案，建议首次接入的集成商采纳。对于已接入的集成商而言，原来的方案（即现在的方案二）依旧兼容，您可以继续使用原方案或使用方案一重新集成。
方案一（推荐）
1. 构建待签名字符串
a. 字符串结构
使用以下参数构建字符串。
注：
- 按照如下顺序组装字符串，顺序不可变动，否则可能会失效；
- 更换绑定万里汇RA账户时，必须修改requestId参数的取值，并保持其他参数取值不变。
clientId= |
字段名 | 数据类型 | 是否必传 | 描述 |
clientId | 字符串 | 是 | 由万里汇指定给集成商的唯一ID。 |
redirectUrl | 字符串 | 是 | 集成商用于接收RA开户结果的回传URL。 字符串最大值：512字符 |
referenceCustomerId | 字符串 | 是 | 由集成商指定给用户的唯一ID。 字符串最大值：64字符 |
storeUrl | 字符串 | 是 | 用户在集成商平台上的店铺URL地址。如： 字符串最大值：256字符 |
storeName | 字符串 | 是 | 用户在集成商平台上注册的商铺名称。 字符串最大值：256字符 |
currency | 字符串 | 是 | 由3个字母组成的ISO4217货币代码，代表RA账户的币种。比如美元为 注：
|
requestId | 字符串 | 有条件必传 | 集成商指定给每个跳转URL的唯一请求ID。 注：
|
b. 字符串编码
对上一步构建出的字符串进行编码，关于编码规则，详见章节：编码标准。
2. 使用RSA生成签名
使用上一步编码过的字符串以及SHA256withRSA混合加密算法来生成签名。
命令行示例：
generatedSignature=sha256withrsa(<clientId=clientId&redirectUrl=redirectUrl&referenceCustomerId=referenceCustomerId&storeUrl=storeUrl&storeName=storeName¤cy=currency&requestId=requestId>)生成签名示例:：
KrwDE9tAPJYB...*****3. 给URL加签和编码
URL结构
URL请求方式：GET
所含参数、域名以及参数排序如下。注意参数顺序不可变动，否则URL会失效：
https://{portal.worldfirst.com}.com/enterprise/auth? clientId= |
构建URL的步骤
- 根据构建的待签名字符串。在字符串末尾加上RSA签名，同时保持其他参数顺序不变。
- 在字符串开头添加万里汇域名：portal.worldfirst.com
- 对整个URL进行编码，关于编码规则，详见章节：编码标准。
URL示例如下：
https://{portal.worldfirst.com}.com/enterprise/auth?clientId=*****&redirectUrl=*****&referenceCustomerId=*****&storeUrl=*****&storeName=*****¤cy=USD&requestId=*****&signature=KrwDE9tAPJYB...*****方案二
1. 构建待签名字符串
a. 字符串结构
使用以下参数构建字符串。
注：
- 按照如下顺序组装字符串，顺序不可变动，否则可能会失效；
- 更换绑定万里汇RA账户时，必须修改requestId参数的取值，并保持其他参数取值不变。
partnerId= |
字段名 | 数据类型 | 是否必传 | 描述 |
partnerId | 字符串 | 是 | 由万里汇指定给集成商的唯一ID。 注：
|
extBizPartnerId | 字符串 | 是 | 由万里汇指定给集成商的唯一ID。 注：
|
redirectUrl | 字符串 | 是 | 集成商用于接收RA开户结果的回传URL。 字符串最大值：512字符 |
referenceCustomerId | 字符串 | 是 | 由集成商指定给用户的唯一ID。 字符串最大值：64字符 |
storeUrl | 字符串 | 是 | 用户在集成商平台上的店铺URL地址。如： 字符串最大值：256字符 |
storeName | 字符串 | 是 | 用户在集成商平台上注册的商铺名称。 字符串最大值：256字符 |
currency | 字符串 | 是 | 由3个字母组成的ISO4217货币代码，代表RA账户的币种。比如美元为 注：
|
requestId | 字符串 | 有条件必传 | 集成商指定给每个跳转URL的唯一请求ID。 注：
|
key | 字符串 | 是 | 集成商密钥。 注：
|
b. 字符串编码
对上一步构建出的字符串进行编码，关于编码规则，详见章节：编码标准。
2. 使用MD5生成签名
使用上一步编码过的字符串以及MD5加密算法来生成签名。
Linux命令行或任意一种编程语言都可以用来计算MD5签名。
关于代码实例和使用方法，参考章节：工具。
生成签名例如： f4bfcde6a3e9edab347ae849e54*****.
3. 给URL加签和编码
URL结构
URL请求方式：GET
所含参数、域名以及参数排序如下。注意参数顺序不可变动，否则URL会失效：
https://{portal.worldfirst.com}.com/enterprise/auth?partnerId= |
构建URL的步骤
- 根据构建的待签名字符串。将key替换为MD5算法生成的signature，同时保持其他参数顺序不变。
- 在字符串开头添加万里汇域名：portal.worldfirst.com
- 对整个URL进行编码，关于编码规则，详见章节：编码标准。
URL示例如下：
https://{portal.worldfirst.com}.com/enterprise/auth?partnerId=*****&extBizPartnerId=*****&redirectUrl=*****&referenceCustomerId=*****&storeUrl=*****&storeName=*****¤cy=USD&requestId=*****&signature=f4bfcde6a3e9edab347ae849e54*****步骤2：验证RA开户结果
用户授权万里汇开通RA账户后，有两种方式来验证授权是否成功：
- 万里汇通过URL向您返回授权结果；
- （可选步骤）您也可以自行调用inquiryAccount接口来验证RA的状态。
接收万里汇返回的授权结果
URL结构
当用户在万里汇门户授权开通RA账户之后，您会收到万里汇向您发送的重定向URL，其中包括如下参数：
https://{domain_name}.com?partnerId= |
字段说明：
字段名 | 数据类型 | 是否必传 | 描述 |
partnerId | 字符串 | 是 | 由万里汇指定给集成商的唯一ID。 更多信息：
|
referenceCustomerId | 字符串 | 否 | 由集成商指定给用户的唯一ID。 更多信息：
|
resultMsg | 字符串 | 是 | 结果码，代表OAuth授权结果。 注：
更多信息：
|
返回URL示例：
https://{domain_name}.com?partnerId=*****&referenceCustomerId=*****&resultMsg=SUCCESSresultMsg
| 结果状态 | 描述 | 处理建议 |
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账户不存在。