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.
Module: FA-30 | Last Updated: 2026-02-24 | Status: Stable
Overview
This guide covers the setup and administration of the Ramp corporate card integration in Encore Health 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 |
| Configure credentials | App credentials in secure secrets storage | Setup → 2. Configure Ramp API Credentials |
| Grant Ramp permissions | RBAC assignment for fa.ramp.* keys | Permissions |
| Validate sync data persistence | fa_ramp_connections + fa_card_transactions integrity checks | Database Tables |
Decision Trees
Connect vs reconnect
- No org connection exists → use Connect Ramp.
- Connection status
expired/error → use Reconnect.
- 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
Setup
1. Enable the Integration
- Navigate to Finance → Settings → Integrations.
- Toggle Enable Ramp Integration to ON.
- Save settings.
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
- Navigate to Finance → Corporate Card Transactions.
- Click Connect Ramp on the connection card.
- Complete the OAuth authorization flow in the Ramp popup.
- Upon success, the connection status changes to Connected.
To receive real-time transaction updates:
- In the Ramp Developer Portal, add a webhook endpoint:
- URL:
https://<your-supabase-url>/functions/v1/ramp-webhook
- Events:
TRANSACTION_CREATED, TRANSACTION_UPDATED
- 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 |
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
User → CardTransactionsPage → useRampSync hook
→ supabase.functions.invoke('ramp-sync')
→ Edge Function: JWT auth + permission check
→ Ramp API (cursor-based pagination)
→ Upsert fa_card_transactions
