Payout Management

Programmatically send money from your Wonder Wallet to bank accounts via FPS, RTGS, or SWIFT. Register a payee once with their bank details, then create payout requests — one-off or scheduled — to transfer funds. Track each transfer through its full lifecycle via webhook callbacks.

Workflow

A payout always starts with a payee. Register it once, then reference its ID in every transfer.

1. Call create payee with the recipient's bank details and transfer method. The response returns a payee.id(UUID).
2. Call create payout request for a transfer.
3. Call retrieve a payout request by payout_requests.id for full payout details, including current transfer_status, and you can receive the webhook on each transfer status change, And need to configure your webhook destination in Wonder dashboard first. Then Wonder will send the webhook to your webhook destination that you configured.

Payee

A payee is the recipient of funds. Register their bank details and transfer method once, then reference their ID in every payout request.

Field	Required	Description
Type	Yes	Business or People.Determines whether company_name (Business) or date_of_birth (People + FPS) is required.
Nickname	Yes	Display name in the Wonder App. Max 50 characters.
Email	Yes	Payee email address. Max 100 characters.
Phone_country_code	Yes	Country calling code (e.g. +852).
Phone_number	Yes	Phone number.
Company_name	No	Required when type = Business. Max 120 characters.
Payout_category_name	Yes	Payout purpose: Related Company Transfer, Capital Investment, or Office Supplies.
Country	Yes	Payee's country code (e.g. HK).
Currency	Yes	Currency of the receiving account (e.g. HKD, USD).
Transfer_method	Yes	HK FPS - Account Number, HK FPS - Mobile, HK FPS - Email, HK FPS - FPS ID, RTGS, or SWIFT.
Date_of_birth	No	Required when transfer_method is FPS and type = People. ISO date format (2000-10-24).

Transfer methods

Wonder supports transfers to both local and abroad.

Transfer Method	Type	Currency	Speed	Notes
FPS	External	HKD/CNY	Minutes to hours	Hong Kong Faster Payment System. Supports transfers via account_number, mobile_number, e-mail, or FPS-ID.
RTGS	External	HKD/CNY/USD	T+1	Real Time Gross Settlement. Typically used for larger-value bank transfers in Hong Kong.
SWIFT	External	Any supported currency	1-3 business days	International wire transfers. Requires SWIFT/BIC code and account details.

info

Choose one transfer method: Only populate one transfer_method for one payee and one payout request.

Payout request

Field	Required	Description
Payee_id	Yes	ID returned by the Create Payee API.
Currency	Yes	Which Wonder Wallet currency to deduct from(e.g. HKD, USD).
Amount	Yes	Transfer amount(e.g. 1000.00).
Reference_id	No	Your system's unique ID. Max 80 characters.
Remark	No	Note sent to the payee's bank. Max 120 characters.
Schedule_at	No	Scheduled transfer time in ISO 8601 UTC format (e.g. 2025-11-29T15:30:00Z). Omitting this executes the transfer immediately.

Transfer status

Status	Description
Initiated	Request created; not yet submitted to the bank network.
Processing transfer	Request is being processed by the bank or payment network.
Settled	Transfer completed successfully. Funds have reached the payee.
Reversed	Transfer was cancelled — either manually rejected or by the system for internal reasons.
Refunded	Bank rejected the transfer after it was sent. An additional pay-in is generated to return the funds to your wallet.
Terminated	Request permanently stopped before processing.

info

Reversed vs Refunded

Reversed: The transfer never reached the bank network. Funds return directly to your wallet.

Refunded: The bank received the funds but rejected the transfer. An additional pay-in transaction is created to restore the balance.

Payout webhook

Wonder sends real-time webhooks to your webhook destination that you configured on Wonder dashboard at every stage of a payout's lifecycle. Use these webhook to track transfers without polling.

Action	When it trrigers
Payout_request.created	A payout request is successfully submitted.
Payout_request.processing transfer	Request is being processed by the bank or payment network.
Payout_request.settled	The transfer completed. Funds have reached the payee's bank account.
Payout_request.reversed	The transfer was reversed by the system for internal reasons. Funds return to your wallet.
Payout_request.refunded	The bank received the funds but rejected the transfer. An additional pay-in transaction is created to restore your wallet balance.

The webhook format for payout request

{
    "payout_request": {
        "id": "1a2b3c4d-1111-2222-3333-444455556666",
        "reference_id": "INV-2026-0001",
        "payee_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "amount": "100.50",
        "currency": "HKD",
        "fee_amount": "1.50",
        "fee_currency": "HKD",
        "remark": "Invoice payment",
        "transfer_method": "HK FPS - Account Number",
        "transfer_status": "Settled",
        "schedule_at": null,
        "error_code": "",
        "error_message": "",
        "settled_at": "2026-07-22T04:05:00Z",
        "reversed_at": null,
        "refunded_at": null,
        "cancelled_at": null,
        "created_at": "2026-07-22T04:00:00Z",
        "updated_at": "2026-07-22T04:05:00Z"
    }
}

Related APIs

Create payee

Register a recipient with their bank details and transfer method. Returns a payee.id (UUID) that you reference in every payout request. Payees persist — create once, reuse indefinitely.

Get a payee

Retrieve a payee's full details — including bank account information and transfer method — by payee_id.

Delete a payee

Soft-delete a payee — sets deleted_at without permanently removing the record.

Create a payout request

Initiate a transfer by referencing a payee.id and other required fields. Optionally set schedule_at for a future transfer.

Get a payout request

Retrieve a payout request's full details and the linked payee information.

Cancel a scheduled payout request

Cancel a payout that hasn't been executed yet. Once cancelled, the transfer will not proceed.