Cards and Spend
Card management
ramp-card-management
CLIMCP
Inspect a user's actual card status, then activate or safely lock/unlock a card. Use for card status, card lock questions, physical card activation, and card lock/unlock actions. For cards locked by overdue tasks, use ramp-complete-tasks to resolve the sanction before re-checking the card.
Skill definition
SKILL.md
--- name: ramp-card-management area: Cards and Spend supported_surfaces: [cli, mcp] description: |- Inspect a user's actual card status, then activate or safely lock/unlock a card. Use for card status, card lock questions, physical card activation, and card lock/unlock actions. For cards locked by overdue tasks, use ramp-complete-tasks to resolve the sanction before re-checking the card. --- # Card Management ## Non-Negotiables - Use `ListCards` to inspect cards. Do not substitute a funds/spend-allocation listing: funds and cards are different entities. - A card whose underlying lifecycle state is `ACTIVE` can still be locked and unable to spend. Never report spendability from lifecycle state alone. - Treat `is_spendable`, `active_locks`, and `blocking_task_count` as the live effective status. Follow each lock's `remediation_action`; an overdue-task sanction routes to `ramp-complete-tasks` rather than repeated manual unlock. - Pass `--agent` for machine-readable JSON output whenever you need to count or inspect returned fields programmatically. - Report the fields returned by the API. Do not invent card lifecycle states. - After every activation or unlock attempt, call `ListCards` again for the same cardholder and exact card UUID. Do not claim success until the postcondition reports `is_spendable: true`. ## Workflow ### Step 1: Inspect card status MCP: ```text ListCards(rationale="Inspect the user's card and effective lock status") ``` CLI: ```bash ramp cards list --rationale "Inspect the user's card and effective lock status" --agent ``` In `--agent` mode the response is wrapped in the standard envelope. Card records live in the returned `cards` array. Admins and managers can inspect a visible employee's cards by passing that cardholder's UUID. Resolve the UUID first, then pass `cardholder_user_uuid`. ```bash ramp users org-chart --rationale "find the employee's user UUID" --agent ramp cards list --cardholder_user_uuid "USER_UUID" --rationale "Inspect this employee's card and effective lock status" --agent ``` ### Step 2: Interpret effective status Match the intended card by its `id`, `last_four`, `display_name`, and cardholder. Inspect its effective lock fields before acting: - `is_spendable: false` means the card cannot spend even if `card_state` is `ACTIVE` or `is_locked` is false. - `active_locks` lists every effective `CARD` or `SPEND_ALLOCATION_MEMBER` lock with its `lock_source` and `remediation_action`. - `blocking_task_count` is the number of outstanding tasks blocking spending. - `GET_ATTENTION_FEED`: load `ramp-complete-tasks`; do not use `LockOrUnlockCard` to bypass the sanction. - `LOCK_OR_UNLOCK_CARD`: continue to the normal lock/unlock flow below only when the card reports `can_unlock=true`. When it is false, do not attempt the unlock; explain each active lock's scope and `remediation_action` instead. - `UNLOCK_FRAUD_LOCKED_CARD`: use the fraud-specific unlock workflow returned by the tool. The existing result is `FraudLockDetected`. - `CONTACT_RAMP`: stop automated unlock attempts and hand the returned lock details to Ramp support. ### Step 4: Activate a physical card First call activation by the physical card's last four digits without `--confirm_delivery`: ```bash ramp cards activate --last_four 1234 --rationale "activate the user's new physical card" --agent ``` If the result says delivery confirmation is required, ask the user to confirm that the physical card has arrived. Only after they confirm, retry with `--confirm_delivery`: ```bash ramp cards activate --last_four 1234 --confirm_delivery --rationale "user confirmed their physical card arrived" --agent ``` Do not ask about delivery or set `--confirm_delivery` unless the first call says it is required. ### Step 5: Lock or unlock a card Before locking or unlocking, inspect and show the user the affected card and ask for explicit confirmation; before locking, also explain that it will block all transactions until the card is unlocked. Run the command only after the user confirms. Do not infer confirmation from a report of suspicious activity or a lost card. Before unlocking, re-run `ListCards`. If any lock's `remediation_action` is `GET_ATTENTION_FEED`, stop this manual flow and load `ramp-complete-tasks`. If `is_spendable` is already true, report the live state without a redundant write. Lock or unlock a card by its id. The id is a required positional argument: ```bash ramp cards lock 7f3c0d2a-9b1e-4a55-8c21-0e9d6b2f4a10 --action lock --rationale "user lost their card" --agent ramp cards lock 7f3c0d2a-9b1e-4a55-8c21-0e9d6b2f4a10 --action unlock --rationale "user found their card" --agent ``` After either write, re-run `ListCards` for the same cardholder. For unlock, the postcondition passes only when the exact card reports `is_spendable: true`. A successful unlock response, `is_locked: false`, or an underlying `ACTIVE` lifecycle state is not sufficient. If normal unlock returns `CardUnlockBlocked`, it is a typed failed precondition, not a partial success. Report its `remaining_locks` and `blocking_task_count`; the returned card remains `is_locked: true` and `is_spendable: false`. Follow each remaining lock's remediation action instead of retrying the same unlock. ## Fields To Inspect | Field | Meaning | |---|---| | `id` | Card UUID used for card actions | | `last_four` | Last four digits used to identify the card | | `display_name` | Card display name when returned | | `card_type` | Physical Ramp card or virtual card | | `card_state` | Underlying/effective lifecycle state; never sufficient alone to prove spendability | | `activation_status` | Whether the card is active, pending delivery, awaiting confirmation, or blocked | | `is_locked` | Live effective lock indicator | | `is_spendable` | Authoritative result for whether the card can currently spend | | `active_locks` | Effective locks, including `lock_type`, `lock_source`, and `remediation_action` | | `blocking_task_count` | Number of attention-feed tasks currently blocking card spending | ## Example Session ``` User: Why can't I use my card? Agent: > ramp cards list --rationale "Inspect the user's card and effective lock status" --agent Agent: This card is locked by an overdue Ramp task. Its underlying lifecycle state does not make it spendable. I'll load `ramp-complete-tasks`, resolve the outstanding item with you, and then re-check this exact card before saying it is unlocked. ``` ## Gotchas | Issue | Fix | |---|---| | Card lifecycle state is `ACTIVE`, but `is_spendable` is false | The card cannot spend; follow `active_locks[].remediation_action` | | Remediation is `GET_ATTENTION_FEED` | Load `ramp-complete-tasks`; do not repeat manual unlock | | `CardUnlockBlocked` | Report `remaining_locks` and `blocking_task_count`, then follow their remediation actions | | Unlock call succeeded, but the re-check is not spendable | Report the remaining locks and do not claim success | | Need another employee's cards | Resolve their user UUID and pass `cardholder_user_uuid` to `ListCards` | | Something broken? | With the user's consent, run `ramp feedback "<user-approved message>"`. This sends only that message to Ramp support; omit secrets and diagnostic artifacts. |