wf-api-integration

WF API Integration Skill

Help users integrate with the WorldFirst API, supporting Java, Golang, and Python, covering transfers, payouts, beneficiary management, account management (balance/quota/sub-accounts/stores/notifications), statement queries, transaction order management, and other modules.

Language Support Notes: Java and Golang cover all modules; Python currently only supports the common modules (common/) and the statement management module (statement-management/), with no Python templates for the remaining modules.

Module Index

Module	Module Directory	Module Description	Official Documentation	Language Support
WorldFirst Transfer	references/transfer/	Transfer funds between WF accounts (consult/initiate/query/result notification)	📄 Official Documentation	Java、Golang
Global Distribution	references/payout/	Payout to third-party bank cards or e-wallets (consult/initiate/query/result notification)	📄 Official Documentation	Java、Golang
Beneficiary Management	references/beneficiary/	Card template query, bind/delete/edit/query beneficiaries, bind result notification	📄 Official Documentation	Java、Golang
Account Management	references/account-management/	Query account information/balance/settlement quota/sub-accounts/stores, receive top-up/balance change notifications	📄 Official Documentation	Java、Golang
Statement Management	references/statement-management/	Query account transaction流水 list and transaction details	📄 Official Documentation	Java、Golang、Python
Transaction Information Management	references/trade-order/	Upload transaction orders (B2C settlement / B2B order association), query results, handle asynchronous notifications	📄 Official Documentation	Java、Golang

Quick Decision Tree

用户咨询 WF API 对接
        |
        +-- 在 WF 账户之间划转资金？ --> 万里汇转账
        |       |
        |       +-- 需要提前获取汇率/手续费？ --> 咨询转账（consultTransfer）
        |       +-- 发起转账？ --> 户到户转账（createTransfer）
        |       +-- 查询转账结果？ --> 查询转账结果（inquiryTransfer）
        |       +-- 接收转账结果回调？ --> 转账结果通知（notifyTransfer）
        |
        +-- 付款到第三方银行卡或电子钱包（发工资、供应商付款、支付宝代发）？ --> 全球分发（代发）
        |       |
        |       +-- 需要提前获取汇率/报价？ --> 咨询代发汇率（consultPayout）
        |       +-- 发起代发？ --> 创建代发（createPayout）
        |       +-- 查询代发结果？ --> 查询代发结果（inquiryPayout）
        |       +-- 接收代发结果回调？ --> 代发结果通知（notifyPayout）
        |
        +-- 管理收款人银行卡（增删改查、卡模版）？ --> 收款人管理
        |       |
        |       +-- 查看卡模版字段要求？ --> 查询卡模版（inquiryTemplate）
        |       +-- 绑定收款人？ --> 绑定收款人（bindBeneficiary）
        |       +-- 删除/编辑/查询收款人？ --> 对应接口
        |       +-- 接收绑卡结果回调？ --> 绑定收款人通知（notifyBindBeneficiary）
        |
        +-- 账户相关查询？ --> 账户管理
        |       |
        |       +-- 查看账户有多少钱？ --> 查询余额（inquiryBalance）
        |       +-- 查看账户基本信息？ --> 查询账户信息（inquiryAccount）
        |       +-- 查看可申报结汇额度？ --> 查询结汇额度（inquiryAvailableQuota）
        |       +-- 查看主/子账号信息？ --> 查询子账号（inquirySubuser）
        |       +-- 查看店铺及关联账号？ --> 查询店铺信息（inquiryStore）
        |       +-- 接收充值/垫付回调？ --> 充值通知（notifyVostro）
        |       +-- 接收余额变动回调？ --> 余额变动通知（notifyBalanceChange）
        |
        +-- 查看账户交易流水或对账？ --> 账单管理
        |       |
        |       +-- 查询流水列表？ --> 查询账单流水（inquiryStatementList）
        |       +-- 查询流水详情？ --> 查询账单详情（inquiryStatementDetail）
        |
        +-- 上传交易订单（跨境结汇 / B2B 订单关联）？ --> 交易信息管理
                |
                +-- 上传交易订单？ --> 提交交易订单（submitTradeOrder）
                +-- 查询上传结果？ --> 查询订单结果（inquiryTradeOrder）
                +-- 接收异步通知？ --> 订单回调通知（notifyTradeOrder）

