Skip to main content
POST
Charge the payer's 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.

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of your organization: the one that issued the invoice.

Format: UUID

​
invoiceId
string<uuid>
required

ID of the invoice to charge.

Format: UUID

Body

application/json
​
dueAt
required

When the charge is due: today or later (ISO 8601 date or date-time).

Minimum string length: 1
Example:

"2026-11-10"

​
expiresAt
required

The last day the charge can be paid: at least one day after dueAt (ISO 8601 date or date-time).

Minimum string length: 1
Example:

"2026-12-10"

​
txnAmount
integer

The amount to charge, in centavos (at least 1). Omit it to charge what the invoice still owes.

Required range: x >= 1
Example:

15000

​
customer
object

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.

Response

Successful response

​
id
string<uuid>
required

ID of the statement.

Example:

"9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f"

​
realm
string<uuid>
required

ID of the realm of the organization that issued the invoice.

Example:

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

​
organization
string<uuid>
required

ID of the organization that issued the invoice.

Example:

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

​
invoice
string<uuid>
required

ID of the invoice.

Example:

"0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a"

​
identifier
string
required

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
string
required

Free text describing the movement. Empty when there is none.

Example:

"Boleto da fatura de outubro"

​
billingAmount
integer
required

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
integer
required

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
enum<string>
required

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.

Available options:
CREDIT,
DEBIT,
NONE
Example:

"CREDIT"

​
status
enum<string>
required

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.

Available options:
CREATED,
PROCESSING,
SCHEDULED,
PAID,
CANCELED,
DONE,
ERROR,
SCHEDULE_ERROR
Example:

"PROCESSING"

​
effectiveAt
string<date-time>
required

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"

​
createdBy
string
required

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
string
required

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
string<date-time>
required

When the statement was recorded.

Example:

"2026-10-01T09:00:00.000Z"

​
updatedAt
string<date-time>
required

When the statement last changed, such as its status.

Example:

"2026-10-08T14:32:11.000Z"

​
paymentData
object

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
object

IDs of the charge in the Banking service: on the same statements as paymentData.

​
error
object | null

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.