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.brAuthentication
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_daysset) - 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}untilregistration_statusisconfirmed - Use webhooks - Configure webhook for
pix.register.confirmedevent
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_accountsUpdating 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}/cancelStatus Reference
Charge Status
opened- Open (initial)paid- Paidoverdue- Overduecanceled- Canceledgeneration_failed- Registration failed
Registration Status
pending- Waitingconfirmed- 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.