Ramp Sandbox Contract Tests and CI Gates

Overview

Separate fast deterministic contract checks from credentialed sandbox smoke tests. CI should reject schema drift and unsafe production targeting without making financial writes or depending on mutable live data.

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 publishes a canonical OpenAPI document for the Developer API and machine-readable guide exports for current behavior.
• The sandbox is isolated from production and cannot move real money; its current API host is https://demo-api.ramp.com.
• Credentialed checks still require the minimum OAuth scopes, and production credentials do not belong in pull-request jobs.
• Unknown fields may be ignored by some endpoints and rejected by others, so request fixtures must be validated against the exact endpoint schema.

Instructions

1. Pin a reviewed copy or checksum of the official OpenAPI document and generate schema fixtures from only the endpoints the integration uses.

1. Run unit tests with sanitized success, validation, authorization, rate-limit, timeout, and pagination fixtures; assert secret redaction and idempotency behavior.

1. Add a drift job that compares the pinned contract with the current official document and produces a human-reviewed change report instead of silently regenerating clients.

1. Gate credentialed sandbox smoke tests behind trusted branches and protected secrets; prove the resolved host is demo-api.ramp.com before any request.

1. Publish the exact commit, contract checksum, deterministic results, optional sandbox result, and production-block assertion as release evidence.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

…

Ramp API Error Triage

Overview

Turn a failing request into a sanitized, reproducible diagnosis. Separate permanent request or authority failures from transient service conditions before retrying anything.

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 returns standard HTTP status codes and may include error_v2.error_code, additional_info, and a user-facing message.
• Every API response includes x-trace-id; preserve it for correlation and support without logging authorization or sensitive payloads.
• 401 indicates a missing, expired, or invalid token; 403 indicates a valid token without sufficient scope or resource authority.
• 429 and 5xx may be retried with bounded exponential backoff; 504 means the request crossed Ramp's 60-second timeout.

Instructions

1. Capture method, sanitized URL, status, response class, x-trace-id, attempt count, environment, grant type, and requested scope without recording secrets or raw sensitive bodies.

1. Validate the request against the current endpoint schema, including required and nested fields; never rely on an unknown field being ignored.

1. For 401, refresh or reacquire the appropriate token once. For 403, compare configured scopes, token-bound scopes, app grant, user role, entity access, and endpoint authority.

1. For 429, 5xx, or 504, retry only idempotent reads or writes protected by an idempotency key, using bounded exponential backoff and jitter.

1. Reproduce in sandbox with the smallest sanitized request, preserve the trace ID and outcome, and escalate persistent vendor-side failures with the evidence bundle.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval…

Ramp Fund-Backed Virtual Card Workflow

Overview

Create the spend authority first, then issue or expose the card through the supported delivery surface. Prefer Ramp's embedded iframe when a person needs to see card details; use the Vault API only for an approved server-side payment flow.

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

• Current virtual cards are backed by Funds and governed by spend controls; legacy Cards management endpoints are being deprecated.
• Embedded Cards sends card details directly from a Ramp-hosted iframe to the user's browser, keeping the application server out of the card-data plane.
• The Vault API returns PAN, CVV, and expiration to a backend and requires Ramp production approval plus materially stronger PCI controls.
• New embedded integrations use the business-specific iframe URL and an exactly matching, verified HTTPS parent origin.

Authentication

Use a server-side Ramp OAuth bearer token from the selected environment with only the required Funds, Virtual Cards, or Embedded Cards scopes. Never send the bearer token to browser code; the backend mints the short-lived embed token. Vault access also requires its documented scopes and Ramp production approval.

Instructions

1. Record the cardholder or service purpose, business entity, owner, amount and interval, eligible spend, expiration, approval path, and termination trigger.

1. Choose embedded iframe or Vault delivery and document why the lower-exposure option is insufficient if selecting Vault.

1. In sandbox, create the required Fund or spend-control object with a unique idempotency key, then capture the returned card identifier without card details.

1. For embedded delivery, verify the exact parent origin and mint short-lived embed tokens on demand from the backend; never expose the Ramp access token to the browser.

