Pix Invoice

Invoice Overview

Invoice is a resource that can be used to receive Pix payments from your clients.

In addition to choosing the Invoice amount, you will be able to include due date, expiration date, fine, interest, discount, and description for a comprehensive billing model.

Invoice Overview

In this section, we will demonstrate how to create an Invoice via API to initiate charges for your customers. To create an Invoice request, it is necessary to provide mandatory information.

NOTE: To ensure that the payer's taxId matches the final user's registration in your system, there are two options.

You can reverse the Invoice if the taxIds do not match, or use the rules parameter in the creation of the Invoice to restrict who can pay this invoice.

The Invoice Status

Each Invoice has a status that can change over time according to its life cycle:

invoice-status

Status	Description
Created	The Invoice was successfully created in Stark Bank.
Paid	The Invoice was paid by the payer.
Canceled	The Invoice was canceled by you or by the system.
Overdue	The Invoice has passed the due date and is now subject to fine and interest.
Expired	The Invoice has passed the expiration date and can no longer be paid.

The Invoice Logs

Every time either you or Stark Bank makes a change to an Invoice, we create a Log. Logs are pretty useful for understanding the life cycle of each Invoice and the changes that happened to it. Here you can see the flow of possible logs:

invoice-log

A paid Invoice can be either partially or fully reversed back to its payer. Multiple reversals can be made for the same invoice and each time, the following flow of logs will occur:

invoice-log-reversal

Log type	Status	Description
Created	Created	The Invoice was successfully created in Stark Bank.
Paid	Paid	The Invoice was paid by the payer.
Credited	Paid	The Invoice payment was credited to your account.
Canceled	Canceled	The Invoice was canceled.
Overdue	Overdue	The Invoice has passed the due date.
Voided	Canceled	The Invoice was voided.
Reversed	Paid	The Invoice payment was partially or fully reversed to the payer.
Updated	Paid	The Invoice was updated after payment (e.g., amount reduction).
Expired	Expired	The Invoice has passed the expiration date and can no longer be paid.

The Invoice Object

Attributes

id STRING

Unique id for the invoice.

amount INTEGER

Amount in cents that was received. Example: 100 (R$1.00).

brcode STRING

BR Code for the invoice Pix payment.

created STRING

Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00".

descriptions LIST OF OBJECTS

List of description objects with key and value.

discountAmount INTEGER

Discount amount in cents.

discounts LIST OF OBJECTS

List of discount objects with percentage and due.

due STRING

Payment due datetime. Example: "2020-04-23T23:00:00.000000+00:00".

expiration INTEGER

Time in seconds from due datetime until expiration.

fee INTEGER

Fee charged in cents.

fine FLOAT

Percentage charged if paid after due datetime.

fineAmount INTEGER

Fine amount in cents.

interest FLOAT

Monthly percentage charged if paid after due datetime.

interestAmount INTEGER

Interest amount in cents.

link STRING

Public URL to the invoice page.

name STRING

Payer full name.

nominalAmount INTEGER

Invoice amount in cents without fine or interest.

pdf STRING

Public URL to the invoice PDF.

rules LIST OF OBJECTS

List of rule objects with key and value.

splits LIST OF OBJECTS

List of Split objects with receiverId and amount.

status STRING

Current invoice status. Options: "created", "paid", "canceled", "overdue", "expired".

tags LIST OF STRINGS

Tags associated with the invoice.

taxId STRING

Payer CPF or CNPJ.

transactionIds LIST OF STRINGS

Ledger transaction IDs linked to the invoice.

updated STRING

Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00".

Creating Invoices

In order to create the Invoice, certain mandatory parameters are required for the request to be made, such as amount, taxId, and name.

In addition to these mandatory points, there are optional fields to enhance your invoice, such as due, fine, interest, expiration, discounts, descriptions, tags, and rules. For more details, you can refer to the documentation in the Invoice section.

Creating Invoice with due, fine, interest, expiration parameters

Due: By adding this parameter, you can set the due date of the requested payment in ISO format.

Example: "2020-11-25T17:59:26.000000+00:00." Default value: 2 days after creation.

Fine: By adding this parameter, you can add a fine to the invoiced amount if the customer pays after the due date and time.

Interest: By adding this parameter, you can add monthly interest, in percentage, charged if the customer pays after the due date.

Expiration: By adding this parameter, you can add time in seconds counted from the due date until the invoice expiration.

After expiration, the invoice can no longer be paid.

Default value: 5097600 (59 days).

Creating Invoice with discounts, description, tags parameters

Discounts: With this parameter, you can set a list of up to 5 discounts specifying the discount percentage and the deadline until the discount is valid.

Tags: By adding this parameter, you can have an array of strings to mark the entity for future queries.

All tags will be converted to uppercase.

Descriptions: With this parameter, you will have a list of up to 15 descriptions containing information to help understand the reason for the charge.

For each description, you can add a title key and a description value.

Creating Invoice with rules parameter

Rules: you can set a list of rules to modify the invoice's behavior.

It is possible to limit the tax IDs allowed to pay this invoice by setting this parameter using the key "allowedTaxIds".

Consulting Invoices

It is possible to retrieve an invoice by its ID or even list them using parameters such as limit, after, before to filter the results, as shown in the example below:

Updating Invoices

Resource that will update certain parameters of your Invoice

To update an Invoice, it is necessary to provide the invoice ID. Additionally, other parameters such as amount, due, expiration, and status can be included in the update process.

If the Invoice has already been paid, it is possible to reduce only the amount, resulting in the corresponding refund. For example, if a R$ 100 invoice has been paid, you can set the amount parameter to R$ 5, and the remaining R$ 95 will be refunded to the payer.

This provides greater flexibility and control over the information associated with your financial transactions.

Canceling an Invoice

To cancel an Invoice, you need to update the invoice status to "canceled".

Only Invoices that have not yet been paid can be canceled.

Reversing Partially an Invoice

To partially reverse a paid Invoice, you need to PATCH the invoice amount to a lower value. The difference between the paid amount and the new amount will be reversed to the payer.

For example, if an Invoice was paid with an amount of 400000 (R$ 4,000.00) and you patch the amount to 3000 (R$ 30.00), it means you reversed 397000 (R$ 3,970.00) back to the payer.

While the reversal is being processed, the invoice status remains paid.

Reversing Fully an Invoice

To fully reverse a paid Invoice, you need to PATCH the invoice amount to 0. This will reverse the entire paid amount back to the payer.

For example, if an Invoice was paid with an amount of 400000 (R$ 4,000.00) and you patch the amount to 0, the full 400000 (R$ 4,000.00) will be reversed to the payer.

After the full reversal is completed, the invoice status remains paid.

Receiving Invoice Webhook

After creation, you can use asynchronous Webhooks to monitor status changes of the entity. The Invoice will follow the following life cycle:

Every time we change an Invoice, we create a Log. Logs are pretty useful for understanding the life cycle of each Invoice. Whenever a new Log is created, we will fire a Webhook to your registered URL.

NOTE: Check the Webhook Get Started for more details on how to receive and process Webhook events.

NOTE: An invoice subscription is required to receive this event.

Invoice

Setup

Invoice Overview

The Invoice Status

The Invoice Logs

The Invoice Object

Attributes

Creating Invoices

Parameters

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Creating Invoice with due, fine, interest, expiration parameters

Parameters

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Creating Invoice with discounts, description, tags parameters

Parameters

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Creating Invoice with rules parameter

Parameters

Python

Javascript

PHP

Java