Cancel an invoice

curl --request POST \
  --url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel

const options = {method: 'POST'};

fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel', 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}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "id": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a",
  "realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "deal": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f",
  "previousInvoiceId": "",
  "dealName": "Mensalidade Plano Pro",
  "description": "Mensalidade Plano Pro - 1/12",
  "allowedPaymentMethods": [
    "PIX_AUTOMATIC"
  ],
  "invoiceNumber": 1,
  "closingAt": "2026-10-01T00:00:00.000Z",
  "dueAt": "2026-10-10T00:00:00.000Z",
  "expiresAt": "2026-11-10T00:00:00.000Z",
  "amount": 15000,
  "status": "CANCELED",
  "displayStatus": "CANCELED",
  "paymentStatus": "NONE",
  "paymentsAttempts": 0,
  "external": {
    "b3BankSlip": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b",
    "b3Pix": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d"
  },
  "debitParties": [
    {
      "partyAccount": {
        "name": "Maria Silva",
        "document": "11144477735",
        "email": "maria.silva@exemplo.com.br",
        "address": {
          "street": "Rua das Flores",
          "number": "123",
          "neighborhood": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "postalCode": "01310-100",
          "complement": "Sala 4"
        },
        "bank": "P3",
        "type": "WALLET",
        "identifier": {
          "realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
          "organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
          "account": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d",
          "wallet": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b"
        }
      },
      "unit": "PERCENTAGE",
      "amount": 100
    }
  ],
  "createdBy": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f",
  "updatedBy": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f",
  "createdAt": "2026-09-01T00:00:00.000Z",
  "updatedAt": "2026-09-01T00:00:00.000Z",
  "contract": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d",
  "paidAt": "2026-10-08T14:32:11.000Z",
  "fine": {
    "amountType": "PERCENT",
    "amount": 2
  },
  "interest": {
    "amountType": "PERCENT",
    "amount": 2
  },
  "discount": {
    "amountType": "PERCENT",
    "amount": 2
  },
  "creditParties": [
    {
      "partyAccount": {
        "name": "Empresa Exemplo Ltda",
        "bank": "P3",
        "type": "WALLET",
        "identifier": {
          "realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
          "organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
          "account": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d",
          "wallet": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b"
        },
        "document": "12345678000195",
        "email": "financeiro@empresaexemplo.com.br"
      },
      "unit": "PERCENTAGE",
      "amount": 100
    }
  ]
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "INVOICE_NOT_CLOSED",
  "origin": "BILLING",
  "message": "Only closed invoices can be canceled"
}

{
  "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": "PIX_AUTOMATIC_FIRST_PAYMENT_NOT_CANCELABLE",
  "origin": "BILLING",
  "message": "The first payment of a PIX Automático can only be canceled together with its consent. Cancel the deal instead."
}

POST

realms

{realmId}

organizations

{organizationId}

invoices

{invoiceId}

cancel

Cancel an invoice

curl --request POST \
  --url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel

const options = {method: 'POST'};

fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel', 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}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "id": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a",
  "realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "deal": "3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f",
  "previousInvoiceId": "",
  "dealName": "Mensalidade Plano Pro",
  "description": "Mensalidade Plano Pro - 1/12",
  "allowedPaymentMethods": [
    "PIX_AUTOMATIC"
  ],
  "invoiceNumber": 1,
  "closingAt": "2026-10-01T00:00:00.000Z",
  "dueAt": "2026-10-10T00:00:00.000Z",
  "expiresAt": "2026-11-10T00:00:00.000Z",
  "amount": 15000,
  "status": "CANCELED",
  "displayStatus": "CANCELED",
  "paymentStatus": "NONE",
  "paymentsAttempts": 0,
  "external": {
    "b3BankSlip": "4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b",
    "b3Pix": "6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d"
  },
  "debitParties": [
    {
      "partyAccount": {
        "name": "Maria Silva",
        "document": "11144477735",
        "email": "maria.silva@exemplo.com.br",
        "address": {
          "street": "Rua das Flores",
          "number": "123",
          "neighborhood": "Centro",
          "city": "São Paulo",
          "state": "SP",
          "postalCode": "01310-100",
          "complement": "Sala 4"
        },
        "bank": "P3",
        "type": "WALLET",
        "identifier": {
          "realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
          "organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
          "account": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d",
          "wallet": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b"
        }
      },
      "unit": "PERCENTAGE",
      "amount": 100
    }
  ],
  "createdBy": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f",
  "updatedBy": "BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f",
  "createdAt": "2026-09-01T00:00:00.000Z",
  "updatedAt": "2026-09-01T00:00:00.000Z",
  "contract": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d",
  "paidAt": "2026-10-08T14:32:11.000Z",
  "fine": {
    "amountType": "PERCENT",
    "amount": 2
  },
  "interest": {
    "amountType": "PERCENT",
    "amount": 2
  },
  "discount": {
    "amountType": "PERCENT",
    "amount": 2
  },
  "creditParties": [
    {
      "partyAccount": {
        "name": "Empresa Exemplo Ltda",
        "bank": "P3",
        "type": "WALLET",
        "identifier": {
          "realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
          "organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
          "account": "2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d",
          "wallet": "8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b"
        },
        "document": "12345678000195",
        "email": "financeiro@empresaexemplo.com.br"
      },
      "unit": "PERCENTAGE",
      "amount": 100
    }
  ]
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "INVOICE_NOT_CLOSED",
  "origin": "BILLING",
  "message": "Only closed invoices can be canceled"
}