1. Exercise suspension or fund termination, reconcile final state through a read, and preserve the approval, object IDs, idempotency keys, and rollback result.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect th…

Ramp-to-ERP Accounting Sync

Overview

Mirror ERP coding structures into Ramp, pull only eligible objects, post them once to the ERP, and send explicit success or failure receipts back to Ramp. Preserve entity boundaries and an auditable idempotency ledger.

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

• An API accounting connection is distinct from Ramp's direct ERP integrations; direct connections are blocked from API sync marking by default.
• Sync-ready filters differ by object type. Transactions and several objects use sync_status=SYNC_READY; bills use sync_ready=true.
• POST /developer/v1/accounting/syncs accepts an idempotency key, sync type, and explicit successful or failed object receipts.
• Multi-entity reads must be scoped with entity_id, and Ramp IDs used for accounting selections differ from ERP remote IDs.

Instructions

1. Inventory entities, object types, chart fields, remote IDs, tax/vendor relationships, direct integrations, owners, and the reconciliation period.

1. Push or update chart-of-accounts structures in bounded validated batches; retain Ramp IDs and ERP remote IDs in a typed mapping table.

1. Fetch each eligible object type with its documented ready-to-sync filter and paginate completely within one entity at a time.

1. Post to the ERP using a stable source-object key, then record the ERP reference and only afterward submit the Ramp success receipt; submit structured failure receipts for rejected objects.

1. Reconcile counts, amounts, currencies, line splits, entities, and status in both systems; quarantine mismatches and repeat reconciliation after any retry.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner ap…

Ramp Integration Cost and Workload Tuning

Overview

Cost tuning is a correctness exercise: remove redundant retrieval, not evidence. Establish a complete baseline, shift change detection to webhooks where supported, and preserve periodic reconciliation for missed or non-evented changes.

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 recommends persisting an initial full sync locally and fetching new or changed records incrementally where endpoint semantics support it.
• Incremental filters are endpoint-specific; for example, transaction synced_after covers accounting sync events, not every transaction update.
• Webhooks reduce polling but do not remove the need for idempotent consumption and periodic reconciliation.
• Batch and page limits are endpoint-specific and must be read from the current schema before tuning.

Instructions

1. Measure requests, pages, transferred bytes, retries, storage growth, reconciliation lag, webhook volume, and operator toil by endpoint and entity.

1. Classify each poll as initial seed, supported incremental read, unsupported change detection, recovery reconciliation, or waste.

1. Replace eligible near-real-time polling with scoped webhooks and a durable deduplicating queue; retain scheduled reconciliation for gaps.

1. Use maximum safe page sizes, endpoint filters with verified semantics, bounded concurrency, conditional local reads, and batch operations where documented.

1. Compare pre/post completeness, latency, error rate, API demand, infrastructure cost, and recovery time before accepting the change.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Data and accounting owners approve any freshn…

Ramp Financial Data Handling Controls

Overview

Minimize the data plane before implementing controls. Keep card details outside application systems through Embedded Cards where possible, and treat transaction, receipt, user, and accounting data as sensitive business records.

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

• Embedded Cards can render card details in a Ramp-hosted iframe so the application server does not receive PAN or CVV.
• Vault API delivery places full card data in the backend data plane and requires Ramp production approval plus the operator's own PCI program.
• OAuth tokens are opaque credentials and must never appear in logs, errors, analytics, or support artifacts.
• Monetary representations and sensitive fields vary by endpoint; use the current schema rather than a universal record assumption.

Instructions

1. Build a field-level inventory for each endpoint, event, queue, database, log, metric, export, backup, and support path, with owner and business purpose.

1. Classify credentials, card data, identity data, receipts, merchant details, accounting codes, and derived analytics; remove fields without a necessary purpose.

1. Choose embedded iframe delivery unless an approved backend Vault use case requires card data; isolate any Vault service and prohibit general telemetry.

1. Apply encryption, least-privilege service and human access, tenant/entity partitioning, redaction, retention, deletion, backup, and legal-hold controls.

