End-to-end: card replacement

• widget if your widget signs the customer’s identity into a JWT (the standard pattern for authenticated fintech, see Widget → Identify logged-in users for the payload shape).
• ui if your app passes the customer’s email through UI metadata.
• The integration’s own name (zendesk, intercom, front, gorgias, hubspot, salesforce, livechat) if you’re routing through a helpdesk.

• Step Name: Lookup Customer
• Method: GET
• URL: https://api.yourbank.com/v1/customers?email=${email}
• Headers: {"x-api-key": "your-cards-api-key"} (per Fini’s API contract when calling your own endpoint; use the third-party scheme if you’re calling a processor’s SaaS API directly).
• Save From Response: {"account_id": "id", "account_status": "status", "is_high_risk": "risk_flags.kyc_recheck_required", "recent_replacement_count": "stats.card_replacements_30d"}

• Step Name: List Active Cards
• Method: GET
• URL: https://api.yourbank.com/v1/customers/${account_id}/cards?status=active
• Headers: same as step 1.
• Save From Response: {"active_cards": "cards"}

[
  {"id": "card_abc", "last_four": "4242", "type": "physical", "product": "Debit"},
  {"id": "card_xyz", "last_four": "1881", "type": "virtual", "product": "Credit"}
]

• Name: Freeze Card
• Description: Freezes a specific card so it can no longer authorize new transactions. Returns a confirmation id for downstream actions to reference.

• Step Name: Freeze card via Cards API
• Method: POST
• URL: https://api.yourbank.com/v1/cards/${card_id}/freeze
• Headers: {"x-api-key": "your-cards-api-key"} (or your processor’s native scheme).
• Body: {"reason": "${reason}", "idempotency_key": "${card_id}-freeze"}
• Save From Response: {"freeze_confirmation_id": "id", "frozen_at": "frozen_at"}

• Name: Order Replacement Card
• Description: Orders a replacement card on the customer's account, shipped to the address provided. Records the prior freeze confirmation for audit. Returns the new card id, expected delivery date, and tracking URL.

• Step Name: Order via Cards API
• Method: POST
• URL: https://api.yourbank.com/v1/customers/${account_id}/cards
• Headers: {"x-api-key": "your-cards-api-key"} (or your processor’s native scheme).
• Body:
  {
    "type": "replacement",
    "prior_freeze_id": "${prior_freeze_confirmation_id}",
    "reason": "${replacement_reason}",
    "shipping_address": {
      "street": "${shipping_street}",
      "city": "${shipping_city}",
      "postal_code": "${shipping_postal_code}",
      "country": "${shipping_country}"
    },
    "idempotency_key": "${prior_freeze_confirmation_id}-replacement"
  }
  
• Save From Response: {"new_card_id": "id", "expected_delivery": "shipping.estimated_delivery", "tracking_url": "shipping.tracking_url", "last_four": "last_four"}

“Use this rule when the customer reports a lost, stolen, damaged, or otherwise compromised card and wants a replacement. Example queries: ‘I lost my debit card’, ‘my card was stolen’, ‘someone took my wallet, please send a new card’, ‘my card stopped working, can you ship me a new one’, ‘I need a replacement card’. Do not use this rule for activation, PIN reset, or transaction disputes, those have their own rules.”

• Name: Intent is card lost or stolen
• Condition group: in the field picker, expand Tag Groups → pick Type of Issue (the default group) or your custom routing group. Operator Equals. Value Card Lost or Stolen.

• Name: Account is active
• Condition group: in the field picker, expand User Attributes → pick account_status. Operator Equals. Value active.

• Name: Extract card details
• Look at: Interaction History
• Find these details:
  • field card_last_four, type String, not required
  • field replacement_reason, type String, required, allowed values: lost, stolen, damaged, compromised
• Instructions: “Extract the last four digits of the card the customer is reporting on, if they mentioned a number like ‘4242’ or ‘card ending in 1881’. If they didn’t mention a number, return an empty string, do not guess. Also extract the replacement_reason from these allowed values: lost, stolen, damaged, compromised. Examples: ‘I lost my wallet’ → lost. ‘someone stole my card at the gas station’ → stolen. ‘my card got cut in half by the ATM’ → damaged. ‘I saw a charge I didn’t make’ → compromised. If unclear, default to compromised.”

• Form Error 1: Postal code doesn’t match country format. Triggered when the entered shipping_postal_code fails the regex for the selected shipping_country. The Form Error specifies which field’s validation it represents; the form re-renders showing the error message until the customer corrects it.
• Form Error 2: Street address too short. Triggered when shipping_street is fewer than 3 characters.

• Name: Resolve card_id
• Look at: Interaction History + User Attributes
• Find these details: field card_id, type String, required.
• Instructions: “Given the user_attribute active_cards (an array of cards with id and last_four) and the tree variable card_last_four: if card_last_four is non-empty and exactly one card in active_cards has a matching last_four, return that card’s id. If card_last_four is empty but active_cards has exactly one entry, return that entry’s id. Otherwise, fail (return empty) so the Fallback below can prompt the customer for clarification.”

Fallback (try the freeze + order chain; if card_id couldn't be resolved, ask)
├── Steps
│   ├── Tool: Freeze Card (in: card_id from the Resolve Read)
│   ├── Form: Shipping address
│   ├── Tool: Order Replacement Card
│   └── Reply: confirmation
└── Reply: "You have multiple cards on file. Which one would you like to replace, the one ending in [list active_cards.last_four]?"

• Action: select Freeze Card.
• Inputs:
  • card_id → bind to the card_id tree variable from the Resolve Read.
  • reason → bind to replacement_reason (from the earlier Read).

• Action: select Order Replacement Card.
• Inputs:
  • account_id → bind to account_id (User Attribute).
  • prior_freeze_confirmation_id → bind to freeze_confirmation_id (upstream Tool output).
  • replacement_reason → bind to replacement_reason.
  • shipping_street, shipping_city, shipping_postal_code, shipping_country → bind each to the matching Form output.

“Confirm to the customer that their old card has been frozen and a replacement is on the way. Mention the new card’s last four digits (${last_four}), the expected delivery date ($), and include the tracking URL ($) so they can monitor delivery. Reassure them that their old card can no longer be used. Suggest they keep an eye out for any unauthorized transactions on the frozen card and reach out if they see any.”

{
  "message": "my wallet was stolen yesterday, my debit card ending in 4242 was in it, please send a replacement",
  "user_attributes": {
    "account_id": "acc_abc123",
    "account_status": "active",
    "is_high_risk": false,
    "recent_replacement_count": 0,
    "active_cards": [
      {"id": "card_42", "last_four": "4242", "type": "physical", "product": "Debit"},
      {"id": "card_88", "last_four": "1881", "type": "virtual", "product": "Credit"}
    ]
  },
  "tag_groups": {
    "Topic": "Card Lost or Stolen"
  },
  "form_submission": {
    "shipping_street": "1 Infinite Loop",
    "shipping_city": "Cupertino",
    "shipping_postal_code": "95014",
    "shipping_country": "US"
  }
}

1. Both top Checks pass.
2. The Read populates card_last_four = 4242 and replacement_reason = stolen.
3. The Form node passes (with the injected form_submission values).
4. The Freeze Tool fires with card_id = card_42 and produces a freeze_confirmation_id.
5. The Order Tool fires with that confirmation flowing into prior_freeze_confirmation_id, plus all four shipping fields from the Form.
6. The Reply interpolates new_card_id, expected_delivery, and tracking_url from the Order Tool’s outputs.

• User Attributes → is_high_risk Equals True
• Tag Groups → Type of Issue Equals Card Lost or Stolen (use Contains instead if your tag group has Tag Selection set to “Multiple tags can be selected”)

• User Attributes → recent_replacement_count Greater Than 1
• Tag Groups → Type of Issue Equals Card Lost or Stolen