Scenario Keyword Matching

Keyword	Route Module
transfer, remittance, WF account transfer, internal transfer, inter-account transfer, account-to-account, transfer, consultTransfer, createTransfer, inquiryTransfer, notifyTransfer, transfer exchange rate, transfer fee, transfer consultation, initiate transfer, transfer status, transfer result, transfer notification, transfer callback	WorldFirst Transfer
payout, payout, payroll, payment to bank card, payment to third party, global distribution, cross-border payout, batch payment, payout exchange rate, payout quote, quoteId, consultPayout, createPayout, inquiryPayout, notifyPayout, payout status, payout result, payout notification, payout callback, e-wallet, Alipay payout, ALIPAY_CN_DETAIL, REFERENCE_ALIPAY_CN, payout to Alipay	Global Distribution (Payout)
beneficiary, beneficiary, bank card management, card binding, payee, receiving account, card template, bank card fields, inquiryTemplate, bindBeneficiary, editBeneficiary, removeBeneficiary, inquiryBeneficiaryList, notifyBindBeneficiary, add beneficiary, delete beneficiary, edit beneficiary, beneficiary list, bind beneficiary notification, card binding callback	Beneficiary Management
balance, account balance, balance, check balance, inquiryBalance, account available balance, currency balance, account information, inquiryAccount, settlement quota, inquiryAvailableQuota, sub-account, inquirySubuser, store information, inquiryStore, top-up notification, notifyVostro, balance change, notifyBalanceChange, advance payment callback, transaction notification	Account Management
Bill, transaction, transaction record, statement, reconciliation, account statement, inquiryStatementList, inquiryStatementDetail, transaction list, transaction details, bill details	Bill inquiry
Trade order, trade order, foreign exchange settlement, B2B order, order upload, PAY_INTO_CHINA, CREATE_B2B_ORDERS, submitTradeOrder, inquiryTradeOrder, notifyTradeOrder, order callback, asynchronous notification, webhook	Trade order management

Clarification wording

When the user's description is vague:

请确认您需要对接的万里汇（WorldFirst）业务模块：

1. 万里汇转账
   在 WF 账户之间划转资金，支持转账前汇率咨询、发起转账、查询转账结果、接收转账结果回调通知
   适用：WF 账户间资金划转

2. 全球分发（代发）
   代发资金到第三方银行卡，支持跨币种汇率咨询、发起代发、查询代发结果、接收代发结果回调通知
   适用：发工资、供应商付款、跨境分发等场景

3. 收款人管理
   管理代发目标银行卡，支持卡模版查询、绑定/编辑/删除/查询收款人、接收绑定结果回调通知
   适用：维护代发收款方的银行卡信息

4. 账户管理
   查询 WF 账户信息、余额、结汇额度、子账号、店铺信息，接收充值/余额变动回调通知
   适用：账户信息查询、余额监控、充值垫付通知处理

5. 账单查询
   查询账户交易流水列表及流水详情
   适用：对账、交易记录查询

6. 交易订单管理
   上传交易订单、查询处理结果、处理异步回调通知
   适用：跨境电商 B2C 结汇、B2B 订单关联

请告诉我您需要对接哪个模块？

Usage process

Confirm module: Confirm the module the user needs to integrate, and read the corresponding module's README.md to learn the API list
Confirm API: Confirm the specific API the user needs to integrate, and read the corresponding API's GUIDE.md to learn the API specification
Load common code: Read references/common/ under the common code templates
Load API code: Read the code templates under the corresponding API directory
Generate code: Generate code according to the user's project structure, replacing the {basePackage}(Java/Python) or {moduleName}(Golang) placeholders
Code check: Execute the checks in the "Post-Code-Generation Checklist"
Test verification: Run unit tests to ensure the code compiles and runs normally