1. Test forbidden-field detection, access denial, tenant separation, deletion propagation, backup expiry, and incident escalation with synthetic sandbox data.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Bounda…

Sanitized Ramp Support Bundle

Overview

Create an evidence package that Ramp support and internal responders can use without exposing credentials, card details, receipts, or unnecessary employee and financial data.

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 responses include x-trace-id, the preferred correlation handle for developer support.
• API error bodies may include error_v2.error_code, additional information, and a message.
• Webhook and deferred-task incidents need delivery/task identifiers and lifecycle state, not copied secrets or full payloads.
• Authorization failures require environment, grant, and scope metadata, but never the bearer token or client secret.

Instructions

1. Open a restricted case directory and record incident window, environment, affected endpoint or event, expected behavior, owner, and data-handling classification.

1. Capture UTC timestamps, method, sanitized path template, status, x-trace-id, error code, attempt count, latency, idempotency key hash, and application release.

1. Add a minimized schema-valid reproducer using placeholders and sandbox IDs; record grant type and scope names without credential values.

1. For webhooks or deferred tasks, include subscription/event/task identifiers, deduplication outcome, state transitions, and sanitized response metadata.

1. Run a secret/card/identity scan, obtain the data owner's sharing approval, generate checksums, and transmit only through the approved support channel.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

The incident owner approves scope; security/data owners approve external sharing. Never upload raw …

Ramp Integration Deployment and Rollout

Overview

Promote the exact tested artifact, not an unreviewed configuration. Resolve environment and credential provenance before startup, begin with bounded reads, and gate all writes behind explicit business approval and reconciliation.

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

• Sandbox and production are separate Ramp environments with different hosts, credentials, tokens, and data.
• OAuth tokens are bound to scopes and environment; a passing sandbox test does not authorize production.
• Webhook consumers must be externally reachable and idempotent, while accounting writers need durable downstream receipts.
• The OpenAPI schema and current guide exports are the contract inputs for release validation.

Instructions

1. Freeze the candidate artifact, dependency lock, OpenAPI checksum, configuration schema, data migration, scopes, event subscriptions, and rollback artifact.

1. Validate secrets are references to the target environment's approved store; reject demo hosts in production and production hosts in sandbox.

1. Deploy dark with outbound writes disabled, prove health, token acquisition, sanitized tracing, queue durability, and one minimum-scope read.

1. Canary one entity, event type, or bounded accounting cohort; reconcile object counts, amounts, duplicates, lag, and errors before expansion.

1. Enable approved writes gradually, monitor rollback thresholds, then preserve artifact digest, config digest, approvers, canary evidence, and final reconciliation.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Service and security owners approve artifact, configuration, and secrets. Finance/data o…

Ramp Enterprise Authority and Scope Review

Overview

Ramp API authority is layered. Build an effective-access matrix rather than treating an OAuth scope as the whole permission decision, and verify both allowed and denied operations per business entity.

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

• Client Credentials represents an internal backend acting with application authority; Authorization Code represents an authorizing user and is required for third-party multi-tenant apps.
• Tokens are scope-bound and environment-bound, and scopes cannot be expanded after issuance.
• Only appropriately privileged users, typically Admin or Business Owner, can authorize Developer API applications.
• Resource behavior also depends on business entity, user role, object ownership, spend controls, and endpoint-specific permissions.

Instructions

1. Inventory applications, environments, grant types, redirect URIs, client owners, scopes, authorizing or service principals, entities, subscriptions, and credential rotation.

1. Map each business operation to exact endpoint, HTTP verb, scope, entity, role, spend approval, data class, and accountable owner.

1. Remove unused scopes and stale clients, then issue new tokens because existing tokens do not acquire changed scopes.

1. Run positive tests for intended reads/writes and negative tests across an ungranted endpoint, entity, role, and environment using sandbox or approved production reads.

1. Schedule recertification and immediate review on owner departure, role change, integration expansion, credential incident, or new entity onboarding.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Business owners approve a…

