curl --request POST \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement \
--header 'Content-Type: application/json' \
--data '
{
"description": "Pagamento recebido em dinheiro na loja."
}
'import requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement"
payload = { "description": "Pagamento recebido em dinheiro na loja." }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({description: 'Pagamento recebido em dinheiro na loja.'})
};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Pagamento recebido em dinheiro na loja.'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement"
payload := strings.NewReader("{\n \"description\": \"Pagamento recebido em dinheiro na loja.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement")
.header("Content-Type", "application/json")
.body("{\n \"description\": \"Pagamento recebido em dinheiro na loja.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"description\": \"Pagamento recebido em dinheiro na loja.\"\n}"
response = http.request(request)
puts response.read_body{
"id": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f",
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"invoice": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a",
"identifier": "MANUAL_SETTLEMENT",
"description": "Pagamento recebido em dinheiro na loja.",
"billingAmount": 15000,
"originalAmount": 15000,
"financialImpactType": "CREDIT",
"status": "DONE",
"effectiveAt": "2026-10-25T12:00:00.000Z",
"createdBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"updatedBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"createdAt": "2026-10-25T12:00:00.000Z",
"updatedAt": "2026-10-25T12:00:00.000Z",
"paymentData": {
"pix": {
"emv": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD",
"dueAt": "2026-10-10T23:59:59.000Z"
},
"bankSlip": {
"digitableLine": "34191790010104351004791020150008291070026000",
"barcode": "34192910700260001790001043510047902015000829",
"dueAt": "2026-10-10T23:59:59.000Z",
"expiresAt": "2026-11-09T23:59:59.000Z"
},
"pixInitiation": {
"paymentUrl": "https://pix.example.com/authorize/9d4e1f6a",
"scheduledTo": "2026-10-10T12:00:00.000Z"
}
},
"external": {
"b3BankSlip": "6711b4c0d8e1a30012b7c9f2",
"b3Pix": "6711b4c0d8e1a30012b7c9f3",
"b3PixBillingInitiationRequest": "6711b4c0d8e1a30012b7c9f4",
"b3PixBillingInitiationRequestItem": "6711b4c0d8e1a30012b7c9f5"
},
"error": {
"code": "PAYMENT_REJECTED",
"detail": "Saldo insuficiente na conta do pagador.",
"description": "O pagamento foi recusado pela instituição do pagador."
}
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "BILLING",
"message": "insufficient permissions"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INVOICE_NOT_FOUND",
"origin": "BILLING",
"message": "invoice not found"
}{
"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"
}
]
}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.
curl --request POST \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement \
--header 'Content-Type: application/json' \
--data '
{
"description": "Pagamento recebido em dinheiro na loja."
}
'import requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement"
payload = { "description": "Pagamento recebido em dinheiro na loja." }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({description: 'Pagamento recebido em dinheiro na loja.'})
};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'description' => 'Pagamento recebido em dinheiro na loja.'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement"
payload := strings.NewReader("{\n \"description\": \"Pagamento recebido em dinheiro na loja.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement")
.header("Content-Type", "application/json")
.body("{\n \"description\": \"Pagamento recebido em dinheiro na loja.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/statements/settlement")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"description\": \"Pagamento recebido em dinheiro na loja.\"\n}"
response = http.request(request)
puts response.read_body{
"id": "9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f",
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"invoice": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a",
"identifier": "MANUAL_SETTLEMENT",
"description": "Pagamento recebido em dinheiro na loja.",
"billingAmount": 15000,
"originalAmount": 15000,
"financialImpactType": "CREDIT",
"status": "DONE",
"effectiveAt": "2026-10-25T12:00:00.000Z",
"createdBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"updatedBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"createdAt": "2026-10-25T12:00:00.000Z",
"updatedAt": "2026-10-25T12:00:00.000Z",
"paymentData": {
"pix": {
"emv": "00020101021226870014br.gov.bcb.pix2565qrcode.exemplo.com.br/pix/v2/9d4e1f6a5204000053039865406150.005802BR5913EMPRESA EXEMPLO6009SAO PAULO62070503***6304ABCD",
"dueAt": "2026-10-10T23:59:59.000Z"
},
"bankSlip": {
"digitableLine": "34191790010104351004791020150008291070026000",
"barcode": "34192910700260001790001043510047902015000829",
"dueAt": "2026-10-10T23:59:59.000Z",
"expiresAt": "2026-11-09T23:59:59.000Z"
},
"pixInitiation": {
"paymentUrl": "https://pix.example.com/authorize/9d4e1f6a",
"scheduledTo": "2026-10-10T12:00:00.000Z"
}
},
"external": {
"b3BankSlip": "6711b4c0d8e1a30012b7c9f2",
"b3Pix": "6711b4c0d8e1a30012b7c9f3",
"b3PixBillingInitiationRequest": "6711b4c0d8e1a30012b7c9f4",
"b3PixBillingInitiationRequestItem": "6711b4c0d8e1a30012b7c9f5"
},
"error": {
"code": "PAYMENT_REJECTED",
"detail": "Saldo insuficiente na conta do pagador.",
"description": "O pagamento foi recusado pela instituição do pagador."
}
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "BILLING",
"message": "insufficient permissions"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INVOICE_NOT_FOUND",
"origin": "BILLING",
"message": "invoice not found"
}{
"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"
}
]
}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.Path Parameters
ID of your realm.
Format: UUID
ID of the organization that issued the invoice.
Format: UUID
ID of the invoice to mark as paid.
Format: UUID
Body
Why the invoice is being marked as paid, such as how the payment was received. Stored on the settlement statement.
1"Pagamento recebido em dinheiro na loja."
Response
Successful response
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.
ID of the statement.
"9d4e1f6a-3b2c-4a5d-8e7f-1a2b3c4d5e6f"
ID of the realm of the organization that issued the invoice.
"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"
ID of the organization that issued the invoice.
"c4bd3f21-dfbd-44e8-8055-68ba15bed410"
ID of the invoice.
"0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a"
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.
"MANUAL_SETTLEMENT"
Free text describing the movement. Empty when there is none.
"Pagamento recebido em dinheiro na loja."
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.
15000
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.
15000
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.
CREDIT, DEBIT, NONE "CREDIT"
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.
CREATED, PROCESSING, SCHEDULED, PAID, CANCELED, DONE, ERROR, SCHEDULE_ERROR "DONE"
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.
"2026-10-25T12:00:00.000Z"
ID of who recorded the statement: the authenticated caller of the API that created it, or the Portão 3 service that wrote it.
"5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b"
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.
"5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b"
When the statement was recorded.
"2026-10-25T12:00:00.000Z"
When the statement last changed, such as its status.
"2026-10-25T12:00:00.000Z"
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.
Show child attributes
Show child attributes
IDs of the charge in the Banking service: on the same statements as paymentData.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes