api-charge-pix（API charge PIX 文档）

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

Pix Charges

Pix Commands

Charge Payments

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:

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

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

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.