Seev PlusDocs
Docs
On/Off-Ramp API

On/Off-Ramp API

Enable USDC ↔ GHS conversions in your app with the Ramp API. Let your users buy USDC with Mobile Money (on-ramp) or sell USDC for Mobile Money (off-ramp).

⬡ API product

Requires merchant activation and an API secret key

The Ramp API lets merchants integrate USDC ↔ GHS (Ghana Cedis) conversion into their own applications. Users can buy USDC with Mobile Money (on-ramp) or sell USDC for Mobile Money (off-ramp) through a simple REST API.

Ramp API access requires merchant activation by SeevCash. Contact support to enable on/off-ramp for your account.

Supported corridors

DirectionUser paysUser receivesPayment method
On-rampGHS (Mobile Money)USDC (Stellar)MTN, Vodafone, AirtelTigo
Off-rampUSDC (Stellar)GHS (Mobile Money)MTN, Vodafone, AirtelTigo

How it works

On-ramp (GHS → USDC)

Your App          Ramp API            User              Stellar
   │                 │                  │                  │
   │── KYC ─────────▶│                  │                  │
   │◀── verified ────│                  │                  │
   │                 │                  │                  │
   │── create order ▶│                  │                  │
   │◀── reference ───│                  │                  │
   │                 │── MoMo prompt ──▶│                  │
   │                 │◀── approves ─────│                  │
   │                 │                  │                  │
   │                 │── send USDC ─────────────────────▶ │
   │◀── completed ───│                  │                  │
  1. KYC — Verify the user's phone number via OTP (one-time setup)
  2. Create order — Specify amount, user details, and destination Stellar wallet
  3. Collect — API sends a Mobile Money prompt to the user's phone
  4. Settle — Once fiat is confirmed, USDC is sent to the user's Stellar wallet

Off-ramp (USDC → GHS)

Your App          Ramp API            User              Stellar
   │                 │                  │                  │
   │── create order ▶│                  │                  │
   │◀── merchant     │                  │                  │
   │   address ──────│                  │                  │
   │                 │                  │                  │
   │── user sends USDC ────────────────────────────────▶ │
   │                 │                  │                  │
   │── confirm ─────▶│                  │                  │
   │                 │── MoMo payout ──▶│                  │
   │◀── completed ───│                  │                  │
  1. Create order — Specify amount and user details
  2. Send USDC — User sends USDC to the merchant's Stellar address (returned in the order)
  3. Confirm crypto — Call the confirm endpoint with the source wallet (tx is auto-detected)
  4. Payout — API disburses GHS to the user's Mobile Money

Authentication

All Ramp API requests require a secret API key in the Authorization header:

Authorization: Bearer sk_live_your_secret_key
EnvironmentBase URL
SandboxProvided during merchant activation
ProductionProvided during merchant activation

Your API base URL is provided when your merchant account is activated for ramp services. All examples below use https://api.your-domain.com as a placeholder.

Rate limits

The API is rate-limited to 100 requests per second per merchant. Exceeding the limit returns 429 Too Many Requests.

Order lifecycle

Every ramp order moves through a deterministic status lifecycle:

StatusMeaning
quote_lockedRate locked, waiting for payment initiation
fiat_pendingMoMo collection initiated, awaiting user approval (on-ramp)
crypto_pendingWaiting for user to send USDC (off-ramp)
fiat_confirmedFiat received, processing crypto send (on-ramp)
crypto_confirmedUSDC received, processing fiat payout (off-ramp)
crypto_sendingUSDC being sent on-chain (on-ramp)
fiat_sendingMoMo payout being sent (off-ramp)
completedOrder fully settled
expiredRate TTL elapsed before payment
cancelledOrder cancelled by merchant or user
failedUnrecoverable error (see failure_reason)

Integration steps

1. KYC Verification

Verify user phone numbers via OTP before their first transaction.

2. On-Ramp (Buy USDC)

Create orders for GHS → USDC conversions via Mobile Money.

3. Off-Ramp (Sell USDC)

Create orders for USDC → GHS conversions with MoMo payout.

4. Webhooks & Polling

Track order status via polling and handle completion events.

Quick start example

Here's a complete on-ramp flow in three API calls:

# 1. Verify user's phone (one-time)
curl -X POST https://api.your-domain.com/api/v1/ramp/kyc/initiate \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Kofi","last_name":"Mensah","phone":"0241234567","provider_name":"MTN"}'

# 2. Verify OTP (sent to user's phone)
curl -X POST https://api.your-domain.com/api/v1/ramp/kyc/verify \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kyc_id":"<kyc_id_from_step_1>","otp_code":"123456"}'

# 3. Create on-ramp order (GHS → USDC)
curl -X POST https://api.your-domain.com/api/v1/ramp/orders \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "onramp",
    "fiat_amount": 100,
    "destination_wallet": "GBUSER...STELLARADDRESS",
    "payment_method": "mobile_money",
    "user": {
      "first_name": "Kofi",
      "last_name": "Mensah",
      "phone": "0241234567",
      "network": "MTN"
    }
  }'

Limits

Default limits apply per merchant. Contact Seev support if your organization needs different limits:

LimitDefault
Minimum per transaction10 GHS
Maximum per transactionConfigured per merchant
Daily volumeConfigured per merchant
Monthly volumeConfigured per merchant
Minimum USDC1 USDC

On this page

Supported corridorsHow it worksOn-ramp (GHS → USDC)Off-ramp (USDC → GHS)AuthenticationRate limitsOrder lifecycleIntegration stepsQuick start exampleLimits