πŸ“– Kona Finance User Guide

Kona Finance: Operation Creation and Management User Guide

Table of Contents

  1. Introduction
  2. Understanding Operations
  3. Workflow Overview
  4. Getting Started
  5. API Integration
  6. Creating an Operation
  7. Retrieving Operation Information
  8. Loan Status Definitions
  9. Managing Repayments
  10. 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:

  1. Data validation
  2. Contract creation for each loan
  3. Contract signing request (via email or WhatsApp)
  4. Blockchain registration of signed loans
  5. Loan investment (manual step)
  6. BRZ to BRL conversion and fund transfer (if required)
  7. Receipt issuance and email delivery

Getting Started

Before integrating with our platform, please contact us to:

  1. Discuss your operation details
  2. Define contract signers and witnesses
  3. Obtain your provider (originator) ID
  4. Receive your template ID for contract content
  5. Acquire a Bearer access token for API authentication

API Integration

Our API is available at:

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

IDStatusDescription
0Not ProcessedLoan registered but not yet processed
1Contract CreatedLoan contract created with provided information
2Contract SentSignature requests sent to all stakeholders
3SignedContract signed by required signers
4Created In DatabaseLoan registered and preparing for blockchain submission
5Created In Smart ContractLoan registered in blockchain, ready for investment
6Paid In SCLoan invested in smart contract
7Fiat Payment In ProgressFiat payment being processed
8Fiat Payment Done, Receipt PendingFiat payment completed
9Fiat Payment Done, Receipt SentFiat payment completed and receipt sent
10Fiat Payment Done, Receipt ErrorFiat payment done, receipt sending failed
11ClosedLoan closed without investment
12ExpiredLoan expired before investment
13CancelledLoan cancelled
14DeletedLoan deleted
99ErrorError 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 item
  • collateral_type: Type of collateral
  • amount: Repayment amount in BRL
  • due_date: Maturity date
  • receipt: Payment receipt file

Best Practices and Tips

  1. Always ensure all required documents are prepared before creating an operation.
  2. Double-check all input data, especially financial information and dates.
  3. Regularly monitor the status of your operations using the retrieval endpoint.
  4. Keep your API access token secure and rotate it periodically.
  5. 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.