Ramp

Authentication Type: OAuth
Description: Create and manage virtual cards with customizable spend controls for payments, AI agents, and procurement workflows. Supports both production and sandbox environments.

Authentication

To authenticate with Ramp, you'll need to create an OAuth application:

1. Follow the Ramp Developer API Getting Started guide to create an OAuth application
2. You'll need to provide:
   • Client ID - From your Ramp OAuth application
   • Client Secret - From your Ramp OAuth application
   • Domain - Your Ramp organization domain

Required Scopes:

• users:read - Look up user information
• cards:read_vault - Access card details (PAN, CVV)
• limits:write - Create spending limits for cards
• limits:read - Read spending limit configurations

Users

Look up Ramp users by email or user ID.

Get User

Look up a Ramp user by email address or user ID to get their UUID for creating virtual cards.

Operation Type: Query (Read)

Parameters:

• email string (nullable): Email address of the user to look up
• userId string (nullable): Ramp user ID to look up

Returns:

• id string: Unique Ramp user ID (UUID)
• email string: User email address
• firstName string (nullable): User first name
• lastName string (nullable): User last name
• role string (nullable): User role in the organization

Example Usage:

{
  "email": "john.smith@company.com"
}

Virtual Cards

Create and manage virtual cards with spending limits and controls.

Create Virtual Card

Creates a new virtual card with customizable spending limits, merchant restrictions, and expiration dates. The card is generated instantly and can be used for payments.

Operation Type: Mutation (Write)

Parameters:

• userId string (required): The Ramp user ID who will own this virtual card
• displayName string (required): Display name for the virtual card (e.g., "Hotel Booking")
• spendingLimitAmount number (required): Spending limit amount in cents (e.g., 500000 for $5,000)
• spendingLimitCurrency string (nullable): Currency code for the spending limit (default: USD)
• spendingLimitInterval string (required): Spending limit interval: TOTAL, DAILY, WEEKLY, MONTHLY, QUARTERLY, or YEARLY. TOTAL means one-time use.
• allowedCategories array of numbers (nullable): Array of allowed merchant category codes (e.g., [18, 20] for travel). If not specified, all categories are allowed.
• expirationDate string (nullable): Optional expiration date in ISO 8601 format (YYYY-MM-DD). Card will auto-expire after this date.

Returns:

• cardId string: Unique identifier for the created card
• displayName string: Display name of the card
• cardNumber string (nullable): 16-digit card number (PAN) - requires PCI compliance
• cvv string (nullable): Card CVV - requires PCI compliance
• expirationMonth string (nullable): Card expiration month (MM)
• expirationYear string (nullable): Card expiration year (YYYY)
• spendingLimit object: Spending limit configuration
  • amount number: Spending limit in cents
  • currency string: Currency code
  • interval string: Spending interval
• status string: Card status (e.g., ACTIVE, SUSPENDED)

Example Usage:

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "AWS Infrastructure - Q1 2024",
  "spendingLimitAmount": 500000,
  "spendingLimitCurrency": "USD",
  "spendingLimitInterval": "MONTHLY",
  "allowedCategories": [18, 20],
  "expirationDate": "2024-12-31"
}

Common Use Cases

AI Agent Payments:

• Create virtual cards for AI agents to make autonomous payments with spending controls
• Set TOTAL spending limits for one-time agent purchases with automatic card expiration
• Restrict AI agent spending to specific merchant categories for security and compliance
• Generate instant virtual cards for agent workflows without manual approval processes

Vendor & Subscription Management:

• Create dedicated virtual cards for each SaaS subscription with MONTHLY spending limits
• Issue one-time use cards (TOTAL interval) for trial subscriptions and vendor evaluations
• Set expiration dates to automatically cancel unwanted subscriptions and free trials
• Track vendor spending by assigning unique cards to each service provider

Team Spend Controls:

• Issue virtual cards to team members with DAILY or WEEKLY spending limits
• Restrict cards to specific merchant categories (e.g., travel, office supplies)
• Look up user IDs by email to quickly provision cards for new team members
• Create cards with automatic expiration for temporary contractors and project-based work

Procurement Automation:

• Generate virtual cards programmatically for approved purchase requests
• Set spending limits that match exact purchase order amounts
• Use merchant category restrictions to enforce procurement policies
• Create audit trails by linking each card to a specific user and purpose