Skip to main content
POST
Deprecated — Create a deal
Creates a deal under a contract: what your organization charges a payer for, how it is paid and when. The invoices follow from chargeType and settings.createAllInvoicesOnStart. With it, every invoice is created now — numberOfInstallments of them, each due one month after the previous one. Without it, a SINGLE or SUBSCRIPTION deal gets its first invoice now, and a RECURRENT deal none until you start it: send its startAt with PUT .../deals/{dealId} — today creates the first invoice at once, a later date (as YYYY-MM-DD) on that day. From then on, each invoice creates the next one when it closes, as long as the deal is open, has a RECURRENT product and its end date has not passed — numberOfInstallments months after firstChargeDate for a RECURRENT deal, endAt (or never) for a SUBSCRIPTION deal. The first invoice is due on firstChargeDate. An invoice closes — and its boleto or PIX charge is issued — as soon as it is created with settings.disableOpenStatus; otherwise an invoice created one at a time closes 5 days before its due date, and of the invoices created at the start the first closes on its due date and the others are created closed. The deal starts now, and its closing and due days are derived from firstChargeDate (see closingAt and dueAt in the response). The contract must be open, the payer must be one of its buyers and every receiver one of its vendors or intermediaries; each receiver’s wallet must be active, and on a P2P deal the payer’s must be active or still pending activation — nothing is debited from a pending wallet until it is active. Deals paid by PIX, PIX_AUTOMATIC or PIX_INITIATION need an active PIX key in your organization’s default wallet. PIX_AUTOMATIC (PIX Automático) and PIX_INITIATION (recurring scheduled PIX) are RECURRENT deals that create every invoice now and close them at once (settings.createAllInvoicesOnStart and settings.disableOpenStatus both true), from RECURRENT products charged LATER, with at least one secondary method. The payment authorization is requested from the bank as the deal is created: the response carries the paymentUrl where the payer authorizes it. The BILLING_DEAL_CREATED webhook event is sent, and BILLING_INVOICE_CREATED for each invoice created (BILLING_INVOICE_CLOSED for each one closed at once). If creating the invoices fails after the deal was saved, the error is returned and the deal and what was already created for it are deleted — a best-effort cleanup that can itself fail; a PIX authorization the bank already created, and the webhook events already sent for its invoices, are not undone. A request sent twice creates two deals. Any member of the organization, or an admin of the realm, can create one; createdBy and updatedBy are set to the ID of the authenticated caller. Answers the deal it created.

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of your organization: the one that issues the deal.

Format: UUID

​
contractId
string<uuid>
required

ID of the contract the deal belongs to. It must be open, and the deal's parties must be parties of it.

Format: UUID

Body

application/json
​
chargeType
enum<string>
required

SINGLE: one invoice, created now. RECURRENT: monthly invoices up to numberOfInstallments months after firstChargeDate. SUBSCRIPTION: monthly invoices, the first created now, until endAt (or until the deal is canceled or terminated). Unless settings.createAllInvoicesOnStart creates them all now, each invoice after the first is created when the previous one closes, and only while the deal has a RECURRENT product (see the description above).

Available options:
SINGLE,
RECURRENT,
SUBSCRIPTION
Example:

"RECURRENT"

​
description
string
required

Description of the deal, up to 90 characters. It names the invoice of a SINGLE deal, and the invoices created at the start when settings.invoiceNameType is DEAL_DESCRIPTION.

Required string length: 1 - 90
Example:

"Mensalidade Plano Pro"

​
products
object[]
required

What the deal charges for. At least one.

Minimum array length: 1
​
paymentMethods
enum<string>[]
required

