Invoice

The Invoice resource facilitates receiving Pix payments from your clients.Alongside specifying the invoice amount, you can customize the due date, expiration date, fines, interest, discounts, and descriptions, enabling a comprehensive billing model.Here is the Invoice log flow, offering a clear and organized perspective of the various stages through which an invoice can go: invoice-log A paid invoice can be partially or fully reversed to its payer. Multiple reversals can be made for the same invoice, and each time, the following log flow will occur: invoice-log-reversal

RESOURCE SUMMARY

Invoice Creation

Generate a customized Invoice

Invoice Update

Update an Invoice

Invoice Consulting

Details about the Invoice payment, enhancing the clarity and completeness of the transaction

Split Receiver

Add information regarding the payment beneficiary

Setup in Sandbox/Production

For each environment:1. Create an account at Stark Bank.2. Create asynchronous Webhook subscriptions to receive update Events. Register an URL using the POST Webhook route to receive Events about the following resources: 2.1 Invoice: Creation and updates of Invoices

Creating Invoices

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.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 in step 7 or use the rules parameter in the creation of the Invoice in step 2.Required parameters to create an InvoiceIn 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 at 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".

Creating Invoice with Split

It enables you to split the payment of an invoice among multiple receivers based on criteria such as settlement date, amount, and predefined rules.To execute this operation, please follow the steps outlined below:Setup the Split Profile Split Profile is the set of rules that will define the behavior of transferring funds from the client's account to the Receivers.Two behaviors are essential for the transfer to occur:IntervalIt is the period during which the transfer of funds from the Workspace to the receiver's destination account will be conducted.You can choose from four methods to execute the interval:DelayIt is the period during which the value will be "retained" in the main Workspace until it is transferred to the receiver's destination account.The Delay is configured by the client, allowing it to determine how long the value should be "retained" before the transfer occurs.For clients who do not configure the Split Profile rules for interval and delay as desired, by default, the Payment Split will have the following properties:Interval - monthlyDelay - 7 days

The setup of Receivers involves adding information regarding the payment beneficiary.

Generate the InvoiceOnce you have completed that step, you can generate an invoice by including the Split parameter along with the receiver ID, as demonstrated in the following example:For each party involved in the transaction, their respective receiver ID must be included, along with the amount to be sent. Therefore, if there are 3 parties in a transaction, three Receiver IDs should be sent, each with its corresponding Amount.

Consulting Invoices

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

Updating Invoices

Resource that will update certain parameters of your InvoiceTo 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.

Receiving Invoice Webhook

Listen to Invoice WebhooksAfter 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.

2.1. Credited Webhook Example

2.2 Canceled Webhook Example

Consulting Split

Once an invoice with Split is created, a Split entity is also generated. It is possible to retrieve it by its ID or list them using parameters such as limit, after, before to filter the results, as shown in the example below:

Invoice

Setup in Sandbox/Production

Creating Invoices

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

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

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

Python

Javascript

PHP

Java

Ruby

Elixir

C#

Go

Clojure

Curl

Python

Javascript

PHP

Java