WorldFirst DocsWorldFirst DocsDOCS

transfer

POST: /aps/api/business/transfer/transfer

Signature required

Use the transfer API to initiate a transfer request. The beneficiary account could be either a bank card(bank account), a WorldFirst account, or an Alipay wallet.

The transfer process is asynchronous. WorldFirst(Alipay) responds to the Partner that the transfer request is being processed, rather than the final result of the transfer. WorldFirst(Alipay) sends the notification about the transfer result with the notifyTransferResult API.

Alternatively, the Partner can utilize the inquiryTransfer API to query the result. WorldFirst(Alipay) responds to the Partner about the result of the transfer in the transferResult.resultCode field.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Field

Data type

Required

Description

transferRequestId

String

Yes

The unique ID assigned by the Partner to identify a transfer request.

Note:

  • This field is an API idempotency field. For details about API idempotency, see the Idempotency chapter.

More information:

  • Maximum length: 64 characters

transferOrderAddition

TransferOrderAddition object

Yes

Additional information about the transfer, such as information about the payer and the beneficiary, and the reference ID of the transfer.

transferFromDetail

TransferFromDetail object

Yes

The transfer amount submitted by the payer.

transferToDetail

TransferToDetail object

Yes

The transfer details for the beneficiary, such as the transfer amount collected by the beneficiary, and the transfer method the beneficiary used.

transferFactor

TransferFactor object

Yes

Indicates different scenarios for the transfer, such as: remitting to China in CNY, or remitting to countries/regions other than China.

Note:

  • For more details about the differences between various scenarios, refer to the Samples section.

More Information

  • The name of the beneficiary's bank account holder is: transferToDetail.transferToMethod.paymentMethodMetaData.bankAccount.holderAccountName.fullName. This value must be the same as the registered legal name of the beneficiary, which is either customer.individual.legalName or customer.company.legalName.
  • Possible values and use cases for transferOrderAddition.transferToAddition.bopCode:
    • 122030: E-commerce trade(default value). transferToRegion must be CN.
    • 228050: Service commission. transferToRegion must be CN.
    • 10101: Advance payment against imports. transferToRegion must be KR.
    • 318134: Goods export. transferToRegion must be TH.
    • 700001: Marketplace settlement. transferToRegion cannot be CN, KR, or TH.
    • 700002: Commission service trade. transferToRegion cannot be CN, KR, or TH.

Generally speaking, there are two common scenarios for Partner transfers inbound to China:

  • The Customer remits money inbound to China in CNY (Complete the settlement of foreign exchange).
    • transferFactor.transferFundType is GLOBAL_CNH_CN.
    • transferOrderAddition.transferToAddition.bopCode is 228050.
    • WorldFirst(Alipay) provides transfer details to the Customer.
  • The Customer transfers money to beneficiaries in China in CNH:

Note: In this scenario, the Customer needs to contact the bank and complete the payment of the remittance.

    • transferToDetail.transferToAmount.currency is CNY.
    • transferFactor.transferFundType is GLOBAL_GLOBAL_SERVICE.
    • transferOrderAddition.transferToAddition.bopCode is SRV.
    • WorldFirst(Alipay) does not provide transfer details to the Customer.

Response parameters

Field

Data type

Required

Description

result

Result object

Yes

Indicates whether this API is called successfully.

transferId

String

No

The unique ID assigned by WorldFirst to identify a transfer.

More information:

  • Maximum length: 64 characters

transferFactor

TransferFactor object

Yes

Indicates different scenarios for the transfer, such as: remitting to China in CNY, or remitting to countries/regions other than China.

Result processing logic

In the response, the result.resultStatus field indicates the result. The following table describes each result status:

Result status

Description

S

This indicates the API call succeeded.

  • This result status indicates that WorldFirst accepts the transfer request and is processing the transfer.
  • For the result of the transfer, wait for the notification from the notifyTransferResult API.
  • If the Partner receives no notifications from the notifyTransferResult API in 20 minutes, use the inquiryTransfer API to query the transfer result. The best practice is making API polling requests at a frequency of 2-3 seconds per request and 10-20 attempts in total.

