How the platform is organized
The Portão 3 API is split into focused services. Each service has its own base URL:Authentication
Portão 3 APIs authenticate with JWT bearer tokens. Except for a few public endpoints (sign-in, health checks, hosted checkout pages), every request must carry a token obtained from the Identity service:POST /auth/sign-in with the client_id / client_secret pair of an API client issued by Portão 3, sent as HTTP Basic credentials. See the Quickstart for the full flow.
Tokens expire after a short period; when one does, sign in again to get a new one.
Transaction PIN
Some sensitive operations — confirming payments and transfers, viewing full card details, administering users — additionally require the authenticated user’s transaction PIN, sent in apin header alongside the bearer token. Requests to those endpoints without a valid PIN are rejected with 403.
Tenancy: realms and organizations
Your access is scoped to a realm (your tenant) and one or more organizations inside it. Most endpoints carry both in the path:realmId and organizationId during onboarding. Requests to a realm or organization your token is not entitled to are rejected with 403.
Environments
The base URLs above are production. A separate development environment is available for building and testing your integration before going live — each endpoint page in the API reference lists both servers, and your Portão 3 contact can provide development credentials. Data is fully isolated between environments.Errors
Most errors return a JSON body with this shape:traceId is present, include it when contacting support — it lets us locate the exact request.
Next steps
Quickstart
Authenticate and make your first API call in minutes.
API Reference
Browse every endpoint, grouped by service.