# Lending (Credit Note)

Issue your own credit operations as Bank Credit Bills (Cédula de Crédito Bancário — CCB) through Stark Infra.

Each CCB is a legally binding loan agreement digitally signed by the borrower and the signers. Stark Infra handles invoice generation, contract signing, payment tracking and disbursement, so you can focus on credit decisions and customer acquisition.

Before disbursing, you may want to evaluate the borrower's credit profile with Credit Holmes — Stark's bureau-backed risk-analysis report — and compute the loan schedule with the preview endpoint.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Credit HolmesGenerate credit analysis reports backed by official bureaus.Credit PreviewSimulate the installment schedule and total cost of a CCB.Credit SignerTrack everyone who must sign the contract and resend signing links.Credit NoteCreate the legally binding CCB and trigger the signing flow.

## Setup

1. Reach out to Stark Infra to enable the Lending product on your workspace.

2. Create a Webhook resource subscribing to credit-note and credit-holmes events.

3. Optionally pre-fund the lending balance with a Pix Request so disbursements run immediately when contracts are signed.

## Typical flow

1. (Optional) Issue a Credit Holmes report to check the borrower's credit profile.

2. Compute the installment schedule with the Credit Preview endpoint.

3. Create the Credit Note, informing the borrower, the signers, the installment invoices and the disbursement account. Each signer receives a link to sign the contract digitally.

4. Once signed, Stark Infra disburses the loan via Pix to the borrower's account and tracks every installment payment through invoices.

## Credit Holmes Overview

CreditHolmes are used to request the credit analysis of a tax ID.

The analysis retrieves credit information from official sources for a given CPF or CNPJ, helping you evaluate the creditworthiness of a borrower.

### The CreditHolmes object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the credit holmes. |
| `taxId` | STRING | CPF or CNPJ of the entity to be analyzed. |
| `competence` | STRING | Month and year of the credit analysis in YYYY-MM format. Example: "2022-06". |
| `status` | STRING | Current status of the credit analysis. Options: "created", "solved", "failed". |
| `result` | OBJECT | Credit analysis result containing financial and credit data for the tax ID. |
| `tags` | LIST OF STRINGS | Tags associated with the credit holmes. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Credit Holmes

`POST /v2/credit-holmes`

Create credit holmes requests to analyze the credit profile of a tax ID.

You can create up to 100 requests in a single call.

**Request**

```python
import starkinfra

holmes = starkinfra.creditholmes.create([
    starkinfra.CreditHolmes(
        tax_id="012.345.678-90",
        competence="2022-06",
        tags=["credit-analysis"]
    )
])

for sherlock in holmes:
    print(sherlock)
```

**Response**

```python
CreditHolmes(
    id=5719405850615809,
    tax_id=012.345.678-90,
    competence=2022-06,
    status=created,
    result=None,
    tags=['credit-analysis'],
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-01T00:00:00.000000+00:00
)
```

### List Credit Holmes

`GET /v2/credit-holmes`

List and filter all credit holmes requests in your workspace. Results are returned paged.

**Request**

```python
import starkinfra

holmes = starkinfra.creditholmes.query(limit=10)

for sherlock in holmes:
    print(sherlock)
```

**Response**

```python
CreditHolmes(
    id=5719405850615809,
    tax_id=012.345.678-90,
    competence=2022-06,
    status=solved,
    result={...},
    tags=['credit-analysis'],
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-01T00:00:00.000000+00:00
)
```

### Get a Credit Holmes

`GET /v2/credit-holmes/:id`

Get a single credit holmes by its id.

**Request**

```python
import starkinfra

sherlock = starkinfra.creditholmes.get("5719405850615809")

print(sherlock)
```

**Response**

```python
CreditHolmes(
    id=5719405850615809,
    tax_id=012.345.678-90,
    competence=2022-06,
    status=solved,
    result={...},
    tags=['credit-analysis'],
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-01T00:00:00.000000+00:00
)
```

### List Credit Holmes Logs

`GET /v2/credit-holmes/log`

Get a paged list of all credit holmes logs. A log tracks a change in the credit holmes entity according to its life cycle.

**Request**

