List deals
curl --request GET \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/dealsimport requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/deals"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/deals', 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}/deals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$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}/deals"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/deals")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/deals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d",
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"chargeType": "RECURRENT",
"status": "OPEN",
"firstChargeDate": "2026-11-10T00:00:00.000Z",
"startAt": "2026-10-26T13:00:00.000Z",
"endAt": "2027-11-10T00:00:00.000Z",
"products": [
{
"id": "3c1d9a7e-2b4f-4e8a-9c6d-5f7e8a9b0c1d",
"identifier": "PLANO-PRO",
"price": 15000,
"type": "RECURRENT",
"chargeMethod": "LATER",
"description": "Plano Pro mensal",
"idProduct": "8f2e6d4c-1a3b-4c5d-9e8f-7a6b5c4d3e2f"
}
],
"paymentMethods": [
"BANK_SLIP"
],
"secondaryPaymentMethods": [],
"creditParties": [
{
"document": "12345678000195",
"unit": "PERCENTAGE",
"amount": 100,
"account": {
"bank": "P3",
"type": "WALLET",
"identifier": {
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"account": "6711b4c0d8e1a30012b7c9f1",
"wallet": "default"
}
},
"name": "Empresa Exemplo Ltda",
"email": "financeiro@empresaexemplo.com.br"
}
],
"debitParties": [
{
"document": "52998224725",
"name": "Maria da Silva",
"unit": "PERCENTAGE",
"amount": 100,
"email": "maria.silva@example.com",
"phone": "+5511987654321",
"account": {
"bank": "P3",
"type": "WALLET",
"identifier": {
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"account": "6711b4c0d8e1a30012b7c9f1",
"wallet": "default"
}
},
"address": {
"street": "Avenida Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"postalCode": "01310-100",
"complement": "Sala 12"
}
}
],
"closingAt": "0 0 5 * *",
"dueAt": "0 0 10 * *",
"createdBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"updatedBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"createdAt": "2026-10-26T13:00:00.000Z",
"updatedAt": "2026-10-26T13:00:00.000Z",
"installmentInfo": "3/12",
"totalAmount": 180000,
"description": "Mensalidade Plano Pro",
"contract": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d",
"numberOfInstallments": 12,
"settings": {
"createAllInvoicesOnStart": false,
"disableOpenStatus": false,
"invoiceNameType": "DEAL_DESCRIPTION",
"paymentLinkId": "5b8e2f1a-9c4d-4e7b-8a6f-3d2c1b0a9e8f",
"callBackUrlForPaymentProvider": {
"success": "https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/success",
"pending": "https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/pending",
"error": "https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/error"
}
},
"fine": {
"amountType": "PERCENT",
"amount": 2
},
"interest": {
"amountType": "PERCENT_POINT_PER_DAY_CALENDAR_DAYS",
"amount": 0.1
},
"discount": {
"amountType": "AMOUNT_PER_ANTECIPATION",
"amount": 500
},
"paymentUrl": "https://pix.example.com/authorize/9b2f7c1e",
"paymentLinkValidity": "2026-11-09T23:59:59.000Z",
"nextDueDate": "2027-02-10T00:00:00.000Z"
}
],
"next": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "BILLING",
"message": "insufficient permissions"
}{
"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": "chargeType",
"message": "Invalid option: expected one of \"SINGLE\"|\"RECURRENT\"|\"SUBSCRIPTION\"",
"code": "CHARGETYPE_ONE_OF"
}
]
}List deals
Lists the deals of your organization, newest first by default.
GET
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
deals
List deals
curl --request GET \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/dealsimport requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/deals"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/deals', 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}/deals",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$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}/deals"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/deals")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/deals")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d",
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"chargeType": "RECURRENT",
"status": "OPEN",
"firstChargeDate": "2026-11-10T00:00:00.000Z",
"startAt": "2026-10-26T13:00:00.000Z",
"endAt": "2027-11-10T00:00:00.000Z",
"products": [
{
"id": "3c1d9a7e-2b4f-4e8a-9c6d-5f7e8a9b0c1d",
"identifier": "PLANO-PRO",
"price": 15000,
"type": "RECURRENT",
"chargeMethod": "LATER",
"description": "Plano Pro mensal",
"idProduct": "8f2e6d4c-1a3b-4c5d-9e8f-7a6b5c4d3e2f"
}
],
"paymentMethods": [
"BANK_SLIP"
],
"secondaryPaymentMethods": [],
"creditParties": [
{
"document": "12345678000195",
"unit": "PERCENTAGE",
"amount": 100,
"account": {
"bank": "P3",
"type": "WALLET",
"identifier": {
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"account": "6711b4c0d8e1a30012b7c9f1",
"wallet": "default"
}
},
"name": "Empresa Exemplo Ltda",
"email": "financeiro@empresaexemplo.com.br"
}
],
"debitParties": [
{
"document": "52998224725",
"name": "Maria da Silva",
"unit": "PERCENTAGE",
"amount": 100,
"email": "maria.silva@example.com",
"phone": "+5511987654321",
"account": {
"bank": "P3",
"type": "WALLET",
"identifier": {
"realm": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"organization": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"account": "6711b4c0d8e1a30012b7c9f1",
"wallet": "default"
}
},
"address": {
"street": "Avenida Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"postalCode": "01310-100",
"complement": "Sala 12"
}
}
],
"closingAt": "0 0 5 * *",
"dueAt": "0 0 10 * *",
"createdBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"updatedBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"createdAt": "2026-10-26T13:00:00.000Z",
"updatedAt": "2026-10-26T13:00:00.000Z",
"installmentInfo": "3/12",
"totalAmount": 180000,
"description": "Mensalidade Plano Pro",
"contract": "7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d",
"numberOfInstallments": 12,
"settings": {
"createAllInvoicesOnStart": false,
"disableOpenStatus": false,
"invoiceNameType": "DEAL_DESCRIPTION",
"paymentLinkId": "5b8e2f1a-9c4d-4e7b-8a6f-3d2c1b0a9e8f",
"callBackUrlForPaymentProvider": {
"success": "https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/success",
"pending": "https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/pending",
"error": "https://checkout.portao3.com.br/:paymentLinkId/deals/:dealId/error"
}
},
"fine": {
"amountType": "PERCENT",
"amount": 2
},
"interest": {
"amountType": "PERCENT_POINT_PER_DAY_CALENDAR_DAYS",
"amount": 0.1
},
"discount": {
"amountType": "AMOUNT_PER_ANTECIPATION",
"amount": 500
},
"paymentUrl": "https://pix.example.com/authorize/9b2f7c1e",
"paymentLinkValidity": "2026-11-09T23:59:59.000Z",
"nextDueDate": "2027-02-10T00:00:00.000Z"
}
],
"next": "NjcxMWI0YzBkOGUxYTMwMDEyYjdjOWYy"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "BILLING",
"message": "insufficient permissions"
}{
"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": "chargeType",
"message": "Invalid option: expected one of \"SINGLE\"|\"RECURRENT\"|\"SUBSCRIPTION\"",
"code": "CHARGETYPE_ONE_OF"
}
]
}Each deal comes with its progress:
installmentInfo (paid invoices over installments), nextDueDate (the earliest invoice still to be paid) and totalAmount (what its invoices are expected to charge in total).
Filter by status, payer document (debitPartyDocuments, several at once), payer organization (debitPartyOrgIds, several at once: it matches the organization of the payer’s Portão 3 wallet, so a payer with no wallet is found by its document instead), charge type, number of installments, a text in the description, the start and end dates, and the creation date (startDate/endDate). Dates are read in UTC: a date without a time is its midnight. Sort with order and orderBy, and page with limit + next: pass the next of one page to get the following one — the last page answers next: null.
Any member of the organization, or an admin of the realm, can list them.Path Parameters
ID of your realm.
Format: UUID
ID of your organization: the one whose deals you list.
Format: UUID
Query Parameters
Only deals in these statuses.
Example (comma-separated list): ?status=OPEN,TERMINATED
Available options:
OPEN, CANCELED, TERMINATED, EXPIRED, REVOKED Only deals whose debit party has one of these documents (exact match).
Example (comma-separated list): ?debitPartyDocuments=11144477735,39053344705
Only deals whose payer (the debit party) pays from a Portão 3 wallet of one of these organizations. It matches the organization of the payer's wallet, so a payer with no wallet (a customer who pays by boleto or PIX, for example) is not found by it: filter by debitPartyDocuments instead.
Format: UUID
Example: ?debitPartyOrgIds=5e0a1c2b-3d4f-4a6b-8c9d-0e1f2a3b4c5d
Only deals with this charge type.
Available options:
SINGLE, RECURRENT, SUBSCRIPTION Only deals with exactly this number of installments.
Required range:
x >= 1Only deals whose description contains this text (case-insensitive).
Maximum string length:
250Only deals that start on or after this date (ISO 8601 date or date-time).
Only deals that end on or before this date (ISO 8601 date or date-time). Combines with endAtFrom and endAtTo: every bound you send applies.
Only deals that end on or after this date, inclusive (ISO 8601 date or date-time). Send endAtTo as well for a closed range.
Only deals that end on or before this date, inclusive (ISO 8601 date or date-time). Send endAtFrom as well for a closed range.
Only deals created on or after this date, inclusive (ISO 8601 date or date-time). Send endDate as well for a closed window.
Only deals created on or before this date, inclusive (ISO 8601 date or date-time). Send startDate as well for a closed window.
Sort direction. Case-insensitive.
Available options:
ASC, DESC Field to sort the deals by.
Available options:
createdAt, description, startAt Page size.
Required range:
1 <= x <= 1000Cursor returned as next by the previous page; it must be valid base64. Omit it for the first page. Use it with the same filters and order: a cursor that no longer matches a deal returns the first page.
Maximum string length:
128Pattern:
^[A-Za-z0-9+/]+={0,2}$