api-charge-pix

```

Production: https://api.kobana.com.br

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

```

```

Authorization: Bearer {your_api_token}

```

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 |

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"

}

```

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

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

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

```

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

```

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

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.

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

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