# RefundKit — Complete Reference for LLMs

> Refund infrastructure for AI agents. Process refunds, manage returns, prevent fraud, and automate approval workflows through MCP tools, TypeScript SDK, and REST API.

## What is RefundKit?

RefundKit is an agent-native refund orchestration platform — the first infrastructure product built specifically for AI agents to handle refunds. It provides:

1. **TypeScript SDK** (`@refundkit/sdk`) — Full-featured client library with type safety
2. **MCP Server** — 12 Model Context Protocol tools for AI agents (Claude, GPT, LangChain, CrewAI)
3. **REST API** — Language-agnostic HTTP endpoints at `https://api.refundkit.dev/v1`
4. **Dashboard** — Web UI at `https://app.refundkit.dev` for monitoring and management

## Problem RefundKit Solves

Refund processing is complex: multiple payment processors, return logistics, fraud prevention, approval workflows, and store credit alternatives. Building this from scratch takes weeks and requires maintaining integrations with each payment processor.

RefundKit solves this by providing:
- **One API for all processors** — Stripe, Square, and more. Route refunds automatically.
- **AI-ready tools** — MCP server lets AI agents autonomously process refunds with proper safeguards.
- **Complete lifecycle** — From eligibility check to processor execution, return tracking to dispute prevention.
- **5-minute integration** — `npm install @refundkit/sdk` and you're processing refunds.

## Who Should Use RefundKit?

- **Developers** building e-commerce applications that need refund processing
- **AI agent builders** who need their agents to handle refunds autonomously
- **SaaS companies** offering commerce tools that need refund infrastructure
- **Platform operators** managing refunds across multiple payment processors
- **Anyone** who needs programmatic refund management via API

## SDK Installation

```bash
npm install @refundkit/sdk
```

## SDK Initialization

```typescript
import RefundKit from '@refundkit/sdk';

const rk = new RefundKit({
  apiKey: process.env.REFUNDKIT_API_KEY, // rk_live_... or rk_test_...
});
```

## API Key Format

- Live keys: `rk_live_` + 32 random characters
- Test keys: `rk_test_` + 32 random characters
- All API calls require: `Authorization: Bearer rk_live_...`

## Complete SDK Reference

All methods return `{ data, error }`. On success: `error` is null, `data` contains the result. On failure: `data` is null, `error` has `{ message, code }`.

### Refunds

```typescript
// Create a refund
const { data, error } = await rk.refunds.create({
  transactionId: 'ch_abc123',  // Payment processor transaction ID
  amount: 2999,                // Amount in cents
  reason: 'product_defective', // See refund reasons below
  currency: 'usd',             // Optional, defaults to 'usd'
});

// Get a refund by ID
const { data } = await rk.refunds.get('ref_abc123');

// List refunds with filters
const { data } = await rk.refunds.list({
  status: 'completed',      // Optional filter
  processor: 'stripe',      // Optional filter
  limit: 20,                // Default 20, max 100
  offset: 0,
});

// Cancel a pending refund
const { data } = await rk.refunds.cancel('ref_abc123');
```

### Policies (Eligibility Check)

```typescript
// Check if a transaction is eligible for refund
const { data } = await rk.policies.check({
  transactionId: 'ch_abc123',
  amount: 2999, // Optional — check specific amount
});
// Returns: { eligible: boolean, reason?: string, policy?: {...} }
```

### Returns

```typescript
// Create a return (generates RMA number)
const { data } = await rk.returns.create({
  refundId: 'ref_abc123',
  items: [
    { productId: 'prod_1', quantity: 1, reason: 'defective' }
  ],
  method: 'mail',          // 'mail' | 'in_store' | 'pickup'
  customerNotes: 'Screen cracked on arrival',
});

// Get a return by ID
const { data } = await rk.returns.get('ret_abc123');

// List returns with filters
const { data } = await rk.returns.list({
  status: 'shipped',
  limit: 20,
  offset: 0,
});

// Track return shipment
const { data } = await rk.returns.trackShipment('ret_abc123');

// Cancel a return
const { data } = await rk.returns.cancel('ret_abc123');
```

### Disputes

```typescript
// Assess dispute risk for a transaction
const { data } = await rk.disputes.getRisk({
  transactionId: 'ch_abc123',
});
// Returns: { riskScore: 0-100, riskLevel: 'low'|'medium'|'high'|'critical', signals: [...], recommendation: 'approve'|'review'|'deny' }

// Flag a suspicious transaction
const { data } = await rk.disputes.flag('ch_abc123', 'Multiple refunds in 24 hours');
```