Ramp Read-Only Connectivity Proof

Overview

Prove the smallest useful path: obtain a token without exposing it, call the current Developer API transaction surface with minimum scope, inspect the response envelope, and record a sanitized environment receipt.

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

• The current Developer API path is /developer/v1; the production host is api.ramp.com and the sandbox host is demo-api.ramp.com.
• The quickstart obtains a token from /developer/v1/token and reads transactions with transactions:read.
• List responses use a data collection and page metadata; callers must follow the documented cursor rather than assume one page is complete.
• Most Ramp monetary values are integers in the smallest unit of the accompanying currency, subject to the endpoint schema.

Authentication

Acquire a server-side OAuth bearer token from /developer/v1/token using the approved grant and minimum transactions:read scope. Keep the client secret and token out of source, browser code, logs, and evidence.

Instructions

1. Resolve the target environment, app owner, grant type, transactions:read scope, and approved secret-store references.

1. Acquire the token using the current authorization flow; retain only expiry, scope names, environment, and a one-way token-instance identifier.

1. Request the smallest documented transaction page from /developer/v1/transactions, with no write scope and no production query wider than approved.

1. Validate status, content type, data, page metadata, transaction IDs, amount representation, currency, and x-trace-id; redact people and merchant details.

1. Test one denial using an ungranted operation or sandbox-only client, then save the sanitized pass/fail receipt and next cursor behavior.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use …

Ramp Integration Incident Runbook

Overview

Protect financial correctness before throughput. Stop unsafe writes, preserve cursors and idempotency state, determine the blast radius by entity and object, and recover through controlled reconciliation.

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 errors expose status, structured error information, and x-trace-id for correlation.
• Webhook delivery and polling can overlap, so recovery must be idempotent and reconcile objects rather than replay blindly.
• 429 and 5xx may be transient; 504 crosses Ramp's 60-second request timeout and leaves write outcomes potentially ambiguous.
• Accounting success is not complete until the downstream ERP receipt and Ramp sync receipt agree.

Instructions

1. Declare severity and owners; freeze deploys, credential changes, cursor advancement, and affected writes while leaving safe reads and evidence capture available.

1. Bound impact by environment, entity, endpoint/event, release, time window, object IDs, amounts, queue depth, webhook lag, and downstream system.

1. Classify vendor, auth, permission, schema, rate, timeout, data, or deployment cause using sanitized trace IDs and exact artifact/config changes.

1. Contain by disabling only the unsafe writer or subscription path; reconcile ambiguous writes and deferred tasks before retries.

1. Recover a bounded cohort with original idempotency keys, compare source and destination totals, then expand gradually and complete post-incident credential/evidence cleanup.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

The incident commander controls containment and recovery. Finance approves financial re…

Ramp OAuth Application and Authentication Setup

Overview

Choose the grant from the trust model. Use Client Credentials for an internal server-to-server integration; use Authorization Code with state and refresh handling for a third-party or multi-tenant application.

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's token endpoint is /developer/v1/token, typically using HTTP Basic authentication for the client.
• Client Credentials tokens last 10 days; Authorization Code and refresh-token access tokens last one hour according to the current authorization guide.
• Authorization Code is required for third-party integrations acting for other businesses; its authorization code is short-lived and redirect URI matching is exact.
• Tokens are opaque, environment-bound, and scope-bound; changing configured scopes requires a new token.

Instructions

1. Identify internal versus third-party architecture, target environments, tenants, redirect origins, required operations, data classes, and accountable application owner.

1. Register separate sandbox and production applications; enable only the selected grant and minimum endpoint scopes.

1. Store client secrets and refresh tokens in an approved secret manager, record rotation/revocation ownership, and prohibit browser or repository exposure.

1. For Authorization Code, generate and verify cryptographically random state and exact HTTPS redirect URIs; for Client Credentials, keep token exchange server-side.

1. Acquire a sandbox token, verify one minimum-scope read plus one denied operation, then document the independently approved production promotion.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Bound…

Ramp Sandbox Development Loop

Overview

