api-charge-pix

📁 universokobana/kobana-agent-skills 📅 Jan 31, 2026

总安装量

周安装量

#32924

全站排名

安装命令

npx skills add https://github.com/universokobana/kobana-agent-skills --skill api-charge-pix

Agent 安装分布

claude-code 8

opencode 2

command-code 2

github-copilot 2

codex 2

gemini-cli 2

Skill 文档

Kobana Charge API Skill

Manage Pix charges, accounts, and payments via Kobana API.

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

Method	Endpoint	Description
GET	`/v2/charge/pix_accounts`	List all Pix accounts
POST	`/v2/charge/pix_accounts`	Create a new Pix account
GET	`/v2/charge/pix_accounts/{uid}`	Get a specific Pix account
PUT	`/v2/charge/pix_accounts/{uid}`	Update a Pix account
DELETE	`/v2/charge/pix_accounts/{uid}`	Delete a Pix account

Pix Charges

Method	Endpoint	Description
GET	`/v2/charge/pix`	List all Pix charges
POST	`/v2/charge/pix`	Create a new Pix charge
GET	`/v2/charge/pix/{uid}`	Get a specific Pix charge
PUT	`/v2/charge/pix/{uid}/update`	Update a Pix charge
DELETE	`/v2/charge/pix/{uid}`	Delete a Pix charge
POST	`/v2/charge/pix/{uid}/cancel`	Cancel a Pix charge

Pix Commands

Method	Endpoint	Description
GET	`/v2/charge/pix/{pix_uid}/commands`	List commands for a Pix charge
GET	`/v2/charge/pix/{pix_uid}/commands/{id}`	Get a specific command

Charge Payments

Method	Endpoint	Description
GET	`/v2/charge/payments`	List all payments
POST	`/v2/charge/payments`	Create a new payment
GET	`/v2/charge/payments/{uid}`	Get a specific payment
DELETE	`/v2/charge/payments/{uid}`	Delete a payment

Creating a Pix Charge

Minimum Required Parameters

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

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

Important: Asynchronous Behavior

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

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

Listing and Filtering

List Pix Charges with Filters

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

Parameter	Description
`status`	Filter by status (opened, paid, overdue, canceled)
`registration_status`	Filter by registration status
`pix_account_uid`	Filter by Pix account
`created_from` / `created_to`	Filter by creation date
`expire_from` / `expire_to`	Filter by expiration date
`paid_from` / `paid_to`	Filter by payment date
`txid`	Filter by TXID
`external_id`	Filter by external ID
`tags`	Filter by tags
`page` / `per_page`	Pagination

List Pix Accounts

GET /v2/charge/pix_accounts

Updating and Canceling

Update a Pix Charge

PUT /v2/charge/pix/{uid}/update

{
  "amount": 550.00,
  "expire_at": "2026-02-15T23:59:59-03:00"
}

Cancel a Pix Charge

POST /v2/charge/pix/{uid}/cancel

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

Common Parameters

Fine (after due date)

{
  "fine_type": "percentage",  // or "amount"
  "fine_percentage": 2.0
}

Interest

{
  "interest_type": "monthly_percentage_calendar",
  "interest_percentage": 1.0
}

Interest types: daily_amount_calendar, daily_percentage_calendar, monthly_percentage_calendar, yearly_percentage_calendar, daily_amount_business, daily_percentage_business, monthly_percentage_business, yearly_percentage_business

Discount

{
  "discount_type": "advance_percentage_calendar",
  "discount_first_percentage": 5.0,
  "discount_first_days": 5
}

Days Active After Due Date

{
  "revoke_days": 30
}

Required when using interest or fines.

Best Practices

Poll or use webhooks – QR Code comes asynchronously
Use external_id – Track charges in your system
Set revoke_days – Required for interest/fines
Validate CPF/CNPJ – Before sending to API
Use X-Idempotency-Key header – Prevent duplicates
Test in sandbox – Before production

Reference Documentation

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

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台