Customer Management

Store your payer's identity and their saved payment methods. The customer object connects your system to Wonder's payment infrastructure — use it when you need saved-card checkout, recurring billing, or batch MIT processing.

Customer

A customer represents a payer in your system. You can create orders without a customer, but if you need saved payment methods or recurring charges, Customer Management is required.

Field	Required	Description
UUID	`Output`	Wonder-generated unique customer identifier. Use this UUID in all subsequent API calls — creating orders, fetching tokens, generating wallet links.
Reference_number	`Yes`	Your system's unique customer ID. Creating a customer with the same `reference_number` updates the existing record instead of creating a duplicate. Max 255 characters.
Name	`Yes`	The customer's display name. Max 255 characters.
Email	`No`	Customer email address. Invoices are sent to this address. Max 255 characters.
Dial_code	`No`	Country calling code (e.g. `+852` ). Max 6 characters.
Phone	`Yes`	Customer phone number. Max 255 characters.
Company_name	`No`	Customer's company name. When filled, `linked_source_type` becomes `Store` instead of `User`. Max 255 characters.
Default_payment_method	`No`	`Credit Card`,`Wechat Pay`,`Alipay`.
Default_payment_token	`No`	UUID of a saved payment token to use as the customer's default. Must belong to this customer.

json

{
  "customer": {
    "name": "Chan Tai Man",
    "email": "chantaiman@example.com",
    "dial_code": "+852",
    "phone": "61234567",
    "company_name": "ABC Trading Ltd",
    "default_payment_method": "Credit Card",
    "reference_number": "CUST-20250629-001"
  }
}

TIP

Linked to orders: Pass customer_uuid when creating an order to associate it with a customer. The order then has access to the customer's saved payment tokens, and the Payment Link page shows saved cards for faster checkout.

Payment tokens

A payment token is a stored representation of a customer's card — created when the customer completes a payment via Payment Link, or Wallet Link. Once saved, you can reference the token in any subsequent API call instead of handling raw card numbers.

Field	Required	Description
Token_type	`Output`	The type of saved payment method: `CreditCard`, `WechatPayAutoDebit`, or `AliPayAutoDebit`.
Token	`Output`	The token value. Pass this in payment requests, recurring plans, or MIT batch files.
State	`Output`	Current state of the token (e.g. `success`). Check this before using the token for charges.
Default	`Output`	Whether this token is the customer's default payment method.
Number	`Output`	Masked card number.
Exp_month	`Output`	Expiration month.
Exp_year	`Output`	Expiration year.
Holder_name	`Output`	Name on the card.
Brand	`Output`	Card network (e.g.`Visa` , `Mastercard`).
Billing_currency	`Output`	Currency the card is billed in (e.g. `HKD`).

TIP

Where tokens are used: Recurring plans auto-charge the saved token on each billing cycle. Batch MIT expectstoken_id in each CSV row — use tokens instead of raw card details for better security and PCI compliance.

Wallet link

Generate a hosted URL where customers can self-manage their payment methods — add, view, or remove cards without involving your support team.

Field	Required	Description
Customer_uuid	`Yes`	The customer who owns this wallet.
Expires_at	`No`	UTC timestamp when the link expires (e.g. `2026-01-01T01:02:03Z`). After expiry the link is no longer accessible.
Redirect_url	`No`	Where to redirect the customer when they click the Back button on the wallet page.
Exp_redirect_url	`No`	Auto-redirect to this URL when the link expires while the customer is on the page.
Mode	`No`	Set to `create_only` to open the wallet directly in add-card mode, skipping the card list view. Requires `redirect_url`.
Options.hide_default_card_element	`No`	Set to `true` to hide the Set-as-default checkbox on the wallet UI.

text

POST /svc/payment/api/v1/openapi/customers/wallet/link

{
  "customer": {
    "customer_uuid": "feac5c50-010a-4582-a84a-673357245ffb",
    "expires_at": "2026-07-01T00:00:00Z",
    "redirect_url": "https://yourapp.com/payment-methods"
  }
}

// Response
{
  "data": {
    "konnect_link": "https://your.domain/wallet/abc123..."
  }
}

INFO

Typical flow: Create a customerAPI → generate a wallet linkAPI→ share the URL with the customer → customer adds a card → the card is saved as a payment token on their profile → use the token for one-click Payment Link checkout, Recurring plans, or Batch MIT files.

Create a customer wallet linkAPI
Generate a hosted URL where customers can self-manage their payment methods — add, view, or remove cards. Configure expiry, redirect URLs and optional create-only mode.

Create a customerAPI

Register a new customer using your reference_number as the unique key. Wonder returns a customer_uuid. If the reference_number already exists, the existing record is updated instead — this provides idempotent create-or-update behaviour.

Get customersAPI
Get a customerAPI

Look up a single customer by customer_uuid or reference_number. List all customers with optional filtering by linked_source_type (User for individuals, Store for companies). Paginated via offset / limit.

Edit a customerAPI

Edit a customer's profile by customer_uuid. All fields except reference_number can be changed. Payment tokens are not affected by profile edits.

Delete a customerAPI

Permanently remove a customer by customer_uuid. This operation is irreversible.

Get customer payment tokensAPI
Get business payment tokensAPI

List all saved cards for a customer by customer_uuid, or across your entire business. Optionally filter by token_type (Credit Card, Wechat Pay, Alipay). Each token can be used directly in order creation, recurring plans, or MIT batch files.

Delete a payment tokenAPI

Permanently remove a stored card by token_uuid, subsequent charges referencing a deleted token will fail — ensure no active recurring plan depends on it.

Check payment token stateAPI

Verify the current state of a token before using it for a charge.

Customer

Payment tokens

Wallet link

Related APIs