---
name: Card Management
description: Create and manage virtual cards via MasterPay Global. Supports single-use cards for one-time purchases and multi-use cards for repeated use.
version: 1.0.0
metadata:
openclaw:
requires:
env:
- AIOT_API_BASE_URL
primaryEnv: AIOT_API_BASE_URL
---
# Card Management
Use this skill when the user needs to create virtual cards, view card details, or manage card lifecycle (lock, unlock, cancel).
Configuration
The default API base URL is `https://payment-api-dev.aiotnetwork.io`. All endpoints are relative to this URL.
To override (e.g. for local development):
export AIOT_API_BASE_URL="http://localhost:8080"
If `AIOT_API_BASE_URL` is not set, use `https://payment-api-dev.aiotnetwork.io` as the base for all requests.
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 authRecommended 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. Submit wallet KYC: POST /api/v1/masterpay/wallets/kyc — required before card creation. Needs profile phone number and id_number set via PUT /profile/document (id_number is sent as orgCode to MasterPay)
4. Create card: POST /api/v1/masterpay/cards/single-use or /multi-use — returns masked PAN and card ATM PIN
5. 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 AND wallet KYC must be submitted (POST /masterpay/wallets/kyc) before creating any MasterPay card — card creation fails with NO_WALLETS if KYC is not complete, and MasterPay rejects cards if wallet KYC is missingMasterPay card responses include a masked PAN and the card ATM PIN — use /cards/:id/details with transaction PIN for the full card number and CVVThe 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 operationsLock/unlock/cancel operations require transaction PIN verificationCancelled cards cannot be reactivated — cancellation is permanentCard 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 creationAgent 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.The full prerequisite chain is: KYC approved → wallet exists → wallet KYC submitted → card creation. Use `get_kyc_status` from the kyc-identity skill to verify KYC approval, then `list_card_wallets` to confirm a wallet exists. If no wallets exist, KYC is not yet approved. Then submit wallet KYC (POST /masterpay/wallets/kyc) before creating any card — MasterPay rejects card creation without wallet KYC.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.