> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nowramp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the key concepts and terminology in NowRamp.

# Core Concepts

This page explains the fundamental concepts in NowRamp.

## Multi-Tenancy Model

NowRamp uses a hierarchical multi-tenant architecture:

```mermaid theme={null}
graph TD
    Partner["Partner (Company)"]
    Project["Project (App/Environment)"]
    Customer["Customer (End User)"]

    Partner --> Project
    Project --> Customer
```

### 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:

```mermaid theme={null}
flowchart LR
    Supported["1. Get Supported"] --> Quotes["2. Get Quotes"]
    Quotes --> Checkout["3. Create Checkout"]
    Checkout --> Track["4. Track Transaction"]
```

<Steps>
  <Step title="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).
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Transaction Statuses

```mermaid theme={null}
stateDiagram-v2
    [*] --> pending: Checkout Created
    pending --> processing: Payment Received
    processing --> completed: Crypto Delivered

    pending --> cancelled: User Cancelled
    pending --> expired: Timed Out
    pending --> failed: Payment Failed
    processing --> failed: Transfer Failed
    processing --> refunded: Refund Issued

    completed --> [*]
    failed --> [*]
    cancelled --> [*]
    expired --> [*]
    refunded --> [*]
```

| Status       | Description                                                   |
| ------------ | ------------------------------------------------------------- |
| `pending`    | Checkout created, awaiting payment                            |
| `processing` | Payment received, processing crypto transfer                  |
| `completed`  | Crypto delivered to wallet                                    |
| `failed`     | Transaction failed (payment declined, compliance issue, etc.) |
| `cancelled`  | Cancelled by user or system                                   |
| `expired`    | Timed out before payment                                      |
| `refunded`   | Payment 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.

```mermaid theme={null}
flowchart TB
    subgraph NowRamp["NowRamp Platform"]
        API["Onramp API"]
        Aggregator["Aggregation Engine"]
        Health["Health Monitor"]
        GeoIP["GeoIP Detection"]
    end

    subgraph PaymentGateways["Payment Gateways"]
        GW1["Gateway A"]
        GW2["Gateway B"]
        GWN["Gateway ..."]
    end

    API --> Aggregator
    Aggregator --> PaymentGateways
    Health --> PaymentGateways
```

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:

| Feature                | Description                                 |
| ---------------------- | ------------------------------------------- |
| `supportsIframe`       | Checkout can be embedded in an iframe       |
| `supportsWidget`       | Provides a JavaScript widget for checkout   |
| `supportsBuy`          | Supports fiat-to-crypto (on-ramp)           |
| `supportsSell`         | Supports crypto-to-fiat (off-ramp)          |
| `kycHandledByProvider` | Identity verification is handled internally |

## Idempotency

The checkout intent endpoint supports idempotency keys to prevent duplicate orders:

```bash theme={null}
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](/guides/callback-urls) for setup instructions.