API Integration Guide

Welcome to the CorpX API. This guide was written for partner teams integrating with the /v1 APIs and webhooks. It complements the technical documentation and focuses on the information needed to start operating in production.

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:

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, med.decide) are issued by CorpX; the rest a tenant manager creates in the panel. See the Authentication Guide.

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 in DynamoDB 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), 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:

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.

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.
• 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.
• 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, API_KEY, BASIC, BEARER, IP_WHITELIST.

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