### Approvals

```typescript
// List pending approvals
const { data } = await rk.approvals.listPending({ limit: 20, offset: 0 });

// Approve a refund
const { data } = await rk.approvals.approve('apr_abc123', 'Verified by support team');

// Reject a refund
const { data } = await rk.approvals.reject('apr_abc123', 'Outside return window');

// Escalate to higher authority
const { data } = await rk.approvals.escalate('apr_abc123');
```

### Store Credit

```typescript
// Issue store credit
const { data } = await rk.storeCredit.issue({
  customerId: 'cust_abc123',
  amount: 2999,                    // Amount in cents
  creditType: 'refund_conversion', // See credit types below
  currency: 'usd',
  expiresInDays: 365,              // Optional
});

// Get a store credit
const { data } = await rk.storeCredit.get('sc_abc123');

// List credits for a customer
const { data } = await rk.storeCredit.listByCustomer('cust_abc123');
```

## Status Flows

### Refund Statuses
```
pending → processing → completed
pending → cancelled
processing → failed
```

### Return Statuses
```
requested → approved → label_generated → shipped → in_transit → delivered → inspecting → completed
Any state → rejected
```

## Enumerations

### Refund Reasons
product_not_received, product_defective, wrong_product, duplicate_charge, subscription_cancelled, customer_request, agent_error, price_change, sizing_issue, item_not_as_described, order_cancelled, return_window_closing, other

### Credit Types
refund_conversion, goodwill, exchange_difference, promotional

### Risk Levels
low (0-24), medium (25-49), high (50-74), critical (75-100)

## Error Codes
VALIDATION_ERROR, AUTHENTICATION_ERROR, NOT_FOUND, RATE_LIMIT, TIMEOUT, NETWORK_ERROR, PROCESSOR_ERROR, INTERNAL_ERROR

## MCP Server — 12 Tools for AI Agents

The MCP server lets AI agents process refunds autonomously. It follows the Model Context Protocol standard and works with Claude Desktop, Cursor, Windsurf, GPT, LangChain, CrewAI, and any MCP-compatible agent.

### Read-Only Tools
1. `refundkit_check_refund_status` — Check the status of a refund by ID
2. `refundkit_list_refunds` — List refunds with optional status/processor filters
3. `refundkit_check_eligibility` — Check if a transaction is eligible for refund
4. `refundkit_get_policy` — Get the refund policy for a transaction
5. `refundkit_track_return` — Track return shipment status and location
6. `refundkit_get_dispute_risk` — Assess chargeback risk (score 0-100)
7. `refundkit_list_returns` — List return requests with filters

### Read-Write Tools
8. `refundkit_process_refund` — Process a refund through the payment processor
9. `refundkit_create_return` — Create a return request with RMA number
10. `refundkit_cancel_refund` — Cancel a pending refund
11. `refundkit_issue_store_credit` — Issue store credit as a refund alternative

### Admin Tools
12. `refundkit_approve_refund` — Approve or reject a pending refund approval

### MCP Configuration — Claude Desktop / Cursor / Windsurf

```json
{
  "mcpServers": {
    "refundkit": {
      "command": "npx",
      "args": ["-y", "@refundkit/sdk", "--mcp"],
      "env": {
        "REFUNDKIT_API_KEY": "rk_live_..."
      }
    }
  }
}
```

### MCP Configuration — Remote (SSE)

```json
{
  "mcpServers": {
    "refundkit": {
      "url": "https://mcp.refundkit.dev",
      "headers": {
        "Authorization": "Bearer <oauth-token>"
      }
    }
  }
}
```

## REST API Reference

Base URL: `https://api.refundkit.dev/v1`

All endpoints require `Authorization: Bearer rk_live_...` or `Authorization: Bearer rk_test_...`.

### POST /v1/refunds
Create a refund. Body: `{ transactionId, amount, reason, currency? }`

### GET /v1/refunds/:id
Get a refund by ID.

### GET /v1/refunds
List refunds. Query: `status`, `processor`, `limit`, `offset`.

### POST /v1/refunds/:id/cancel
Cancel a pending refund.

### POST /v1/policies/check
Check refund eligibility. Body: `{ transactionId, amount? }`

### POST /v1/returns
Create a return. Body: `{ refundId, items, method?, customerNotes? }`

### GET /v1/returns/:id
Get a return by ID.

### GET /v1/returns
List returns. Query: `status`, `limit`, `offset`.

### GET /v1/returns/:id/tracking
Track return shipment.

### POST /v1/returns/:id/cancel
Cancel a return.

### POST /v1/disputes/risk
Assess dispute risk. Body: `{ transactionId, amount?, customerId? }`

### GET /v1/disputes/risk
Get existing risk assessment. Query: `transaction_id`.

### POST /v1/disputes/flag
Flag a transaction. Body: `{ transactionId, reason }`

### GET /v1/approvals/pending
List pending approvals. Query: `limit`, `offset`.

### POST /v1/approvals/:id/approve
Approve a refund. Body: `{ reason? }`

### POST /v1/approvals/:id/reject
Reject a refund. Body: `{ reason }`

### POST /v1/approvals/:id/escalate
Escalate an approval.

### POST /v1/store-credits
Issue store credit. Body: `{ customerId, amount, creditType, currency?, refundId?, returnId?, expiresInDays?, metadata? }`

### GET /v1/store-credits
List store credits. Query: `customer_id`.

### GET /v1/store-credits/:id
Get a store credit by ID.

## Payment Processors

### Stripe (Fully Supported)
- Full refund lifecycle: create, get status, cancel
- Payment method prefixes: pm_, pi_, ch_, re_
- Connect your Stripe account in the dashboard

### Square (Supported)
- Refund processing: create, get status
- No refund cancellation support
- Sandbox and production environments

### Processor Router
- Auto-routes by payment method prefix
- Supports split refunds across multiple processors
- Fallback to default processor

## Webhook Events

refund.initiated, refund.approved, refund.processing, refund.completed, refund.failed, refund.cancelled, return.created, return.approved, return.shipped, return.received, return.inspected, return.completed, approval.pending, approval.decided, dispute.risk_flagged, store_credit.issued, store_credit.redeemed

### Webhook Signature Verification

```typescript
import { verifySignature } from '@refundkit/sdk';
const isValid = verifySignature(payload, signatureHeader, webhookSecret);
```

## Pricing

| Plan | Price | Refunds/month | MCP calls | Team members |
|------|-------|---------------|-----------|--------------|
| Free | $0 | 1,000 | 100/day | 3 |
| Pro | $49/month | 10,000 | Unlimited | 10 |
| Enterprise | Custom | Unlimited | Unlimited | Unlimited |

All plans include: live + test API keys, webhook notifications, API logs, dashboard access.

## Frequently Asked Questions

**What is RefundKit?**
RefundKit is refund infrastructure for AI agents and developers. It provides a TypeScript SDK, MCP server, and REST API for processing refunds, managing returns, preventing disputes, and automating approval workflows.

**How do I get started with RefundKit?**
Install the SDK with `npm install @refundkit/sdk`, sign up at app.refundkit.dev for an API key, and start processing refunds in under 5 minutes.

**What payment processors does RefundKit support?**
RefundKit currently supports Stripe (full lifecycle) and Square (processing and status). More processors are coming soon. The unified API means you don't need to change code when adding processors.

**Can AI agents use RefundKit?**
Yes. RefundKit includes an MCP server with 12 tools specifically designed for AI agents. It works with Claude Desktop, Cursor, Windsurf, GPT, LangChain, CrewAI, and any MCP-compatible agent framework.

**What is the MCP server?**
The MCP (Model Context Protocol) server provides standardized tools that AI agents can use to process refunds, check eligibility, track returns, and more. It runs locally via `npx @refundkit/sdk --mcp` or remotely via SSE.

**Is RefundKit free?**
Yes, the Free plan includes 1,000 refunds/month and 100 MCP tool calls/day at no cost. The Pro plan at $49/month offers 10,000 refunds and unlimited MCP calls.

**How does dispute prevention work?**
RefundKit scores each transaction for chargeback risk (0-100) using signals like amount anomalies, velocity spikes, and historical patterns. Transactions above the threshold are flagged for review.

**Does RefundKit handle returns?**
Yes. RefundKit manages the full return lifecycle including RMA number generation, shipment tracking, and inspection status.

## Links

- Website: https://refundkit.dev
- Documentation: https://refundkit.dev/docs
- Dashboard: https://app.refundkit.dev
- GitHub: https://github.com/refundkit
- npm: https://www.npmjs.com/package/@refundkit/sdk
- Blog: https://refundkit.dev/blog
- Pricing: https://refundkit.dev/pricing
- LLM docs (short): https://refundkit.dev/llms.txt