> ## 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. # Mark an invoice as paid > Marks an invoice your organization issued as paid, for a payment received outside Portão 3, by recording a `MANUAL_SETTLEMENT` statement for everything still owed. The settlement is a `CREDIT`, `DONE` statement whose `billingAmount` is computed from the ledger when you call it — the `DONE` debits minus the `DONE` credits — and whose `originalAmount` is the invoice amount. It is not checked against the invoice's status: before the invoice closes its amount is usually not owed yet, so the settlement can record `0` or less. The invoice becomes paid, the `BILLING_INVOICE_PAID` webhook event is sent and, when your NFSe configuration issues on paid invoices (`INVOICE_PAID`), its NFSe is issued. When the invoice has a PIX Automático or recurring PIX installment in `SCHEDULED` status, its charge is canceled first. An installment that is not scheduled yet (`CREATED`) is left as it is, and a PIX Automático charge is only canceled while it is still pending. If canceling a recurring PIX charge fails, or the PIX Automático charge can't be read, the Banking service's error is returned (`origin` `BANKING`, with its own status and `code`) and nothing is recorded. If canceling a PIX Automático charge fails, the error is returned the same way unless the charge was already attempted or its date is before today; then the invoice is marked as paid anyway, and the payer may still be charged. The invoice's status is not checked: use it on an unpaid invoice, since marking a paid or a canceled invoice records another settlement and leaves the invoice paid. Any member of the organization, or an admin of the realm, can mark one as paid; `createdBy` is set to the ID of the authenticated caller. Answers the settlement statement it recorded. ## OpenAPI ````yaml /api-reference/billing.openapi.json post /realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement 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}/invoices/{invoiceId}/statements/settlement: post: tags: - Invoice Statements summary: Mark an invoice as paid description: >- Marks an invoice your organization issued as paid, for a payment received outside Portão 3, by recording a `MANUAL_SETTLEMENT` statement for everything still owed. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdStatementsSettlement 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 the organization that issued the invoice. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: invoiceId in: path required: true description: |- ID of the invoice to mark as paid. Format: `UUID` schema: type: string format: uuid example: 0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a requestBody: required: true content: application/json: schema: type: object properties: description: type: string minLength: 1 description: >- Why the invoice is being marked as paid, such as how the payment was received. Stored on the settlement statement. example: Pagamento recebido em dinheiro na loja. required: - description responses: '201': description: Successful response content: application/json: schema: type: object properties: id: type: string description: ID of the statement. example: 9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f format: uuid realm: type: string description: >- ID of the realm of the organization that issued the invoice. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the organization that issued the invoice. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid invoice: type: string description: ID of the invoice. example: 0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a format: uuid identifier: type: string description: >- The kind of movement. Portão 3 writes `INVOICE_CLOSED` (a `DEBIT` for the invoice amount, when the invoice closes), one statement per payment instrument created for the invoice — `BANK_SLIP_CREATED` (boleto), `PIX_CREATED` (PIX charge), `P2P_CREATED` (a debit from the payer's Portão 3 account) and `PIX_INITIATION_CREATED` (PIX Automático or recurring scheduled PIX) —, `INTEREST_AND_FINES` (a `DEBIT` for what a late boleto or PIX payment paid above the charge) and `MANUAL_SETTLEMENT` (the invoice was marked as paid by hand). A statement recorded through the API carries the label it was sent with. example: MANUAL_SETTLEMENT description: type: string description: >- Free text describing the movement. Empty when there is none. example: Pagamento recebido em dinheiro na loja. billingAmount: type: integer description: >- Amount in centavos (`15000` is R$ 150,00) that counts toward the invoice balance while the statement is `DONE`: as paid when `financialImpactType` is `CREDIT`, as owed when it is `DEBIT`. A payment instrument starts at `0` and takes the amount actually paid when it is paid. example: 15000 originalAmount: type: integer description: >- Reference amount in centavos: the amount a payment instrument charges, the invoice amount on `INVOICE_CLOSED` and `MANUAL_SETTLEMENT`, or the amount sent on a statement recorded through the API. Informational: it does not change the balance. example: 15000 financialImpactType: type: string enum: - CREDIT - DEBIT - NONE description: >- `CREDIT`: reduces what is owed (a payment, a discount). `DEBIT`: adds to what is owed (the invoice amount, interest and fines, a fee). `NONE`: no effect on the balance. example: CREDIT status: type: string enum: - CREATED - PROCESSING - SCHEDULED - PAID - CANCELED - DONE - ERROR - SCHEDULE_ERROR description: >- Only `DONE` counts toward the balance. `DONE`: in effect — the amount owed, a paid instrument, an adjustment or a settlement. `CREATED`: a payment instrument waiting to be paid (a PIX charge, a registered boleto, a PIX Automático installment not scheduled yet). `PROCESSING`: a boleto being registered, or a debit from the payer's account in progress. `SCHEDULED`: a PIX Automático or scheduled PIX installment waiting for its date. `CANCELED`: a PIX Automático or scheduled PIX installment that was canceled. `ERROR`: the charge failed. `SCHEDULE_ERROR`: a PIX Automático installment could not be scheduled. `PAID` is not used. example: DONE effectiveAt: type: string description: >- When the movement took effect. For Portão 3's own statements it is when the statement was created; a statement recorded through the API carries the date it was sent with. example: '2026-10-25T12:00:00.000Z' format: date-time createdBy: type: string description: >- ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it. example: 5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b updatedBy: type: string description: >- Who last changed the statement. It is set when the statement is created and later status changes (a payment confirmed, an installment scheduled) do not change it, so it is usually the same as `createdBy`. example: 5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b createdAt: type: string description: When the statement was recorded. example: '2026-10-25T12:00:00.000Z' format: date-time updatedAt: type: string description: When the statement last changed, such as its status. example: '2026-10-25T12:00:00.000Z' format: date-time paymentData: type: object properties: pix: type: object properties: emv: type: string description: The PIX copy-and-paste code (EMV) the payer pays. example: >- 00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD dueAt: type: string description: When the PIX charge is due. example: '2026-10-10T23:59:59.000Z' format: date-time required: - emv description: >- The PIX charge, on a `PIX_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment). bankSlip: type: object properties: digitableLine: type: string description: >- The boleto's typeable line (linha digitável). Empty until the boleto is registered. example: '34191790010104351004791020150008291070026000' barcode: type: string description: >- The boleto's barcode. Empty until the boleto is registered. example: '34192910700260001790001043510047902015000829' dueAt: type: string description: When the boleto is due. example: '2026-10-10T23:59:59.000Z' format: date-time expiresAt: type: string description: After this date the boleto can no longer be paid. example: '2026-11-09T23:59:59.000Z' format: date-time required: - digitableLine - barcode description: >- The boleto, on a `BANK_SLIP_CREATED` statement (and on the `INTEREST_AND_FINES` statement of its late payment). pixInitiation: type: object properties: paymentUrl: type: string description: Link where the payer authorizes the payment. example: https://pix.example.com/authorize/9d4e1f6a scheduledTo: type: string description: >- When the payment is scheduled to be charged: the invoice's due date. example: '2026-10-10T12:00:00.000Z' format: date-time required: - paymentUrl description: >- The authorized PIX payment, on a `PIX_INITIATION_CREATED` statement. description: >- The payment instrument: on `BANK_SLIP_CREATED`, `PIX_CREATED` and `PIX_INITIATION_CREATED` statements, and on the `INTEREST_AND_FINES` statement of a late boleto or PIX payment. external: type: object properties: b3BankSlip: type: string description: ID of the boleto. example: 6711b4c0d8e1a30012b7c9f2 b3Pix: type: string description: ID of the PIX charge. example: 6711b4c0d8e1a30012b7c9f3 b3PixBillingInitiationRequest: type: string description: >- ID of the PIX Automático authorization, or of the recurring scheduled PIX payment, this statement belongs to. Every installment of the same deal shares it. example: 6711b4c0d8e1a30012b7c9f4 b3PixBillingInitiationRequestItem: type: string description: >- ID of this installment's scheduled charge. Empty until the charge is scheduled. example: 6711b4c0d8e1a30012b7c9f5 description: >- IDs of the charge in the Banking service: on the same statements as `paymentData`. error: description: >- Why a PIX Automático or scheduled PIX charge failed. Present once a failure was recorded, and kept if a later attempt succeeds. `null` on a few statements recorded through the API with an empty `error`. type: object properties: code: type: string description: Error code, or `UNKNOWN_ERROR`. example: PAYMENT_REJECTED detail: type: string description: Detail of the failure, or `Desconhecido`. example: Saldo insuficiente na conta do pagador. description: type: string description: Description of the failure, or `Erro desconhecido`. example: O pagamento foi recusado pela instituição do pagador. nullable: true required: - id - realm - organization - invoice - identifier - description - billingAmount - originalAmount - financialImpactType - status - effectiveAt - createdBy - updatedBy - createdAt - updatedAt description: >- One entry of an invoice's ledger: the amount owed, a payment instrument and its payment, interest and fines, an adjustment or a manual settlement. '403': description: >- `INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm. 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 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: >- `INVOICE_NOT_FOUND` — No invoice with this ID was issued by the organization. `DEAL_NOT_FOUND` — The invoice has a scheduled PIX payment to cancel, but its deal no longer exists. 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: - INVOICE_NOT_FOUND - DEAL_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: INVOICE_NOT_FOUND origin: BILLING message: invoice not found '422': description: >- `BAD_REQUEST` — `description` is missing or empty, 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: - 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: BAD_REQUEST origin: BILLING message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: description message: 'Invalid input: expected string, received undefined' code: DESCRIPTION_REQUIRED ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.