Kobana Pix Payment via MCP

Pay Pix charges and decode QR codes using the kobana-mcp-payment MCP server tools.

Prerequisites

The kobana-mcp-payment MCP server must be configured. See [MCP Server Setup](#mcp-server-setup) below.

Available MCP Tools

Pix Payments

Pix Decoding

Payment Batches

Financial Accounts

Paying a Pix Charge

Step 1: Get the Financial Account UID

First, list available financial accounts to get the source financialaccountuid:

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

This returns the charge details: amount, merchant name, key, description, etc.

Step 3: Create the Payment

Use the createpaymentpix tool with the required parameters:

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": "[email protected]",
  "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-..." }
  ]
}

Or create new payments directly in the batch:

{
  "financial_account_uid": "018df180-7208-727b-...",
  "payments": [
    {
      "emv": "00020126580014br.gov.bcb.pix...",
      "amount": 150.00
    }
  ]
}

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

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

Status Reference

Payment Status

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

Registration Status

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

MCP Server Setup

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS) or %APPDATA%\Claude\claudedesktopconfig.json (Windows):

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

Sandbox Environment

{
  "mcpServers": {
    "kobana-payment": {
      "command": "npx",
      "args": ["-y", "kobana-mcp-payment"],
      "env": {
        "KOBANA_ACCESS_TOKEN": "your_sandbox_token",
        "KOBANA_API_URL": "https://api-sandbox.kobana.com.br"
      }
    }
  }
}

Claude Code Configuration

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"
      }
    }
  }
}

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"
      ]
    }
  }
}

Best Practices

1. Get financial account first - Use listfinancialaccounts to get available accounts
2. Decode before paying - Use decodepixemv to validate the charge data
3. Use batches for efficiency - Create multiple payments in a single batch
4. Check batch status - Poll getpaymentbatch or use webhooks
5. Approve when needed - Some accounts require manual approval
6. Use external_id - Track payments in your system
7. Test in sandbox - Configure sandbox environment first

Reference Documentation

See [references/REFERENCE.md](references/REFERENCE.md) for complete MCP server documentation and all available tools.