> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# BaaS tenant guide

Welcome to the CorpX **BaaS** API. This guide is for the tenant that operates on `https://tenant.api.corpx.com`. If you received a credential in internet banking, use the [Internet banking section](/ib/guias/comece-aqui/primeiros-passos) — this text is not that onboard.

## Base URLs

| Environment     | Base URL                       | Notes                                                                                                             |
| --------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `dev` (sandbox) | —                              | **Temporarily unavailable.** The sandbox environment will be restored soon. Contact support for more information. |
| `prd`           | `https://tenant.api.corpx.com` | Production, monitored 24/7                                                                                        |

The production URL and OAuth credentials are provided during onboarding. Replace the placeholders in the examples with the values assigned to your tenant.

## Authentication

Partners authenticate directly against our Identity Provider. Two flows are supported:

* **Client Credentials** – machine-to-machine integrations. Use the client id/secret issued by CorpX and request tokens at the token endpoint.
* **Authorization Code** – browser-based flows. CorpX provisions the redirect URIs and returns the authorization code to your application.

Include the access token in every call:

```http
Authorization: Bearer <access_token>
```

Tokens contain the tenant context and required roles, so no additional headers are needed for identification.

Each credential has **scopes** that bound the routes it can reach (and,
optionally, the accounts). If the credential lacks the route's scope, the answer
is `403 insufficient_scope` naming what is missing. Money-moving scopes
(`pix_out.create`, `ted.create`, `internal_transfer.create`,
`boleto_payment.create`, `refund.create`) are issued by CorpX; the
rest a tenant manager creates in the panel. See the
[Authentication Guide](/baas/guias/autenticacao/oauth2).

## Required Headers

| Header            | When                               | Description                                                                                                     |
| ----------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `X-Tenant-Id`     | On every call, except `/v1/health` | Identifies the tenant in multi-tenant workloads. Required by the API Gateway and WAF.                           |
| `Idempotency-Key` | All POST/PUT/PATCH operations      | Unique per request. The CorpX API stores the response for 24 hours and returns HTTP 409 if the payload differs. |
| `Content-Type`    | POST/PUT/PATCH                     | Always `application/json`.                                                                                      |

## Idempotency Behavior

* `Idempotency-Key` is required on mutable endpoints (`/v1/accounts/{accountId}/pix/out`, `/v1/accounts/{accountId}/pix/out/refund`, etc.).
* Keys expire after 24 hours.
* A second request with the same key and identical payload returns HTTP 200/202 with the cached body.
* A second request with the same key and different payload returns HTTP 409 `idempotency_conflict`.

## Date and time (UTC)

Date/time fields use **ISO 8601 / RFC 3339** and **always carry an explicit offset** — read the offset, don't assume. Two cases:

* **UTC (`Z`)** — webhooks (`occurredAt` and fields inside `data`) and the "our-side" timestamps in REST responses (`createdAt`, `updatedAt`, `completedAt`, `reconciledAt`, `fetchedAt`, balance, QR `createdAt`/`expiresAt`/`paidAt`).
* **São Paulo time (`-03:00`)** — the **transaction time** in the statement and transaction lookups: `timestamp` (statement / `/pix/transactions`) and `occurredAt` (`/pix/payments/lookup`, boleto). The `startDate`/`endDate` filter day is also BRT.

For **request** bodies that require an instant (e.g. `expirationDate` on dynamic QR), use RFC 3339 with an explicit offset (`Z` or offset). More detail: [Webhooks](/baas/guias/conta/webhooks).

## Authorization Matrix

The system evaluates the combination `(subject, action, resource, tenant)`. Actions exposed to partners:

