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

StatusDescription
pendingCheckout created, awaiting payment
processingPayment received, processing crypto transfer
completedCrypto delivered to wallet
failedTransaction failed (payment declined, compliance issue, etc.)
cancelledCancelled by user or system
expiredTimed out before payment
refundedPayment refunded to customer

​
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:
FeatureDescription
supportsIframeCheckout can be embedded in an iframe
supportsWidgetProvides a JavaScript widget for checkout
supportsBuySupports fiat-to-crypto (on-ramp)
supportsSellSupports crypto-to-fiat (off-ramp)
kycHandledByProviderIdentity verification is handled internally

​
Idempotency

The checkout intent endpoint supports idempotency keys to prevent duplicate orders: 
curl -X POST https://api.nowramp.com/public/v1/onramp/checkout-intent \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout_user123_1705123456" \
  -d '{"projectId": "...", "gateway": "...", ...}'
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.