```python
import starkinfra

logs = starkinfra.creditholmes.log.query(limit=10)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id=5155165527080961,
    type=created,
    created=2022-06-01T00:00:00.000000+00:00,
    holmes=CreditHolmes(id=5719405850615809, status=created, ...)
)
```

### Get a Credit Holmes Log

`GET /v2/credit-holmes/log/:id`

Get a single credit holmes log by its id.

**Request**

```python
import starkinfra

log = starkinfra.creditholmes.log.get("5155165527080961")

print(log)
```

**Response**

```python
Log(
    id=5155165527080961,
    type=created,
    created=2022-06-01T00:00:00.000000+00:00,
    holmes=CreditHolmes(id=5719405850615809, status=created, ...)
)
```

## Credit Preview Overview

CreditPreviews are used to preview a credit operation before creating it.

You can simulate the installment schedule, the IOF tax amount, the disbursed amount and the effective interest rates of a Credit Note without persisting anything. Previews are computed on the fly and are not saved.

### The CreditPreview object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `type` | STRING | Type of the credit preview. Options: "credit-note". |
| `credit` | OBJECT | CreditNotePreview object with the simulation parameters and, in the response, the computed results. Its "type" defines the amortization schedule: "sac" (constant amortization), "price" (fixed installments), "american" (periodic interest and principal at maturity), "bullet" (principal and interest at maturity) or "custom" (you provide the invoices and the rates are computed). Input fields: "taxId", "scheduled" (disbursement datetime), "nominalInterest" (% per year), "initialDue" (first installment due datetime), "count" (number of installments), "initialAmount" (installment amount in cents), "interval" ("day", "week", "month", "quarter", "semester" or "year" - default "month"), "nominalAmount" or "amount" (in cents), "rebateAmount" and, for the "custom" type, "invoices" as {"amount", "due"} objects. Computed fields returned: "amount" (net disbursed amount), "taxAmount" (IOF), "interest" (effective rate, % per year), "nominalInterest", "count", "initialDue", "initialAmount" and the full "invoices" schedule. |

### Create Credit Previews

`POST /v2/credit-preview`

Create credit previews to simulate credit notes before actually creating them. You can create up to 100 previews in a single request.

For the "sac" and "price" types, provide exactly one of "count" or "initialAmount" - the other one is computed. For all types except "custom", provide exactly one of "nominalAmount" or "amount".

**Request**

```python
import starkinfra

previews = starkinfra.creditpreview.create([
    starkinfra.CreditPreview(
        type="credit-note",
        credit=starkinfra.creditpreview.CreditNotePreview(
            type="sac",
            nominal_amount=100000,
            nominal_interest=15.0,
            scheduled="2022-06-28",
            initial_due="2022-07-28",
            count=12,
            tax_id="012.345.678-90"
        )
    )
])

for preview in previews:
    print(preview)
```

**Response**

```python
CreditPreview(
    type=credit-note,
    credit=CreditNotePreview(
        type=sac,
        nominal_amount=100000,
        rebate_amount=0,
        tax_amount=1126,
        amount=98874,
        interest=17.34,
        nominal_interest=15.0,
        scheduled=2022-06-28T00:00:00.000000+00:00,
        initial_due=2022-07-28T00:00:00.000000+00:00,
        initial_amount=9583,
        count=12,
        invoices=[Invoice(amount=9583, due=2022-07-28), ..., Invoice(amount=8438, due=2023-06-28)]
    )
)
```

## Credit Signer Overview

Credit Signers represent every person or entity that must sign the CCB contract of a Credit Note.

Signers are created together with the Credit Note, through its "signers" parameter, and are returned embedded in the CreditNote object. Signers registered in your credit profile and the SCD signature are appended automatically.

When the method is "link" or "token", the signer receives the signing link or token on the registered contact (email or phone). If a signer misses it, you can trigger a new delivery.

### The CreditSigner object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the credit signer. |
| `name` | STRING | Signer full name. |
| `contact` | STRING | Signer contact that receives the signing link or token. Can be an email, a phone number or, for the "server" and "organization" methods, a URL. |
| `method` | STRING | Signing method. Options: "link" (signing link sent to the contact), "token" (signing token sent to the contact), "server" and "organization" (automatic signatures over URL contacts). |
| `signed` | STRING | Datetime when the signer signed the contract. Empty until the signature happens. Example: "2022-06-02T00:00:00.000000+00:00". |