| Resource Type    | Example Resource Key    | Actions                                                                                                                                                                   |
| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account`        | `account:123456`        | `read`, `pix_send`, `pix_qr_create`, `pix_qr_static_create`, `pix_qr_due_date_create`, `pix_qr_capture`, `pix_qr_cancel`, `pix_qr_read`, `pix_refund`, `pix_invoice_read` |
| `account_holder` | `account-holder:123456` | `pix_key_list`, `pix_key_preview`, `pix_key_create`, `pix_key_delete`, `internal_transfer_create`, `ted_transfer_create`                                                  |

Denied decisions return HTTP 403 `forbidden`. Contact CorpX support if you need new actions or roles.

`GET /v1/tenant/accounts` and `GET /v1/tenant/accounts/search` do not go through this matrix: they are tenant routes and require the credential scope `read`. The `read` in the table above is a different thing — it is the action on an account you already know.

## Error Catalog

All responses use the envelope documented in `errors.md`. Highlights:

* 400 `missing_headers` → missing or malformed header.
* 401 `invalid_signature` → webhook ingress HMAC failure.
* 409 `idempotency_conflict` → idempotency mismatch.
* 429 `rate_limit` → default burst of 100 rps, sustained 6,000 rph per tenant.
* 429 `partner_rate_limited` → the banking provider turned the call down for too many requests. Not a limit on your account nor on your quota; retry with exponential backoff.
* 429 `dict_lookup_limit_exceeded` → your account's PIX key lookup quota closed. Do not retry: find which window went over and read [PIX key lookups](/baas/guias/pagar/consulta-dict), which describes how the consumption is measured and monitored.
* 5xx `partner_error` → CorpX API unavailable or partner outage. We recommend implementing retries (up to three times) with exponential backoff.

## Integrator Portal

Use the Integrator Portal for administrative operations and monitoring:

* Link: `https://backoffice.api.corpx.com`
* Capabilities: dashboard with account data, available/locked/total balances, recent transactions and statement.
* PIX lookup bucket: your DICT consumption per account and per time window, and the lookups refused by a limit. See [PIX key lookups](/baas/guias/pagar/consulta-dict).
* Webhooks: configuration and maintenance of delivery URLs.

## Webhooks

### Available Events

* `GET /v1/webhooks/events` - List available event types

### Outbound (CorpX API → Tenant)

* Delivery headers: `X-Webhook-Event`, `X-Webhook-ID`, `X-Webhook-Tenant`, `Authorization`, `Idempotency-Key`.
* IP Whitelist: `34.138.140.223`, `34.138.161.100`, `35.231.250.193`, `35.196.71.29`, `34.138.56.192`.
* Retries: exponential backoff (up to 6 attempts) and DLQ for manual replay.
* Retry: Use `POST /v1/webhooks/{subscriptionId}/deliveries/{deliveryId}/retry` to resend a failed delivery.
* Supported authentication types: `HMAC` (signature in `X-Signature`) and `NONE`.

## Testing Checklist

1. **Authentication**: Request your production credentials and obtain your first OAuth2 token.
2. **Security**: Follow the [security recommendations](/baas/guias/autenticacao/recomendacoes-de-seguranca): user context on outgoing payments, IP allowlist and a credential with the smallest scope.
3. **Receiving (QR Codes)**: Generate a dynamic QR code and check its status using the examples in `examples.md`.
4. **Payment (Cashout)**: Perform a PIX `out` transfer using a test key.
5. **Account Management**: Check the balance and retrieve the statement of recent transactions.
6. **PIX Keys**: List, preview, and register PIX keys for the account holder.
7. **Webhooks**: Validate notification receipt and use replay when needed.
8. **MED**: List open infractions and disputes for your account.
9. **PIX status**: right after an async PIX `out`, call `GET /v1/accounts/{accountId}/pix/payments/lookup?identifier=...&waitForFinalStatus=10` and check that the response carries the final status, or the last status if the wait expires. Use an HTTP client timeout of at least 20 s.

## Support & Contacts

* **Slack:** Private channel per client — request access from the CorpX team during onboarding.
* **Email:** `api@corpx.com`