F

This indicates the API call failed. For more information on why the call failed, see result.resultCode.

  • If the result.resultCode is ORDER_IS_RESERVED, it means the payment has been reserved. For details about how to handle a payment reversal, refer to the Handle a reversal chapter.
  • If the result.resultCode is ORDER_NEEDS_RETRY, the Partner needs to check the specific reason in the result.resultMessage field and retry the same order.

U

This indicates the API call result is unknown.

  • Query the result of the transfer with the inquiryTransfer API. The best practice is to make inquiries with inquiryTransfer 3 seconds after initiating a transfer.

Result codes

result.resultCode

For oversea transfers

resultCode

resultStatus

resultMessage

Further action

SUCCESS

S

Success

PROCESS_FAIL

F

A general business failure occurred. Do not retry.

Human intervention is usually needed. It is recommended that you contact WorldFirst Technical Support to resolve the issue.

PARAM_ILLEGAL

F

Illegal parameters exist. For example, a non-numeric input, or an invalid date.

Check and verify whether the request fields, including the header fields and body fields, are correct and valid.

For details on the fields of each API, see the specific API Structure section.

REQUEST_TRAFFIC_EXCEED_LIMIT

U

The request traffic exceeds the limit.

Call the interface again to resolve the issue. If the issue persists, contact WorldFirst Technical Support.

INVALID_API

F

The called API is invalid or not active.

Check whether the correct API is being called.

INVALID_CLIENT

F

The client is invalid.

The Client ID does not exist or is invalid.

INVALID_SIGNATURE

F

The signature is invalid.

Make sure the request is properly signed with a valid signature. For more details, refer to the following chapter:

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTP method.

Ensure the HTTP method is POST.

UNKNOWN_EXCEPTION

U

The API call is failed, which is caused by unknown reasons.

The service might be down, retry later. If the issue persists, contact WorldFirst Technical Support.

TRANSFER_IN_PROCESS

U

The transfer is being processed.

Query the transfer result with the inquiryTransfer API.

FX_RATE_INVALID

F

The foreign exchange rate is invalid.

Retry with the correct currency exchange rate.

CARD_INFO_NOT_MATCH

F

The card information does not match.

Retry with the correct card information.

USER_NOT_EXIST 

F

The user does not exist.

Retry with the correct user information.

USER_ACCOUNT_ABNORMAL

F

The user account status is abnormal.

Retry with a different user. If the issue persists, contact WorldFirst Technical Support for more details.

AMOUNT_EXCEED_LIMIT

F

The amount exceeds the limit.

Make sure the amount submitted is correct and retry.

RISK_REJECT

F

The transfer is rejected for risk control reasons.

Prompt the user that the request is rejected because the risk control failed.

UN_SUPPORT_BUSINESS

F

Unsupported business.

Invalid parameters are used e.g. currency is incorrect. Retry with the correct information.

BALANCE_NOT_ENOUGH

F

Balance is not enough.

Make sure the balance is sufficient and retry.

BIC_NOT_MATCH_WITH_COUNTRY

F

BIC code does not match with the country. Retry with the correct information.

ORDER_IS_REVERSED

F

Transfer reversal due to incorrect beneficiary information. Retry with the correct information.

ORDER_NEED_RETRY

U

Note: This result message explains the reason for the error. Retry the order to fix the issue.

For transfers inbound to China

resultCode

resultStatus

resultMessage

Further action

SUCCESS

S

Success

PROCESS_FAIL

F

A general business failure occurred. Do not retry.

Human intervention is usually needed. It is recommended that you contact WorldFirst Technical Support to resolve the issue.

PARAM_ILLEGAL

F

Illegal parameters exist. For example, a non-numeric input, or an invalid date.

Check and verify whether the request fields, including the header fields and body fields, are correct and valid.

For details on the fields of each API, see the specific API Structure section.

REQUEST_TRAFFIC_EXCEED_LIMIT

U

The request traffic exceeds the limit.

