# RevCent Check Direct Operations Overview for AI/MCP Clients

## Purpose

This document is an AI/MCP-focused overview of Check Direct items and their retrieval operations:

- `GetCheckDirects`
- `GetCheckDirect`

A Check Direct is the official payment item created when a Sale uses `payment_type: check_direct`. It represents a physical-check payment and fills a role similar to a credit-card Transaction: it is the payment record connected to the Sale and its related commerce items.

This overview helps AI agents and MCP clients create check-based Sales safely, retrieve the resulting Check Direct record, follow related entity IDs, distinguish physical checks from other payment types, and use BigQuery for reporting.

---

## Core Mental Model

```text
Sale = purchase or order event
payment_type: check_direct = physical-check payment path
Check Direct = official payment item created for that Sale
```

Creation flow:

```text
CreateSale receives payment_type: check_direct
    ↓
RevCent creates the Sale and related commerce items
    ↓
RevCent creates a Check Direct payment item
    ↓
The Sale exposes the Check Direct ID in check_directs
    ↓
GetCheckDirect retrieves the official payment record
```

There is no standalone `CreateCheckDirect` MCP operation. Check Direct creation is a downstream result of creating a Sale with the physical-check payment type.

---

## Related Documentation

| Document | Link | Why It Matters |
|---|---|---|
| Ecosystem Check Direct overview | `https://revcent.com/documentation/markdown/ecosystem/item/CheckDirect.md` | Non-technical meaning and relationship graph. |
| Knowledge Base Check Payments page | `https://kb.revcent.com/en/payments/check` | Web-app location for viewing Check Direct records. |
| Sales overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSale.md` | Parent Sale lifecycle and payment paths. |
| CreateSale | `https://revcent.com/documentation/markdown/mcp/operation/CreateSale.md` | Sale schema and `check_direct` payment-type guidance. |
| Transactions overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTransaction.md` | Credit-card payment item used for comparison. |
| Offline Payments overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md` | Alternate and external payment item used for comparison. |
| Pending Refund overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPendingRefund.md` | Refund records related to Check Direct context. |
| GetCheckDirects | `https://revcent.com/documentation/markdown/mcp/operation/GetCheckDirects.md` | Operation-specific bounded list guidance. |
| GetCheckDirect | `https://revcent.com/documentation/markdown/mcp/operation/GetCheckDirect.md` | Operation-specific single-record guidance. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct operation for metrics and broad analysis. |

---

## Official Payment Entry

For a check-based Sale, the Check Direct item is the official payment entry.

Use this payment-object mapping:

| Sale Payment Type | Official Payment Item |
|---|---|
| `credit_card` | Transaction |
| `paypal` | PayPal Transaction |
| `offline_payment` | Offline Payment |
| `check_direct` | Check Direct |

The Check Direct and Transaction are similar in ecosystem role because each connects the payment side of the purchase to the Sale. They are not technically equivalent.

```text
Transaction
    = credit-card payment attempt through a Gateway

Check Direct
    = physical-check payment record created from the Sale payment type
```

Do not look for Gateway response codes, card authorization details, or processor decline fields on a Check Direct.

---

## Physical Check Only

Check Direct means a physical check, not ACH and not an electronic check.

Physical-check workflows can involve:

- a check number,
- instructions for who the check is payable to,
- a mailing destination,
- waiting for receipt,
- deposit and clearing,
- returned or bounced check handling,
- accounts-receivable reconciliation.

AI/MCP clients should not relabel an ACH or electronic-check request as `check_direct` merely because both involve bank accounts.

---

## Creating a Check Direct Through CreateSale

The current `CreateSale` MCP schema creates a check-based Sale by setting:

```json
{
  "payment_type": "check_direct"
}
```

This fragment is not a complete request. The client must also provide all required `CreateSale` fields, including the authoritative Campaign, Products, Customer context, and IP address required by the operation.

The MCP `CreateSale` schema does not expose a nested Check Direct object. Use the standard Sale fields and non-sensitive Metadata or internal IDs for reconciliation when appropriate.

Example structural request:

```json
{
  "campaign": "XXXXXXXXXXXXXXXXXXXX",
  "iso_currency": "USD",
  "ip_address": "203.0.113.10",
  "payment_type": "check_direct",
  "customer": {
    "first_name": "Jane",
    "last_name": "Customer",
    "email": "jane@example.com"
  },
  "product": [
    {
      "id": "XXXXXXXXXXXXXXXXXXXX",
      "quantity": 1
    }
  ],
  "metadata": [
    {
      "name": "remittance_reference",
      "value": "AR-REFERENCE"
    }
  ]
}
```

