Card Management

Card Management

Use this skill when the user needs to create virtual cards, view card details, or manage card lifecycle (lock, unlock, cancel).

Available Tools

• list_card_wallets — List all MasterPay card wallets and balances (required before card creation) | GET /api/v1/masterpay/wallets | Requires auth
• create_single_use_card — Create a single-use virtual card for a one-time purchase | POST /api/v1/masterpay/cards/single-use | Requires auth
• create_multi_use_card — Create a multi-use virtual card for repeated purchases | POST /api/v1/masterpay/cards/multi-use | Requires auth
• list_cards — List all cards in a wallet (defaults to first wallet) | GET /api/v1/masterpay/wallets/cards | Requires auth
• list_cards_by_wallet — List cards for a specific wallet UUID | GET /api/v1/masterpay/wallets/:wallet_uuid/cards | Requires auth
• get_card — Get details of a specific card by UUID (includes card ATM PIN, no transaction PIN required) | GET /api/v1/masterpay/cards/:id | Requires auth
• get_card_details — Get full unmasked card number, CVV, and expiry (sensitive) | POST /api/v1/masterpay/cards/:id/details | Requires auth | Requires transaction PIN
• get_card_types — Get available card types and their properties | GET /api/v1/masterpay/cards/types | Requires auth
• lock_card — Lock (block) a card to prevent transactions | POST /api/v1/masterpay/cards/:id/lock | Requires auth | Requires transaction PIN
• unlock_card — Unlock (reactivate) a previously locked card | POST /api/v1/masterpay/cards/:id/unlock | Requires auth | Requires transaction PIN
• cancel_card — Permanently cancel (suspend) a card | POST /api/v1/masterpay/cards/:id/cancel | Requires auth | Requires transaction PIN
• list_applied_cards — List all card applications and their status | GET /api/v1/cards | Requires auth
• get_applied_card — Get details of a specific card application | GET /api/v1/cards/:id | Requires auth
• apply_card — Apply for a new payment card (physical or virtual) | POST /api/v1/cards/apply | Requires auth

Recommended Flows

Create a Virtual Card (MasterPay)

Create a single-use or multi-use virtual card via MasterPay

1. Check KYC status: GET /api/v1/masterpay/kyc/status — must be 'approved' (use get_kyc_status from kyc-identity skill)
2. List wallets: GET /api/v1/masterpay/wallets — verify at least one wallet exists (no wallets means KYC is not yet approved)
3. Create card: POST /api/v1/masterpay/cards/single-use or /multi-use — returns masked PAN and card ATM PIN
4. Get full details: POST /api/v1/masterpay/cards/:id/details (requires transaction PIN) — returns full card number and CVV

Apply for a Card

Apply for a new physical or virtual card via the card application flow

1. Get card types: GET /api/v1/masterpay/cards/types — see available types (silver, gold, titanium, hybrid_metal, digital_virtual, digital_virtual_2)
2. Apply: POST /api/v1/cards/apply with {card_type, delivery_method, full_name, phone_number, email, address?}
3. Track: GET /api/v1/cards/:id — check application status

Rules

• KYC must be approved before creating any MasterPay card — card creation fails with NO_WALLETS if KYC is not complete
• MasterPay card responses include a masked PAN and the card ATM PIN — use /cards/:id/details with transaction PIN for the full card number and CVV
• The card ATM PIN (visible in get_card, list_cards, and card creation responses) is for ATM/POS use — it is different from the transaction PIN used for sensitive operations
• Lock/unlock/cancel operations require transaction PIN verification
• Cancelled cards cannot be reactivated — cancellation is permanent
• Card application (POST /cards/apply) requires card_type (silver/gold/titanium/hybrid_metal/digital_virtual/digital_virtual_2) and delivery_method (delivery/on_the_spot)
• Card application (/cards/apply) is for ordering new cards — use /masterpay/cards/single-use or /multi-use for instant virtual card creation

Agent Guidance

Follow these instructions when executing this skill:

• Always follow the documented flow order. Do not skip steps.

• If a tool requires authentication, verify the session has a valid bearer token before calling it.

• If a tool requires a transaction PIN, ask the user for it fresh each time. Never cache or log PINs.

• Never expose, log, or persist secrets (passwords, tokens, full card numbers, CVVs).

• If the user requests an operation outside this skill's scope, decline and suggest the appropriate skill.

• If a step fails, check the error and follow the recovery guidance below before retrying.

• KYC must be approved before creating any MasterPay card. Use get_kyc_status from the kyc-identity skill to verify, then list_card_wallets to confirm a wallet exists. If no wallets exist, KYC is not yet approved.

• MasterPay card responses (creation, get_card, list_cards) include the card ATM PIN in the response — no transaction PIN is needed to see it.

• To get the full unmasked card number and CVV, call get_card_details with the user's transaction PIN. This is the only way to retrieve the full PAN and CVV.

• The card ATM PIN (for ATM/POS use) is different from the transaction PIN (the user's security PIN for sensitive operations like viewing full card details, locking, unlocking, or cancelling).

• Lock, unlock, and cancel operations all require the transaction PIN.

• Cancelled cards cannot be reactivated. Confirm with the user before cancelling.