api-charge-pix

Original：🇺🇸 English
Translated

Guide for managing Pix charges, accounts, and payments using Kobana API. Use when the user wants to create, list, update, or cancel Pix charges, manage Pix accounts, or handle charge payments.

1installs
Sourceuniversokobana/kobana-agent-skills
Added on

NPX Install

npx skill4agent add universokobana/kobana-agent-skills api-charge-pix

Tags

Translated version includes tags in frontmatter
kobana-apipix-paymentscharge-managementaccount-administrationwebhook-integration

SKILL.md Content

View Translation Comparison →

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

MethodEndpointDescription
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

MethodEndpointDescription
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

MethodEndpointDescription
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

MethodEndpointDescription
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

json
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)

json
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:
  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

List Pix Charges with Filters

GET /v2/charge/pix?status=opened&created_from=2026-01-01&per_page=50
ParameterDescription
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

json
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)

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

Interest

json
{
  "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

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

Days Active After Due Date

json
{
  "revoke_days": 30
}
Required when using interest or fines.

Best Practices

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

Reference Documentation

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