# lipila-mcp

MCP Server + Agent Skills for the [Lipila](https://lipila.io) payment gateway.

## What's Included

### MCP Server (`index.js`)
Expose Lipila payment tools to any MCP-compatible AI agent.

**Tools:**
| Tool | Description |
|------|-------------|
| `lipila_collect_mobile` | Initiate MoMo collection (MTN, Airtel, Zamtel) |
| `lipila_collect_card` | Initiate card payment (Visa, MC, Amex) |
| `lipila_disburse` | Send money to mobile wallet |
| `lipila_check_status` | Check transaction status |
| `lipila_webhook_verify` | Parse webhook callback payload |

### Agent Skill (`skills/SKILL.md`)
Full API reference, workflows, and error handling for Hermes Agent.

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Get your API key

- Sandbox: https://dashboard.lipila.dev
- Production: https://dashboard.lipila.io

### 3. Configure your agent

**Hermes Agent** — add to `config.yaml`:
```yaml
mcp_servers:
  lipila:
    command: node
    args: ["/path/to/lipila-mcp/index.js"]
    env:
      LIPILA_API_KEY: "lsk_your_key_here"
      LIPILA_ENV: "production"  # or "sandbox"
```

**Claude Code** — add to `~/.claude/settings.json`:
```json
{
  "mcpServers": {
    "lipila": {
      "command": "node",
      "args": ["/path/to/lipila-mcp/index.js"],
      "env": {
        "LIPILA_API_KEY": "lsk_your_key_here",
        "LIPILA_ENV": "production"
      }
    }
  }
}
```

**Codex** — add to `~/.codex/config.toml`:
```toml
[mcp_servers.lipila]
command = "node"
args = ["/path/to/lipila-mcp/index.js"]

[mcp_servers.lipila.env]
LIPILA_API_KEY = "lsk_your_key_here"
LIPILA_ENV = "production"
```

**Antigravity** — add to `~/.gemini/antigravity-ide/mcp_config.json`:
```json
{
  "mcpServers": {
    "lipila": {
      "command": "node",
      "args": ["/path/to/lipila-mcp/index.js"],
      "env": {
        "LIPILA_API_KEY": "lsk_your_key_here",
        "LIPILA_ENV": "production"
      }
    }
  }
}
```

### 4. Restart your agent

## API Reference

### Base URLs
- Sandbox: `https://api.lipila.dev/api/v1`
- Production: `https://blz.lipila.io/api/v1`

### Authentication
All requests use `x-api-key` header.

### Collections — Mobile Money
```
POST /collections/mobile-money
```
| Field | Type | Required |
|-------|------|----------|
| referenceId | string | Yes |
| amount | number | Yes |
| narration | string | Yes |
| accountNumber | string | Yes |
| currency | string | Yes |
| email | string | No |

### Collections — Card
```
POST /collections/card
```
Same fields as mobile money.

### Disbursements
```
POST /disbursements/mobile-money
```
Same fields as collections.

### Transaction Status
```
GET /transactions/{referenceId}
```

### Webhooks
Lipila sends callbacks with:
```json
{
  "referenceId": "...",
  "amount": 1.75,
  "currency": "ZMW",
  "status": "Successful",
  "paymentType": "Card",
  "type": "Collection",
  "accountNumber": "260xxxxxxxxxx",
  "identifier": "TXN123456789",
  "message": "Payment completed successfully.",
  "externalId": "MP250000987654321"
}
```

## License

MIT