The IDs and values above are placeholders. Never copy them into a live request.

---

## Consequential Action Rule

Creating a Sale with `payment_type: check_direct` creates commerce records and identifies the official payment path as physical check.

Before calling `CreateSale`, verify:

- the user intends to create a real Sale,
- physical check is the intended payment method,
- Campaign, Product, Customer, currency, quantity, price, Shipping, Tax, and Discount inputs are authoritative,
- the user understands whether fulfillment should wait for receipt or clearing,
- no unnecessary bank-account or routing information is being collected,
- the active account mode is correct.

Do not state that the check has been received, deposited, or cleared merely because the Check Direct item was created.

---

## Check Direct Record Fields

`GetCheckDirect` and each `GetCheckDirects` result can include:

| Field | Meaning |
|---|---|
| `id` | The 20-character Check Direct ID. |
| `created_date_unix` | Unix timestamp when the item was created. |
| `updated_date_unix` | Unix timestamp when the item was last updated. |
| `amount` | Check payment amount. |
| `campaign_id` | Related Campaign ID. |
| `campaign_name` | Related Campaign name. |
| `check_number` | Recorded check number. |
| `customer` | Related Customer details. |
| `received` | Whether the physical check has been received. |
| `status` | Current recorded check status. |
| `third_party_shop` | Originating Shop details, when applicable. |
| `metadata` | Metadata name/value entries. |

Treat returned amounts, receipt state, status, and IDs as authoritative. Do not infer receipt or clearing state from dates or user-supplied prose.

---

## Payment-Sensitive Data Rule

Check and Customer details can be sensitive.

For customer-facing MCP workflows:

- verify the visitor is authorized for the record,
- return only the fields needed for the request,
- do not disclose a Check Direct based only on a name, email, phone number, or claimed order reference,
- do not request or expose raw bank account or routing numbers,
- avoid repeating a full check number when a masked or minimal confirmation is sufficient.

Use exact IDs obtained from authorized RevCent context whenever possible.

---

## Related Entity IDs

A Check Direct response can expose arrays of related IDs, including:

- `sales`
- `product_sales`
- `shipping`
- `tax`
- `discounts`
- `trials`
- `subscriptions`
- `subscription_renewals`
- `pending_refunds`
- `chargebacks`
- `fraud_detections`
- `api_calls`
- `ai_threads`
- `ai_assistants`

It can also expose empty or populated relationship arrays for other payment items where the shared relationship schema applies.

Follow a related ID only when the user's request needs that context. For example:

```text
GetCheckDirect returns sales: [sale_id]
    ↓
Use GetSale with the exact sale_id
    ↓
Inspect Products, Shipping, Tax, Discounts, and the full purchase context
```

Do not guess related record contents from the existence of an ID.

---

## Operation: GetCheckDirects

### Purpose

`GetCheckDirects` returns a bounded, paginated list of Check Direct records.

Use it for:

- finding recent Check Direct items,
- identifying the correct Check Direct ID,
- reviewing a small operational list,
- filtering by Campaign, currency, Shop, Metadata, or Customer,
- supporting a narrow accounts-receivable or customer-service workflow.

Do not use it for metrics, aggregation, broad analysis, data mining, bulk retrieval, or document-property searching.

### Required inputs

| Field | Type | Constraints |
|---|---:|---|
| `date_start` | integer | Unix timestamp in seconds. |
| `date_end` | integer | Unix timestamp in seconds; the range cannot exceed 90 days. |
| `limit` | integer | From 1 through 25. |
| `page` | integer | Pagination page. |

### Optional filters

| Field | Type | Purpose |
|---|---:|---|
| `campaign_filter` | array<string> | Filter by one or more 20-character Campaign IDs. |
| `currency_filter` | array<string> | Filter by ISO 4217 currency code. |
| `shop_filter` | array<string> | Filter by one or more 20-character Shop IDs. |
| `metadata_filter` | array<object> | Filter by Metadata name/value pairs. |
| `customer_id` | string | Filter to a specific Customer. |

The Metadata filter supports `METADATA_NAME_EXISTS` as the value when the user wants records containing a Metadata name regardless of its value.

### Example input