Call the interface again to resolve the issue. If the issue persists, contact WorldFirst Technical Support.

INVALID_API

F

The called API is invalid or not active.

Check whether the correct API is being called.

INVALID_CLIENT

F

The client is invalid.

The Client ID does not exist or is invalid.

INVALID_SIGNATURE

F

The signature is invalid.

Make sure the request is properly signed with a valid signature. For more details, refer to the following chapter:

METHOD_NOT_SUPPORTED

F

The server does not implement the requested HTTP method.

Ensure the HTTP method is POST.

UNKNOWN_EXCEPTION

U

The API call is failed, which is caused by unknown reasons.

The service might be down, retry later. If the issue persists, contact WorldFirst Technical Support.

TRANSFER_IN_PROCESS

U

The transfer is being processed.

Query the transfer result with the inquiryTransfer API.

FX_RATE_INVALID

F

The foreign exchange rate is invalid.

Retry with the correct currency exchange rate.

CARD_INFO_NOT_MATCH

F

The card information does not match.

Retry with the correct card information.

USER_NOT_EXIST 

F

The user does not exist.

Retry with the correct user information.

USER_ACCOUNT_ABNORMAL

F

The user account status is abnormal.

Retry with a different user. If the issue persists, contact WorldFirst Technical Support for more details.

AMOUNT_EXCEED_LIMIT

F

The amount exceeds the limit.

Make sure the amount submitted is correct and retry.

RISK_REJECT

F

The transfer is rejected for risk control reasons.

Prompt the user that the request is rejected because the risk control failed.

UN_SUPPORT_BUSINESS

F

Unsupported business.

Invalid parameters are used e.g. currency is incorrect. Retry with the correct information.

BALANCE_NOT_ENOUGH

F

Balance is not enough.

Make sure the balance is sufficient and retry.

ABNORMAL_BANK_ACCOUNT_STATUS

F

Bank account status is abnormal. Retry with another card.

BANK_ACCOUNT_NOT_EXIST

F

Bank account does not exist. Retry with another card.

BANK_ACCOUNT_CLOSED

F

Bank account is closed. Retry with another card.

BANK_ACCOUNT_FROZEN

F

Bank account is frozen. Retry with another card.

BANK_ACCOUNT_REPORTED_LOST

F

Bank account is reported as lost. Retry with another card.

PAYMENT_FAILED

F

Transaction fails. Retry with another card.

TRANSACTION_AMOUNT_EXCEEDS_BANK_LIMIT

F

Transaction amount exceeds bank limit.

INVALID_TRANSACTION_AMOUNT

F

Transaction failed due to invalid transaction amount.

BANK_PROCESS_FAILED

F

Bank system failed to process.

BANK_DECLINED

F

System error of the bank. Do not retry.

BANK_ACCOUNT_RESTRICTED

F

Bank account is restricted. Contact bank.

WITHDRAW_AMOUNT_EXCEEDS_BANK_LIMIT

F

Withdraw amount exceeds the daily limit of the bank.

BANK_ACCOUNT_NOT_MATCH_WITH_HOLDER_NAME

F

Bank account does not match with the account name. Retry with the correct information.

ABNORMAL_BANK_ACCOUNT_STATUS_OR_INCORRECT_INFORMATION

F

Bank account status is abnormal or the bank account information is incorrect. Retry with another card or retry with the correct information.

BANK_ACCOUNT_NOT_EXIST_OR_INCORRECT

F

Bank account does not exist or bank account information is incorrect. Retry with the correct information.

BANK_ACCOUNT_NOT_SUPPORTED

F

Type of the bank account is not supported. Retry with another card.

BANK_ACCOUNT_OVERDUE

F

Bank account is overdue. Retry with another card.

BANK_ACCOUNT_DORMANT

F

Bank account is dormant. Retry with another card.

INACTIVE_BANK_ACCOUNT

F

Bank account is inactive. Retry with another card.

ORDER_NEED_RETRY

U

Note: This result message explains the reason for the error. Retry the order to fix the issue.

USER_STATUS_ABNORMAL

F

The status of the user is abnormal. Retry with another card.

