π Kona Finance User Guide
Kona Finance: Operation Creation and Management User Guide
Table of Contents
- Introduction
- Understanding Operations
- Workflow Overview
- Getting Started
- API Integration
- Creating an Operation
- Retrieving Operation Information
- Loan Status Definitions
- Managing Repayments
- Best Practices and Tips
Introduction
This guide provides comprehensive instructions for creating and managing operations within the Kona Finance platform. It covers the entire process from initial setup to handling repayments, ensuring you can effectively utilize our system for loan management.
Understanding Operations
An operation in Kona Finance represents a collection of loans created by the same originator on a specific date. Key points to remember:
- Multiple loans can be grouped into a single operation.
- Loans within an operation can be for different borrowers.
- Operations can be created with a single loan if desired.
- Grouping can be based on any relevant characteristic (e.g., same merchant, same day).
Workflow Overview
When you register an operation, the following automated process is initiated:
- Data validation
- Contract creation for each loan
- Contract signing request (via email or WhatsApp)
- Blockchain registration of signed loans
- Loan investment (manual step)
- BRZ to BRL conversion and fund transfer (if required)
- Receipt issuance and email delivery
Getting Started
Before integrating with our platform, please contact us to:
- Discuss your operation details
- Define contract signers and witnesses
- Obtain your provider (originator) ID
- Receive your template ID for contract content
- Acquire a Bearer access token for API authentication
API Integration
Our API is available at:
- Testing: https://testing.private.kona.finance/swagger/
- Production: https://private.kona.finance/swagger/
Note: A Bearer access token is required for API usage.
Creating an Operation
Use the {BASE_URL}/operation
endpoint to create a new operation. Required information includes:
{
"name": "Credit Session",
"json_content": {"items": []},
"operation_date": "2024-05-03",
"template": 123,
"email_subject": "Please sign this document",
"interest_rate": "0.065"
}
The json_content
field should contain an array of loan objects. Each loan object should include:
{
"company_name": "Company Name",
"company_email": "[email protected]",
"company_phone": "+55000111222",
"cnpj": "50.111.222/0003-45",
"cpf": "123.456.789-10",
"address": "Rua Rio 123",
"zip_code": "12340-000",
"city": "Ibiuna",
"state": "SP",
"pix": "12.345.678/0001-10",
"bank_code": "0123",
"bank_name": "Bank Name",
"bank_agency": "123",
"bank_account": "12.345.678-9",
"total_locked": 100.0,
"loan_amount": 90.0,
"maturity": "2024-05-24",
"repayments": 1,
"interest_rate": "0.065",
"fiscal_notes_to_anticipate_link": "Google drive link",
"fiscal_notes_clients_link": "Google drive link"
}
Important Validations:
- Ensure all fiscal note documents are created before operation creation.
- Format zip codes with 3 digits after the dash (e.g., "12340-000").
- The interest rate must satisfy:
total_locked = loan_amount / (1 - interest_rate)
Retrieving Operation Information
To fetch operation details, use the endpoint: {BASE_URL}/operation/<id>
Loan Status Definitions
ID | Status | Description |
---|---|---|
0 | Not Processed | Loan registered but not yet processed |
1 | Contract Created | Loan contract created with provided information |
2 | Contract Sent | Signature requests sent to all stakeholders |
3 | Signed | Contract signed by required signers |
4 | Created In Database | Loan registered and preparing for blockchain submission |
5 | Created In Smart Contract | Loan registered in blockchain, ready for investment |
6 | Paid In SC | Loan invested in smart contract |
7 | Fiat Payment In Progress | Fiat payment being processed |
8 | Fiat Payment Done, Receipt Pending | Fiat payment completed |
9 | Fiat Payment Done, Receipt Sent | Fiat payment completed and receipt sent |
10 | Fiat Payment Done, Receipt Error | Fiat payment done, receipt sending failed |
11 | Closed | Loan closed without investment |
12 | Expired | Loan expired before investment |
13 | Cancelled | Loan cancelled |
14 | Deleted | Loan deleted |
99 | Error | Error occurred in workflow (additional information provided) |
Managing Repayments
To inform the system about repaid collateral, use the {BASE_URL}/inform_repayment
endpoint. Include:
item
: JSON object with all fields of the repaid collateral itemcollateral_type
: Type of collateralamount
: Repayment amount in BRLdue_date
: Maturity datereceipt
: Payment receipt file
Best Practices and Tips
- Always ensure all required documents are prepared before creating an operation.
- Double-check all input data, especially financial information and dates.
- Regularly monitor the status of your operations using the retrieval endpoint.
- Keep your API access token secure and rotate it periodically.
- For any issues or unexpected behavior, contact our support team promptly.
For further assistance or queries, please don't hesitate to reach out to our support team.
Updated about 2 months ago