Keep the default loop deterministic and offline, then use Ramp sandbox for the smallest behavior that needs vendor execution. Make environment resolution visible and fail closed before any local write can reach production.

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 sandbox uses https://demo.ramp.com for the UI and https://demo-api.ramp.com for Developer API calls.
• Sandbox has no real money movement and supports demo actions for creating transactions and advancing selected bill or reimbursement states.
• Sandbox permissions still affect demo actions and API behavior.
• The official OpenAPI document provides request and response schemas for local fixtures and contract checks.

Instructions

1. Create a typed environment resolver with explicit sandbox default, an allowlist of Ramp hosts, and a hard production-write interlock.

1. Generate minimal sanitized fixtures from the reviewed OpenAPI contract for success, empty page, pagination, error, webhook duplicate, and ambiguous-write cases.

1. Run unit and contract tests offline; assert no credential, card detail, receipt, or personal field enters snapshots or logs.

1. Use a sandbox account and demo actions to create only the lifecycle state under test; record object IDs and reset/cleanup ownership.

1. Compare sandbox observations with fixtures, update only after review, and save the contract checksum and exact test artifact.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Developers may use approved sandbox data and credentials. Any production read, production credential, real business data, or write requires s…

Legacy Expense Platform to Ramp Migration

Overview

Treat the migration as a sequence of independently reconciled cohorts, not a bulk import. Map business meaning before identifiers, keep legacy and Ramp authority explicit during coexistence, and retire the old platform only after financial close.

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 users, entities, funds, cards, transactions, bills, reimbursements, vendors, and accounting objects have distinct relationships and endpoint contracts.
• Current virtual-card authority is fund-backed and governed through spend controls; legacy card abstractions should not be mapped one-to-one without review.
• Accounting connections distinguish Ramp identifiers from ERP remote identifiers and require explicit sync receipts.
• Webhook coverage and incremental filters vary by object, so migration reconciliation cannot depend on one universal change feed.

Instructions

1. Inventory legacy tenants/entities, users, roles, cards, limits, policies, vendors, open expenses, bills, reimbursements, receipts, accounting mappings, integrations, and retention duties.

1. Create a signed semantic mapping for each object and state, including unsupported values, money/currency conversion, ownership, destination ID, and disposition.

1. Build sandbox fixtures for normal, boundary, duplicate, missing-owner, invalid-currency, closed-period, and rollback cases; validate against current Ramp schemas.

1. Migrate one entity or department cohort, run parallel read/reconciliation, and hold card or accounting writes until users, controls, balances, and mappings are approved.

1. Cut over with frozen checkpoints and named authority, reconcile open and late-arriving items through financial close, then revoke legacy access under retention policy.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a boun…

Ramp Sandbox and Production Isolation

Overview

Make environment selection a typed security boundary. Keep credentials and data from crossing it, verify resolved hosts before token exchange, and require an explicit interlock before production writes.

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 sandbox uses demo.ramp.com and demo-api.ramp.com; production uses app.ramp.com and api.ramp.com.
• Tokens are valid only in the environment where issued, and sandbox and production applications have independent credentials and settings.
• Production Embedded Cards origins must be exact verified HTTPS origins; localhost is not accepted for production integrations.
• Sandbox cannot move real money, but its successful behavior does not prove production authorization or data equivalence.

Instructions

1. Define a closed environment enum with host, application ID, secret references, redirect URIs, parent origins, webhook endpoints, entity allowlists, and write policy.

1. Create separate Ramp applications and secret-manager namespaces; prohibit a configuration from carrying credentials or webhook secrets across environments.

1. Validate host allowlists, TLS, redirect/origin exactness, and token environment before each startup; print only non-secret environment identity.

1. Run synthetic and sandbox tests, then promote the same artifact and reviewed configuration schema without copying sandbox data or credentials.

1. Require a time-bound production-write enablement with owner, entity, operation, rollback, and automatic fail-closed behavior.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Security owns…

Ramp Integration Observability

Overview

