How to upsert a billing

This endpoint will receive and queue up to 50 billings at a time.
There is no rate limit.

No billing/invoice data will be returned on this request. It only gets the data, validates a few parameters and retrieves the success of the queuing process. All the billing/invoice data will only be sent by webhook (if configured, Neofin will send one webhook for each payment installment created) or retrieved by Listing billings or Retrieving a billing. If the customer who will be charged is not registered with Neofin, their registration will be carried out using the data provided when creating the invoice.

Attention

The billing only will be upserted if you pass the same Integration Identifier. Avoid use values non-static values (like a timestamp) as your Integration Identifiers.

Billing attributes

This endpoint receives the following parameters:

Parameter	Type	Description	Example
address_city	String - Mandatory - Not Empty	Contains your customer city address.	"São Paulo"
address_complement	String - Mandatory - Not Empty	Contains the complement for your customer address.	"Second Floor"
address_neighborhood	String - Mandatory - Not Empty	Contains the neighborhood of your customer address.	"Brooklyn"
address_number	String - Mandatory - Not Empty	Contains the number related to your customer address.	"356"
address_state	AddressStateEnum - Mandatory - Not Empty	Contains the State abbreviation where your customer is located.	"SP"
address_street	String - Mandatory - Not Empty	The street name of your customer address.	"Avenida Paulista"
address_zip_code	String - Mandatory - Not Empty	The zip code of your customer address.	"01405-001"
amount	Number - Mandatory - Not Empty	The total amount of the billing/invoice in BRL cents, without comma.	10050
type	BillingTypeStrEnum - Mandatory - Not Empty	Payment method type.	"pix"
boleto_pdf	String - Optional - Not Empty	Downloadable URL path for the PDF boleto file.	"https://yourdomain.com.br/path_to_file/boleto.pdf"
boleto_base64	String - Optional - Not Empty	Base64 that generates a PDF boleto file.	-
boleto	Boleto - Optional - Not Empty	Details for generating a PDF boleto when "type" is "generic".	See field descriptions
by_mail	Boolean - Mandatory - Not Empty	Indicates if the billing/invoice communication should be sent by email.	"true"
by_whatsapp	Boolean - Mandatory - Not Empty	Indicates if the billing/invoice communication should be sent by WhatsApp.	"false"
customer_document	String - Mandatory - Not Empty	CPF (11 digits) or CNPJ (14 digits).	"75730786000100"
code	String - Optional - Not Empty	Typefull line code of the generated boleto when payment_method is "generic".	"45454 45454656465 5454564656 61 46445456465465"
hash	String - Optional - Not Empty	"Pix Copia e Cola" line code of the generated pix when payment_method is "generic".	"45454 45454656465 5454564656 61 46445456465465"
customer_mail	String - Mandatory - Not Empty	The main email address where your customer will receive billing/invoice communications.	"customer@gmail.com"
customer_name	String - Mandatory - Not Empty	Your customer name.	"Maria Quinteros"
customer_phone	String - Mandatory - Not Empty	Customer phone number including country code.	"+5511987654321"
customer_secondary_phone	String - Optional - Empty	Secondary phone number.	"+5511987654321"
discount_before_payment	Number - Mandatory - Not Empty	Percentage discount if paid before the due date.	5
discount_before_payment_due_date	Number - Mandatory - Not Empty	Days before the due date when discount applies.	5
due_date	Number - Mandatory - Not Empty	Due date as Unix Timestamp.	1678316400
fees	Number - Mandatory - Not Empty	Monthly fine percentage if unpaid.	1
fine	Number - Mandatory - Not Empty	Fine percentage for late payment.	2
installment_type	InstallmentTypeStrEnum - Optional - Not Empty	Type of installment for due date calculation.	"monthly"
installments	Number - Mandatory - Not Empty	Number of installments.	2
installments_data	List [InstallmentDataEnum] - Optional - Not Empty	Object containing installment details.	See JSON example
integration_identifier	String - Optional - Not Empty	Custom invoice identifier.	"Neofin-103923"
nfe_number	String - Optional - Not Empty	Invoice/receipt identifier.	"123123123"
recipients	List[String] - Optional - Not Empty	Emails to receive billing in CC.	["email1@company.com", "email2@company.com"]
description	String - Optional - Not Empty	Comment or description of a billing.	"Thanks for paying."

AddressStateEnum

AC: Acre

AL: Alagoas

AP: Amapá

AM: Amazonas

BA: Bahia

CE: Ceará

DF: Distrito Federal

ES: Espírito Santo

GO: Goiás

MA: Maranhão

MT: Mato Grosso

MS: Mato Grosso do Sul

MG: Minas Gerais

PA: Pará

PB: Paraíba

PR: Paraná

PE: Pernambuco

PI: Piauí

RJ: Rio de Janeiro

RN: Rio Grande do Norte

RS: Rio Grande do Sul

RO: Rondônia

RR: Roraima

SC: Santa Catarina

SP: São Paulo

SE: Sergipe

TO: Tocantins

InstallmentTypeStrEnum

"weekly"

"biweekly"

"monthly"

"custom"

BillingTypeStrEnum

The payment method you want to charge your customer. If you provide the "generic" payment method, we will expect your boleto issued by your bank. If that's the case, please provide the "code" and "boleto_pdf" information.

"boleto"

"pix"

"bolepix"

"tedin"

"pixin"

"credit_card"

"generic"

InstallmentData

Fields

Field	Type	Description
amount	Number	Installment amount in BRL cents.
due_date	Number	Due date as a Unix Timestamp.
installment_number	Number	Installment number.

