> ## 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. # Charge the payer's wallet > Charges an invoice your organization issued from the payer's Portão 3 wallet. P2P must be enabled for your organization. The payer's wallet (in `debitParties`) is debited `txnAmount` or, without it, what the invoice still owes, and the money goes to your organization's account. The invoice must accept `P2P` (in its `allowedPaymentMethods` or as a secondary payment method of its deal), must not be paid or canceled, and the amount must be at least 1 centavo. One statement is recorded per payer: `PROCESSING` while the debit settles, `ERROR` when it is refused — the request then answers the error. The `BILLING_INVOICE_PAYMENT_CREATED` webhook event is sent. A request sent twice charges twice. Any member of the organization, or an admin of the realm, can charge it. `customer` is not used. Answers the `P2P_CREATED` statements. ## OpenAPI ````yaml /api-reference/billing.openapi.json post /realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/p2p-billing 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}/p2p-billing: post: tags: - Invoice Statements summary: Charge the payer's wallet description: >- Charges an invoice your organization issued from the payer's Portão 3 wallet. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdP2pBilling 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 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 charge. Format: `UUID` schema: type: string format: uuid example: 0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a requestBody: required: true content: application/json: schema: type: object properties: dueAt: minLength: 1 description: >- When the charge is due: today or later (ISO 8601 date or date-time). example: '2026-11-10' anyOf: - type: string format: date - type: string format: date-time expiresAt: minLength: 1 description: >- The last day the charge can be paid: at least one day after `dueAt` (ISO 8601 date or date-time). example: '2026-12-10' anyOf: - type: string format: date - type: string format: date-time txnAmount: description: >- The amount to charge, in centavos (at least 1). Omit it to charge what the invoice still owes. example: 15000 type: integer minimum: 1 customer: description: >- The payer printed on the boleto or the PIX charge. Each field sent replaces the invoice's payer data; the ones omitted keep it. Not used by `p2p-billing`. type: object properties: name: description: Name of the payer. example: Maria Silva type: string email: description: E-mail of the payer. example: maria.silva@exemplo.com.br type: string document: description: CPF or CNPJ of the payer, digits only. example: '11144477735' type: string address: description: >- Address of the payer. When sent, it replaces the whole stored address. type: object properties: street: type: string example: Rua das Flores number: type: string example: '123' complement: type: string example: Sala 4 neighborhood: type: string example: Centro city: type: string example: São Paulo state: type: string description: State abbreviation (UF). example: SP postalCode: type: string description: Postal code (CEP), as `NNNNN-NNN`. example: 01310-100 required: - dueAt - expiresAt responses: '201': description: Successful response content: application/json: schema: type: array items: 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: P2P_CREATED description: type: string description: >- Free text describing the movement. Empty when there is none. example: Boleto da fatura de outubro 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: PROCESSING 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-01T09: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-01T09:00:00.000Z' format: date-time updatedAt: type: string description: When the statement last changed, such as its status. example: '2026-10-08T14:32:11.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. `BILLING_P2P_NOT_ENABLED` — 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: >- `INVOICE_NOT_FOUND` — The organization issued no invoice with this ID. 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 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: >- `INVOICE_NOT_PAYABLE` — The invoice is paid or canceled. `INVOICE_PAYMENT_METHOD_NOT_ALLOWED` — `P2P` is neither one of the invoice's `allowedPaymentMethods` nor one of its deal's secondary payment methods. `INVOICE_NOTHING_TO_CHARGE` — No `txnAmount` was sent and the invoice owes nothing. `INVOICE_PAYER_WALLET_MISSING` — The invoice's payer has no Portão 3 wallet (`debitParties[].partyAccount.identifier`). `BAD_REQUEST` — The body is invalid — a `dueAt` in the past, an `expiresAt` not after `dueAt`, a `txnAmount` that is not a whole number of centavos of at least 1 — 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: - INVOICE_NOT_PAYABLE - INVOICE_PAYMENT_METHOD_NOT_ALLOWED - INVOICE_NOTHING_TO_CHARGE - INVOICE_PAYER_WALLET_MISSING - 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: INVOICE_NOT_PAYABLE origin: BILLING message: invoice is already paid or canceled ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.