Kobana Charge Pix Skill

Manage Pix charges, accounts, and payments via Kobana.

How It Works

This skill supports two modes of operation:

1. MCP (preferred) — If the kobana-mcp-charge MCP server is available, use MCP tools directly. This is simpler and recommended.
2. REST API (fallback) — If MCP is not available, use HTTP calls to the Kobana API.

Rule: Always try MCP tools first. Only fall back to the REST API if MCP tools are not available or not configured.

MCP Mode

Available MCP Tools

Pix Accounts

Pix Charges

Creating a Pix Charge (MCP)

Step 1: Get the Pix Account UID

Use tool: list_charge_pix_accounts

Step 2: Create the Pix Charge

Instant Pix (e-commerce, delivery):

{
  "amount": 150.00,
  "pix_account_uid": "018df180-7208-727b-...",
  "expire_at": "2026-01-31T12:30:00-03:00",
  "registration_kind": "instant",
  "payer": {
    "document_number": "111.321.322-09",
    "name": "João da Silva"
  },
  "external_id": "order_12345"
}

Billing Pix (invoices, subscriptions):

{
  "amount": 500.00,
  "pix_account_uid": "018df180-7208-727b-...",
  "expire_at": "2026-02-10T23:59:59-03:00",
  "registration_kind": "billing",
  "payer": {
    "document_number": "12.345.678/0001-90",
    "name": "Company LTDA"
  },
  "fine_type": "percentage",
  "fine_percentage": 2.0,
  "interest_type": "monthly_percentage_calendar",
  "interest_percentage": 1.0,
  "revoke_days": 30
}

Step 3: Get the QR Code

The initial response may not contain the QR Code (asynchronous registration). Poll using get_charge_pix until registration_status is confirmed.

Use tool: get_charge_pix
Parameters: { "uid": "019c0cbe-f018-717e-..." }

MCP Server Setup

Claude Code

If you installed the kobana-agent-skills plugin, the MCP servers are already configured. Just set the environment variable before running Claude Code:

export KOBANA_ACCESS_TOKEN="your_access_token"
claude

For sandbox, also set:

export KOBANA_API_URL="https://api-sandbox.kobana.com.br"

Or add to .mcp.json in your project root:

{
  "mcpServers": {
    "kobana-charge": {
      "command": "npx",
      "args": ["-y", "kobana-mcp-charge"],
      "env": {
        "KOBANA_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kobana-charge": {
      "command": "npx",
      "args": ["-y", "kobana-mcp-charge"],
      "env": {
        "KOBANA_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Important: Replace your_access_token with your actual Kobana API token. Claude Desktop does not support environment variable expansion (${VAR}) — you must paste the real token value directly.

For sandbox, add "KOBANA_API_URL": "https://api-sandbox.kobana.com.br" to the env object.

Remote MCP (Hosted)

{
  "mcpServers": {
    "kobana-charge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.kobana.com.br/charge/mcp",
        "--header",
        "Authorization: Bearer your_access_token"
      ]
    }
  }
}

API Mode (Fallback)

Base URLs

Production: https://api.kobana.com.br
Sandbox:    https://api-sandbox.kobana.com.br

Authentication

Authorization: Bearer {your_api_token}

API Endpoints Overview

Pix Accounts

Pix Charges

Pix Commands

Charge Payments

Creating a Pix Charge (API)

Minimum Required:

POST /v2/charge/pix

{
  "amount": 100.50,
  "pix_account_uid": "018df180-7208-727b-...",
  "expire_at": "2026-12-02T10:03:56-03:00"
}

Complete Example (Billing Pix):

POST /v2/charge/pix

{
  "amount": 500.00,
  "pix_account_uid": "018df180-7208-727b-...",
  "expire_at": "2026-02-10T23:59:59-03:00",
  "registration_kind": "billing",
  "payer": {
    "document_number": "12.345.678/0001-90",
    "name": "Company LTDA",
    "email": "finance@company.com"
  },
  "fine_type": "percentage",
  "fine_percentage": 2.0,
  "interest_type": "monthly_percentage_calendar",
  "interest_percentage": 1.0,
  "discount_type": "advance_percentage_calendar",
  "discount_first_percentage": 5.0,
  "discount_first_days": 5,
  "revoke_days": 30,
  "external_id": "invoice_2026_001",
  "tags": ["monthly", "subscription"],
  "message": "Invoice January/2026"
}

Important: Asynchronous Behavior

The QR Code is NOT returned in the initial response. Options:

1. Poll the charge - GET /v2/charge/pix/{uid} until registration_status is confirmed
2. Use webhooks - Configure webhook for pix.register.confirmed event

Listing and Filtering

GET /v2/charge/pix?status=opened&created_from=2026-01-01&per_page=50

Common Parameters

Required

Payer Data

Fine and Interest (Billing Pix only)

Tracking

Pix Types

Instant Pix (registration_kind: "instant")

• Short expiration (minutes to hours)
• No interest, fines, or discounts
• Use for: e-commerce, delivery, point-of-sale

Billing Pix (registration_kind: "billing")

• Formal due date
• Supports interest, fines, discounts
• Stays active after due date (if revoke_days set)
• Use for: monthly invoices, subscriptions

Status Reference

Charge Status

• opened - Open (initial)
• paid - Paid
• overdue - Overdue
• canceled - Canceled
• generation_failed - Registration failed

Registration Status

• pending - Waiting
• confirmed - Ready (has QR Code)
• rejected / failed - Error

Best Practices

1. Prefer MCP when available - Simpler and more reliable
2. Poll or use webhooks - QR Code comes asynchronously
3. Use external_id - Track charges in your system
4. Set revoke_days - Required for interest/fines
5. Validate CPF/CNPJ - Before creating the charge
6. Use X-Idempotency-Key header - Prevent duplicates (API mode)
7. Test in sandbox - Before production

Reference Documentation

See references/REFERENCE.md for complete documentation including all parameters, response formats, error codes, MCP tools, and API endpoints.