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://api.corpxapi.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.

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.

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.
• 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.corpxapi.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.
• Replay: Use the POST /v1/webhooks/replay endpoint with eventId + tenantId to trigger a new delivery attempt.
• 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: support@corpxapi.com