Before using WorldFirst services to receive money, the Customer needs to open a Receiving Account(RA) with WorldFirst. The process to open a Receiving Account for the Customer is names as the Customer onboarding process.

Workflow

Figure 1. Customer onboarding process

Procedure

1. The Customer needs to bind the account on the Partner's portal to WorldFirst by making an account binding request.
2. The Partner processes the request and redirects the Customer to a WorldFirst authorization page.

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

3. On the authorization page:

1. The Customer needs to log into WorldFirst portal to proceed.
2. Customer authorizes WorldFirst on the authorization page.
3. WorldFirst processes the account binding request and creates a unique Receiving Account for the Customer.

4. WorldFirst redirects the Customer back to the Partner's portal.

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.

5. The Partner needs to call the inquiryAccount API to validate the Receiving Account has been successfully created. WorldFirst returns relevant account information such as the account number, active status, currency, etc.

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:

Where,

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.

Generate a signature:

echo -n "partnerId=*****&extBizPartnerId=*****&redirectUrl=*****&referenceCustomerId=*****&storeUrl=*****&storeName=*****p&currency=USD&requestId=*****&key=*****@***.***" | md5sum

Generated signature: f4bfcde6a3e9edab347ae849e54*****.

Alternatively, generate a signature with Java:

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=*****&extBizPartnerId=*****&redirectUrl=*****&referenceCustomerId=*****&storeUrl=*****&storeName=*****p&currency=USD&requestId=*****&key=*****@***.***";
        String signature = MD5Lower(sign_data);
        System.out.println(signature);
    }
}

Sign the URL

Construct a signed URL with the following rules:

Sample content after inserting the signature to the URL:

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

Encode the URL

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

Redirection URLs: 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 portal. This URL is not required to be signed.

The URL has the following structure:

Sample URL:

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

Where:

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

Result processing logic

You can test whether the Receiving Account has been successfully created guided by the following criteria:

• Merchant successfully gets onboard on the WorldFirst authorization page, creates a shop and Receiving Account. WorldFirst redirects the Merchant back to the Partner's portal. Considering the resultMsg field of this redirection URL:

• If resultMsg=SUCCESS, WorldFirst has successfully created a Receiving Account for the Merchant.
• If resultMsg=CURRENCY_OUT_OF_SUPPORTED_RANGE, WorldFirst failed to create a Receiving Account for the Merchant since WorldFirst does not support the Receiving Account's currency. The Merchant needs to choose a supported currency for the Receiving Account instead.
• If resultMsg=PARAM_ILLEGAL, WorldFirst failed to create a Receiving Account for the Merchant since an illegal parameter is selected. Generate another redirection URL with correct parameters.
• If resultMsg=CURRENCY_ALREADY_EXISTS, WorldFirst failed to create a Receiving Account for the Merchant since the currency selected for the Receiving Account already exists.
• If resultMsg=SIGNATURE_VERIFICATION_FAILED, WorldFirst failed to create a Receiving Account for the Merchant since the redirection URL failed to pass signature verification process. The Partner needs to regenerate a signature for the URL.

After completing the Customer onboarding process, it is suggested as the best practice for the Partner to call the inquiryAccount API to check whether the Receiving Account has been created.

• If the referenceCustomerId field is missing when calling the inquiryAccount API, the API request fails. In the response messages, the resultCode field is PARAM_ILLEGAL.
• If the inquiry succeeds

• If the Receiving Account has been successfully created, a list of Receiving Accounts is demonstrated in the response message.
• If the Receiving Account does not exist, no Receiving Account is returned in the response message.

Subsequently, the Customer can log into the WorldFirst website, and check whether the shop and Receiving Account created is correct.