Wonder
post/api/v1/openapi/payees

Create payee

Create a Payee and its PayoutAccount.

Idempotent reuse

If a payee under the current business already exists with the same transfer_method, country, currency, and payout-account details for that method (see matrix below), the API returns the existing payee id with a success response and does not create a new payee.

Matching is scoped to the current business.

Conditional field matrix

transfer_methodRequired block
HK FPS - Account Numberpayee.payout_account.hk_fps.bank_account (bank_code / account_name / account_number)
HK FPS - Mobilehk_fps.mobile + hk_fps.full_name
HK FPS - Emailhk_fps.email + hk_fps.full_name
HK FPS - FPS IDhk_fps.fps_id + hk_fps.full_name
RTGSrtgs.bank_account (swift_code / account_name / account_number)
SWIFTswift.bank_account (swift_code / account_name / account_number)

date_of_birth condition

When payee.type = People and transfer_method is one of the HK FPS methods below, payout_account.date_of_birth is required:

  • HK FPS - Account Number
  • HK FPS - Mobile
  • HK FPS - Email
  • HK FPS - FPS ID

Format: YYYY-MM-DD.

Header parameters

X-Skip-Signature
string

Example: TRUE

Signature
string

Example: good

Credential
string

Example: {{credential}}

x-request-id
string

Example: {{$string.uuid}}

x-i18n-lang
string

Example: zh-CN

Content-typerequired
string

Example: application/json

Request body · application/json

required
object

In the current implementation, email / phone / nickname are always validated; empty values fail, so they are documented as required. `company_name` is optional.

typerequired
enum<string>

Payee type. - `People`: individual; for HK FPS methods, `date_of_birth` is typically required - `Business`: company

PeopleBusiness

Example: People

emailrequired
string<email>

Contact email. Required; max 100 characters; must pass email format validation. Failure → `810002 Invalid email`.

Example: alice@example.com

nicknamerequired
string

Nickname. Required; max 50 characters (runes). Empty or too long → `810004 Invalid nickname`.

Example: Alice HK

company_name
string

Company / entity name. Optional; when provided, max 120 characters (runes). Too long → `810005 Invalid company name`.

Example: Alice Trading

phone_numberrequired
string

Phone number (without country code). Validated together with `phone_country_code`. Failure → `810003 Invalid mobile number`.

Example: 91234567

required
object
phone_country_coderequired
string

Phone country code (without `+`). Validated together with `phone_number`. Failure → `810003 Invalid mobile number`.

Example: 852

payout_category_namerequired
enum<string>

Payout category name. Must exist in `revenue_expense_categories.category_name`. Empty or not found → `810000 Invalid category`.

Other Staff ExpensesOther InvestmentMiscellaneous ExpensesMerchant DisbursementMedical ServicesLoan RepaymentInventories & SuppliesGoods TradeGeneral Office OverheadsCharitable DonationCapital InvestmentWonder Extended ServicesTaxesStaff TrainingRelated Company TransferProfessional ServicesOffice SuppliesPayrollWonder Treasury ServicesTravel ExpensesTransportationSubscriptionStaff AccommodationRent & Management FeePensionLogistics Expenses

Example: Merchant Disbursement

Responses

Created successfully, or the existing payee `id` when the same payout-account details already exist under the current business (idempotent reuse).

coderequired
enum<integer>

Always 200 on success

200

Example: 200

messagerequired
enum<string>

Always succeed on success

succeed

Example: succeed

object
required
object
Next Delete (archive) payee