> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Deprecated — Create a deal > Deprecated: use `POST .../deals`; contracts are being removed. 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. ## OpenAPI ````yaml /api-reference/billing.openapi.json post /realms/{realmId}/organizations/{organizationId}/contracts/{contractId}/deals openapi: 3.0.3 info: title: Billing version: 1.0.0 description: >- Portão 3 billing API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Full billing surface — contracts, deals, invoices, statements, payment links, checkout and NFSe orchestration. (The product/supplier catalog moved to registry.) Confidence tiers: generated:typed=74 copied:manual=0 unknown=5. servers: - url: https://api.billing.v2.portao3.com.br/ description: production - url: https://api.billing.dev.3pers.com.br/ description: development security: [] tags: - name: Contracts - name: Deals - name: Invoices - name: Invoice Entries - name: Invoice Statements - name: NFSe Configuration - name: Payment Links paths: /realms/{realmId}/organizations/{organizationId}/contracts/{contractId}/deals: post: tags: - Deals summary: Deprecated — Create a deal description: 'Deprecated: use `POST .../deals`; contracts are being removed.' operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdContractsByContractIdDeals parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of your organization: the one that issues the deal. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: contractId in: path required: true description: >- ID of the contract the deal belongs to. It must be open, and the deal's parties must be parties of it. Format: `UUID` schema: type: string format: uuid example: 7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d requestBody: required: true content: application/json: schema: type: object properties: chargeType: type: string enum: - SINGLE - RECURRENT - SUBSCRIPTION description: >- `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). example: RECURRENT description: type: string minLength: 1 maxLength: 90 description: >- 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`. example: Mensalidade Plano Pro products: minItems: 1 type: array items: type: object properties: identifier: type: string minLength: 1 description: Your label for the product. example: PLANO-PRO description: type: string minLength: 1 description: Description of the product. example: Plano Pro mensal price: type: integer minimum: 1 description: >- Price in centavos, a whole number (`15000` is R$ 150,00), charged on each invoice the product appears on. example: 15000 chargeMethod: type: string enum: - INSTANT - LATER description: >- `LATER`: added to the invoice and paid with it. `INSTANT`: debited from the payer's Portão 3 wallet as soon as it is added — only on `P2P` deals. example: LATER type: type: string enum: - RECURRENT - ONE_TIME - ON_EVENT description: >- `RECURRENT`: on every invoice. `ONE_TIME`: on the first invoice only — on every invoice when `settings.createAllInvoicesOnStart` is `true`. `ON_EVENT`: never charged automatically. example: RECURRENT idProduct: description: >- ID of the product in your product catalog, if it comes from one. example: 8f2e6d4c-1a3b-4c5d-9e8f-7a6b5c4d3e2f type: string required: - identifier - description - price - chargeMethod - type description: What the deal charges for. At least one. paymentMethods: type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX_AUTOMATIC - PIX - P2P example: BANK_SLIP description: >- 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"]` secondaryPaymentMethods: description: >- 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"]` type: array items: type: string enum: - PIX - BANK_SLIP example: PIX settings: description: How the deal creates its invoices. type: object properties: createAllInvoicesOnStart: description: >- `true`: create every invoice now, each due one month after the previous one. Required as `true` for `PIX_AUTOMATIC` and `PIX_INITIATION`. example: false type: boolean disableOpenStatus: default: false description: >- `true`: close each invoice — and issue its payment — as soon as it is created. `false` (the default): an invoice created one at a time stays open, gathering charges, until 5 days before it is due; of the invoices created at the start (`createAllInvoicesOnStart`), the first stays open until its due date and the others are created closed. Required as `true` for `PIX_AUTOMATIC` and `PIX_INITIATION`. example: false type: boolean invoiceNameType: description: >- `DEAL_DESCRIPTION`: name the invoices created at the start after the deal's description — as ` - /` on a `RECURRENT` deal, the description alone otherwise. Omitted, and for invoices created one at a time: they are named after their month (`Nov/26`), except a `SINGLE` deal's invoice, which takes the description. example: DEAL_DESCRIPTION type: string enum: - DEAL_DESCRIPTION paymentLinkId: description: >- ID of the payment link the deal comes from. Set by the payment-link checkout: leave it out. example: 5b8e2f1a-9c4d-4e7b-8a6f-3d2c1b0a9e8f type: string numberOfInstallments: type: integer description: >- 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 firstChargeDate: description: >- 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' anyOf: - type: string format: date - type: string format: date-time creditParties: minItems: 1 type: array items: type: object properties: document: type: string minLength: 1 pattern: ^[A-Za-z0-9]+$ description: >- CPF or CNPJ of the receiver, without punctuation (a valid one). It must be a vendor or intermediary of the contract. example: '12345678000195' name: type: string description: Name of the receiver. example: Empresa Exemplo Ltda email: description: E-mail of the receiver. example: financeiro@empresaexemplo.com.br anyOf: - type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: string enum: - '' unit: type: string enum: - PERCENTAGE description: 'Always `PERCENTAGE`: `amount` is a percentage.' example: PERCENTAGE amount: type: number description: >- The receiver's share of every payment, in percent. The shares of all receivers must add up to 100; your organization keeps what is not transferred to the others. example: 100 account: type: object properties: bank: type: string enum: - P3 description: Always `P3`. example: P3 type: type: string enum: - WALLET description: Always `WALLET`. example: WALLET identifier: type: object properties: realm: type: string minLength: 1 description: ID of the wallet owner's realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b organization: type: string minLength: 1 description: ID of the wallet owner's organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 account: type: string minLength: 1 description: ID of the organization's account. example: 6711b4c0d8e1a30012b7c9f1 wallet: type: string minLength: 1 description: >- ID of the wallet, or `default` for the account's default wallet. It must be active. example: default required: - realm - organization - account - wallet description: Which wallet. required: - bank - type - identifier description: The Portão 3 wallet the share is paid into. required: - document - unit - amount - account description: Who receives the money, and each one's share. At least one. debitParties: minItems: 1 maxItems: 1 type: array items: type: object properties: document: type: string pattern: ^[A-Za-z0-9]+$ description: >- CPF or CNPJ of the payer, without punctuation (a valid one). It must be a buyer of the contract. example: '52998224725' name: type: string minLength: 1 description: Name of the payer. example: Maria da Silva email: description: >- E-mail of the payer. Omitted: the contract buyer's e-mail is used. example: maria.silva@example.com anyOf: - type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: string enum: - '' phone: description: >- Phone of the payer, in E.164 format: `+`, the country code and the number, digits only. A Brazilian number is `+55`, the 2-digit area code and 8 or 9 digits. It is the phone printed on the payer's fiscal documents. Omitted: the contract buyer's phone is used, when it is a valid one. example: '+5511987654321' type: string pattern: ^\+(?:55[0-9]{10,11}|(?!55)[1-9]\d{7,14})$ unit: type: string enum: - PERCENTAGE description: 'Always `PERCENTAGE`: `amount` is a percentage.' example: PERCENTAGE amount: type: number description: 'The payer''s share of each invoice, in percent: `100`.' example: 100 account: description: >- The payer's Portão 3 wallet the invoices are debited from. Required, with every field, for `P2P` deals. type: object properties: bank: type: string enum: - P3 description: Always `P3`. example: P3 type: type: string enum: - WALLET description: Always `WALLET`. example: WALLET identifier: description: Which wallet. type: object properties: realm: description: ID of the payer's realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b type: string organization: description: ID of the payer's organization. example: 1d3f5a7c-9e2b-4c6d-8f0a-2b4c6d8e0f1a type: string account: description: ID of the payer's account. example: 6711b4c0d8e1a30012b7c9f9 type: string wallet: description: >- ID of the payer's wallet, or `default` for the account's default wallet. It must be active. example: default type: string address: description: >- The payer's billing address, printed on its boletos and PIX charges. Required, with every field but `complement`, for `BANK_SLIP` and `PIX` deals — and for deals that create all their invoices at the start with `PIX` or `BANK_SLIP` among `secondaryPaymentMethods`. Otherwise, an omitted address is the contract buyer's. type: object properties: street: type: string description: Street. example: Avenida Paulista number: type: string description: Number. example: '1000' complement: description: Complement, up to 50 characters. example: Sala 12 type: string neighborhood: type: string description: Neighborhood. example: Bela Vista city: type: string description: City. example: São Paulo state: description: State, as its two-letter code (`SP`, `RJ`, …). example: SP type: string postalCode: type: string description: Postal code (CEP), as `NNNNN-NNN`. example: 01310-100 required: - document - name - unit - amount description: 'Who pays: exactly one payer.' fine: default: null description: >- Fine charged once on an invoice paid after its due date. `null` or omitted: none. type: object properties: amountType: type: string enum: - FIXED_VALUE - PERCENT description: >- `PERCENT`: `amount` is a percentage of the invoice, from 0.1 to 99.99. `FIXED_VALUE`: `amount` is a whole number of centavos, at least 1. example: PERCENT amount: type: number description: The fine, per `amountType`. example: 2 required: - amountType - amount nullable: true interest: default: null description: >- Interest charged on an invoice paid late, from the day after its due date. `null` or omitted: none. type: object properties: amountType: type: string enum: - AMOUNT_CALENDAR_DAYS - AMOUNT_WORKING_DAYS - PERCENT_POINT_PER_DAY_CALENDAR_DAYS - PERCENT_POINT_PER_DAY_WORKING_DAYS description: >- `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS`: `amount` is a percentage, from 0.1 to 99.99 — per day on a PIX charge, but per MONTH on a boleto. `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS`: `amount` is a whole number of centavos per calendar or working day, at least 1. example: PERCENT_POINT_PER_DAY_CALENDAR_DAYS amount: type: number description: The interest, per `amountType`. example: 0.1 required: - amountType - amount nullable: true discount: default: null description: >- Discount for an invoice paid before its due date. `null` or omitted: none. type: object properties: amountType: type: string enum: - AMOUNT_PER_ANTECIPATION - PERCENT_PER_ANTECIPATION description: >- `PERCENT_PER_ANTECIPATION`: `amount` is a percentage of the invoice, from 0.1 to 99.99. `AMOUNT_PER_ANTECIPATION`: `amount` is a whole number of centavos, at least 1. example: AMOUNT_PER_ANTECIPATION amount: type: number description: The discount, per `amountType`. example: 500 required: - amountType - amount nullable: true endAt: description: >- 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' anyOf: - type: string format: date - type: string format: date-time required: - chargeType - description - products - paymentMethods - firstChargeDate - creditParties - debitParties responses: '201': description: Successful response content: application/json: schema: type: object properties: id: type: string description: ID of the deal. example: 9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d format: uuid description: type: string description: >- 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 realm: type: string description: ID of the realm of the organization that issues the deal. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the organization that issues the deal. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid contract: type: string description: >- ID of the contract the deal belongs to. Absent on a deal created without a contract. example: 7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d format: uuid chargeType: type: string enum: - SINGLE - RECURRENT - SUBSCRIPTION description: >- `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. example: RECURRENT status: type: string enum: - OPEN - CANCELED - TERMINATED - EXPIRED - REVOKED description: >- `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. example: OPEN firstChargeDate: type: string description: >- 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' format: date-time numberOfInstallments: type: number description: >- 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: type: object properties: createAllInvoicesOnStart: type: boolean description: >- `true`: every invoice of the deal was created with the deal, each due one month after the previous one. Otherwise the deal creates its invoices one at a time, the next one when the previous one closes. example: false disableOpenStatus: type: boolean description: >- `true`: each invoice is closed — and its payment issued — as soon as it is created. Otherwise an invoice created one at a time stays open, gathering charges, until 5 days before its due date; of the invoices created at the start, the first stays open until its due date and the others were created closed. example: false invoiceNameType: type: string enum: - DEAL_DESCRIPTION description: >- `DEAL_DESCRIPTION`: the invoices created at the start are named after the deal's description — as ` - /` on a `RECURRENT` deal. Absent, and for invoices created one at a time: they are named after their month (`Nov/26`), except a `SINGLE` deal's invoice, which takes the description. example: DEAL_DESCRIPTION paymentLinkId: type: string description: >- ID of the payment link the deal was created from. Only on deals created by a payment-link checkout. example: 5b8e2f1a-9c4d-4e7b-8a6f-3d2c1b0a9e8f format: uuid callBackUrlForPaymentProvider: type: object properties: success: type: string description: After a successful payment. example: >- https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/success pending: type: string description: While the payment is pending. example: >- https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/pending error: type: string description: After a failed payment. example: >- https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/error description: >- The pages the payer returns to. Only on deals created by a payment-link checkout. description: How the deal creates its invoices. startAt: type: string description: >- When the deal starts: when it was created, unless it was changed with `PUT`. example: '2026-10-26T13:00:00.000Z' format: date-time endAt: type: string nullable: true description: >- 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' format: date-time products: type: array items: type: object properties: id: type: string description: ID of the product inside the deal. example: 3c1d9a7e-2b4f-4e8a-9c6d-5f7e8a9b0c1d format: uuid identifier: type: string description: Your label for the product. example: PLANO-PRO description: type: string description: Description of the product. example: Plano Pro mensal price: type: number description: >- Price in centavos (`15000` is R$ 150,00), charged on each invoice the product appears on. example: 15000 type: type: string enum: - RECURRENT - ONE_TIME - ON_EVENT description: >- Which invoices charge the product. `RECURRENT`: every invoice of the deal. `ONE_TIME`: the first invoice only — or every invoice, when the deal creates all its invoices at the start (`settings.createAllInvoicesOnStart`). `ON_EVENT`: no invoice charges it automatically. example: RECURRENT chargeMethod: type: string enum: - INSTANT - LATER description: >- When the product is charged. `LATER`: it is added to the invoice and paid with it. `INSTANT`: it is debited from the payer's Portão 3 wallet as soon as it is added (only on `P2P` deals). example: LATER idProduct: type: string description: >- ID of the product in your product catalog, when the deal was created from one. example: 8f2e6d4c-1a3b-4c5d-9e8f-7a6b5c4d3e2f required: - id - identifier - price - type - chargeMethod description: A product the deal charges for. description: What the deal charges for. paymentMethods: type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX_AUTOMATIC - PIX - P2P example: BANK_SLIP description: >- 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"]` secondaryPaymentMethods: type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX_AUTOMATIC - PIX - P2P description: >- Other ways the payer can pay the invoices: `PIX` and/or `BANK_SLIP`. Empty when there are none. --- Example: `[]` example: [] creditParties: type: array items: type: object properties: document: type: string description: >- CPF or CNPJ of the receiver, digits only (an alphanumeric CNPJ in upper case). example: '12345678000195' name: type: string description: Name of the receiver. example: Empresa Exemplo Ltda email: type: string description: E-mail of the receiver. example: financeiro@empresaexemplo.com.br unit: type: string enum: - PERCENTAGE description: 'Always `PERCENTAGE`: `amount` is a percentage.' example: PERCENTAGE amount: type: number description: >- The receiver's share of every payment, in percent. The shares of all receivers add up to 100; the deal's own organization keeps what is not transferred to the others. example: 100 account: type: object properties: bank: type: string enum: - P3 description: 'Always `P3`: a Portão 3 account.' example: P3 type: type: string enum: - WALLET description: Always `WALLET`. example: WALLET identifier: type: object properties: realm: type: string description: ID of the wallet owner's realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the wallet owner's organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid account: type: string description: ID of the organization's account. example: 6711b4c0d8e1a30012b7c9f1 wallet: type: string description: >- ID of the wallet, or `default` for the account's default wallet. example: default required: - realm - organization - account - wallet description: Which wallet. required: - bank - type - identifier description: The wallet the share is paid into. required: - document - unit - amount - account description: >- Who receives the money the deal collects, and their share of it. description: Who receives the money and each one's share. debitParties: type: array items: type: object properties: document: type: string description: >- CPF or CNPJ of the payer, digits only (an alphanumeric CNPJ in upper case). example: '52998224725' name: type: string description: Name of the payer. example: Maria da Silva email: type: string description: E-mail of the payer. example: maria.silva@example.com phone: type: string description: >- Phone of the payer, in E.164 format (`+`, the country code and the number, digits only). Absent when the deal has none. example: '+5511987654321' unit: type: string enum: - PERCENTAGE description: 'Always `PERCENTAGE`: `amount` is a percentage.' example: PERCENTAGE amount: type: number description: >- The payer's share of each invoice, in percent: `100`, since a deal has one payer. example: 100 account: type: object properties: bank: type: string enum: - P3 description: 'Always `P3`: a Portão 3 account.' example: P3 type: type: string enum: - WALLET description: Always `WALLET`. example: WALLET identifier: type: object properties: realm: type: string description: ID of the wallet owner's realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the wallet owner's organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid account: type: string description: ID of the organization's account. example: 6711b4c0d8e1a30012b7c9f1 wallet: type: string description: >- ID of the wallet, or `default` for the account's default wallet. example: default required: - realm - organization - account - wallet description: Which wallet. required: - bank - type - identifier description: >- The payer's Portão 3 wallet the invoices are debited from. Present on `P2P` deals. address: type: object properties: street: type: string description: Street. example: Avenida Paulista number: type: string description: Number. example: '1000' complement: type: string description: Complement. example: Sala 12 neighborhood: type: string description: Neighborhood. example: Bela Vista city: type: string description: City. example: São Paulo state: type: string description: State, as its two-letter code. example: SP postalCode: type: string description: Postal code (CEP), as `NNNNN-NNN`. example: 01310-100 required: - street - number - neighborhood - city - state - postalCode description: >- The payer's billing address. Present on boleto and PIX deals. required: - document - name - unit - amount description: Who pays the deal. description: Who pays. closingAt: type: string description: >- When each invoice created one at a time closes, as a cron expression `0 0 * *`: 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: type: string description: >- When each invoice is due, as a cron expression `0 0 * *`: `firstChargeDate`'s day. example: 0 0 10 * * createdBy: type: string description: ID of who created the deal. example: 5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b updatedBy: type: string description: ID of who last changed the deal. example: 5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b fine: description: Fine for late payment. `null` when the deal has none. type: object properties: amountType: type: string enum: - FIXED_VALUE - PERCENT description: >- `PERCENT`: `amount` is a percentage of the invoice. `FIXED_VALUE`: `amount` is in centavos. example: PERCENT amount: type: number description: >- The fine: a percentage (`2` is 2%) or an amount in centavos, per `amountType`. example: 2 required: - amountType - amount nullable: true interest: description: Interest for late payment. `null` when the deal has none. type: object properties: amountType: type: string enum: - AMOUNT_CALENDAR_DAYS - AMOUNT_WORKING_DAYS - PERCENT_POINT_PER_DAY_CALENDAR_DAYS - PERCENT_POINT_PER_DAY_WORKING_DAYS description: >- `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS`: `amount` is a percentage — per calendar or working day on a PIX charge, but per MONTH on a boleto. `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS`: `amount` is in centavos per calendar or working day. example: PERCENT_POINT_PER_DAY_CALENDAR_DAYS amount: type: number description: >- The interest: a percentage or an amount in centavos, per `amountType`. example: 0.1 required: - amountType - amount nullable: true discount: description: Discount for early payment. `null` when the deal has none. type: object properties: amountType: type: string enum: - AMOUNT_PER_ANTECIPATION - PERCENT_PER_ANTECIPATION description: >- `PERCENT_PER_ANTECIPATION`: `amount` is a percentage of the invoice. `AMOUNT_PER_ANTECIPATION`: `amount` is in centavos. example: AMOUNT_PER_ANTECIPATION amount: type: number description: >- The discount: a percentage or an amount in centavos, per `amountType`. example: 500 required: - amountType - amount nullable: true createdAt: type: string description: When the deal was created. example: '2026-10-26T13:00:00.000Z' format: date-time updatedAt: type: string description: When the deal last changed. example: '2026-10-26T13:00:00.000Z' format: date-time paymentUrl: type: string description: >- Link where the payer authorizes the payments. Only on `PIX_AUTOMATIC` and `PIX_INITIATION` deals. example: https://pix.example.com/authorize/9b2f7c1e paymentLinkValidity: type: string nullable: true description: >- Until when `paymentUrl` can be used. Only on `PIX_AUTOMATIC` deals; `null` on `PIX_INITIATION` deals. example: '2026-11-09T23:59:59.000Z' format: date-time required: - id - realm - organization - chargeType - status - firstChargeDate - startAt - endAt - products - paymentMethods - secondaryPaymentMethods - creditParties - debitParties - closingAt - dueAt - createdBy - updatedBy - createdAt - updatedAt description: >- A deal: what an organization charges a payer for, how and when. '400': description: >- `DEBIT_PARTY_DOCUMENT_MISMATCH_CONTRACT` — The payer is not a buyer of the contract. `CREDIT_PARTY_DOCUMENT_MISMATCH_CONTRACT` — A receiver is not a vendor or intermediary of the contract. `INVALID_PARTY_REALM_ORG` — A receiver's wallet belongs to a realm and organization that don't match the contract's. `PARTY_REALM_ORG_NOT_FOUND` — A receiver's wallet organization does not exist, is not active, or has another document. `CREDIT_AMOUNT_MISMATCH` — The receivers' shares don't add up to 100. `DEBIT_AMOUNT_MISMATCH` — The payer's share is not 100. `INVALID_CHARGE_METHOD` — A product is charged `INSTANT` on a deal that is not paid by `P2P`. `WALLET_NOT_ACTIVE` — A receiver's wallet is not active, or — on a `P2P` deal — the payer's is neither active nor pending activation. `PIX_DICT_NOT_FOUND` — The deal is paid by `PIX`, `PIX_AUTOMATIC` or `PIX_INITIATION`, and your organization's default wallet has no active PIX key. `CREDIT_DEBIT_WALLET_MUST_BE_DIFFERENT` — On a `P2P` deal, the payer's wallet is also a receiver's. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - DEBIT_PARTY_DOCUMENT_MISMATCH_CONTRACT - CREDIT_PARTY_DOCUMENT_MISMATCH_CONTRACT - INVALID_PARTY_REALM_ORG - PARTY_REALM_ORG_NOT_FOUND - CREDIT_AMOUNT_MISMATCH - DEBIT_AMOUNT_MISMATCH - INVALID_CHARGE_METHOD - WALLET_NOT_ACTIVE - PIX_DICT_NOT_FOUND - CREDIT_DEBIT_WALLET_MUST_BE_DIFFERENT description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: DEBIT_PARTY_DOCUMENT_MISMATCH_CONTRACT origin: BILLING message: Debit party document 52998224725 must be in contract parties '403': description: >- `INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm. `BILLING_P2P_NOT_ENABLED` — The deal is paid by `P2P`, and P2P is not enabled for your organization. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - INSUFFICIENT_PERMISSIONS - BILLING_P2P_NOT_ENABLED description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: INSUFFICIENT_PERMISSIONS origin: BILLING message: insufficient permissions '404': description: >- `CONTRACT_NOT_FOUND` — The organization has no contract with this ID. `WALLET_NOT_FOUND` — A receiver's wallet — or, on a `P2P` deal, the payer's — does not exist. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - CONTRACT_NOT_FOUND - WALLET_NOT_FOUND description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: CONTRACT_NOT_FOUND origin: BILLING message: Contract not found '422': description: >- `CONTRACT_NOT_OPEN` — The contract was terminated. `DEAL_START_AT_INVALID` — The contract only starts after today. `DEAL_END_AT_REQUIRED` — The contract has an end date and the `SUBSCRIPTION` deal has no `endAt`. `DEAL_END_AT_INVALID` — The deal would end after the contract. `CREATE_INVOICE_ERROR` — The deal's first invoice could not be created; nothing was kept. `BAD_REQUEST` — The body is invalid — a missing field, more than one payment method, a `firstChargeDate` in the past, a PIX Automático deal that breaks its rules, a payer without the address or wallet the payment method needs — or a path parameter is not a valid ID; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - CONTRACT_NOT_OPEN - DEAL_START_AT_INVALID - DEAL_END_AT_REQUIRED - DEAL_END_AT_INVALID - CREATE_INVOICE_ERROR - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: CONTRACT_NOT_OPEN origin: BILLING message: Contract is not open ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.