Pre-Generation Questions (MUST ASK)

Before generating code,mustask the user all of the following questions through the AskUserQuestion tool. All questions must be fully collected before starting to generate any code.

Basic information

Project path: What is your project path?
Language selection: Do you need to generate Java, Golang, or Python code?
Base Package / Module Name：
- Java: Please provide the base package (e.g. com.example.project）
- Golang: Please provide the Go module name (e.g. github.com/example/project）
- Python: Please provide the base package (e.g. wf_integration), used to organize import paths

WfConfig configuration properties (used to generate the WfConfig class, placeholders are prohibited)

The following propertiesmustcollect real values from the user before generating WfConfig.It is strictly prohibitedto generate YOUR_CLIENT_ID and other placeholders in the code for the user to replace themselves.

WF Client ID: Please provide your WorldFirst Client ID
WF User ID: Please provide your WorldFirst login User ID
API Base URL: Please provide the API gateway address (default https://open-sea.worldfirst.com）
Private key file path: Please provide the RSA private key file path (PKCS#8 format), e.g. /etc/wf/certs/private_key.pem
Public key file path: Please provide the WorldFirst RSA public key file path, e.g. /etc/wf/certs/wf_public_key.pem

Important: The values provided by the user are directly filled into the generated WfConfig code. If the user indicates that a value is temporarily uncertain, use a Spring XML property placeholder (e.g. ${wf.clientId}), Go environment variable reading (e.g. os.Getenv("WF_CLIENT_ID")), or Python environment variable reading (e.g. os.environ.get("WF_CLIENT_ID")) instead of hardcoded placeholder strings.

Module-specific questions (ask as needed)

The following questions are asked only when the user selects the corresponding module:

Payee management module：

Integration Mode: Which Payout integration scenario are you using—Card Details mode(pass bank card information directly for each payout) orCard Token mode(bind the payee first to obtain a token)?
- Card Details mode: only need to integrate inquiry-template/(query card template)
- Card Token mode: need to integrate all 6 interfaces

Trade Order Management Module：

Business Scenario: Which business scenarios need to be supported?
- PAY_INTO_CHINA (B2C settlement): need to integrate all 3 interfaces (submitTradeOrder, inquiryTradeOrder, notifyTradeOrder)
- CREATE_B2B_ORDERS (B2B order association): only need submitTradeOrder
- Both: generate the complete suite

Common Dependencies

All modules share the following components, located in references/common/：

Java (references/common/java/)

Component	Path	Description
WfConfig	config/WfConfig.java	Configuration management (clientId, baseUrl, key path, timeout)
WfSigner	signer/WfSigner.java	RSA256 signing/verification
WfHttpClientUtil	util/WfHttpClientUtil.java	HTTP client wrapper (signature injection, response verification)
Result	model/response/Result.java	Unified response result object
WfErrorCode	model/exception/WfErrorCode.java	Error code enumeration
WfException	model/exception/WfException.java	Business exception class

Golang (references/common/golang/)

Component	Path	Description
WfConfig	config/config.go	Configuration management
WfSigner	signer/signer.go	RSA256 signing/verification (Signer interface + implementation)
WfHttpClient	util/wf_http_client.go	HTTP client wrapper
Result	model/response/result.go	Unified response result
WfErrorCode	model/exception/error_code.go	Error code definitions
WfException	model/exception/wf_exception.go	Exception definitions

Python (references/common/python/)

Component	Path	Description
WfConfig	config/wf_config.py	Configuration management
WfSigner	signer/wf_signer.py	RSA256 signing/verification
WfHttpClient	util/wf_http_client.py	HTTP client wrapper
Result	model/response/result.py	Unified response result
WfErrorCode	model/exception/wf_error_code.py	Error code definitions
WfException	model/exception/wf_exception.py	Exception definitions

Common Code Generation Rules

WfConfig: Use the user's real values collected in Pre-Generation Questions (items 4-8) to fill field default values,placeholders are prohibited
Result.java / result.go / result.py: Shared, generated only on first generation, reused if already exists
WfErrorCode: Shared, error codes for new interfaces are appended to the existing file, not generated repeatedly
WfException: Shared, reused if already exists

Code Standards

Java

Java 8 (Java 9+ proprietary syntax is prohibited)
CamelCase class names, lowerCamelCase variable names, UPPER_SNAKE_CASE constant names
Left brace on the same line, 4-space indentation, maximum 120 characters per line
All public methods must have Javadoc, use SLF4J logging

Golang

Standard library first, one file per package
Dependency injection pattern (constructor injection)
{moduleName} Replace the placeholder with the module path from the user's actual go.mod

Python

Python 3.10+, use type hints to annotate parameters and return values
snake_case module names, function names, and variable names, PascalCase class names, UPPER_SNAKE_CASE constant names
4-space indentation, maximum 120 characters per line, follow PEP 8 standards
Use dataclass or ordinary class definitions for Model, attributes use snake_case
Dependency management is declared via requirements.txt , core dependencies:requests>=2.28.0、cryptography>=41.0.0
{basePackage} Replace the placeholder with the user's actual base package name (used for import paths)

Signature Algorithm

All WF APIs use RSA256 signatures. The signature content format is:

POST {apiPath}\n{clientId}.{requestTime}.{requestBody}

See details in references/common/ the signature tool code under.

Test Code Generation

Generate one integration test class for each Client class, calling the WF API for real.

Test Code Specifications

Generate tests only for Client classes: only for *Client.java generate the corresponding *ClientTest.java
Keep only one successful test method: each test class contains only testXXX_Success() one test method
Real HTTP calls: do not Mock HTTP responses; through client.init() initialize real calls to the WF API
Use placeholders for configuration: clientId, key path, etc. use ${wf.xxx} placeholders, configured by the user

POST-GENERATION CHECKLIST

⚠️ Important: after each code generation,mustperform the following checks to ensure code quality and completeness.

1. Model Class Field Consistency Check

Purpose: ensure that the generated Model class fields are completely consistent with the template files, avoiding field omission.

Check Steps：

Traverse all generated Model classes (located in model/domain/、model/request/、model/response/）
Compare each generated class with the corresponding template file (references/{module}/{interface}/{language}/model/, where {language} is java、golang or python）
Check whether the field count, field names, and field types are consistent
Java: check whether Getter/Setter methods are complete; Python: check whether dataclass field or property definitions are complete

Check Command Example：

# 对比生成的 FundMoveDetail.java 与模板
diff generated/FundMoveDetail.java references/statement-management/inquiry-statement-list/java/model/domain/FundMoveDetail.java

2. Unit Test Run Check

Purpose: ensure that the generated code can compile and run normally, with no syntax errors.

Check Steps：

Enter the user project directory
Run the compilation command to ensure there are no compilation errors
Run the generated unit tests to ensure the test cases can execute normally

Expected Results：

Compilation succeeds, no errors
Unit tests can run normally (even if test cases fail, ensure the code can run)

3. Package Name and Import Check

Purpose: ensure that the generated code package names are correct and import statements have no conflicts.

Check Points：

Java: package name matches the path provided by the user; Python: module path matches the project structure
No missing import statements (including in Python from ... import ...）
No circular dependencies

Checklist Execution Record

After each code generation, the reply must include the following check record:

✅ 代码生成后检查完成

1. Model 类字段一致性检查：
   - [x] FundMoveDetail.java - 18个字段，与模板一致
   - [x] StatementRecord.java - 24个字段，与模板一致
   - [x] ForeignExchangeQuote.java - 3个字段，与模板一致
   - [x] OperatorInfo.java - 2个字段，与模板一致
   - [x] Amount.java - 2个字段，与模板一致
   - [x] RelatedStatement.java - 3个字段，与模板一致

2. 单元测试运行检查：
   - [x] 编译成功
   - [x] 单元测试可正常运行

3. 包名和导入检查：
   - [x] 包名正确
   - [x] 导入语句完整

Module Interface Details

WorldFirst Transfer (transfer)

📄 Official Documentation

Interface	Directory	Description	Official Documentation
Inquiry Transfer	consult-transfer/	Get exchange rate, fees, and other information before transfer	📄
Account-to-Account Transfer	create-transfer/	Transfer between WorldFirst accounts	📄
Query transfer result	inquiry-transfer/	Query transfer result (PROCESSING status requires polling)	📄
Transfer result notification	notify-transfer/	Callback notification: receive transfer result notification pushed by WorldFirst (WF → integrator)	📄

Notes:

Transfer is an asynchronous interface,PROCESSING status must be polled
transferRequestId is an idempotency key, same ID + different body → REPEAT_REQ_INCONSISTENT
businessSceneCode Required when transferring between main/sub-account balances MULTI_ACCOUNT_TRANSFER
notifyTransfer is a callback notification interface (WF → integrator), must verify signature then return SUCCESS, business logic handled asynchronously
The callback notification must return a success response, otherwise WorldFirst will retry up to 7 times

Global payout (payout)

📄 Official documentation

API	Directory	Description	Official documentation
Consult payout exchange rate	consult-payout/	Consult fees, validate card template, obtain cross-currency exchange rate quote	📄
Create payout	create-payout/	Payout to bank card or e-wallet	📄
Query payout result	inquiry-payout/	Query payout order status	📄
Payout result notification	notify-payout/	Callback notification: receive payout result notification pushed by WorldFirst (WF → integrator)	📄
Notes:

Supports four payout modes (mutually exclusive):
- Card detail mode (BANK_ACCOUNT_DETAIL) — pass bank card details directly
- Card token mode (BENEFICIARY_TOKEN) — use the token of an already bound beneficiary
- Alipay account detail mode (ALIPAY_CN_DETAIL) — payout to an Alipay account, pass an empty object for paymentMethodMetaData
- Linked Alipay wallet mode (REFERENCE_ALIPAY_CN) — payout to a linked Alipay wallet, pass referenceCustomerId for paymentMethodId
Cross-currency payout must first call consultPayout to obtain quoteId
notifyPayout is a callback notification interface (WF → integrator), must verify signature then return SUCCESS, business logic handled asynchronously
The callback notification must return a success response, otherwise WorldFirst will retry up to 7 times
For complete nested object field definitions, see references/payout/field-reference.md

Beneficiary management (beneficiary)

📄 Official documentation

API	Directory	Description	Official documentation	Language support
Query card template	inquiry-template/	Query the card template field requirements for a specified country/currency/account type	📄	Java、Golang
Bind beneficiary	bind/	Bind a beneficiary to a WF account and obtain beneficiaryToken	📄	Java、Golang
Delete beneficiary	remove/	Delete an already bound beneficiary	📄	Java、Golang
Edit beneficiary	edit/	Modify beneficiary nickname	📄	Java、Golang
Query beneficiary list	inquiry-list/	Paginated query of already bound beneficiaries	📄	Java、Golang
Beneficiary binding notification	notify-bind/	Callback notification: receive beneficiary binding result notification (WF → integrator)	📄	Java、Golang

Account management (account-management)

📄 Official documentation

API	Directory	Description	Official documentation
Query account information	inquiry-account/	Query WF account information (account type, account number, activation status, currency, etc.)	📄
Query balance	inquiry-balance/	Query WF account balance, supports filtering by currency and balance type	📄
Query settlement quota	inquiry-available-quota/	Query declarable settlement quota, supports four accumulation methods	📄
Query sub-account information	inquiry-subuser/	Query WorldFirst main account and sub-account information, supports pagination	📄
Query store information	inquiry-store/	Query store information and store-associated account information, supports pagination	📄
Recharge notification	notify-vostro/	Receive WorldFirst recharge/advance callback notification (WF → integrator)	📄
Balance change notification	notify-balance-change/	Receive WorldFirst balance account transaction change callback notification (WF → integrator)	📄

Notes:

notifyVostro and notifyBalanceChange are callback notification interfaces (WF → integrator), not actively called interfaces
Callback notifications must return a success response, otherwise WorldFirst will retry up to 7 times
inquirySubuser can only be called by the main account; calls from sub-accounts return USER_ACCOUNT_NOT_PRIMARY
Balance value is an integer in the smallest currency unit (e.g., USD 100.00 → value = 10000)

Statement management (statement-management)

📄 Official documentation

Interface	Directory	Description	Official documentation
Query statement transactions	inquiry-statement-list/	Query WF account transaction records with pagination	📄
Query statement details	inquiry-statement-detail/	Query detailed information of a specified statement transaction	📄

Notes:

pageSize is fixed at 10 and cannot be modified by the caller
pageNumber range 1-50
inquiryStatementDetail 's accountingBizNo must be obtained via inquiryStatementList Obtain

Trade information management (trade-order)

📄 Official documentation

Interface	Directory	Description	Official documentation
Submit trade order	submit-trade-order/	Upload trade order (B2C settlement / B2B order association)	📄
Query order result	inquiry-trade-order/	Query upload result (PAY_INTO_CHINA only)	📄
Order callback notification	notify-trade-order/	Handle WF asynchronous callback notification (PAY_INTO_CHINA only)	📄

Notes:

sceneCode determines the set of required fields
tradeOrders limit: B2C up to 100, B2B up to 10
For complete nested object field definitions, see references/trade-order/field-reference.md

Security red lines

⛔ The following rules are thesecurity red linesfor WorldFirst API integration. Violations may cause fund loss or security incidents and must be strictly followed.

Private keys must not be hardcoded: RSA private keys must be loaded via file path or key management service; hardcoding private key content in source code is strictly prohibited.
Private keys must not be logged: Private key content must not appear in any log output, including debug-level logs.
Private keys must not be uploaded to public repositories: Private key files must not be uploaded to public code repositories such as GitHub or GitLab, and must be added to .gitignore。
clientId / secretKey must not be stored in plaintext: clientId and key configuration must be managed through environment variables, a configuration center, or encrypted files; it is prohibited to write them in plaintext in code or commit them to a version repository in configuration files.
Responses must be signature-verified: After receiving a WF API response, the WF public key must be used to verify the signature, confirming that the response came from WorldFirst and preventing man-in-the-middle tampering.
Asynchronous notifications must be signature-verified: After receiving asynchronous callback notifications such as notifyTradeOrder, notifyVostro, notifyBalanceChange, notifyTransfer, notifyPayout, and notifyBindBeneficiary, the signature must be verified before processing business logic to prevent forged notifications.
Idempotency guarantee: Fund-related APIs such as transfers (createTransfer) and payouts (createPayout) must use a unique transferRequestId / payoutRequestId to prevent duplicate deductions caused by retries.
HTTPS mandatory: All API requests must be sent over HTTPS; plaintext HTTP transmission is prohibited.
Transfer/payout results must not be assumed: After initiating a transfer or payout, the final status must be confirmed through a query API (inquiryTransfer / inquiryPayout) or an asynchronous notification; it is prohibited to determine the final result solely based on the status in the request response.
Production keys and test keys must be isolated: The production environment and the test environment must use different clientIds and key pairs, and mixing them is strictly prohibited.

About this skill

Module Index

Quick Decision Tree

Scenario Keyword Matching

Clarification wording

Usage process

Pre-Generation Questions (MUST ASK)

Basic information

WfConfig configuration properties (used to generate the WfConfig class, placeholders are prohibited)

Module-specific questions (ask as needed)

Common Dependencies

Java (references/common/java/)

Golang (references/common/golang/)

Python (references/common/python/)

Common Code Generation Rules

Code Standards

Java

Golang

Python

Signature Algorithm

Test Code Generation

Test Code Specifications

POST-GENERATION CHECKLIST

1. Model Class Field Consistency Check

2. Unit Test Run Check

3. Package Name and Import Check

Checklist Execution Record

Module Interface Details

WorldFirst Transfer (transfer)

Global payout (payout)

Beneficiary management (beneficiary)

Account management (account-management)

Statement management (statement-management)

Trade information management (trade-order)

Security red lines