```json
{
  "date_start": 1767225600,
  "date_end": 1769817600,
  "limit": 25,
  "page": 1,
  "currency_filter": ["USD"],
  "customer_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

Use authoritative timestamps and IDs rather than copying example values.

### Pagination

The response includes:

- `results`,
- `total_count`,
- `total_pages`.

Do not automatically traverse every page. Switch to `BigQueryRunQuery` when the user intent is analytical.

---

## Operation: GetCheckDirect

### Purpose

`GetCheckDirect` retrieves one Check Direct by its exact ID.

Input:

```json
{
  "check_direct_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

The ID must be an exact 20-character Check Direct ID from an authoritative source, such as:

- a Sale's `check_directs` relationship array,
- a selected `GetCheckDirects` result,
- an authorized account event or related record,
- a verified user-provided Check Direct ID.

Use `GetCheckDirect` when the user needs:

- the amount or check number for a specific payment record,
- authoritative received or status fields,
- the related Customer, Campaign, or Shop context,
- exact related entity IDs for a narrow follow-up.

Never guess, truncate, transform, or loosely match the ID.

---

## Choosing the Correct Retrieval Path

```text
Do you have the exact Check Direct ID?
    ├─ Yes → GetCheckDirect
    └─ No
        ↓
Do you need a small operational list within a narrow date range?
    ├─ Yes → GetCheckDirects
    └─ No
        ↓
Is the request for totals, counts, trends, or comparison?
    ├─ Yes → BigQueryRunQuery
    └─ No → Obtain the missing authoritative context
```

---

## Check Direct Status and Receipt

The retrieval schema includes `received` and `status`.

Use these fields carefully:

- `received` answers whether RevCent records the physical check as received.
- `status` provides the current authoritative status string.
- creation of the item alone does not prove receipt,
- receipt alone should not automatically be described as clearing,
- do not invent a status enum not returned by RevCent.

If a workflow must decide whether to ship or provide service, apply the business's authorized policy to the authoritative record state rather than making a generic assumption.

---

## Refund Handling

There is no `RefundCheckDirect` MCP operation.

RevCent's Check Direct documentation directs refund handling to the associated commerce entity, such as:

- Product Sale,
- Shipping,
- Tax,
- Subscription Renewal,
- another relevant Sale component.

That workflow can create Pending Refund context related to the Check Direct.

AI/MCP clients must not promise an electronic reversal of a physical check. Before initiating a refund workflow, determine:

- which item is being refunded,
- whether the refund is full or partial,
- whether the original check was received and cleared,
- how the business will issue the return payment,
- whether the user has authorized the consequential action.

---

## Critical Analytics Rule

Do **not** use `GetCheckDirects` pagination to calculate metrics or produce reports.

Use `GetBigQueryTables` to retrieve the current schema, then use `BigQueryRunQuery` for questions such as:

- How much revenue used Check Direct this month?
- How many Check Direct Sales are related to each Campaign or Shop?
- Which Customers or Products use physical checks most often?
- How many check-based Sales have Pending Refunds?
- How does physical-check volume compare with other payment methods?

Do not guess table or field names.

---

## BigQuery Check Table

The documented table is:

```text
`revcent.user.check`
```

Fields include:

| Field | Type | Meaning |
|---|---|---|
| `created_at` | TIMESTAMP | When the Check was created. |
| `id` | STRING | Check Direct ID. |
| `amount` | FLOAT | Check amount. |
| `live_mode` | BOOLEAN | Whether the record is live or test data. |
| `campaign` | STRING | Related Campaign ID. |
| `iso_currency` | STRING | Three-character currency code. |
| `customer` | STRING | Related Customer ID. |
| `third_party_shop` | STRING | Related Third Party Shop ID. |
| `tax` | REPEATED STRING | Related Tax IDs. |
| `shipping` | REPEATED STRING | Related Shipping IDs. |
| `product_sale` | REPEATED STRING | Related Product Sale IDs. |
| `pending_refund` | REPEATED STRING | Related Pending Refund IDs. |
| `metadata` | REPEATED RECORD | Metadata name, value, and entry date. |

For accurate reporting:

- separate live and test data,
- group monetary totals by currency unless explicit conversion logic is provided,
- avoid double-counting repeated relationships,
- join through documented IDs,
- state the date range and filters used.

---

## Check Direct vs Other Payment Items

| User Question | Correct Item |
|---|---|
| Was a card attempted, approved, or declined by a Gateway? | Transaction |
| What PayPal payment belongs to this Sale? | PayPal Transaction |
| What alternate or external payment belongs to this Sale? | Offline Payment |
| What physical-check payment belongs to this Sale? | Check Direct |

Use the authoritative Sale payment type and relationship IDs. Do not infer the payment item from a Product name, Customer note, or Metadata label.

---

## Fulfillment and Accounts-Receivable Guidance

A Check Direct can be created before the entire physical-check lifecycle is complete.

An AI/MCP workflow should distinguish:

```text
Sale and Check Direct created
    ≠ necessarily received

received = true
    ≠ necessarily cleared

authoritative cleared business state
    → apply business fulfillment policy
```

RevCent provides the connected payment and order records. The business determines whether fulfillment waits for creation, receipt, deposit, or clearing.

---

## Metadata Guidance

Use Metadata for non-sensitive reconciliation context, such as:

- purchase-order reference,
- invoice reference,
- internal remittance reference,
- support case,
- business unit,
- accounts-receivable owner.

Do not store raw bank account or routing numbers in general-purpose Metadata. Do not invent a Check Direct schema field when a supported Metadata reference is sufficient.

---

## Live and Test Mode

Check Directs can belong to live or test Sale activity.

For operational retrieval, make sure the selected record belongs to the intended environment. For reporting, exclude test records from production payment totals unless the user explicitly asks for them.

Mixing test and live Check Directs can overstate accounts receivable, Sale value, and payment-method adoption.

---

## Best Practices

1. Treat Check Direct as the official payment item for a `check_direct` Sale.
2. Remember that it represents a physical check, not ACH or electronic check.
3. Create it through the Sale workflow; do not look for `CreateCheckDirect`.
4. Use exact Check Direct IDs from authorized RevCent results.
5. Use `GetCheckDirects` only for bounded operational discovery.
6. Use `GetCheckDirect` for one authoritative record.
7. Treat `received` and `status` as authoritative and do not invent clearing state.
8. Protect check and Customer details in customer-facing workflows.
9. Use the related commerce item and Pending Refund workflow for refunds.
10. Use `BigQueryRunQuery` for metrics, reconciliation, and broad analysis.
11. Separate live/test records and monetary totals by currency.
12. Keep raw bank and routing details out of general-purpose Metadata.

---

## Common Mistakes to Avoid

- Treating Check Direct as a card Transaction.
- Treating Check Direct as ACH or electronic check.
- Looking for a standalone creation or refund operation.
- Assuming item creation means the physical check arrived.
- Assuming receipt means the check cleared.
- Guessing a status enum or interpreting a missing status.
- Creating a check-based Sale without the user's explicit intent.
- Disclosing a Check Direct based only on unverified Customer claims.
- Storing or repeating unnecessary banking details.
- Paging through `GetCheckDirects` for reporting.
- Mixing live/test data or currencies.
- Assuming every future Subscription Renewal uses the initial Sale's check payment path.

---

## AI/MCP Decision Guide

| User Intent | Recommended Action |
|---|---|
| “Create this Sale to be paid by physical check.” | Verify the full Sale and use `CreateSale` with `payment_type: check_direct`. |
| “Show me this check payment.” | Use `GetCheckDirect` with the exact ID. |
| “Find recent checks for this Customer.” | Use `GetCheckDirects` with a narrow date range and `customer_id`. |
| “Which payment entry belongs to this check-based Sale?” | Retrieve the Sale, use its `check_directs` ID, then call `GetCheckDirect`. |
| “Has the check arrived?” | Retrieve the Check Direct and report the authoritative `received` value. |
| “Has it cleared?” | Use only an authoritative state that supports clearing; do not infer from creation or receipt. |
| “Refund this check payment.” | Identify and refund the correct related commerce item; confirm how return funds will be issued. |
| “How much physical-check revenue did we receive?” | Use `GetBigQueryTables`, then `BigQueryRunQuery`. |

---

## Final AI/MCP Instruction

Treat Check Direct as the official physical-check payment item created by a Sale with `payment_type: check_direct`.

Use `GetCheckDirects` for narrow, bounded discovery and `GetCheckDirect` for one exact record. Follow returned relationship IDs only when the user's request needs more context. Never infer receipt or clearing from item creation, and protect check-related details as payment-sensitive data.

Use the appropriate related-item refund workflow for refunds and `BigQueryRunQuery` for all metrics, aggregation, reconciliation, and broad analysis.


---
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.