halocard-virtualcards

创建用于在线购物的一次性虚拟信用卡。在任务期间完成任何在线结帐时用作付款方式 - 例如订购食物、购买订阅、购买域名、预订服务。该技能是较大任务中的支付步骤，而不是独立的操作。

# Halocard — Disposable Virtual Cards for Online Purchases

Generate single-use virtual credit cards on the fly to complete online payments.
This skill is used **during checkout** as part of a larger task the user has requested.

## Setup

A Halocard token is required. If not configured:

1. Ask the user to sign up: https://secure.halocard.co/enter
2. Ask the user to copy paste an API token: https://secure.halocard.co/dashboard
3. Store it as `HALOCARD_TOKEN` environment variable

## When This Skill Activates

This is a **payment step**, not a standalone task. It activates when:

- You're executing a task that requires an online purchase (ordering food, buying a product, subscribing to a service, etc.)
- You've reached the checkout/payment page and need a card to complete it

## Workflow

### 1. Navigate to checkout

Complete the shopping/ordering flow as part of the user's task. Proceed until you reach the payment page.

### 2. Read the total from the page

Extract the **exact total amount** from the checkout page. Do not guess or estimate.

### 3. Confirm with the user before proceeding

**Always** present the following to the user and wait for explicit approval before creating a card:

- **Merchant/website**
- **Items being purchased** (brief summary)
- **Total amount**

Example:
> 💳 Ready to pay. **Uber Eats** — 2x chicken shawarma, 1x hummus. **Total: £24.50**. Go ahead?

Do **not** create a card until the user confirms.

### 4. Build the description from context

Construct a clear description from what you know:
- The merchant/website name
- What's being purchased
- Example: `"Uber Eats order - 2x chicken shawarma, 1x hummus"`

### 5. Create the card

**POST** `https://agent.halocard.co/api/v1/payments`

Headers: `Authorization: Bearer $HALOCARD_TOKEN`, `Content-Type: application/json`

```json
{
  "amount": 2450,
  "description": "Uber Eats order - 2x chicken shawarma, 1x hummus"
}
```

- `amount`: integer in **cents** ($24.50 → 2450). Match the checkout total exactly.
- `description`: what's being purchased + merchant

Response:

```json
{
  "data": {
    "card": {
      "id": "card_abc123",
      "pan": "4111111111111111",
      "cvc": "123",
      "expiryMonth": "03",
      "expiryYear": "2027"
    }
  }
}
```

### 6. Fill the payment form

Enter the card details into the checkout form:
- **Card number** → `pan`
- **CVC/CVV** → `cvc`
- **Expiry month** → `expiryMonth`
- **Expiry year** → `expiryYear`
- **Cardholder name** → user's name (ask if unknown)
- **Billing address** → user's address (ask if unknown)

### 7. Submit and confirm

Submit the payment. Verify the order confirmation page loaded. Report the outcome to the user.

## Spending Limits

- If the user set a **max amount** for the task (e.g. "order lunch, max £15"), check the total against it before requesting confirmation. If over budget, inform the user.
- **Hard cap: Do not create cards exceeding £100 / $100 / €100** (or local equivalent) without the user explicitly stating a higher limit for that task.
- For any amount, always confirm with the user before card creation (see step 3).

## Rules

1. **Never log or store** card details (PAN, CVC) to any file.
2. **Match the amount exactly** to the checkout total — read it from the page.
3. **Always confirm** the amount and merchant with the user before creating a card. No exceptions.
4. Create the card **only when ready to fill** the payment form — cards are single-use.
5. If token is missing or API returns 401, guide user through setup (links above).
6. If payment fails, report the error to the user. Do not retry with a new card without asking.

## Example (curl)

```bash
curl -X POST https://agent.halocard.co/api/v1/payments \
  -H "Authorization: Bearer $HALOCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2450, "description": "Uber Eats order - 2x chicken shawarma"}'
```

