Ramp Corporate Card Integration — Admin Guide

​

Overview

​

Quick Reference

​

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

​

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

​

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)

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

​

Database Tables

​

fa_ramp_connections

​

fa_card_transactions

​

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

​

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