Samples

paymentMethodMetaData

Content of the paymentMethodMetaData parameter varies depending on the value of holderAccountType.

For individual bank accounts

When the beneficiary is holding an individual bank account, namely, the value of holderAccountType is INDIVIDUAL, alter the paymentMethodMetaData string according to the following sample code:

copy
"{\"bankAccountNo\":\"621111111111****\",\"bankName\":\"招商银行\",\"holderAccountName\":{\"fullName\":\"ZHANGSAN\"},\"holderAccountType\":\"INDIVIDUAL\"}"

For company bank accounts

When the beneficiary is holding a company bank account, namely, the value of holderAccountType is COMPANY, alter the paymentMethodMetaData string according to the following sample code:

The following sample code considers a transfer request destined to a Chinese bank in Hangzhou:

copy
"{\"bankAccountNo\":\"621111111111****\",\"bankName\":\"招商银行\",\"holderAccountName\":{\"fullName\":\"ZHANGSAN\"},\"holderAccountType\":\"COMPANY\",\"bankAddress\":{\"city\":\"HANGZHOU\",\"state\":\"JIANGSU\",\"zipCode\":\"310000\"},\"branchBankName\":\"招商银行西湖支行\",\"routingNumber\":\"30826103****\"}"

The following sample code considers a transfer request destined to a bank account located in Australia. The currency used in the transfer is CNY:

copy
"{\"bankAccountNo\":\"*********6901\",\"holderAccountName\":{\"fullName\":\"G***L PREMIUM BUY (MACAU) LIMITED.l\"},\"holderAccountType\":\"COMPANY\",\"bankName\":\"CHN Pingan Bank \",\"branchBankName\":\"\",\"bankAddress\":{\"region\":\"AU\",\"state\":\"\",\"city\":\"\",\"address*\":\"\",\"********\":\"\",\"zipCode\":\"\"},\"routingNumber\":\"123456\",\"bankBIC\":\"swftcode\",\"bankAccountIBAN\":\"\",\"holderAddress\":{\"region\":\"AO\",\"state\":\"123213q we\",\"city\":\"qwewqe\",\"address*\":\"********\",\"address*\":\"1112222\",\"zipCode\":\"1234546\"}}"

For details about card elements information, contact WorldFirst(Alipay) Support Team.

For Alipay wallets

When the beneficiary account is an Alipay Wallet, which means the value of the transferToDetail.transferToMethod.paymentMethodType is WALLET, alter the transferToDetail.transferToMethod field according to the following sample code:

copy
{
    "paymentMethodType": "WALLET",
    "paymentMethodMetaData": {
        "customerId": "13800001111",
        "customerName":{
            "fullName":"USER FULL NAME"
        },
      "paymentMethodDetailType": "ALIPAY_CN"
    }
}

The customerId field is the registered phone number of the beneficiary's Alipay wallet.

Request

This section illustrates sample request codes for different currency exchange scenarios

Case 1.1. Transfer to a bank account, without currency exchange:

copy
{
  "transferRequestId": "******",
  "transferFromDetail": {
    "transferFromAmount": {
      "currency": "CNY",
      "value": "30"
    }
  },
  "transferOrderAddition": {
    "referenceOrderId": "******",
    "transferFromAddition": {
      "merchant": {
        "referenceMerchantId": "******",
        "merchantName": "****** LIMITED",
        "merchantAddress": {
          "region": "MO",
          "state": "A Freguesia da Se",
          "city": "A Freguesia da Se",
          "address1": "******, No. 123, ****** Plaza, 19 andar, Macau SAR"
        }
      },
      "transferFromRegion": "MO"
    },
    "transferToAddition": {
      "beneficiary": {
        "userName": {
          "fullName": "****** LIMITED.l"
        }
      },
      "transferToRegion": "AU",
      "bopCode": "700002"
    }
  },
  "transferFactor": {
    "transferFundType": "GLOBAL_GLOBAL_SERVICE"
  },
  "transferToDetail": {
    "transferToAmount": {
      "currency": "CNY",
      "value": "30"
    },
    "transferToMethod": {
      "paymentMethodType": "BANK_ACCOUNT",
      "paymentMethodMetaData": "{\"bankAccountNo\":\"*********6901\",\"holderAccountName\":{\"fullName\":\"****** LIMITED.l\"},\"holderAccountType\":\"COMPANY\",\"bankName\":\"CHN Pingan Bank \",\"branchBankName\":\"\",\"bankAddress\":{\"region\":\"AU\",\"state\":\"\",\"city\":\"\",\"address*\":\"\",\"********\":\"\",\"zipCode\":\"\"},\"routingNumber\":\"123456\",\"bankBIC\":\"swftcode\",\"bankAccountIBAN\":\"\",\"holderAddress\":{\"region\":\"AO\",\"state\":\"123213q we\",\"city\":\"qwewqe\",\"address*\":\"********\",\"address*\":\"1112222\",\"zipCode\":\"1234546\"}}"
    }
  }
}

