card-provisioning

What this skill does

# Card Provisioning

Creates virtual or physical corporate cards in Airwallex Issuing — one workflow to set up a cardholder, issue a card with spend limits, and optionally manage ongoing spend.

**Tone:** The target user is a busy entrepreneur, not a finance analyst. Keep language conversational and action-oriented — say "Your Adobe card is set up with a $50/month limit" rather than "Card ID card_xxx created with authorization_controls.transaction_limits.limits[0].amount = 50.00." Show business labels (card nicknames, cardholder names) first; keep raw IDs and technical details in the background unless the user asks for them.

## When to use

- User asks to create a virtual or physical card
- User wants to set up a card for a specific purpose (e.g., "card for Adobe", "travel card")
- User needs to provision cards for team members (batch)
- User wants to update card limits or review card spend
- User asks "what are we spending on software cards?" or wants spend aggregation by category

## When NOT to use

This skill only covers Issuing-domain operations (cards, cardholders, issuing-transactions). If the task requires anything outside that domain, **stop — this is the wrong skill.** Redirect the user:

- Viewing sensitive card details (PAN, CVV) → direct to Airwallex Dashboard
- Wire transfers / payouts → not yet available (use Airwallex Dashboard)
- Setting up suppliers / beneficiaries → **beneficiary-creation** skill
- Creating invoices → **contract-to-billing** skill
- FX conversions, balances, treasury → **manage-cashflow** skill
- Ad-hoc tasks outside card workflow → **awx-best-practices** skill (fallback)

## Non-negotiables

### Terminology

- **Cards draw from the account's currency balance — no "card balance."** Say "$X/month limit" or "$X drawn this month."
- **Cardholder ≠ Card.** One cardholder can have multiple cards. Match or create cardholder first.
- **`AUTHORIZED` ≠ money moved.** It's a hold. `CLEARED` = money left. Be explicit when reporting.
- **Spend limits are always per interval + currency.** Say "$50.00 per month in USD."

### 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, placeholder values, or "reasonable guesses."
- **Flag generic or test-like cardholder names.** If all cards in a batch share the same cardholder name, or the name appears generic/test-like (e.g., "Test Account", "Demo User", "Admin", "Card 1"), flag this as unusual and ask the user to confirm before proceeding. In production, generic names are a high-risk fraud signal.
- **Always fetch fresh data** — re-fetch before every step.
- **Prefer business labels over raw IDs in user-facing output.** Show cardholder names and card nicknames first; surface IDs only when operationally necessary or when the user asks.
- **One wallet, multiple currencies.** Say "AUD balance" — never "AUD wallet."
- **Default to sandbox.** Confirm with user before any production write.
- **Always set a spend limit** — never create an unlimited card. Every card must have an explicit limit amount, currency, and interval.
- **Always require a purpose/nickname** for each card.
- **Never handle or display PAN, CVV, or expiry.** Direct user to the Airwallex Dashboard — this is the **sole** channel for viewing sensitive card data. When refusing PAN/CVV/expiry requests, do NOT mention any get-card endpoint, SDK, or alternative technical path as a partial workaround. Frame the refusal as a platform-level security boundary: sensitive card details are never accessible through the agent in any form — even masked. Mentioning other APIs weakens the security message.
- **Do NOT invent advanced card-control fields** (MCC restriction, merchant controls, etc.) — see "Card & cardholder constraints" below.
- **Write safety.** Show the full payload to the user and get confirmation before every card create / update / cardholder create. **Confirm row-by-row in a batch** — never get a single up-front "yes" and then issue the rest unattended. Batch template previews do NOT count as confirmation — confirm and execute each individual payload (per cardholder, per card).
- **Never retrieve full card details via API.** Direct user to the Airwallex Dashboard.
- **Before increasing limits, show current spend vs limit first** — fetch the card's current limits and recent spend via the card-limits / transactions endpoints.
- **Flag unusual spend patterns** — alert if spend jumped 3x+ vs previous period.
- **Flag cards approaching their limit** — if utilization is ≥ 80%, proactively warn and offer to adjust (e.g., "Your AWS card is at $412 / $500 (82%) — want me to increase it?").
- **Confirm card spec before creating** — **production cards spend real money immediately**.
- **Search for existing cardholder by email before creating** — avoid duplicates.
- **Never fabricate cardholder or card IDs.** If the user gives a placeholder ID, list cardholders or cards to find the real UUID.
- **Batch requests:** if the user gives names/emails but no `form_factor`, currency, interval, or program purpose, ASK ONCE for shared defaults before creating. Process rows sequentially — never in parallel.
- **Card and cardholder IDs are UUIDs** — never use placeholders like `card_abc` or `cardholder_xyz`. If you only have a name or label, look up the real UUID first.

### Card & cardholder constraints

- **`created_by`** — full legal name of the **person requesting** the card, not the cardholder. Ask the user if unspecified.
- **`is_personalized`** — VIRTUAL → `false`, PHYSICAL → `true`. Ask the user if the form factor is unspecified; do not default silently in production.
- **Body shape differs by surface.** Use the templates in [references/card-templates.md](references/card-templates.md) — do NOT build the payload incrementally or guess fields. Verify the exact field shape against the resource schema for your surface before sending. Common pitfalls (`MULTIPLE` vs `MULTI`, `program` wrapper vs flat fields, `authorization_controls` nesting) are catalogued in [api_traps.md](../awx-best-practices/references/api_traps.md).
- **Merchant category / MCC restriction support is unconfirmed in this workflow unless explicitly documented.** Do NOT invent fields like `allowed_categories`. Only claim the restriction was applied if the API response explicitly shows the enforced control.
- **INDIVIDUAL cardholder quirks** (not surfaced by schema or manifest): `individual.address` uses `country` (not `country_code`); `individual.express_consent_obtained` is the string `"yes"` (not boolean `true`). Ask the user for DOB, address, and email — never fabricate.
- **DELEGATE cardholder** has minimal fields — no DOB or address required.
- **Physical-card delivery is create-time only.** The card-update operation does NOT accept `postal_address` or `delivery_details` — if either is wrong after creation, close and re-issue. Two valid paths at create time: (a) cardholder has a registered `postal_address` and card create uses it by default; (b) pass `postal_address` directly on card create to override. For EXPRESS shipment (or any China destination), `delivery_details.mobile_number` (E.164) is required. Always confirm the address with the user.
- **Physical cards are created `INACTIVE`** — activate after delivery via the card-activate operation.
- **Authorizations vs transactions:** there is no separate authorizations resource — list issuing-transactions with `status: AUTHORIZED` to see pending holds.
- **Spend aggregation is manual.** No built-in category filter or `cards spending` endpoint — list transactions per card (filter by `card_id`)