How the invoices are paid — exactly one: BANK_SLIP (boleto), PIX (a PIX charge), P2P (a debit from the payer's Portão 3 wallet), PIX_AUTOMATIC (PIX Automático: the payer authorizes the recurring payments once, through paymentUrl in the response) or PIX_INITIATION (recurring scheduled PIX, authorized the same way).

Example: ["BANK_SLIP"]

Available options:
BANK_SLIP,
PIX_INITIATION,
PIX_AUTOMATIC,
PIX,
P2P
​
firstChargeDate
required

Due date of the first invoice (ISO 8601 date or date-time, read in UTC); the next ones are due on the same day of the following months. Today or later — strictly after today for PIX_INITIATION, today or later in Brasília time for PIX_AUTOMATIC.

Example:

"2026-11-10"

​
creditParties
object[]
required

Who receives the money, and each one's share. At least one.

Minimum array length: 1
​
debitParties
object[]
required

Who pays: exactly one payer.

Required array length: 1 element
​
secondaryPaymentMethods
enum<string>[]

Other ways the payer can pay: PIX and/or BANK_SLIP. Required, with at least one, for PIX_AUTOMATIC and PIX_INITIATION. Only invoices created at the start (settings.createAllInvoicesOnStart) accept them.

Example: ["PIX"]

Available options:
PIX,
BANK_SLIP
​
settings
object

How the deal creates its invoices.

​
numberOfInstallments
integer

With settings.createAllInvoicesOnStart, how many invoices are created now, whatever the charge type. Otherwise it sets when a RECURRENT deal ends: numberOfInstallments months after firstChargeDate. Required for RECURRENT, a whole number of at least 2; defaults to 1 otherwise.

Example:

12

​
fine
object | null

Fine charged once on an invoice paid after its due date. null or omitted: none.

​
interest
object | null

Interest charged on an invoice paid late, from the day after its due date. null or omitted: none.

​
discount
object | null

Discount for an invoice paid before its due date. null or omitted: none.

​
endAt

End date of a SUBSCRIPTION deal (ISO 8601 date or date-time); omitted, it has no end. Ignored by SINGLE and RECURRENT deals, whose end follows from their invoices. When the contract has an end date, the deal's end can't be after it — and a SUBSCRIPTION deal must then have one.

Example:

"2027-12-31"

Response

Successful response

A deal: what an organization charges a payer for, how and when.

​
id
string<uuid>
required

ID of the deal.

Example:

"9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d"

​
realm
string<uuid>
required

ID of the realm of the organization that issues the deal.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

​
organization
string<uuid>
required

ID of the organization that issues the deal.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

​
chargeType
enum<string>
required

SINGLE: one invoice. RECURRENT: monthly invoices up to numberOfInstallments months after firstChargeDate. SUBSCRIPTION: one invoice a month until the deal ends, is terminated or is canceled. After the first, each invoice is created when the previous one closes — unless the deal created them all at the start (settings.createAllInvoicesOnStart) — and only while the deal has a RECURRENT product.

Available options:
SINGLE,
RECURRENT,
SUBSCRIPTION
Example:

"RECURRENT"

​
status
enum<string>
required

OPEN: active — it creates invoices and can be changed or canceled. CANCELED: canceled through the API. TERMINATED: it reached its end date (checked daily), its end date was moved to today or earlier, or its contract was terminated. EXPIRED: a PIX Automático or recurring PIX deal whose payer never authorized the payment, a few days after the first due date. REVOKED: the payer revoked the PIX Automático authorization.

Available options:
OPEN,
CANCELED,
TERMINATED,
EXPIRED,
REVOKED
Example:

"OPEN"

​
firstChargeDate
string<date-time>
required

Due date of the first invoice. The later invoices are due on the same day of each following month.

Example:

"2026-11-10T00:00:00.000Z"

​
startAt
string<date-time>
required

When the deal starts: when it was created, unless it was changed with PUT.

Example:

"2026-10-26T13:00:00.000Z"

​
endAt
string<date-time> | null
required

When the deal ends. SINGLE: when it was created. RECURRENT: numberOfInstallments months after firstChargeDate. SUBSCRIPTION: the end date you set, or null for no end. Once the end date has passed, a daily routine terminates an OPEN deal.

Example:

"2027-11-10T00:00:00.000Z"

​
products
object[]
required

What the deal charges for.

​
paymentMethods
enum<string>[]
required

How the invoices are paid: one of BANK_SLIP (boleto), PIX (a PIX charge), P2P (a debit from the payer's Portão 3 wallet), PIX_AUTOMATIC (PIX Automático) or PIX_INITIATION (recurring scheduled PIX).

Example: ["BANK_SLIP"]

Available options:
BANK_SLIP,
PIX_INITIATION,
PIX_AUTOMATIC,
PIX,
P2P
​
secondaryPaymentMethods
enum<string>[]
required

Other ways the payer can pay the invoices: PIX and/or BANK_SLIP. Empty when there are none.

Example: []

Available options:
BANK_SLIP,
PIX_INITIATION,
PIX_AUTOMATIC,
PIX,
P2P
Example:
​
creditParties
object[]
required

Who receives the money and each one's share.

​
debitParties
object[]
required

Who pays.

​
closingAt
string
required

When each invoice created one at a time closes, as a cron expression 0 0 <day of month> * *: 5 days before firstChargeDate's day, or that same day when settings.disableOpenStatus is true. Invoices created at the start close on their own due date.

Example:

"0 0 5 * *"

​
dueAt
string
required

When each invoice is due, as a cron expression 0 0 <day of month> * *: firstChargeDate's day.

Example:

"0 0 10 * *"

​
createdBy
string
required

ID of who created the deal.

Example:

"5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b"

​
updatedBy
string
required

ID of who last changed the deal.

Example:

"5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b"

​
createdAt
string<date-time>
required

When the deal was created.

Example:

"2026-10-26T13:00:00.000Z"

​
updatedAt
string<date-time>
required

When the deal last changed.

Example:

"2026-10-26T13:00:00.000Z"

​
description
string

Description of the deal. It names the invoice of a SINGLE deal, and the invoices created at the start when settings.invoiceNameType is DEAL_DESCRIPTION.

Example:

"Mensalidade Plano Pro"

​
contract
string<uuid>

ID of the contract the deal belongs to. Absent on a deal created without a contract.

Example:

"7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d"

​
numberOfInstallments
number

With settings.createAllInvoicesOnStart, how many invoices were created at the start. Otherwise it sets when a RECURRENT deal ends: numberOfInstallments months after firstChargeDate. 1 unless it was sent.

Example:

12

​
settings
object

How the deal creates its invoices.

​
fine
object | null

Fine for late payment. null when the deal has none.

​
interest
object | null

Interest for late payment. null when the deal has none.

​
discount
object | null

Discount for early payment. null when the deal has none.

​
paymentUrl
string

Link where the payer authorizes the payments. Only on PIX_AUTOMATIC and PIX_INITIATION deals.

Example:

"https://pix.example.com/authorize/9b2f7c1e"

​
paymentLinkValidity
string<date-time> | null

Until when paymentUrl can be used. Only on PIX_AUTOMATIC deals; null on PIX_INITIATION deals.

Example:

"2026-11-09T23:59:59.000Z"