Case 1.2. Transfer to Alipay Wallet, without currency exchange:

copy
{
  "transferRequestId": "******",
  "transferFromDetail": {
    "transferFromAmount": {
      "currency": "CNY",
      "value": "30"
    }
  },
  "transferOrderAddition": {
    "referenceOrderId": "******",
    "transferFromAddition": {
      "merchant": {
        "referenceMerchantId": "******",
        "merchantName": "****** LIMITED",
        "merchantAddress": {
          "region": "MO",
          "state": "A Freguesia da Se",
          "city": "A Freguesia da Se",
          "address1": "******, No. 123, ****** Plaza, 19 andar, Macau SAR"
        }
      },
      "transferFromRegion": "MO"
    },
    "transferToAddition": {
      "beneficiary": {
        "userId": "******",
        "userName": {
          "fullName": "****** LIMITED.l"
        }
      },
      "transferToRegion": "CN",
      "bopCode": "228050"
    }
  },
  "transferFactor": {
    "transferFundType": "GLOBAL_CNH_CN"
  },
  "transferToDetail": {
    "transferToAmount": {
      "currency": "CNY",
      "value": "30"
    },
    "transferToMethod": {
        "paymentMethodType": "WALLET",
        "paymentMethodMetaData": {
            "customerId": "13800001111",
            "customerName":{
                "fullName":"USER FULL NAME"
            },
        "paymentMethodDetailType": "ALIPAY_CN"
        }
    }
  }
}

Case 2.1. Transfer to a bank account in China, with currency exchange:

copy
{
  "transferFactor": {
    "delegationMode": "TRANSFER",
    "transferFundType": "GLOBAL_CNH_CN"
  },
  "transferFromDetail": {
    "transferFromAmount": {
      "currency": "USD",
      "value": "2135"
    }
  },
  "transferOrderAddition": {
    "referenceOrderId": "******",
    "transferFromAddition": {
      "merchant": {
        "merchantAddress": {
          "address1": "**********************",
          "city": "***",
          "region": "US",
          "state": "Auckland"
        },
        "merchantId": "2188******",
        "merchantName": "******"
      },
      "transferFromRegion": "US"
    },
    "transferToAddition": {
      "beneficiary": {
        "userId": "2021******",
        "userName": {
          "fullName": "******"
        }
      },
      "bopCode": "228050",
      "transferToRegion": "CN"
    }
  },
  "transferRequestId": "******",
  "transferToDetail": {
    "transferQuote": {
      "baseCurrency": "USD",
      "quoteCurrencyPair": "USD/CNY",
      "quoteExpiryTime": "2022-02-13T16:56:14+08:00",
      "quoteId": "2022******",
      "quotePrice": "6.48118695",
      "quoteUnit": "1"
    },
    "transferToAmount": {
      "currency": "CNY",
      "value": "13837"
    },
    "transferToMethod": {
      "paymentMethodMetaData": "{\"bankAccountNo\":\"********0002\",\"bankAddress\":{\"region\":\"CN\"},\"bankBIC\":\"ICBKCNBJ***\",\"bankName\":\"工商银行\",\"holderAccountName\":{\"fullName\":\"***\"},\"holderAccountType\":\"INDIVIDUAL\"}",
      "paymentMethodType": "BANK_ACCOUNT"
    }
  }
}