Boleto

If the "type" is "generic" and you cannot or do not have the means to provide a link to download the boleto through "boleto_pdf", you can use this field to enter the boleto data you generated, and we will generate a PDF in the Neofin bill format.

Fields

Field	Type	Description
barcode_number	String	Code required to generate the barcode.
discount_value	Number	Nominal value of discount before maturity.
discount_value_2	Number	Nominal value of rebates.
document_due_date	String	Due date in ISO 8601 standard.
document_issue_date	String	Date of last update of the document in ISO 8601 standard.
document_number	String	Document number informed by the bank when generating the invoice.
document_processing_date	String	Document creation date in ISO 8601 standard.
document_value	Number	Invoice amount in decimal.
drawee_name	String	Beneficiary's name.
drawee_tax_number	String	Beneficiary document (CPF or CNPJ).
fillable_code	String	Typeable invoice line.
fine_rate	Number	Fine in percentage.
interest_rate	Number	Interest in percentage.
recipient_bank_code	String	Code of the bank where the bill was generated.
recipient_bank_digit	String	Bank code digit.
recipient_bank_internal_number	String	Number generated by the bank when creating the invoice, usually identified as "nosso número".
branch	String	Bank branch number.
account_number	String	Beneficiary's bank account number.
account_number_digit	String	Digit of the bank account number.
charging_category	String	Category of the charge for classification purposes.

Usage Example

{
   "barcode_number": "123456789012",
   "discount_value": 50,
   "discount_value_2": 10,
   "document_due_date": "2025-04-01T12:00:00Z",
   "document_issue_date": "2025-03-28T12:00:00Z",
   "document_number": "4545454545",
   "document_processing_date": "2025-03-28T12:00:00Z",
   "document_value": 150.75,
   "drawee_name": "Maria Quinteros",
   "drawee_tax_number": "75730786000100",
   "fillable_code": "1234567890",
   "fine_rate": 2,
   "interest_rate": 1,
   "recipient_bank_code": "033",
   "recipient_bank_digit": "6",
   "recipient_bank_internal_number": "12345678",
   "branch": "1234",
   "account_number": "567890",
   "account_number_digit": "1",
   "charging_category": "standard"
}

Use cases

Automatic Installments

If you want Neofin to automatically calculate your installments, you must send the parameters:

installments and installment_type and do not send the parameter installments_data.

Example: Today is 01/01/2024 and you want to charge R$1000,00 from a customer who is going to pay in 10 installments of R$100,00. The first due date you want to receive is 01/02/2024.

You must fill:

Neofin will create 10 payment billings of R$100,00, the first one with due date 01/02/2024, the second with due_date 01/03/2024, etc, and the last one with due_date 01/11/2023.

Custom Installments

If you want custom installments, you must send the parameters installments,installment_type and installments_data

Example: Today is 01/01/2024 and you want to charge R$1000,00 from a customer who is going to pay in 3 installments, 1) R$100,00 with due date 01/02/2024, 2) R$200,00 with due date 10/02/2024 and 3) R$700,00 with due date 20/02/2024. The first due date you want to receive is 01/02/2024.

You must fill:

Neofin will create 3 payment billings with your installments definitions.

Payments Methods

Boleto

Or billet, this payment method is very common in Brazil and heavily used in payments between companies (B2B). It has a barcode to be read by the payer bank mobile app or ATMs and takes 2 to 3 days for the money to be transferred between bank accounts. You should send the string 'boleto'.

Pix

Instant Payment Method created by Brazilian Central Bank. It has a QRCode read by the payer bank mobile app and the money is transferred real time between bank accounts. You should send the string pix.

Bolepix

A mix between Boleto and Pix. Both payment methods are available (BarCode and QRcode) and the payer can choose which one to use. You should send the string bolepix.

Ted In

Bank Account Transfer. The money is transferred in real time. You should send the string 'tedin'.

Pix In

Bank Account Transfer but using the Pix Key instead the Bank Account Data. The Pix Key can be a phone number, an email address, a document (CPF or CNPJ) or a random uuid. The money is transferred in real time. You should send the string 'pixin'.

Credit Card

The payer can use the credit card to pay the billing/invoice. Used in recorrence. You should send the string 'credit_card'.

Generic

Used when the charge is generated outside the Neofin platform and integrated into it for the use of the charge rule and/or negativity and protest. You should send the string 'generic'.

cURL request example

Return example:


{
    "message": "Billings successfully queued.",
    "errors": {}
}

When upserting be aware of the editable fields:

Editable fields

address_city

address_complement

address_neighborhood

address_number

address_state

address_street

address_zip_code

amount*

boleto: Only when the type is generic.

by_mail

by_whatsapp

customer_mail

customer_name

customer_trade_name

customer_phone

customer_secondary_phone

discount_before_payment

discount_before_payment_due_date

due_date*

fees

fine

installment_type

installments

installments_data

integration_identifier

nfe_number

recipients

type*

How to upsert a billing

Billing attributes#

AddressStateEnum#

InstallmentTypeStrEnum#

BillingTypeStrEnum#

InstallmentData#

Fields#

Boleto#

Fields#

Usage Example#

Use cases#

Automatic Installments#

Custom Installments#

Payments Methods#

cURL request example#

Editable fields#

Billing attributes

AddressStateEnum

InstallmentTypeStrEnum

BillingTypeStrEnum

InstallmentData

Fields

Boleto

Fields

Usage Example

Use cases

Automatic Installments

Custom Installments

Payments Methods

cURL request example

Editable fields