Monitor both transport health and business completeness. A low error rate is insufficient if events are missing, objects remain unsynced, or duplicate financial effects occur.

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 returns x-trace-id on API responses for request correlation.
• Webhook deliveries carry a stable event ID across retries and may arrive out of order.
• Deferred operations have task state that must be polled or reconciled rather than inferred from request acceptance.
• Accounting correctness requires agreement among Ramp source state, downstream references, and Ramp sync receipts.

Instructions

1. Define service objectives for request success and latency, webhook receive/processing lag, queue age, deferred-task age, sync completeness, duplicate suppression, and reconciliation freshness.

1. Emit method plus path template, status class, environment, entity surrogate, trace ID, attempt, latency, page count, event type, event-ID hash, and release without sensitive values.

1. Track business-state gauges for unsynced and failed objects, unmatched ERP references, webhook reconciliation gaps, suspended workers, and production-write interlock state.

1. Alert on sustained symptom and business impact with a runbook link, owner, environment, affected entity/object class, and safe diagnostic query.

1. Test dashboards and alerts with sandbox events and fault injection; verify telemetry redaction, cardinality bounds, retention, and incident usefulness.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Service owners approve SLOs and alerts; security/privacy approve telemetry fields …

Ramp API Throughput and Sync Performance

Overview

Measure first, then tune by endpoint and object lifecycle. Maximize useful work per request while staying below shared limits and keeping checkpoints at durable commit boundaries.

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's default rate limit is 200 requests per rolling 10-second window per source IP, subject to current documentation and approved increases.
• API requests exceeding 60 seconds return 504; pagination and smaller work units are the primary controls for large reads.
• Most list endpoints support cursor-style pagination, but page sizes and incremental filters are endpoint-specific.
• Accounting batch endpoints may have explicit item caps and all-or-nothing behavior; current schema controls each batch.

Instructions

1. Benchmark request latency, response bytes, records per page, pages per entity, retries, 429/504 rate, queue lag, database time, and reconciliation duration.

1. Separate initial full seed, incremental reads, webhook-driven fetches, periodic reconciliation, writes, and deferred tasks into independent budgets.

1. Increase page size only within the endpoint schema, bound concurrency below the shared IP window, add jitter, and persist after each downstream commit.

1. Use webhooks to trigger targeted reads, batch only where documented, and poll deferred tasks with bounded schedules rather than holding API requests open.

1. Load-test with synthetic or sandbox data, compare p50/p95/p99 plus completeness, then canary and retain rollback thresholds.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Platform owners approve capacity and concurrency; data/accounting o…

Ramp Production Readiness Gate

Overview

Convert launch assumptions into evidenced gates. Review the exact artifact, environment, OAuth authority, data handling, endpoint contracts, reconciliation, incident controls, and rollback before any production write.

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

• Production is isolated from sandbox and requires its own Ramp application, credentials, scopes, redirects, subscriptions, and approved business access.
• Third-party integrations use Authorization Code; internal server integrations may use Client Credentials.
• Card, accounting, bill, reimbursement, and other writes create business effects that need endpoint-specific idempotency and reconciliation.
• Current OpenAPI and guide exports may supersede copied examples or generated client assumptions.

Instructions

1. Freeze the exact artifact, dependency lock, configuration digest, schema checksum, target entities, operations, scopes, event types, data classes, and owners.

1. Prove production host/application/secret provenance, minimum authority, credential rotation, negative access, and no sandbox fallback.

1. Pass unit, contract, schema-drift, security, redaction, pagination, retry, idempotency, duplicate-event, deferred-task, and rollback tests.

1. Execute a read-only production inventory and reconcile expected entities and source objects; resolve every unexplained difference.

1. Obtain independent approvals, canary the smallest cohort with writes explicitly enabled, reconcile business effects, and record go/no-go plus rollback authority.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Application, security, privacy, business, and finance/accou…

Ramp Rate-Limit and Timeout Control

Overview

