Skip to main content

​
Core Concepts

This page explains the fundamental concepts in NowRamp.

​
Multi-Tenancy Model

NowRamp uses a hierarchical multi-tenant architecture:

​
Partners

Partners are top-level tenants representing companies using the platform. Each partner has:
  • Unique identifier and branding
  • One or more projects
  • API key management
  • Webhook configurations

​
Projects

Projects are sub-tenants under partners, typically representing different applications or environments (staging, production). Projects have:
  • Isolated customer base
  • Custom gateway configurations
  • Specific currency and limit settings
  • Branding options

​
Customers

Customers are end users under a project. They’re identified by an externalCustomerId that you provide, allowing you to link them to users in your system.

​
Aggregator Flow

The onramp flow works in four steps:
1

Supported Configuration

Fetch available gateways, currencies, and payment methods for your project. Results are filtered by the user’s country (auto-detected via GeoIP or passed explicitly).
2

Quote Comparison

NowRamp fans out to all enabled gateways in parallel and returns ranked quotes — best rate, lowest fees, and fastest delivery. Quotes include fee breakdowns, estimated time, and KYC requirements.
3

Checkout Intent

The user selects a quote and provides a wallet address. NowRamp creates an order with the chosen gateway and returns a checkout URL (iframe or redirect).
4

Transaction Tracking

Poll the transaction endpoint or listen for webhooks. Statuses are normalized across all gateways into a consistent set: pending, processing, completed, failed, cancelled, expired, refunded.

​
Transaction Statuses

​
Provider Architecture

NowRamp aggregates multiple payment gateways and handles the complexity of different APIs, checkout methods, and status formats behind a unified interface. The aggregation engine handles:
  • Parallel quote fetching — requests fan out to all gateways simultaneously
  • Quote ranking — quotes are scored by rate, fees, speed, and reliability
  • Currency merging — combines supported currencies across all gateways into a single list
  • Health monitoring — tracks gateway availability and excludes unhealthy providers
  • GeoIP filtering — uses IP-to-country detection to show region-appropriate options
  • Status normalization — maps gateway-specific statuses to a unified set

​
Gateways

Each gateway has different capabilities. Use the features field from the supported config to adapt your UI:

​
Idempotency

The checkout intent endpoint supports idempotency keys to prevent duplicate orders:
Requests with the same idempotency key within 24 hours return the original response.

​
Webhooks

Transaction events are delivered to your configured webhook URL in real-time. Events include transaction.completed, transaction.failed, transaction.refunded, and more. Failed deliveries are retried with exponential backoff and moved to a dead-letter queue after exhausting retries. See the Callback URLs guide for setup instructions.