> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ramp Corporate Card Integration — Admin Guide

> This guide covers the setup and administration of the Ramp corporate card integration in Encore OS. The integration syncs card transactions from your Ramp acco…

## Overview

This guide covers the setup and administration of the Ramp corporate card integration in Encore OS. The integration syncs card transactions from your Ramp account for GL coding and financial reporting.

## Quick Reference

| I need to…                     | Pattern                                                         | Location                                                                       |
| ------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Enable Ramp integration        | Finance settings toggle + save                                  | [Setup → 1. Enable the Integration](#1-enable-the-integration)                 |
| Configure credentials          | App credentials in secure secrets storage                       | [Setup → 2. Configure Ramp API Credentials](#2-configure-ramp-api-credentials) |
| Grant Ramp permissions         | RBAC assignment for `fa.ramp.*` keys                            | [Permissions](#permissions)                                                    |
| Validate sync data persistence | `fa_ramp_connections` + `fa_card_transactions` integrity checks | [Database Tables](#database-tables)                                            |

## Decision Trees

### Connect vs reconnect

1. No org connection exists → use **Connect Ramp**.
2. Connection status `expired`/`error` → use **Reconnect**.
3. Connected but stale sync → run **Sync Now** and verify webhook/scheduler health.

## Pattern Library

* **Webhook verification pattern:** HMAC-SHA256 with timing-safe signature comparison.
* **Token storage pattern:** encrypted token columns scoped by `organization_id`.
* **Sync idempotency pattern:** unique key `(organization_id, ramp_transaction_id)` to prevent duplicates.

## Common Mistakes

| Mistake                       | Impact                                         | Fix                                               |
| ----------------------------- | ---------------------------------------------- | ------------------------------------------------- |
| Missing `RAMP_WEBHOOK_SECRET` | Webhook events rejected or unsafe verification | Configure secret and validate signature checks    |
| Ignoring token expiry states  | Sync failures after credential expiration      | Monitor connection status and reconnect promptly  |
| Not honoring API rate limits  | Sync throttling/timeouts                       | Use bounded retries and backoff for 429 responses |

## Pre-Flight Checklist

* [ ] App credentials and webhook secret configured.
* [ ] Webhook endpoint URL and events configured in Ramp portal.
* [ ] Required `fa.ramp.*` permissions assigned to intended roles.
* [ ] Initial sync tested and transaction upserts verified.

***

## Setup

### 1. Enable the Integration

1. Navigate to **Finance → Settings → Integrations**.
2. Toggle **Enable Ramp Integration** to ON.
3. Save settings.

### 2. Configure Ramp API Credentials

The following secrets must be configured in your Supabase project (Settings → Cloud → Secrets):

| Secret Name           | Description                                    |
| --------------------- | ---------------------------------------------- |
| `RAMP_CLIENT_ID`      | OAuth client ID from Ramp Developer Portal     |
| `RAMP_CLIENT_SECRET`  | OAuth client secret from Ramp Developer Portal |
| `RAMP_API_KEY`        | API key for direct API calls                   |
| `RAMP_WEBHOOK_SECRET` | HMAC signing secret for webhook verification   |

### 3. Connect Your Ramp Account

1. Navigate to **Finance → Corporate Card Transactions**.
2. Click **Connect Ramp** on the connection card.
3. Complete the OAuth authorization flow in the Ramp popup.
4. Upon success, the connection status changes to **Connected**.

### 4. Configure Webhook (Optional)

To receive real-time transaction updates:

1. In the Ramp Developer Portal, add a webhook endpoint:
   * **URL:** `https://<your-supabase-url>/functions/v1/ramp-webhook`
   * **Events:** `TRANSACTION_CREATED`, `TRANSACTION_UPDATED`
2. Copy the webhook signing secret to the `RAMP_WEBHOOK_SECRET` Supabase secret.

***

## Permissions

| Permission Key              | Description              | Default Roles              |
| --------------------------- | ------------------------ | -------------------------- |
| `fa.ramp.view_transactions` | View card transactions   | org\_admin, manager, staff |
| `fa.ramp.sync`              | Trigger transaction sync | org\_admin, manager        |
| `fa.ramp.connect`           | Connect/disconnect Ramp  | org\_admin                 |
| `fa.ramp.settings`          | Manage Ramp settings     | org\_admin                 |

All permissions are auto-granted to `org_admin` via the RBAC trigger.

***

## Database Tables

### `fa_ramp_connections`

Stores OAuth connection state per organization. One row per org (enforced by unique constraint on `organization_id`).

| Column                    | Description                                     |
| ------------------------- | ----------------------------------------------- |
| `status`                  | `connected`, `disconnected`, `expired`, `error` |
| `access_token_encrypted`  | Encrypted OAuth access token                    |
| `refresh_token_encrypted` | Encrypted OAuth refresh token                   |
| `last_synced_at`          | Timestamp of last successful sync               |

### `fa_card_transactions`

Stores synced Ramp transactions. Unique constraint on `(organization_id, ramp_transaction_id)` prevents duplicates.

***

## Security

* **Multi-tenant isolation:** RLS policies ensure organizations can only see their own data.
* **Token storage:** OAuth tokens are stored encrypted; never logged or returned to the client.
* **Webhook verification:** HMAC-SHA256 with timing-safe comparison prevents forged events.
* **Edge function auth:** All management endpoints require valid JWT + permission checks.

***

## Troubleshooting

| Issue                       | Resolution                                                   |
| --------------------------- | ------------------------------------------------------------ |
| Connection shows "Expired"  | Click **Reconnect** to re-authorize with Ramp                |
| Sync fails with timeout     | Ramp API rate limit (200 req/10s); retry after a few seconds |
| Webhook events not arriving | Verify webhook URL and secret in Ramp Developer Portal       |
| Missing transactions        | Click **Sync Now**; check date range filters                 |

***

## Architecture

```text theme={null}
User → CardTransactionsPage → useRampSync hook
  → supabase.functions.invoke('ramp-sync')
    → Edge Function: JWT auth + permission check
      → Ramp API (cursor-based pagination)
        → Upsert fa_card_transactions
```

For detailed technical documentation, see the FA-30 spec and integration doc.