Coordinate all workers that share an egress IP, because independent per-process retries can amplify a rolling-window breach. Preserve idempotency and reconcile ambiguous writes before retry.

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 currently documents a default limit of 200 requests per rolling 10-second window per source IP.
• A 429 means pause and back off; immediate retries worsen contention.
• Requests taking longer than 60 seconds terminate with 504, so large reads should be paginated and work units reduced.
• Ramp recommends exponential backoff; actual throughput is lower than theoretical throughput and endpoint constraints still apply.

Instructions

1. Inventory all services, jobs, tenants, endpoints, and retry layers sharing each source IP; measure arrival rate, burst, latency, 429/504, and business priority.

1. Implement one shared rolling-window limiter below the documented ceiling, with reserved capacity for interactive or recovery traffic.

1. Use bounded exponential backoff with full jitter for 429, 5xx, and safe 504 cases; cap attempts and total elapsed time.

1. Retry reads freely within budget, but retry writes only with an endpoint-supported idempotency key and post-timeout reconciliation.

1. Reduce pages or query scope for 504s, canary concurrency changes, and request a vendor increase only with measured demand and completeness evidence.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Approval Boundaries

Platform owners approve budgets and retry policy; business/finance owners approve write replay; Ramp must approve any limit increase.

Output

A shared-egress inventory, limit…

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.

Instructions

1. Define business capabilities, actors, tenants/entities, latency, volumes, data classes, financial effects, recovery objectives, and prohibited actions.

1. Partition separate OAuth applications and services for read-only ingestion, event receipt, accounting writes, and card/spend authority where trust differs.

1. Place an allowlisted typed adapter behind secret-managed token acquisition; centralize rate budget, pagination, error parsing, trace IDs, and schema-version evidence.

1. Ingest verified webhooks into a durable deduplicating queue, process asynchronously, and reconcile current API state plus downstream effects on a schedule.

1. Design deployment, observability, incident isolation, data retention, negative-access tests, and rollback; threat-model every path that can spend, sync, or expose card data.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp operation or replace owner approval.

Typed Ramp API Client Patterns

Overview

Generate or handcraft only the surface the application needs. Wrap transport concerns once, expose business-safe methods, and keep the official OpenAPI checksum next to the generated or reviewed client.

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 publishes an OpenAPI schema and plain-text current documentation; client code must track the exact reviewed contract.
• The API base uses /developer/v1; token acquisition, resource paths, and special surfaces such as Vault may use distinct hosts or controls.
• List pagination, monetary values, errors, idempotency, and deferred tasks are endpoint-specific.
• Unknown fields are not uniformly handled, so outgoing requests need schema validation.

Authentication

Centralize the approved OAuth grant and server-side bearer-token lifecycle in the adapter. Cache tokens only in protected memory or an approved secret mechanism, refresh before expiry, and bind every client instance to one explicit Ramp environment and minimum scope set.

Instructions

1. Inventory required endpoint/verb/scope pairs and select the smallest generated or handwritten client surface.

1. Centralize environment allowlists, token caching before expiry, redacted headers, timeouts, shared rate budget, trace-ID capture, and structured error_v2 parsing.

1. Implement reusable cursor iteration that yields committed pages and preserves empty-page, continuation, cancellation, and resume behavior.

1. Require typed integer monetary values with currency, endpoint-specific idempotency keys for writes, and explicit deferred-task or reconciliation results.

1. Pin the OpenAPI checksum, test success and failure fixtures, and produce a reviewed diff before regenerating or exposing new operations.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit …

Ramp Integration Security Baseline

Overview

Protect credentials and financial authority as separate assets. Minimize scopes and data paths, verify webhook authenticity from raw bytes, and require idempotent, approved, reconciled writes.

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 access tokens are opaque bearer credentials bound to environment and scope; they must not be logged or exposed to browser code.
• Webhook subscriptions return a secret and deliveries include X-Ramp-Signature, an HMAC-SHA256 signature over the exact raw request body.
• Embedded Cards can keep PAN/CVV outside application servers; Vault brings card data into the backend and requires production approval.
• Authorization Code flows require strong state verification and exact redirect URIs; Client Credentials is for internal server-side integrations.

Instructions

1. Threat-model clients, redirects, token exchange, secret stores, API adapters, webhook ingress, queues, logs, card delivery, accounting writes, admin access, and support paths.

1. Split applications by trust boundary, request minimum scopes, isolate environments and tenants/entities, and assign rotation plus emergency revocation owners.

1. Verify webhook signatures over raw bytes before parsing, validate expected event type and business, deduplicate by event ID, and process asynchronously.

1. Prefer embedded card delivery; isolate any approved Vault service and prohibit PAN/CVV from logs, queues, analytics, support tools, and general databases.

1. Test stolen-token containment, replay, cross-tenant/entity denial, redirect/state failure, secret rotation, webhook-secret rotation, and financial-write reconciliation.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools do not authorize a Ramp o…

Ramp API Contract Upgrade

Overview

Treat documentation or schema drift as a migration. Diff the exact contracts, map affected business behavior and stored data, then canary a reviewed artifact without silently changing scopes or writes.

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 publishes a changelog, OpenAPI schema, guide exports, and API reference; each may reveal a different class of impact.
• Legacy Cards endpoints are being deprecated for virtual-card management in favor of Funds and Cards (Virtual).
• Adding configured scopes does not update an existing token; new tokens are required.
• Unknown fields may be accepted or rejected by endpoint, so compatibility must be tested against the current schema.

Authentication

Preserve the approved OAuth grant and minimum scopes while comparing contracts. If required scopes change, configure them through review, issue a new environment-bound bearer token, revoke superseded credentials, and repeat positive and negative authority tests.

Instructions

1. Freeze old and new OpenAPI checksums, relevant guide/changelog snapshots, client version, endpoint manifest, scopes, stored schemas, and exact deployed artifact.

1. Diff paths, verbs, request/response fields, enums, requiredness, pagination, money units, errors, limits, deprecations, and authorization.

1. Classify each consumer and stored record as compatible, adapter-needed, backfill-needed, behavior-changed, scope-changed, or blocked.

1. Update a narrow adapter and fixtures, issue new minimum-scope tokens if required, and run old/new sandbox tests plus rollback compatibility.

1. Deploy dark, canary one bounded cohort, reconcile results and business effects, then expand or roll back with preserved checkpoints.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a know…

Ramp Webhook Verification and Processing

Overview

Verify authenticity before parsing, acknowledge only after durable receipt, and treat each event as a notification to reconcile current resource state. Design for retries, duplicates, and out-of-order delivery.

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

• New subscriptions begin pending_verification; Ramp sends a challenge that must be returned and submitted to activate the subscription.
• Business deliveries include X-Ramp-Webhook-ID and X-Ramp-Signature; the latter is HMAC-SHA256 of the exact raw request body using the subscription secret.
• Receivers must respond within 10 seconds. Ramp retries 429, 5xx, timeouts, and connection errors up to 10 total attempts with exponential backoff and jitter.
• The same event ID is reused across retries, and events may arrive out of order.

Instructions

1. Select only documented event types and underlying read scopes; register an HTTPS endpoint and store the returned webhook secret in an approved secret manager.

1. Complete the challenge flow and record subscription ID, state, business, events, scopes, endpoint, secret version, and owner without logging the secret.

1. Capture exact raw bytes, verify X-Ramp-Signature with constant-time comparison, validate expected event/business, then deduplicate by stable event ID.

1. Durably enqueue the verified event before returning 2xx within 10 seconds; process asynchronously and fetch current resource state when business action needs full or ordered data.

1. Test duplicates, invalid signature, unknown event, out-of-order events, 429/5xx retry, secret rotation, queue failure, and scheduled API reconciliation.

Tool Discipline

• Use Glob to locate candidate code, manifests, fixtures, and evidence without widening scope.
• Use Grep to find relevant endpoints, fields, permissions, identifiers, errors, and stale assumptions.
• Use Read to inspect the smallest required local files and authoritative evidence.
• Use Write only for a new approved local draft, test, configuration, or evidence artifact.
• Use Edit only for a bounded approved change with a known rollback.
• Local file tools …