Back to Details

api-charge-pix

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Kobana Charge API Skill

Kobana Charge API Skill

Manage Pix charges, accounts, and payments via Kobana API.
通过Kobana API管理Pix收费、账户及支付。

Base URLs

基础URL

Production: https://api.kobana.com.br
Sandbox:    https://api-sandbox.kobana.com.br
Production: https://api.kobana.com.br
Sandbox:    https://api-sandbox.kobana.com.br

Authentication

身份验证

Authorization: Bearer {your_api_token}
Authorization: Bearer {your_api_token}

API Endpoints Overview

API 端点概览

Pix Accounts

Pix账户

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
方法端点描述
GET
/v2/charge/pix_accounts
列出所有Pix账户
POST
/v2/charge/pix_accounts
创建新的Pix账户
GET
/v2/charge/pix_accounts/{uid}
获取指定Pix账户
PUT
/v2/charge/pix_accounts/{uid}
更新Pix账户
DELETE
/v2/charge/pix_accounts/{uid}
删除Pix账户

Pix Charges

Pix收费单

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
方法端点描述
GET
/v2/charge/pix
列出所有Pix收费单
POST
/v2/charge/pix
创建新的Pix收费单
GET
/v2/charge/pix/{uid}
获取指定Pix收费单
PUT
/v2/charge/pix/{uid}/update
更新Pix收费单
DELETE
/v2/charge/pix/{uid}
删除Pix收费单
POST
/v2/charge/pix/{uid}/cancel
取消Pix收费单

Pix Commands

Pix命令

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
方法端点描述
GET
/v2/charge/pix/{pix_uid}/commands
列出Pix收费单的所有命令
GET
/v2/charge/pix/{pix_uid}/commands/{id}
获取指定命令

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
方法端点描述
GET
/v2/charge/payments
列出所有支付记录
POST
/v2/charge/payments
创建新的支付记录
GET
/v2/charge/payments/{uid}
获取指定支付记录
DELETE
/v2/charge/payments/{uid}
删除支付记录

Creating a Pix Charge

创建Pix收费单

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

完整示例（账单式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"
}
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

Pix类型

Instant Pix (
registration_kind: "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"
)

账单式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
  • 正式到期日
  • 支持利息、罚款、折扣
  • 若设置
    revoke_days
    ，到期后仍保持有效
  • 适用场景：月度账单、订阅服务

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
二维码不会在初始响应中返回。可选方案：
  1. 轮询收费单 - 调用GET 
    /v2/charge/pix/{uid}
    ，直到
    registration_status
    变为
    confirmed
  2. 使用Webhooks - 配置
    pix.register.confirmed
    事件的Webhook

Listing and Filtering

列出与筛选

List Pix Charges with Filters

带筛选条件列出Pix收费单

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
GET /v2/charge/pix?status=opened&created_from=2026-01-01&per_page=50
参数描述
status
按状态筛选（opened、paid、overdue、canceled）
registration_status
按注册状态筛选
pix_account_uid
按Pix账户筛选
created_from
/ 
created_to
按创建日期筛选
expire_from
/ 
expire_to
按到期日期筛选
paid_from
/ 
paid_to
按支付日期筛选
txid
按TXID筛选
external_id
按外部ID筛选
tags
按标签筛选
page
/ 
per_page
分页参数

List Pix Accounts

列出Pix账户

GET /v2/charge/pix_accounts
GET /v2/charge/pix_accounts

Updating and Canceling

更新与取消

Update a Pix Charge

更新Pix收费单

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

{
  "amount": 550.00,
  "expire_at": "2026-02-15T23:59:59-03:00"
}
json
PUT /v2/charge/pix/{uid}/update

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

Cancel a Pix Charge

取消Pix收费单

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

Status Reference

状态参考

Charge Status

收费单状态

  • opened
    - Open (initial)
  • paid
    - Paid
  • overdue
    - Overdue
  • canceled
    - Canceled
  • generation_failed
    - Registration failed
  • opened
    - 已创建（初始状态）
  • paid
    - 已支付
  • overdue
    - 已逾期
  • canceled
    - 已取消
  • generation_failed
    - 注册失败

Registration Status

注册状态

  • pending
    - Waiting
  • confirmed
    - Ready (has QR Code)
  • rejected
    / 
    failed
    - Error
  • pending
    - 待处理
  • confirmed
    - 已就绪（包含二维码）
  • rejected
    / 
    failed
    - 错误

Common Parameters

通用参数

Fine (after due date)

逾期罚款

json
{
  "fine_type": "percentage",  // or "amount"
  "fine_percentage": 2.0
}
json
{
  "fine_type": "percentage",  // 或 "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
json
{
  "interest_type": "monthly_percentage_calendar",
  "interest_percentage": 1.0
}
利息类型：
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
}
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.
json
{
  "revoke_days": 30
}
必填，当使用利息或罚款时。

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
  1. 轮询或使用Webhooks - 二维码为异步返回
  2. 使用external_id - 在您的系统中跟踪收费单
  3. 设置revoke_days - 使用利息/罚款时必填
  4. 验证CPF/CNPJ - 发送至API前验证
  5. 使用X-Idempotency-Key请求头 - 防止重复请求
  6. 在沙箱环境测试 - 上线前先在沙箱测试

Reference Documentation

参考文档

See references/REFERENCE.md for complete API documentation including all parameters, response formats, and error codes.
完整API文档（包含所有参数、响应格式及错误码）请查看references/REFERENCE.md。