Ramp Integration Reference Architecture

Overview

Separate trust and failure domains: credential broker, typed adapter, event ingress, durable work ledger, financial connectors, reconciliation, and evidence. Keep write authority narrower than read and observability paths.

Prerequisites

• Identify the Ramp application, environment, business entities, affected data and workflows, accountable owner, and rollback boundary.
• Read references/official-docs.md and re-check endpoint schemas, scopes, limits, and support status before a live operation.
• Use synthetic fixtures or Ramp sandbox until production access and business effects are explicitly approved.
• Prepare approved secret storage and a sanitized evidence location.

Current Contract

• Ramp supports direct Developer API, webhooks, MCP, and CLI surfaces for different automation jobs; long-lived deterministic integrations belong on the Developer API.
• Webhook events are notifications and may be duplicated or out of order; fetch current resource state before acting when needed.
• OAuth grant, scope, principal, entity, and object policy jointly determine authority.
• Accounting and card workflows have distinct approval, idempotency, sensitive-data, and reconciliation requirements.