{
  "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": "PIX_AUTOMATIC_FIRST_PAYMENT_NOT_CANCELABLE",
  "origin": "BILLING",
  "message": "The first payment of a PIX Automático can only be canceled together with its consent. Cancel the deal instead."
}

Only a CLOSED invoice — issued and not paid yet — can be canceled. A scheduled PIX payment of the invoice is canceled with it; for PIX Automático, once no invoice of the deal is left to pay, the payer’s authorization is released too. The first payment of a PIX Automático can only be canceled together with its authorization: cancel the deal instead. A boleto or PIX charge already issued for it is not canceled, and no webhook event is sent. Any member of the organization, or an admin of the realm, can cancel it. Answers the invoice as stored, now CANCELED.

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 cancel.

Format: UUID

Response

Successful response

An invoice.

string<uuid>

required

ID of the invoice.

Example:

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

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"

deal

string<uuid>

required

ID of the deal that generated the invoice. Read the deal with GET .../deals/{dealId}.

Example:

"3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f"

previousInvoiceId

string

required

Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.

Example:

""

dealName

string

required

The deal's description. Empty when the invoice has none.

Example:

"Mensalidade Plano Pro"

description

string

required

The invoice's name. Empty when it has none (show dealName instead).

Example:

"Mensalidade Plano Pro - 1/12"

allowedPaymentMethods

enum<string>[]

required

How the invoice can be paid: BANK_SLIP (boleto), PIX (PIX charge), PIX_AUTOMATIC (PIX Automático), PIX_INITIATION (recurring scheduled PIX) or P2P (a debit from the payer's Portão 3 account). The first one is the deal's main method.

Example: ["PIX_AUTOMATIC","PIX"]

Available options:

BANK_SLIP,

PIX_INITIATION,

PIX_AUTOMATIC,

PIX,

P2P

invoiceNumber

integer

required

The installment number, from 1.

Example:

1

closingAt

string<date-time>

required

When the invoice closes: it stops gathering charges and its payment is issued.

Example:

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

dueAt

string<date-time>

required

When the invoice is due.

Example:

"2026-10-10T00:00:00.000Z"

expiresAt

string<date-time>

required

The last day the invoice's charge can be paid.

Example:

"2026-11-10T00:00:00.000Z"

amount

integer

required

Amount of the invoice, in centavos (15000 is R$ 150,00): the sum of its charges.

Example:

15000

status

enum<string>

required

The stored status. OPEN: still gathering charges. CLOSED: issued and waiting for payment. PAID. CANCELED.

Available options:

OPEN,

CLOSED,

PAID,

CANCELED

Example:

"CANCELED"

displayStatus

enum<string>

required

The invoice's status as the Portão 3 app shows it, computed when you read it — the same rule on every invoice route. OPEN: still gathering charges. READY_TO_PAYMENT: issued, and less than a day past its due date. OVERDUE: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). PAID. CANCELED. Only for PIX Automático: READY_TO_SCHEDULE (the payment is not scheduled with the payer's bank yet), SCHEDULED (it will be charged on the due date), PAYMENT_FAILED (the due-date charge did not go through and is being retried, until 5 days after the due date), REVOKED (canceled because the payer revoked the authorization) and EXPIRED (canceled because the payer never authorized it).

Available options:

OPEN,

READY_TO_PAYMENT,

OVERDUE,

PAID,

CANCELED,

READY_TO_SCHEDULE,

SCHEDULED,

PAYMENT_FAILED,

REVOKED,

EXPIRED

Example:

"CANCELED"

paymentStatus

enum<string>

required

Progress of the automatic charge from the payer's Portão 3 account (P2P). NONE for every other invoice.

Available options:

NONE,

PENDING,

PROCESSING,

PROCESSED,

FAILED

Example:

"NONE"

paymentsAttempts

integer

required

How many times the automatic P2P charge was attempted.

Example:

0

external

object

required

IDs of the invoice's boleto and PIX charge, once created.

Show child attributes

debitParties

object[]

required

Who pays: one payer.

Show child attributes

createdBy

string

required

Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal.

Example:

"BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f"

updatedBy

string

required

Who last changed the invoice.

Example:

"BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f"

createdAt

string<date-time>

required

When the invoice was created.

Example:

"2026-09-01T00:00:00.000Z"

updatedAt

string<date-time>

required

When the invoice was created. It does not move when the invoice changes.

Example:

"2026-09-01T00:00:00.000Z"

contract

string<uuid>

ID of the invoice's contract. Absent on an invoice of a deal created without a contract.

Example:

"7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d"

paidAt

string<date-time>

When the invoice was paid. Absent until it is.

Example:

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

fine

object

Late fee charged after the due date, when the deal has one.

Show child attributes

interest

object

Interest charged after the due date, when the deal has it.

Show child attributes

discount

object

Discount for paying early, when the deal has one.

Show child attributes

creditParties

object[]

Who receives the money. Absent when you read the invoice as its payer (role=BUYER).

Show child attributes

Overview

Identity

Banking

Billing

Accounting

Registry

Platform

Notification

Rule Engine

Scheduling

Travel

Vehicles

Attachments

Cancel an invoice

Path Parameters

Response