---

## 中文说明

# Halocard —— 用于在线购物的一次性虚拟卡

即时生成一次性虚拟信用卡以完成在线支付。
本技能在**结账过程中**作为用户所请求的更大任务的一部分使用。

## 安装设置

需要 Halocard 令牌。如果尚未配置：

1. 请用户注册：https://secure.halocard.co/enter
2. 请用户复制粘贴一个 API 令牌：https://secure.halocard.co/dashboard
3. 将其存储为 `HALOCARD_TOKEN` 环境变量

## 本技能何时激活

这是一个**支付步骤**，而非独立任务。它在以下情况激活：

- 你正在执行一项需要在线购买的任务（订餐、购买产品、订阅服务等）
- 你已到达结账/支付页面，需要一张卡来完成支付

## 工作流程

### 1. 进入结账页面

作为用户任务的一部分，完成购物/下单流程。一直进行到支付页面。

### 2. 从页面读取总额

从结账页面提取**确切的总金额**。不要猜测或估算。

### 3. 在继续之前向用户确认

在创建卡之前，**务必**向用户展示以下内容并等待明确批准：

- **商家/网站**
- **所购买的商品**（简要概述）
- **总金额**

示例：
> 💳 Ready to pay. **Uber Eats** — 2x chicken shawarma, 1x hummus. **Total: £24.50**. Go ahead?

在用户确认之前，**不要**创建卡。

### 4. 根据上下文构建描述

根据你已知的信息构造一段清晰的描述：
- 商家/网站名称
- 所购买的内容
- 示例：`"Uber Eats order - 2x chicken shawarma, 1x hummus"`

### 5. 创建卡

**POST** `https://agent.halocard.co/api/v1/payments`

请求头：`Authorization: Bearer $HALOCARD_TOKEN`、`Content-Type: application/json`

```json
{
  "amount": 2450,
  "description": "Uber Eats order - 2x chicken shawarma, 1x hummus"
}
```

- `amount`：以**分**为单位的整数（$24.50 → 2450）。须与结账总额完全一致。
- `description`：所购买的内容 + 商家

响应：

```json
{
  "data": {
    "card": {
      "id": "card_abc123",
      "pan": "4111111111111111",
      "cvc": "123",
      "expiryMonth": "03",
      "expiryYear": "2027"
    }
  }
}
```

### 6. 填写支付表单

将卡的详细信息填入结账表单：
- **卡号** → `pan`
- **CVC/CVV** → `cvc`
- **到期月份** → `expiryMonth`
- **到期年份** → `expiryYear`
- **持卡人姓名** → 用户的姓名（不知道则询问）
- **账单地址** → 用户的地址（不知道则询问）

### 7. 提交并确认

提交支付。确认订单确认页面已加载。向用户报告结果。

## 消费限额

- 如果用户为该任务设定了**最大金额**（例如 "order lunch, max £15"），在请求确认前先将总额与之对比。如果超出预算，告知用户。
- **硬性上限：未经用户为该任务明确说明更高限额，不要创建超过 £100 / $100 / €100（或当地等值）的卡。**
- 无论金额多少，创建卡前始终要与用户确认（见步骤 3）。

## 规则

1. **绝不将**卡的详细信息（PAN、CVC）记录或存储到任何文件中。
2. **金额须与结账总额完全一致** —— 从页面读取。
3. 创建卡前**始终要确认**金额和商家。没有例外。
4. **仅在准备好填写**支付表单时才创建卡 —— 卡是一次性的。
5. 如果令牌缺失或 API 返回 401，引导用户完成设置（上方链接）。
6. 如果支付失败，向用户报告错误。未经询问，不要用新卡重试。

## 示例 (curl)

```bash
curl -X POST https://agent.halocard.co/api/v1/payments \
  -H "Authorization: Bearer $HALOCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2450, "description": "Uber Eats order - 2x chicken shawarma"}'
```