### Update a Credit Signer

`PATCH /v2/credit-signer/:id`

Update the delivery state of a credit signer's signing token or link. Setting "isSent" to false marks it as not delivered, causing it to be sent again to the signer's contact. Use it when a signer misses the original email or SMS.

**Request**

```python
import starkinfra

signer = starkinfra.creditsigner.resend_token("6306107546853376")

print(signer)
```

**Response**

```python
CreditSigner(
    id=6306107546853376,
    name=Jamie Lannister,
    contact=jamie.lannister@gmail.com,
    method=link,
    signed=
)
```

## Credit Note Overview

Credit Notes represent credit operations issued to individuals or businesses as Bank Credit Bills (Cédula de Crédito Bancário - CCB). They carry all the information needed to formalize a lending operation, including signers, installment invoices and the disbursement payment details.

Once created, the credit note generates a contract that must be digitally signed by all signers. After signing, the disbursement is transferred via Pix to the borrower's account and each installment is tracked through invoices.

Here we will show you how to create and manage them.

### The CreditNote object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the credit note. |
| `templateId` | STRING | ID of the credit note template used. Templates are enabled for your workspace through your credit profile. |
| `name` | STRING | Borrower full name. |
| `taxId` | STRING | Borrower CPF or CNPJ. |
| `nominalAmount` | INTEGER | Nominal amount in cents of the credit note, before taxes. Example: 100000 (R$1,000.00). |
| `rebateAmount` | INTEGER | Amount in cents discounted from the disbursed amount. Example: 100 (R$1.00). |
| `taxAmount` | INTEGER | Tax amount in cents (IOF) embedded in the operation, computed from the borrower type (individual or business) and the operation duration. |
| `amount` | INTEGER | Net amount in cents disbursed to the borrower. |
| `interest` | FLOAT | Effective interest rate of the credit operation, in % per year, computed from the disbursed amount and the invoice schedule. Example: 27.5. |
| `nominalInterest` | FLOAT | Nominal interest rate of the credit operation, in % per year, computed from the nominal amount and the invoice schedule. Example: 25.2. |
| `rules` | LIST OF OBJECTS | List of rules modifying the credit note behavior, as {"key", "value"} objects. Currently available key: "invoiceCreationMode", with values "scheduled" (default - each installment invoice is issued a few days before its due date), "instant" (all invoices are issued as soon as the note is disbursed) or "never" (invoices are not issued automatically). |
| `scheduled` | STRING | Datetime when the credit note will be disbursed after signing. Example: "2022-06-28T00:00:00.000000+00:00". |
| `expiration` | INTEGER | Time span, in seconds, counted from the scheduled datetime, for the borrower and signers to sign the contract before the credit note expires. Default: 604800 (7 days). |
| `externalId` | STRING | Unique external ID that prevents the creation of duplicate credit notes on unintended retries. |
| `tags` | LIST OF STRINGS | Tags associated with the credit note. |
| `status` | STRING | Current status of the credit note. Options: "created" (awaiting signatures), "signed" (contract signed by all signers), "processing" (disbursement in progress), "success" (disbursement settled), "failed" (disbursement failed), "canceled" and "expired" (not signed before the expiration). |
| `signers` | LIST OF OBJECTS | List of CreditSigner objects representing every person or entity that must sign the contract, as {"id", "name", "contact", "method", "signed"} objects. Signers registered in your credit profile and the SCD signature are appended automatically. |
| `invoices` | LIST OF OBJECTS | List of Invoice objects representing the installments to be paid by the borrower, with their "id", "amount", "due", "fine", "interest", "expiration", "descriptions" and "tags". |
| `payment` | OBJECT | Transfer object used to disburse the credit amount to the borrower, including its "id" and "status" once the disbursement is initiated. |
| `paymentType` | STRING | Type of the payment object. Options: "transfer". |
| `streetLine1` | STRING | Borrower main address street line. |
| `streetLine2` | STRING | Borrower complement address street line. |
| `district` | STRING | Borrower address district. |
| `city` | STRING | Borrower address city. |
| `stateCode` | STRING | Borrower address state code. Example: "SP". |
| `zipCode` | STRING | Borrower address zip code. Example: "01310-100". |
| `documentId` | STRING | Unique id of the digital signing document attached to this credit note. |
| `workspaceId` | STRING | ID of the workspace that issued the credit note. |
| `debtorWorkspaceId` | STRING | ID of the borrower's workspace, when it differs from the issuing workspace. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction ids linked to the disbursement and its chargebacks. |
| `created` | STRING | Creation datetime. Example: "2022-01-01T00:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2022-01-01T00:00:00.000000+00:00". |

