Kobana Payment Pix Skill

Pay Pix charges, decode QR codes, and manage Pix payments via Kobana.

How It Works

This skill supports two modes of operation:

1. MCP (preferred) — If the kobana-mcp-payment 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 Payments

Pix Decoding

Payment Batches

Financial Accounts

Paying a Pix Charge (MCP)

Step 1: Get the Financial Account UID

Use tool: list_financial_accounts

Step 2: Decode the Pix EMV (Optional)

Before paying, decode the QR code to validate the charge data:

Use tool: decode_pix_emv
Parameters: {
  "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000..."
}

Step 3: Create the Payment

Payment by EMV (Dynamic Pix):

{
  "financial_account_uid": "018df180-7208-727b-...",
  "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000...",
  "amount": 150.00,
  "external_id": "payment_001"
}

Payment by Pix Key (Static Pix):

{
  "financial_account_uid": "018df180-7208-727b-...",
  "type": "key",
  "key_type": "email",
  "key": "recipient@example.com",
  "amount": 150.00,
  "beneficiary": {
    "document_number": "12.345.678/0001-90",
    "name": "Company LTDA"
  },
  "external_id": "payment_002"
}

Step 4: Create a Batch to Send

After creating payments, create a batch to send them to the bank:

Use tool: create_payment_pix_batch
Parameters: {
  "financial_account_uid": "018df180-7208-727b-...",
  "payments": [
    { "uid": "019c0cbe-f018-717e-..." }
  ]
}

Step 5: Check Batch Status

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

If the batch is awaiting_approval, approve it:

Use tool: approve_payment_batch
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-payment": {
      "command": "npx",
      "args": ["-y", "kobana-mcp-payment"],
      "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-payment": {
      "command": "npx",
      "args": ["-y", "kobana-mcp-payment"],
      "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-payment": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.kobana.com.br/payment/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 Payments

Pix Decoding

Payment Batches

Paying a Pix Charge (API)

Step 1: Decode the Pix EMV (Optional but Recommended)

POST /v2/payment/pix/decode

{
  "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000..."
}

Step 2: Create the Payment

By EMV (QR Code/Copy-Paste):

POST /v2/payment/pix

{
  "financial_account_uid": "018df180-7208-727b-...",
  "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000...",
  "amount": 150.00,
  "scheduled_to": "2026-01-31",
  "external_id": "payment_001"
}

By Pix Key (Static Pix):

POST /v2/payment/pix

{
  "financial_account_uid": "018df180-7208-727b-...",
  "type": "key",
  "key_type": "email",
  "key": "recipient@example.com",
  "amount": 150.00,
  "beneficiary": {
    "document_number": "12.345.678/0001-90",
    "name": "Company LTDA"
  },
  "external_id": "payment_001"
}

Important: Two-Step Flow

Pix payments require a two-step process:

1. Create Payment - POST /v2/payment/pix creates a pending payment
2. Create Batch - POST /v2/payment/pix_batches sends payments to the bank

Creating a Batch:

POST /v2/payment/pix_batches

{
  "financial_account_uid": "018df180-7208-727b-...",
  "payments": [
    { "uid": "019c0cbe-f018-717e-..." }
  ]
}

Batch Approval Workflow

Some financial accounts require manual approval:

1. Batch created - Status: pending or awaiting_approval
2. Approve - PUT /v2/payment/batches/{uid}/approve
3. Or Reprove - PUT /v2/payment/batches/{uid}/reprove

Listing and Filtering

GET /v2/payment/pix?status=pending&per_page=50

Common Parameters

Required

For EMV Payment (Dynamic Pix)

For Key Payment (Static Pix)

Beneficiary

Optional

Payment Types

By EMV (Dynamic Pix)

• Use when you have a QR code or copy-paste string
• Amount may be fixed by the charge
• Most common for invoices and bills

By Pix Key (Static Pix)

• Use when paying directly to a Pix key
• You define the amount
• Use for donations, tips, or manual payments

Key Types

Status Reference

Payment Status

• pending - Pending (initial)
• awaiting_approval - Awaiting approval
• approved - Approved
• confirmed - Confirmed by bank
• rejected - Rejected by bank
• reproved - Reproved (canceled before sending)

Registration Status

• pending - Waiting for registration
• requested - Sent to bank
• confirmed - Confirmed at bank
• rejected / failed - Error

Batch Status

• pending - Pending (initial)
• awaiting_approval - Awaiting approval
• approved - Approved
• confirmed - All payments confirmed
• reproved - Reproved

Best Practices

1. Prefer MCP when available - Simpler and more reliable
2. Decode before paying - Validate the charge data before creating payment
3. Use batches for multiple payments - More efficient than individual payments
4. Set external_id - Track payments in your system
5. Schedule payments - Use scheduled_to for future-dated payments
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.