Case 2.2. Transfer to an Alipay wallet, with currency exchange:

copy
{
  "transferFactor": {
    "delegationMode": "TRANSFER",
    "transferFundType": "GLOBAL_CNH_CN"
  },
  "transferFromDetail": {
    "transferFromAmount": {
      "currency": "USD",
      "value": "2135"
    }
  },
  "transferOrderAddition": {
    "referenceOrderId": "******",
    "transferFromAddition": {
      "merchant": {
        "merchantAddress": {
          "address1": "**********************",
          "city": "***",
          "region": "US",
          "state": "Auckland"
        },
        "merchantId": "2188******",
        "merchantName": "******"
      },
      "transferFromRegion": "US"
    },
    "transferToAddition": {
      "beneficiary": {
        "userId": "2021******",
        "userName": {
          "fullName": "******"
        }
      },
      "bopCode": "228050",
      "transferToRegion": "CN"
    }
  },
  "transferRequestId": "******",
  "transferToDetail": {
    "transferQuote": {
      "baseCurrency": "USD",
      "quoteCurrencyPair": "USD/CNY",
      "quoteExpiryTime": "2022-02-13T16:56:14+08:00",
      "quoteId": "2022******",
      "quotePrice": "6.48118695",
      "quoteUnit": "1"
    },
    "transferToAmount": {
      "currency": "CNY",
      "value": "13837"
    },
    "transferToMethod": {
        "paymentMethodType": "WALLET",
        "paymentMethodMetaData": {
            "customerId": "13800001111",
            "customerName":{
                "fullName":"USER FULL NAME"
            },
        "paymentMethodDetailType": "ALIPAY_CN"
        }
    }
  }
}

Response

Case 1. Success

copy
{
  "result": {
    "resultCode": "TRANSFER_IN_PROCESS",
    "resultMessage": "The transfer is being processed",
    "resultStatus": "U"
  },
  "transferFactor": {
    "delegationMode": "TRANSFER",
    "transferFundType": "GLOBAL_CNH_CN"
  },
  "transferId": "2022******"
}


Case 2. Bank reversal

For more information about the reversal scenario, refer to the Handle a reversal chapter.

copy
{
  "transferFactor": {
    "delegationMode": "TRANSFER",
    "transferFundType": "GLOBAL_GLOBAL_SERVICE"
  },
  "transferFinishTime": "2022-07-05T15:58:12+08:00",
  "transferFromDetail": {
    "feeAmount": {
      "currency": "USD",
      "value": "1000"
    },
    "transferFromAmount": {
      "currency": "USD",
      "value": "8445298"
    }
  },
  "transferId": "1234567890",
  "transferRequestId": "1234567890",
  "transferResult": {
    "resultCode": "ORDER_IS_REVERSED",
    "resultMessage": "account closed",
    "resultStatus": "F"
  },
  "transferToDetail": {
    "reverseAmount": {
      "currency": "USD",
      "value": "100"
    },
    "transferToAmount": {
      "currency": "USD",
      "value": "100"
    },
    "transferToMethod": {
      "paymentMethodMetaData": "{\"bankAccount\":\"{\\\"cardAddress\\\":\\\"***\\\",\\\"holderAccountName\\\":{\\\"fullName\\\":\\\"H***D\\\"},\\\"holderAccountType\\\":\\\"COMPANY\\\",\\\"bankBIC\\\":\\\"WIHBHKHH\\\",\\\"bankAccountNo\\\":\\\"*****2831\\\",\\\"bankName\\\":\\\"OCBC WING HANG BANK LIMITED\\\",\\\"bankAddress\\\":{\\\"region\\\":\\\"HK\\\"}}\",\"paymentMethodDetailType\":\"bankAccount\"}",
      "paymentMethodType": "BANK_ACCOUNT"
    }
  }
}

@2024 WorldFirst