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 customers to the WorldFirst portal, where they can authorize WF to set up a Receiving Account (RA). The following sections address the overall workflow, steps to build a signed redirect URL, and how to verify authorization.

Workflow

Figure 1. Workflow to create a Receiving Account (RA)

Figure 1 outlines the processes involved in creating and validating a Receiving Account:

1. The customer initiates the account binding request to WorldFirst on your portal.
2. The customer is redirected to WorldFirst's authorization page using a redirect URL. For detailed instructions, see Step 1: 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. Upon approval, WorldFirst processes the account binding request and generates a unique RA for the customer.
4. Verify the authorization result using the following methods:

• After authorization is completed, WorldFirst guides the customer back to your website using another redirect URL. The URL will provide result messages indicating whether the RA is created successfully. For more information, see Step 2: Verify authorization success.
• (Optional but recommended) You can also call the inquiryAccount API to ensure that the customer's RA exists and is valid.

Procedure

Step 1: 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.

There are two available methods to construct the redirect URL. You can choose either, but we highly recommend Method 1, as it establishes a stronger and more secure channel for exchanging resources between both ends. If you are a partner who has already completed integration, you are currently using Method 2. You may continue using Method 2 or reintegrate using Method 1 to update the redirect URL.

Method 1 (Recommended)

1. Construct a canonicalized query string

a. Build the query string

Use the following parameters to build a canonicalized query string.

Note:

• You must comply with the sequence of the parameters as defined below. Otherwise, the URL might fail.
• To change the bound WF Receiving Account, you must use a different requestId and ensure the value of other parameters remains the same.

b. Encode the query string

Before proceeding to the next step, encode the entire query string. For detailed instructions, see Message Encoding.

2. Generate an RSA signature

Use SHA256withRSA and the assembled query string from the previous step to generate a signature:

Sample command line:

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

Sample signature output:

KrwDE9tAPJYB...*****

3. Sign and encode the URL

URL structure

Request method: GET

The following sample URL includes the domain name and the necessary parameters. Please note that the sequence of the parameter cannot be changed, otherwise the URL will fail.

Build the URL

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

See the following sample URL with values:

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

Method 2

1. Construct a canonicalized query string

a. Build the query string

Use the following parameters to build a canonicalized query string.

Note:

• You must comply with the sequence of the parameters as defined below. Otherwise, the URL might fail.
• To change the bound WF Receiving Account, you must use a different requestId and ensure the value of other parameters remains the same.

b. Encode the query string

Before proceeding to the next step, encode the entire query string. For detailed instructions, see Message Encoding.

2. Generate an MD5 signature

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

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

For further explanations and code samples, refer to the Tools chapter.

Sample signature output: f4bfcde6a3e9edab347ae849e54*****.

3. Sign and encode the URL

URL structure

Request method: GET

The following sample URL includes the domain name and the necessary parameters. Please note that the sequence of the parameter cannot be changed, otherwise the URL will fail.

Build the URL

1. Build a canonicalized query string as per the table in Step 1: Construct a Canonicalized Query String. Replace key with 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) before the query string.
3. Encode the entire URL before publishing it. For detailed instructions, refer to the Message Encoding chapter.

See the following sample URL with values:

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

Step 2: Verify authorization success

After the customer authorizes WorldFirst to create a Receiving Account, confirm the authorization success using the following methods:

• Receive authorization results from WorldFirst: WorldFirst returns the result through a redirect URL after authorization is completed.
• Call the inquiryAccount API (Optional but recommended): You can call the inquiryAccount API to validate if the customer's Receiving Account (RA) is valid.

Receive authorization results from WorldFirst

Review parameters in the URL

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

Sample URL structure:

Sample URL with values:

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

Check the resultMsg

After obtaining the resultMsg value from WorldFirst, refer to the following table to interpret its meaning and suggested actions.

(Optional but recommended) Call the inquiryAccount API

While optional, it is highly recommended to call the inquiryAccount API immediately after authorization. This ensures the customer's RA is ready for fund transfers. For more information, see 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 receive a list of Receiving Accounts (or a single RA if only one currency is specified), indicating successful RA creation.
• Alternatively, if the response message contains no data, it indicates that the RA does not exist.