# RevCent MCP Guide: `AddCardToCustomer`

AI/MCP-focused guide for adding a credit card to an existing RevCent Customer.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Customer Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewCustomer.md` | Broad overview of Customer records, customer lifecycle, related records, customer cards, groups, and customer-facing AI safety. |
| GetCustomer | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomer.md` | Retrieve the Customer before and after customer mutation operations. |
| SearchCustomers | `https://revcent.com/documentation/markdown/mcp/operation/SearchCustomers.md` | Locate a Customer when the Customer ID is unknown. |
| GetCustomers | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomers.md` | Bounded operational Customer retrieval. Not for reporting/metrics. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct operation for customer reporting, metrics, aggregation, and data mining. |


---

## Operation Summary

Operation:

```text
AddCardToCustomer
```

Title:

```text
Add Card To Customer
```

Purpose:

```text
Add a credit card to an existing Customer.
```

Use this operation when a verified Customer needs a new credit card attached to their RevCent account.

---

## Critical Security Note

Card data is sensitive payment information.

Best practice:

```text
Use secure, PCI-appropriate collection flows whenever possible.
```

Do not collect raw card data inside unsafe public AI chat.

If a Secure Form or Customer Portal flow is available, prefer that flow for customer-entered card data.

---

## When to Use

Use `AddCardToCustomer` when:

- the Customer already exists,
- the user explicitly wants to add a card,
- the Customer is verified/authorized,
- the payment collection flow is secure,
- billing information should optionally differ from existing customer details,
- the new card should optionally be set as default.

---

## Input Schema

Required top-level fields:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `customer_id` | string | Yes | 20-character Customer ID. |
| `payment` | object | Yes | Payment object containing the credit card. |

Optional top-level fields:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `bill_to` | object | No | Billing information. If omitted, existing Customer information is used. |

---

## `payment.credit_card` Object

Required fields inside `payment.credit_card`:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `card_number` | string | Yes | Full card number, digits only. |
| `exp_month` | integer | Yes | Expiration month as one or two digit integer. |
| `exp_year` | integer | Yes | Expiration year as two digit integer. |

Optional fields:

| Field | Type | Description |
|---|---:|---|
| `card_code` | string | Card code, digits only. |
| `set_as_default` | boolean | Whether to set the newly added card as the customer's default card for payment. |

Example:

```json
{
  "customer_id": "CCCCCCCCCCCCCCCCCCCC",
  "payment": {
    "credit_card": {
      "card_number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 30,
      "card_code": "123",
      "set_as_default": true
    }
  }
}
```

---

## `bill_to` Object

Use `bill_to` when billing details differ from the existing Customer record.

Fields:

```text
first_name
last_name
address_line_1
address_line_2
city
state
zip
country
company
email
phone
```

If `bill_to` is omitted, existing Customer information is used.

---

## Output Schema

Successful output can include:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` indicates success. |
| `customer_id` | 20-character ID returned by the operation. |
| `customer_card_id` | Newly created 20-character Customer Card ID. |
| `result` | Result message. |


---

## Recommended Workflow

```text
1. GetCustomer to verify the Customer.
2. Confirm the Customer is authorized to add a card.
3. Use a secure card collection flow.
4. Confirm whether the card should be default.
5. AddCardToCustomer.
6. GetCustomer to verify the new card summary is attached.
```

---

## Customer-Facing AI Verification Warning

Customer operations can expose or modify sensitive customer, contact, address, payment, group, purchase, subscription, trial, refund, fraud, chargeback, note, and lifecycle context.

If this operation is used inside a customer-facing AI flow, such as:

- AI Voice Agent,
- public chatbot,
- customer portal assistant,
- SMS assistant,
- any visitor-facing AI workflow,

AI/MCP should verify that the visitor is actually the customer, or is otherwise authorized, before providing information, modifying customer data, adding cards, changing status, or changing group membership.

Recommended rule:

```text
Do not act on a Customer record in a public-facing flow based only on visitor-provided input.
```

Use a secondary value from the retrieved RevCent Customer record, such as customer email, customer phone, or another record-backed value.

Safe customer-facing flow:

```text
Visitor provides customer/account input
    ↓
AI locates/retrieves the Customer
    ↓
AI verifies a secondary value from the retrieved Customer record
    ↓
AI confirms the requested action
    ↓
Only then performs the operation
```

For consequential actions, require explicit confirmation immediately before running the operation.


---

## Reporting Guidance

This operation is not a reporting or analytics operation.

Do not use customer mutation operations or customer lookup/search operations for:

- reporting,
- metrics,
- aggregation,
- data mining,
- segmentation reports,
- customer lifetime value reports,
- customer counts,
- broad analysis,
- bulk retrieval.

Use:

```text
BigQueryRunQuery
```

for those purposes.

If AI/MCP intended to use operational customer actions or lookup actions for reporting and then realizes `BigQueryRunQuery` is correct, it does not need to tell the user. It should simply run `BigQueryRunQuery`.


---

## Common Mistakes to Avoid

Do not:

- collect raw card data in unsafe public chat,
- add a card to the wrong Customer,
- set `set_as_default = true` unless intended,
- assume billing info is the same if the user provides separate billing details,
- store card data in metadata or notes,
- disclose card information beyond safe summaries.

---

## Final AI/MCP Instruction

Use `AddCardToCustomer` to add a credit card to an existing verified Customer. Required fields are `customer_id` and `payment.credit_card` with `card_number`, `exp_month`, and `exp_year`. Prefer secure payment collection flows.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.