### Create Credit Notes

`POST /v2/credit-note`

Create credit notes in bulk. You can create up to 100 credit notes in a single request.

Provide either the nominalAmount (pre-tax) or the amount (net disbursed value) - the other one, along with the taxAmount (IOF) and the interest rates, is computed from the invoice schedule.

**Request**

```python
import starkinfra

notes = starkinfra.creditnote.create([
    starkinfra.CreditNote(
        template_id="5745297609744384",
        name="Jamie Lannister",
        tax_id="012.345.678-90",
        nominal_amount=100000,
        scheduled="2022-06-28",
        invoices=[
            starkinfra.creditnote.Invoice(
                amount=102612,
                due="2022-07-28"
            )
        ],
        payment=starkinfra.creditnote.Transfer(
            bank_code="20018183",
            branch_code="1234",
            account_number="129340-1",
            name="Jamie Lannister",
            tax_id="012.345.678-90"
        ),
        payment_type="transfer",
        signers=[
            starkinfra.creditsigner.CreditSigner(
                name="Jamie Lannister",
                contact="jamie.lannister@gmail.com",
                method="link"
            )
        ],
        external_id="my-internal-id-123456",
        street_line_1="Av. Paulista, 200",
        street_line_2="Apto. 51",
        district="Bela Vista",
        city="Sao Paulo",
        state_code="SP",
        zip_code="01310-100"
    )
])

for note in notes:
    print(note)
```

**Response**

```python
CreditNote(
    id=5745297609744385,
    template_id=5745297609744384,
    name=Jamie Lannister,
    tax_id=012.345.678-90,
    nominal_amount=100000,
    tax_amount=626,
    amount=99374,
    interest=38.61,
    nominal_interest=30.69,
    status=created,
    external_id=my-internal-id-123456,
    scheduled=2022-06-28T00:00:00.000000+00:00,
    expiration=604800,
    payment_type=transfer,
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-01T00:00:00.000000+00:00
)
```

### List Credit Notes

`GET /v2/credit-note`

List and filter all credit notes created in your workspace. Results are returned paged.

**Request**

```python
import starkinfra

notes = starkinfra.creditnote.query(
    limit=10,
    status="signed",
    after="2022-06-01",
    before="2022-06-30"
)

for note in notes:
    print(note)
```

**Response**

```python
CreditNote(
    id=5745297609744385,
    template_id=5745297609744384,
    name=Jamie Lannister,
    tax_id=012.345.678-90,
    nominal_amount=100000,
    tax_amount=626,
    amount=99374,
    interest=38.61,
    nominal_interest=30.69,
    status=signed,
    external_id=my-internal-id-123456,
    scheduled=2022-06-28T00:00:00.000000+00:00,
    expiration=604800,
    payment_type=transfer,
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-02T00:00:00.000000+00:00
)
```

### Get a Credit Note

`GET /v2/credit-note/:id`

Get a single credit note by its id.

**Request**

```python
import starkinfra

note = starkinfra.creditnote.get("5745297609744385")

print(note)
```

**Response**

