As a WorldFirst partner, you can easily settle funds with your Chinese customers by calling the createTransfer API. To achieve this, you need to construct a redirect URL that takes your customer to the WorldFirst portal where they authorize WF to set up a Receiving Account (RA). The following sections address the overall procedure, steps to build a signed redirect URL, and ways to validate if authorization is successful.

Procedure

Figure 1. Process to open a Receiving Account (RA)

Figure 1 introduces the processes of creating and validating a Receiving Account:

1. At your portal, the customer requests to bind the account to WorldFirst.
2. By using a redirect URL, you take the customer to WorldFirst authorization page. For detailed instructions, see the next section: Construct a Redirect URL.
3. On the authorization page, WorldFirst prompts the customer to log in and authorize WorldFirst to establish an RA with the specified currencies and marketplace. When the customer approves, WorldFirst continues to process the account binding request and generate a unique RA for the customer.
4. Verify authorization result using the following methods:

• After authorization is completed, WorldFirst guides the customer back to your website by using another redirect URL. The URL will send back result messages that indicate if an RA is created successfully. For further information, see the last section: Verify whether Authorization is Successful.
• (Optional but recommended) You can also call the inquiryAccount API to ensure that the customer's RA exists and is valid.

Construct a redirect URL

After the customer initiates an account binding request, you need to build a redirect URL that takes your customer to the WorldFirst authorization page.

Follow these steps to construct the redirect URL:

1. Construct a canonicalised query string

a. Build the query string

Use the following parameters to build a canonicalised query string.

Note: You must comply with the sequence of the parameters as defined below. Otherwise, the URL might fail.

b. Encode the query string

Encode the entire query string before you move to the next step. For detailed instructions, refer to chapter: Message Encoding.

2. Generate a MD5 signature

Use the encoded query string from the previous step and MD5 algorithm to create a signature.

You can use any preferred programming language or Linux commands to calculate a MD5 signature.

For further explanations and code samples, refer to Chapter: Tools.

Sample signature output: f4bfcde6a3e9edab347ae849e54*****.

3. Sign and encode the URL

URL structure

The redirect URL uses the GET request method, takes https scheme, uses portal.worldfirst.com as its domain name and includes an ordered query string in its URL body closely following a question mark (?) with each key-value pair separated by an ampersand (&).

Here is a sample URL structure:

Method: GET

Build the URL

1. Build a canonicalise query string as per the table in Step 1: Construct a Canonicalised Query String. Replace key with the signature from Step 2: Generate a MD5 Signature and keep the sequence of other key-value pairs unchanged.
2. Add the WorldFirst domain name (portal.worldfirst.com) prior to the query string.
3. Encode the entire URL before you publish it. For detailed instructions, refer to chapter: Message Encoding.

Below is a sample URL with values:

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

Verify whether authorization is successful

After the customer authorizes WorldFirst to create a Receiving Account, there are two ways to know whether authorization is successful:

• WorldFirst returns the result through a redirect URL after authorization is completed.
• (Optional but recommended) You may also call the inquiryAccount API to validate if the customer's RA is valid.

Receive authorization results from WorldFirst

URL structure

As soon as your customer authorizes WorldFirst to set up a Receiving Account, you will get a redirect URL from the WorldFirst which uses the following parameters as sequenced in the table below:

Sample URL structure:

Sample URL with values:

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

resultMsg

After getting the value of resultMsg from the WorldFirst, use the table below to understand its value, the corresponding meaning and the suggested action.

(Optional) Call the InquiryAccount API

Although this is an optional last step to verify the validity of a Receiving Account, it is still highly recommended that you call the inquiryAccount API immediately after authorization to ensure that the customer has an RA number ready for the fund transfer. For further details, refer to Chapter: Manage your accounts.

When the API call fails

Check whether referenceCustomerId is correct when the resultCode in the response body says PARAM_ILLEGAL.

When the API call succeeds

• You might get a list of Receiving Accounts (or get only one RA if only one currency is specified) in the response message, indicating that the Receiving Accounts are created successfully.
• Or, you might get nothing in the response message, indicating that the RA does not exist.