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 — this text is not that onboard.

Base URLs

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:

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.

Required Headers

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), including fee.occurredAt. 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.

Authorization Matrix

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

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

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, 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.
• 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. Receiving (QR Codes): Generate a dynamic QR code and check its status using the examples in examples.md.
3. Payment (Cashout): Perform a PIX out transfer using a test key.
4. Account Management: Check the balance and retrieve the statement of recent transactions.
5. PIX Keys: List, preview, and register PIX keys for the account holder.
6. Webhooks: Validate notification receipt and use replay when needed.
7. MED: List open infractions and disputes for your account.

Support & Contacts

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