{
  "feature": "payment-methods",
  "version": "1.0.0",
  "description": "Saved payment methods with card tokenization, add/remove/set default, Luhn validation, expiry monitoring, and digital wallet support.",
  "category": "payment",
  "tags": [
    "payment-methods",
    "tokenization",
    "pci-dss",
    "cards",
    "wallets",
    "apple-pay",
    "google-pay"
  ],
  "fields": [
    {
      "name": "method_id",
      "type": "text",
      "label": "Payment Method ID",
      "required": true,
      "validation": [
        {
          "type": "pattern",
          "value": "^pm_[a-zA-Z0-9]+$",
          "message": "Payment method ID must match the required format"
        }
      ]
    },
    {
      "name": "customer_id",
      "type": "text",
      "label": "Customer ID",
      "required": true
    },
    {
      "name": "type",
      "type": "select",
      "label": "Payment Method Type",
      "required": true,
      "options": [
        {
          "value": "card",
          "label": "Credit/Debit Card"
        },
        {
          "value": "bank_account",
          "label": "Bank Account"
        },
        {
          "value": "wallet",
          "label": "Digital Wallet"
        }
      ]
    },
    {
      "name": "last_four",
      "type": "text",
      "label": "Last Four Digits",
      "required": true,
      "validation": [
        {
          "type": "pattern",
          "value": "^[0-9]{4}$",
          "message": "Last four digits must be exactly 4 numeric characters"
        }
      ]
    },
    {
      "name": "brand",
      "type": "select",
      "label": "Card Brand",
      "required": false,
      "options": [
        {
          "value": "visa",
          "label": "Visa"
        },
        {
          "value": "mastercard",
          "label": "Mastercard"
        },
        {
          "value": "amex",
          "label": "American Express"
        },
        {
          "value": "discover",
          "label": "Discover"
        },
        {
          "value": "diners",
          "label": "Diners Club"
        },
        {
          "value": "jcb",
          "label": "JCB"
        },
        {
          "value": "unionpay",
          "label": "UnionPay"
        }
      ]
    },
    {
      "name": "exp_month",
      "type": "number",
      "label": "Expiration Month",
      "required": false,
      "validation": [
        {
          "type": "min",
          "value": 1,
          "message": "Expiration month must be between 1 and 12"
        },
        {
          "type": "max",
          "value": 12,
          "message": "Expiration month must be between 1 and 12"
        }
      ]
    },
    {
      "name": "exp_year",
      "type": "number",
      "label": "Expiration Year",
      "required": false,
      "validation": [
        {
          "type": "min",
          "value": 2024,
          "message": "Expiration year must not be in the past"
        }
      ]
    },
    {
      "name": "is_default",
      "type": "boolean",
      "label": "Default Payment Method",
      "required": true,
      "default": false
    },
    {
      "name": "billing_address",
      "type": "json",
      "label": "Billing Address",
      "required": false
    },
    {
      "name": "token",
      "type": "token",
      "label": "Payment Provider Token",
      "required": true
    },
    {
      "name": "wallet_type",
      "type": "select",
      "label": "Wallet Type",
      "required": false,
      "options": [
        {
          "value": "apple_pay",
          "label": "Apple Pay"
        },
        {
          "value": "google_pay",
          "label": "Google Pay"
        },
        {
          "value": "paypal",
          "label": "PayPal"
        }
      ]
    },
    {
      "name": "fingerprint",
      "type": "text",
      "label": "Card Fingerprint",
      "required": false
    },
    {
      "name": "status",
      "type": "select",
      "label": "Method Status",
      "required": true,
      "options": [
        {
          "value": "active",
          "label": "Active"
        },
        {
          "value": "expired",
          "label": "Expired"
        },
        {
          "value": "revoked",
          "label": "Revoked"
        }
      ]
    }
  ],
  "rules": {
    "never_store_raw_card_data": {
      "description": "Raw card numbers (PAN), CVV, and magnetic stripe data must never be stored, logged, or transmitted through the application. All card data is tokenized by the payment provider before reaching the server. PCI DSS Level 1 compliance required.\n"
    },
    "luhn_check": {
      "description": "Card numbers are validated client-side using the Luhn algorithm before submission to the payment provider for tokenization.\n"
    },
    "one_default_per_customer": {
      "description": "Each customer may have exactly one default payment method. Setting a new default automatically unsets the previous one.\n"
    },
    "duplicate_detection": {
      "description": "Duplicate cards are detected using the card fingerprint (hash of card number). Adding a card with the same fingerprint is rejected.\n"
    },
    "expiry_monitoring": {
      "description": "Cards expiring within 30 days trigger a notification to the customer. Expired cards are marked with status \"expired\" and cannot be used for new charges.\n"
    },
    "secure_deletion": {
      "description": "Removing a payment method revokes the token with the payment provider and deletes the local record. Token revocation is confirmed before local deletion.\n"
    },
    "wallet_verification": {
      "description": "Digital wallet payment methods (Apple Pay, Google Pay) are verified through the wallet provider's authentication flow. Device-specific tokens are used for charges.\n"
    },
    "max_payment_methods": {
      "description": "A customer may store a maximum of 10 payment methods. Attempting to add beyond this limit returns an error.\n"
    }
  },
  "outcomes": {
    "payment_method_added": {
      "priority": 1,
      "given": [
        "customer submits card details via secure form",
        "card passes Luhn validation",
        "payment provider returns a valid token",
        "card fingerprint is not a duplicate"
      ],
      "then": [
        {
          "action": "create_record",
          "type": "payment_method",
          "target": "payment_method",
          "description": "Payment method stored with token, last four, brand, and expiry"
        },
        {
          "action": "set_field",
          "target": "is_default",
          "value": true,
          "when": "existing_method_count == 0"
        },
        {
          "action": "emit_event",
          "event": "payment_method.added",
          "payload": [
            "method_id",
            "customer_id",
            "type",
            "brand",
            "last_four"
          ]
        }
      ],
      "result": "Payment method tokenized and saved securely",
      "error": "PAYMENT_METHOD_INVALID_CARD"
    },
    "wallet_added": {
      "priority": 2,
      "given": [
        "customer initiates wallet setup (Apple Pay, Google Pay)",
        "wallet provider authentication succeeds",
        "device token received"
      ],
      "then": [
        {
          "action": "create_record",
          "type": "payment_method",
          "target": "payment_method",
          "description": "Wallet payment method created with device token"
        },
        {
          "action": "emit_event",
          "event": "payment_method.added",
          "payload": [
            "method_id",
            "customer_id",
            "type",
            "wallet_type"
          ]
        }
      ],
      "result": "Digital wallet linked as payment method"
    },
    "payment_method_removed": {
      "priority": 3,
      "given": [
        "customer requests removal of a payment method",
        "payment method is not the sole method on an active subscription"
      ],
      "then": [
        {
          "action": "call_service",
          "target": "payment_provider",
          "description": "Revoke token with payment provider"
        },
        {
          "action": "delete_record",
          "type": "payment_method",
          "target": "payment_method",
          "description": "Local record removed after token revocation confirmed"
        },
        {
          "action": "emit_event",
          "event": "payment_method.removed",
          "payload": [
            "method_id",
            "customer_id",
            "type"
          ]
        }
      ],
      "result": "Payment method removed and token revoked",
      "error": "PAYMENT_METHOD_EXPIRED"
    },
    "default_changed": {
      "priority": 4,
      "given": [
        "customer sets a different payment method as default",
        "target payment method is active and not expired"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "is_default",
          "value": false,
          "description": "Previous default unset"
        },
        {
          "action": "set_field",
          "target": "is_default",
          "value": true,
          "description": "New default set"
        },
        {
          "action": "emit_event",
          "event": "payment_method.default_changed",
          "payload": [
            "method_id",
            "customer_id",
            "previous_default_id"
          ]
        }
      ],
      "result": "Default payment method updated"
    },
    "expiring_card_notification": {
      "priority": 5,
      "given": [
        {
          "field": "type",
          "operator": "eq",
          "value": "card"
        },
        "card expires within 30 days"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "payment_method.expiring",
          "payload": [
            "method_id",
            "customer_id",
            "exp_month",
            "exp_year"
          ]
        },
        {
          "action": "notify",
          "channel": "email",
          "description": "Notify customer to update their expiring card"
        }
      ],
      "result": "Customer notified of upcoming card expiration"
    },
    "card_expired": {
      "priority": 6,
      "given": [
        {
          "field": "type",
          "operator": "eq",
          "value": "card"
        },
        "current date is past card expiry"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "status",
          "value": "expired"
        },
        {
          "action": "set_field",
          "target": "is_default",
          "value": false,
          "when": "is_default == true",
          "description": "Expired card cannot remain as default"
        }
      ],
      "result": "Card marked as expired, removed from default if applicable"
    },
    "duplicate_card": {
      "priority": 1,
      "error": "PAYMENT_METHOD_DUPLICATE",
      "given": [
        "customer adds a card",
        "card fingerprint matches an existing active payment method"
      ],
      "then": [
        {
          "action": "notify",
          "channel": "ui",
          "description": "Inform customer this card is already on file"
        }
      ],
      "result": "Duplicate card rejected"
    },
    "method_limit_reached": {
      "priority": 2,
      "error": "PAYMENT_METHOD_LIMIT_REACHED",
      "given": [
        "customer attempts to add a payment method",
        "customer already has 10 active payment methods"
      ],
      "then": [
        {
          "action": "notify",
          "channel": "ui",
          "description": "Inform customer of the payment method limit"
        }
      ],
      "result": "Cannot add more payment methods, limit reached"
    }
  },
  "errors": [
    {
      "code": "PAYMENT_METHOD_DUPLICATE",
      "message": "This card is already saved to your account.",
      "status": 409
    },
    {
      "code": "PAYMENT_METHOD_LIMIT_REACHED",
      "message": "You have reached the maximum number of saved payment methods (10).",
      "status": 400
    },
    {
      "code": "PAYMENT_METHOD_INVALID_CARD",
      "message": "The card number is invalid. Please check and try again.",
      "status": 400
    },
    {
      "code": "PAYMENT_METHOD_EXPIRED",
      "message": "This payment method has expired and cannot be used for charges.",
      "status": 400
    },
    {
      "code": "PAYMENT_METHOD_TOKENIZATION_FAILED",
      "message": "Unable to securely process this payment method. Please try again.",
      "status": 500
    },
    {
      "code": "PAYMENT_METHOD_REMOVAL_BLOCKED",
      "message": "This payment method cannot be removed because it is linked to an active subscription.",
      "status": 409
    }
  ],
  "events": [
    {
      "name": "payment_method.added",
      "description": "New payment method saved to customer account",
      "payload": [
        "method_id",
        "customer_id",
        "type",
        "brand",
        "last_four"
      ]
    },
    {
      "name": "payment_method.removed",
      "description": "Payment method removed and token revoked",
      "payload": [
        "method_id",
        "customer_id",
        "type"
      ]
    },
    {
      "name": "payment_method.default_changed",
      "description": "Customer changed their default payment method",
      "payload": [
        "method_id",
        "customer_id",
        "previous_default_id"
      ]
    },
    {
      "name": "payment_method.expiring",
      "description": "Payment method expiring within 30 days",
      "payload": [
        "method_id",
        "customer_id",
        "exp_month",
        "exp_year"
      ]
    }
  ],
  "related": [
    {
      "feature": "subscription-billing",
      "type": "required",
      "reason": "Subscriptions charge against saved payment methods"
    },
    {
      "feature": "cart-checkout",
      "type": "required",
      "reason": "Checkout uses saved or new payment methods"
    },
    {
      "feature": "refunds-returns",
      "type": "optional",
      "reason": "Refunds issued to original payment method"
    },
    {
      "feature": "invoicing-payments",
      "type": "optional",
      "reason": "Invoice payments may use saved methods"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_payment_methods",
        "description": "Saved payment methods with card tokenization, add/remove/set default, Luhn validation, expiry monitoring, and digital wallet support.",
        "success_metrics": [
          {
            "metric": "policy_violation_rate",
            "target": "0%",
            "measurement": "Operations that violate defined policies"
          },
          {
            "metric": "audit_completeness",
            "target": "100%",
            "measurement": "All decisions have complete audit trails"
          }
        ],
        "constraints": [
          {
            "type": "regulatory",
            "description": "All operations must be auditable and traceable",
            "negotiable": false
          },
          {
            "type": "security",
            "description": "Sensitive fields must be encrypted at rest and never logged in plaintext",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before modifying sensitive data fields",
        "before permanently deleting records"
      ],
      "escalation_triggers": [
        "error_rate > 5",
        "consecutive_failures > 3"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "payment_method_added",
          "permission": "autonomous"
        },
        {
          "action": "wallet_added",
          "permission": "autonomous"
        },
        {
          "action": "payment_method_removed",
          "permission": "human_required"
        },
        {
          "action": "default_changed",
          "permission": "supervised"
        },
        {
          "action": "expiring_card_notification",
          "permission": "autonomous"
        },
        {
          "action": "card_expired",
          "permission": "autonomous"
        },
        {
          "action": "duplicate_card",
          "permission": "autonomous"
        },
        {
          "action": "method_limit_reached",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "accuracy",
        "over": "speed",
        "reason": "financial transactions must be precise and auditable"
      }
    ],
    "verification": {
      "invariants": [
        "sensitive fields are never logged in plaintext",
        "all data access is authenticated and authorized",
        "error messages never expose internal system details"
      ]
    },
    "coordination": {
      "protocol": "request_response",
      "consumes": [
        {
          "capability": "subscription_billing",
          "from": "subscription-billing",
          "fallback": "fail"
        },
        {
          "capability": "cart_checkout",
          "from": "cart-checkout",
          "fallback": "fail"
        }
      ]
    }
  }
}