```python
CreditNote(
    id=5745297609744385,
    template_id=5745297609744384,
    name=Jamie Lannister,
    tax_id=012.345.678-90,
    nominal_amount=100000,
    tax_amount=626,
    amount=99374,
    interest=38.61,
    nominal_interest=30.69,
    status=signed,
    signers=[{id: 6306107546853376, name: Jamie Lannister, method: link, contact: jamie.lannister@gmail.com, signed: 2022-06-02T00:00:00.000000+00:00}],
    document_id=07d05b14-9d83-4439-9622-d2b313b05a10,
    external_id=my-internal-id-123456,
    scheduled=2022-06-28T00:00:00.000000+00:00,
    expiration=604800,
    payment_type=transfer,
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-02T00:00:00.000000+00:00
)
```

### Cancel a Credit Note

`DELETE /v2/credit-note/:id`

Cancel a credit note that has not reached a final status yet. Credit notes with status "created", "signed" or "processing" can be canceled, which also cancels the signing document. Credit notes with status "success", "failed", "expired" or already "canceled" are returned unchanged.

**Request**

```python
import starkinfra

note = starkinfra.creditnote.cancel("5745297609744385")

print(note)
```

**Response**

```python
CreditNote(
    id=5745297609744385,
    template_id=5745297609744384,
    name=Jamie Lannister,
    tax_id=012.345.678-90,
    nominal_amount=100000,
    status=canceled,
    external_id=my-internal-id-123456,
    created=2022-06-01T00:00:00.000000+00:00,
    updated=2022-06-03T00:00:00.000000+00:00
)
```

### Get a Credit Note PDF

`GET /v2/credit-note/:id/pdf`

Get the CCB contract PDF file of a credit note. After all signers have signed, the returned file carries the digital signatures.

**Request**

```python
import starkinfra

pdf = starkinfra.creditnote.pdf("5745297609744385")

with open("credit-note.pdf", "wb") as file:
    file.write(pdf)
```

**Response**

```python
(binary PDF file content)
```

### Get a Credit Note Payment PDF

`GET /v2/credit-note/:id/payment/pdf`

Get the disbursement transfer receipt PDF file of a credit note. Only available for credit notes with status "success".

**Request**

```python
import starkinfra

pdf = starkinfra.request.get(
    path="/credit-note/5745297609744385/payment/pdf"
).content

with open("credit-note-payment.pdf", "wb") as file:
    file.write(pdf)
```

**Response**

```python
(binary PDF file content)
```

### List Credit Note Logs

`GET /v2/credit-note/log`

Get a paged list of all credit note logs. A log tracks a change in the credit note entity according to its life cycle, as {"id", "type", "errors", "note", "created"} objects.

**Request**

```python
import starkinfra

logs = starkinfra.creditnote.log.query(
    limit=10,
    note_ids=["5745297609744385"],
    types=["signed"]
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id=6532638269505536,
    type=signed,
    errors=[],
    note=CreditNote(
        id=5745297609744385,
        name=Jamie Lannister,
        status=signed
    ),
    created=2022-06-02T00:00:00.000000+00:00
)
```

### Get a Credit Note Log

`GET /v2/credit-note/log/:id`

Get a single credit note log by its id.

**Request**

```python
import starkinfra

log = starkinfra.creditnote.log.get("6532638269505536")

print(log)
```

**Response**

```python
Log(
    id=6532638269505536,
    type=signed,
    errors=[],
    note=CreditNote(
        id=5745297609744385,
        name=Jamie Lannister,
        status=signed
    ),
    created=2022-06-02T00:00:00.000000+00:00
)
```

---

## Other Languages

- [Python](https://docs.starkinfra.com/get-started/lending-python.md)
- [Node.js](https://docs.starkinfra.com/get-started/lending-node.md)
- [PHP](https://docs.starkinfra.com/get-started/lending-php.md)
- [Java](https://docs.starkinfra.com/get-started/lending-java.md)
- [Ruby](https://docs.starkinfra.com/get-started/lending-ruby.md)
- [Elixir](https://docs.starkinfra.com/get-started/lending-elixir.md)
- [.NET](https://docs.starkinfra.com/get-started/lending-dotnet.md)
- [Go](https://docs.starkinfra.com/get-started/lending-go.md)
- [Clojure](https://docs.starkinfra.com/get-started/lending-clojure.md)
- [cURL](https://docs.starkinfra.com/get-started/lending-curl.md)