Complete customer onboarding process

2022-04-29 12:00

Before utilizing WorldFirst services, the Customer needs to bind his or her account on the Partner's platform to WorldFirst.

After completing the customer onboarding process, a unique Receiving Account is assigned to the Customer for initializing and receiving monetary transfers.

Workflow

Screen Shot 2022-04-18 at 5.53.36 PM.png

Figure 1. Customer onboarding process

Procedure

To complete the Customer onboarding process, a Customer needs to bind his or her account to WorldFirst.

On the Partner's website, the Customer initiates an account binding request.
The Partner processes the request and redirects the Customer to a WorldFirst webpage.

Note: To generate the URL to the webpage, refer to the Redirection URLs: Partner > WorldFirst section.

On the WorldFirst webpage,

The Customer needs to either register a new WorldFirst login or use an existing one to proceed.
The Customer authorizes WorldFirst.
WorldFirst processes the account binding request and creates a unique Receiving Account for the Customer.

WorldFirst redirects the Customer back to the Partner's website.

Note: For more details about the redirection URL in this step and learn how to handle the URL, refer to the Redirection URLs: WorldFirst > Partner section.

The Partner needs to call the inquiryRaDetail API to validate the Customer's Receiving Account.
WorldFirst returns the Partner with relevant information such as:

Status of the Receiving Account(active or inactive).
Wallet account number.
Currency that the Receiving Account is currently using, etc.

Redirection URLs

This section introduces the necessary steps to generate redirection URLs.

Partner > WorldFirst

Method: Get

Generate a signature

You need to generate a signature before signing a URL.

Generate a signature with the MD5 algorithm using the MD5 Utility.

Construct the content with the following rules:

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

Where,

Field	Date type	Required	Description
partnerId	String	Yes	The unique ID that is assigned by WorldFirst to identify an onboard Partner. For example, `2333444455557777` More information: Maximum length: 64 characters
extBizPartnerId	String	Yes	The unique ID that is assigned by WorldFirst to identify an external Partner that is not onboard with WorldFirst. For example, `2333000011112222`. More information: Maximum length: 64 characters
redirectUrl	String	Yes	Callback URL. For example, `https://www.xxx.com/app/complete-payment-binding`. Note: Partner needs to encode this URL before transmission. For more details, refer to the Encode the URL step. More information: Maximum length: 512 characters
referenceCustomerId	String	Yes	The unique ID that is assigned by the Partner to identify a Customer. For example, `123456` Note: WorldFirst uses this field for idempotence control when Customers apply for Receiving Accounts. More information: Maximum length: 64 characters
storeUrl	String	Yes	URL of the Customer's store on Partner's website. For example, `https://www.xxx.com/seller/1/` More information: Maximum length: 256 characters
storeName	String	Yes	The name of the Customer's store that is registered on the Partner's website. More information: Maximum length: 256 characters
currency	String	Yes	Receiving Account's currency. If multiple currencies exist, use "," to separate the currencies. For example, `USD`. More information: Maximum length: 256 characters
affiliate_id	String	No	The Partner's channel ID to track Customer registration. For example, `aff-id-1234567`. More information: Maximum length: 64 characters
requestId	String	Yes	The unique ID that is assigned by the Partner to identify the request. Note: WorldFirst uses this field to perform idempotency control onto Receiving Accounts when the Partner attempts to change the bound Receiving Account. More information: Maximum length: 32 characters
key	String	Yes	Secret key provided by the Partner. For example, `test_security_key@email.com`. Note: The Partner needs to exchange this cipher with WorldFirst beforehand by contacting WorldFirst Technical Support.

Note: the very order of the parameters cannot be changed. For example, If the URL has extBizPartnerId in front of partnerId, the redirection URL may fail.

Sample:

copy
echo -n "partnerId=1234567890&extBizPartnerId=1234567890&redirectUrl=testurl&referenceCustomerId=qwertyuiop&storeUrl=teststore&storeName=qwertyuiop&currency=USD&requestId=1234567890&key=test_security_key@email.com" | md5sum

