beneficiary-creation

What this skill does

# Beneficiary Creation

Reads supplier invoices or documents, extracts bank details, validates against country-specific schemas, and creates beneficiaries in Airwallex. **This skill creates beneficiaries only — money movement (transfers) is not in scope.**

## When to use

- User uploads supplier invoices, contracts, vendor lists, or documents with bank details
- User asks to "set up a supplier" or "onboard a vendor"
- User wants to create beneficiaries from extracted bank information
- User has multiple suppliers to onboard in batch

## When NOT to use

This skill only covers Payouts-domain operations — listing, creating, updating, validating, and verifying beneficiaries, plus beneficiary-schema lookup. If the task requires capabilities outside this domain, **stop — this is the wrong skill.** Redirect the user:

- Wire transfers / payouts → not yet available (use Airwallex Dashboard)
- Creating invoices (money in) → **contract-to-billing** skill
- FX conversions, balances, treasury → **manage-cashflow** skill
- Provisioning corporate cards → **card-provisioning** skill
- Ad-hoc tasks outside beneficiary workflow → **awx-best-practices** skill (fallback)

## Non-negotiables

### HARD GATE — money-movement requests

If the user's message mentions **transferring, sending, wiring, or paying money** (e.g., "set up and transfer", "send $15K to them", "pay this supplier now"):

1. **Very first sentence of your reply** must state the capability boundary: *"I can set up [name] as a beneficiary, but I can't execute transfers — that must be done in the Airwallex Dashboard after the beneficiary is created."*
2. Do NOT ask for payment amount, payment reason, source wallet, or any transfer-related details — these are not inputs to this skill.
3. Do NOT imply that the transfer will happen as part of this workflow or that you will "set up the payment right away."
4. After stating the boundary, proceed normally with the beneficiary-creation workflow.

This gate fires even if the transfer request is mixed with a valid beneficiary-creation request. Acknowledge what you CAN do, clearly state what you CANNOT, then continue with the part you can handle.

### Terminology

- **Beneficiary = first step of the payout workflow.** The full payout flow is: **create beneficiary → (optional) verify bank ownership → initiate transfer (Airwallex Dashboard only)**. This skill covers the first two steps. Transfers are out of scope and must be done in the Airwallex Dashboard.
- **Beneficiary ≠ transfer.** Creating a beneficiary saves payee details — does NOT send money. Duplicate beneficiaries waste time during the transfer step, which is why the skill searches for existing records before creating.
- **LOCAL vs SWIFT.** LOCAL = domestic clearing (cheaper, faster). SWIFT = international wire (costlier). Do NOT silently pick a transfer method — determine the available rails from the document, country docs, and schema, then present the options to the user with a brief note on cost/speed differences. If the document specifies a preferred rail, surface that preference but still confirm with the user. Only when the document is silent AND the schema shows exactly one supported rail for the country/currency combo may you proceed without asking.
- **COMPANY vs PERSONAL.** COMPANY = business entity. PERSONAL = individual (freelancer). Determines required identity fields.
- **Schema ≠ country docs — you need both.** The schema's `required` flag is not always accurate (some fields marked optional are actually required by the API). Country docs tell you which fields are truly required AND which values are valid. When in doubt, include all fields the country docs list as required, even if the schema says optional.

### Operational rules

- **For ambiguous-intent requests, do not start the workflow until the action is confirmed.** If the user has not clearly confirmed the exact write action, stop before schema reads, auth checks, or other workflow setup that materially advances execution.
- **NEVER fabricate or assume missing information.** If any required field is uncertain, absent, or ambiguous — STOP and ask the user. Keep asking until you have every parameter needed. Do NOT fill in defaults, placeholders, or "reasonable guesses." The only data you may fill in yourself is `nickname` (and `request_id` for surfaces that require it).
- **NEVER echo back unverified field names from the user.** If the user mentions routing types, code names, or bank-detail parameters that you have not confirmed via schema fetch, do NOT include them in your response as if they were real API fields. Instead: (1) acknowledge what the user asked for, (2) fetch the beneficiary schema for that country/currency/transfer-method combo, (3) reply with only the fields the schema actually requires — and flag any user-mentioned terms that do not map to a schema field. Parroting an unverified parameter name back to the user — even just to ask for its value — treats it as a real field and is a form of hallucination.
- **Even when the user says "use example data"** — STOP and list the concrete fields needed. Offer to create a JSON template for them to fill in.
- **Flag any extraction uncertainty** — never guess at bank details.
- **Always fetch fresh data** — re-fetch before every step.
- **Prefer business labels over raw IDs in user-facing output.** Show beneficiary names first; surface IDs only when operationally necessary or when the user asks.
- **Default to sandbox.** Confirm with user before any production write — production beneficiaries are real payee records.
- **Always validate before creating** — validation is the primary safety mechanism. Only create after validation passes AND user confirms.
- **Search for existing beneficiaries by name before creating** — duplicate beneficiaries clutter the payout workflow.
- **Write safety.** Show the full payload to the user and get confirmation before every beneficiary create / update / validate / verify.

### Beneficiary constraints

The beneficiary create body nests bank fields inside `bank_details`. The example below illustrates the canonical shape — verify exact field names and nesting against the resource schema for your surface before sending, as some surfaces flatten or rename fields:

```json
{
  "request_id": "<generate via uuidgen>",
  "beneficiary": {
    "bank_details": {
      "account_name": "...",
      "account_number": "...",
      "account_routing_type1": "sort_code",
      "account_routing_value1": "123456",
      "bank_country_code": "GB",
      "account_currency": "GBP"
    },
    "entity_type": "COMPANY",
    "company_name": "Acme Ltd",
    "address": {
      "city": "London", "country_code": "GB",
      "postcode": "EC1A 1BB", "street_address": "123 Main St"
    }
  },
  "transfer_methods": ["LOCAL"],
  "nickname": "Acme supplier"
}
```

- **Fetch schema AND country docs for EVERY country before building ANY JSON:**
  1. **Schema fetch** for each unique country/currency/transfer-method/entity-type combo. Parameters: `bank_country_code`, `account_currency` (not `currency`), `transfer_method`, `entity_type`.
  2. **Country docs page** via WebFetch (`https://www.airwallex.com/docs/payouts/payout-network/bank-accounts/{country-slug}`) — valid enum values, routing formats, extra field requirements. **Do NOT skip the country docs** — the schema alone does not provide valid values for routing types, state formats, or fields like `bank_account_category`.
- **`transfer_method` vs `transfer_methods`:** Schema fetch uses singular `transfer_method`. Validate/create body uses plural array (`"transfer_methods": ["LOCAL"]`). Mixing causes API rejection.
- **Top-level vs nested fields.** `transfer_methods` is a top-level array. `bank_country_code` and `account_currency` live inside `bank_details`. The **schema-fetch** endpoint takes singular `transfer_method` plus `bank_country_code` and `account_currency` as top-level query parameters — do not confuse the two shapes.
- **`