# Credit Note

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

**Attributes**

| 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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `templateId` | REQUIRED | ID of the credit note template to be used. Templates are enabled for your workspace through your credit profile. |
| `name` | REQUIRED | Borrower full name. Example: "Jamie Lannister" |
| `taxId` | REQUIRED | Borrower CPF (11 digits) or CNPJ (14 digits). Example: "012.345.678-90" |
| `scheduled` | REQUIRED | Datetime when the credit note should be disbursed after signing. Example: "2022-06-28" |
| `invoices` | REQUIRED | List of up to 100 Invoice objects representing the installments to be paid by the borrower. Each invoice takes a required "amount" (in cents) and optional "due", "fine" (default 2.0), "interest" (default 1.0), "expiration", "descriptions" and "tags". All invoices must share the same fine and interest. |
| `payment` | REQUIRED | Transfer object used to disburse the credit amount to the borrower's account, with required "name", "taxId", "bankCode" (receiver institution ISPB, 8 digits), "branchCode" and "accountNumber", and optional "accountType" ("checking", "payment", "salary" or "savings") and "tags". Do not send an "amount" in the payment object - the disbursed amount is computed by the API. |
| `paymentType` | REQUIRED | Type of the payment object. Options: "transfer". |
| `signers` | REQUIRED | List of up to 10 CreditSigner objects representing every person or entity that must sign the contract, each with required "name", "contact" and "method". Methods: "link" (signing link sent to an email or phone contact), "token" (signing token sent to an email or phone contact), "server" and "organization" (automatic signatures over URL contacts). Signers registered in your credit profile and the SCD signature are appended automatically. |
| `externalId` | REQUIRED | Unique external ID to prevent the creation of duplicate credit notes on unintended retries. Example: "my-internal-id-123456" |
| `streetLine1` | REQUIRED | Borrower main address street line. |
| `streetLine2` | REQUIRED | Borrower complement address street line. |
| `district` | REQUIRED | Borrower address district. |
| `city` | REQUIRED | Borrower address city. |
| `stateCode` | REQUIRED | Borrower address state code. Example: "SP". |
| `zipCode` | REQUIRED | Borrower address zip code. Example: "01310-100". |
| `nominalAmount` | OPTIONAL | Nominal amount in cents to be lent, before taxes. Provide either nominalAmount or amount. Example: 100000 (R$1,000.00). |
| `amount` | OPTIONAL | Net amount in cents to be disbursed to the borrower. Provide either nominalAmount or amount. Example: 100000 (R$1,000.00). |
| `rebateAmount` | OPTIONAL | Amount in cents to be discounted from the disbursed amount. Default is 0. Example: 100 (R$1.00). |
| `expiration` | OPTIONAL | Time span, in seconds, counted from the scheduled datetime, for the contract to be signed before the credit note expires. Default: 604800 (7 days). |
| `rules` | OPTIONAL | List of rules modifying the credit note behavior, as {"key", "value"} objects. Currently available key: "invoiceCreationMode", with values "scheduled" (default), "instant" or "never". |
| `tags` | OPTIONAL | List of strings to tag the credit note for future queries. |

**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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter credit notes by the specified status. Options: "created", "signed", "processing", "success", "failed", "canceled", "expired". |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. Max = 100. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the credit note entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the credit note entity. |

**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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the credit note entity. |

**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".

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the credit note entity. |

**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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `noteIds` | OPTIONAL | List of credit note ids linked to the desired logs. Max = 100. |
| `types` | OPTIONAL | Filter logs by log type. Options: "created", "signing", "signed", "sending", "sent", "success", "failed", "refunded", "canceled", "expired", "updated", "registered". |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the credit note log entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**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
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

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