Generated signature for this sample: f4bfcde6a3e9edab347ae849e54db41d.

Alternatively, generate a signature with Java:

copy
package com.alipay.iopentools;

import java.math.BigInteger;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

/**
 * MD5 encryption/authentication tool class
 */
public class MD5Utils1 {

    /**
     * String encrypted to MD5 without salt
     *
     * @param plainText Pass in the string to be encrypted
     * @return Generate 32-bit (lowercase letters + numbers) string after MD5 encryption
     */
    public static String MD5Lower(String plainText) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            md.update(plainText.getBytes());
            return new BigInteger(1, md.digest()).toString(16);
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
            return null;
        }
    }


    /**
     * Test
     *
     * @param args
     */
    public static void main(String[] args) {
        String sign_data = "partnerId=1234567890&extBizPartnerId=1234567890&redirectUrl=testurl&referenceCustomerId=qwertyuiop&storeUrl=teststore&storeName=qwertyuiop&currency=USD&requestId=1234567890&key=test_security_key@email.com";
        String signature = MD5Lower(sign_data);
        System.out.println(signature);
    }
}

Sign the URL

Construct a signed URL with the following rules:

https://portal.worldfirst.com.cn/enterprise/auth?partnerIdextBizPartnerId=extBizPartnerId&redirectUrl=redirectUrl&referenceCustomerId=referenceCustomerId&storeUrl=storeUrl&storeName=storeName&currency=currency&affiliate_id=affiliate_id&requestId=requestId&signature=signature

Sample content after inserting the signature to the URL:

copy
https://portal.worldfirst.com.cn/enterprise/auth?partnerId=1234567890&extBizPartnerId=1234567890&redirectUrl=testurl&referenceCustomerId=qwertyuiop&storeUrl=teststore&storeName=qwertyuiop&currency=USD&requestId=1234567890&signature=f4bfcde6a3e9edab347ae849e54db41d

Encode the URL

Partner needs to certify the URL is properly encoded before transmission. For more information, refer to the Message encoding chapter.

WorldFirst > Partner

After the Customer completes the authorization process and creates Receiving Account on the WorldFirst website, this URL redirects the customer back to the Partner's website. This URL is not required to be signed.

The URL has the following structure:

https://xxx.xxx.com?partnerId=partnerId&extBizPartnerId=extBizPartnerId&referenceCustomerId=referenceCustomerId&resultMsg=resultMsg

Sample URL:

copy
https://xxx.xxx.com?partnerId=2021650000005097&extBizPartnerId=200102041532&resultMsg=SUCCESS

Where:

Field	Data type	Required	Description
partnerId	String	Yes	The unique ID that is assigned by WorldFirst to identify a contracted Partner. Maximum length: 64 characters
extBizPartnerId	String	Yes	The unique ID that is assigned by WorldFirst to identify an external Partner that is not onboard with WorldFirst. Maximum length: 64 characters
referenceCustomerId	String	No	The unique ID that is assigned by the Partner to identify a Customer. This parameter is required when the partner redirects to WorldFirst. Maximum length: 64 characters
resultMsg	String	Yes	Messages of the result. `SUCCESS` indicates that OAuth is successful. Other returned value indicates OAuth is not successful. Refer to the Result code section down below for details. Maximum length: 512 characters

Note: the very order of the parameters cannot be changed. For example, If the URL has extBizPartnerId in front of partnerId, the redirection URL may fail.

Result code

`resultMsg`Message	Status	Description	Further Action
SUCCESS	S	Success
PARAM_ILLEGAL	F	Illegal parameter	Retry with the correct parameters.
CURRENCY_ALREADY_EXISTS	F	Currency already exists	Retry with the correct currency.
CURRENCY_OUT_OF_SUPPORTED_RANGE	F	Currency is not supported	Retry with the correct currency.
SYSTEM_BUSY	U	System is busy	Retry later or contact WorldFirst Technical Support.
SIGNATURE_VERIFICATION_FAILED	F	Invalid signature	Check the signature and retry.

Next steps

Once the customer onboarding process is completed, it is possible to:

Make prefunding deposits