On-ramp

The Tender on-ramp converts a fiat bank payment (e.g. NGN transfer) into cryptocurrency and delivers it to a wallet address on the customer’s chosen blockchain — all in a single integration.

How it works

Get a quote

Call POST /onramp/quote with the fiat amount and target cryptocurrency. Tender returns a live exchange rate, an estimated crypto output, and a quoteId that is valid for a short window (typically 60 seconds).

Initiate the on-ramp

Call POST /onramp/initiate with the quoteId, the customer’s wallet address, and their contact details. Tender creates a virtual bank account and returns the transfer details to show your customer.

Customer pays

Customer makes a local bank transfer to the virtual account. No crypto wallet or exchange account is needed on their side — just a standard bank transfer.

Tender processes automatically

Once payment is confirmed, Tender runs the pipeline automatically:

Forwards the fiat to the swap provider
Swaps fiat → intermediate crypto (USDT on Tron)
Delivers the final crypto to the targetAddress on the targetChain

Poll for completion

Call GET /onramp/{reference} to track progress. The stages object shows exactly where the pipeline is at any moment.

Pipeline stages

After payment is confirmed, the on-ramp moves through these stages in order:

Stage	What happens
`payment`	Fiat payment confirmed by the payment provider
`payout`	Fiat forwarded to the swap provider’s account
`swap`	Fiat swapped to intermediate crypto (e.g. USDT on Tron)
`swapWithdraw`	Swapped crypto withdrawn to Tender’s swap wallet (skipped by default)
`cryptoSend`	Crypto sent from Tender’s swap wallet to the customer’s `targetAddress`

Each stage has a status of pending, in_progress, completed, failed, or skipped.

Overall status values

Status	Meaning
`pending_payment`	Waiting for the customer’s bank transfer
`processing`	Payment confirmed; pipeline is running
`crypto_sent`	Crypto dispatched to `targetAddress`
`completed`	Fully settled
`failed`	Terminal failure — see `failureReason` and `stages[*].lastError`

Key concepts

Quotes are required and single-use

Before initiating, you must call /onramp/quote to lock in a rate. The returned quoteId is:

Time-limited — expires after time_to_lock seconds (shown as expiresAt)
Single-use — consumed the moment it is passed to /onramp/initiate

Attempting to initiate with an expired or already-used quote returns a 400 error.

Virtual bank accounts expire

The virtual bank account returned by /onramp/initiate expires after 1 hour. If the customer does not pay within that window, the on-ramp request moves to failed status.

Supported chains and currencies

Use the discovery endpoints to present your customers with what is available:

GET /onramp/chains — chains that support on-ramp delivery
GET /onramp/coins — cryptocurrencies available, optionally filtered by chain

Integration

This section walks through every step of a real on-ramp integration, from discovery to polling for completion. All examples use the sandbox environment.

Prerequisites

A Tender merchant account with API credentials
Your TENDER_ACCESS_ID and TENDER_ACCESS_SECRET set as environment variables

Authentication guide

Onramp endpoints use Signed (HMAC) authentication — an HMAC-SHA256 signature is required on every request. Follow the authentication guide for full details and code examples in Node.js, Python, and PHP before continuing.

The examples below assume you have a makeHeaders() helper and a BASE constant as described in that guide:

const BASE = 'https://sandbox-api.tender.cash/v1/api';
// makeHeaders() → { 'x-access-id', 'x-request-id', 'x-timestamp', 'authorization', ... }

Step 1 — Discover available chains and coins

Show your customers which blockchains and currencies they can receive.

// Fetch supported chains
const chainsRes = await fetch(`${BASE}/onramp/chains`, {
  headers: makeHeaders(),
});
const { data: chains } = await chainsRes.json();
// chains = [{ id: "tron", name: "Tron", icon: "...", ... }]

// Fetch supported coins (optionally filter by chain)
const coinsRes = await fetch(`${BASE}/onramp/coins?chain=tron`, {
  headers: makeHeaders(),
});
const { data: coins } = await coinsRes.json();
// coins = [{ id: "usdt", name: "Tether USD", symbol: "USDT", ... }]

import requests

chains_res = requests.get(f"{BASE}/onramp/chains", headers=make_headers())
chains = chains_res.json()["data"]

coins_res = requests.get(f"{BASE}/onramp/coins?chain=tron", headers=make_headers())
coins = coins_res.json()["data"]

Step 2 — Get a quote

Once the customer has chosen a target currency and entered their fiat amount, fetch a live quote.

const quoteRes = await fetch(`${BASE}/onramp/quote`, {
  method: 'POST',
  headers: makeHeaders(),
  body: JSON.stringify({
    fiatAmount:     50000,      // NGN, in whole units (not kobo)
    fiatCurrency:   'NGN',      // defaults to NGN if omitted
    targetCurrency: 'USDT',
    targetChain:    'tron',
  }),
});

const { data: quote } = await quoteRes.json();
console.log(quote);
/*
{
  quoteId:               "b7f2a1c3-9d4e-4b2f-a8c0-1e2d3f4a5b6c",
  fiatCurrency:          "NGN",
  fiatAmount:            50000,
  targetCurrency:        "USDT",
  targetChain:           "tron",
  rate:                  0.000597,
  estimatedCryptoAmount: "29.850000",
  expiresAt:             "2025-06-10T10:05:00.000Z"
}
*/

quote_res = requests.post(
    f"{BASE}/onramp/quote",
    headers=make_headers(),
    json={
        "fiatAmount":     50000,
        "fiatCurrency":   "NGN",
        "targetCurrency": "USDT",
        "targetChain":    "tron",
    },
)
quote = quote_res.json()["data"]

Quotes expire at expiresAt. Display a countdown and call /onramp/quote again if the customer lets it lapse before confirming.

Step 3 — Show the quote to your customer

Display the estimated output and ask for confirmation before initiating.

You pay:        ₦50,000 NGN
You receive:  ≈ 29.85 USDT
Network:         Tron (TRC-20)
Rate expires:    in 58 seconds

The estimated amount is based on the rate at quote time. The actual amount delivered may differ slightly if the quote expires and a fresh rate is applied internally.

Step 4 — Initiate the on-ramp

After the customer confirms, call /onramp/initiate with the quoteId and their wallet address.

const initiateRes = await fetch(`${BASE}/onramp/initiate`, {
  method: 'POST',
  headers: makeHeaders(),
  body: JSON.stringify({
    quoteId:       quote.quoteId,
    targetAddress: 'TRDFGhjkytywooiueonuoo',  // customer's USDT/Tron address
    customer: {
      email: 'customer@example.com',
      name:  'Ada Obi',
    },
    metadata: { orderId: 'ORD-9821' },  // your own reference, optional
  }),
});

const { data: onramp } = await initiateRes.json();
console.log(onramp);
/*
{
  reference:   "a3f1c2d4-8e7b-4f0a-9c1d-2e3f4a5b6c7d",
  status:      "pending_payment",
  bankTransfer: {
    accountNumber: "0123456789",
    accountName:   "Tender / Ada Obi",
    bankName:      "Wema Bank"
  },
  expiresAt: "2025-06-10T11:00:00.000Z",
  amount:    { value: 50000, currency: "NGN" }
}
*/

initiate_res = requests.post(
    f"{BASE}/onramp/initiate",
    headers=make_headers(),
    json={
        "quoteId":       quote["quoteId"],
        "targetAddress": "TRDFGhjkytywooiueonuoo",
        "customer": {
            "email": "customer@example.com",
            "name":  "Ada Obi",
        },
    },
)
onramp = initiate_res.json()["data"]
reference = onramp["reference"]

Error cases to handle:

Error message	Cause	Fix
`"Quote not found or already used"`	`quoteId` was already consumed or never existed	Fetch a fresh quote
`"Quote has expired"`	`expiresAt` passed before `/initiate` was called	Fetch a fresh quote
Joi validation error	`quoteId` missing, not a UUID, or `targetAddress` empty	Fix the request body

Step 5 — Display bank transfer details

Show the returned bankTransfer details so the customer knows where to send money.

Please transfer ₦50,000 to:

  Bank:           Wema Bank
  Account name:   Tender / Ada Obi
  Account number: 0123456789

  This account expires at 11:00 AM UTC.
  Do not send a different amount.

Store the reference — you will use it to poll for status.

Step 6 — Poll for completion

Poll GET /onramp/{reference} until status is crypto_sent or completed.

async function pollOnramp(reference, intervalMs = 10000) {
  while (true) {
    const res  = await fetch(`${BASE}/onramp/${reference}`, { headers: makeHeaders() });
    const { data } = await res.json();

    console.log(`Status: ${data.status}`, data.stages);

    if (data.status === 'crypto_sent' || data.status === 'completed') {
      console.log('On-ramp complete!');
      return data;
    }

    if (data.status === 'failed') {
      throw new Error(`On-ramp failed: ${data.failureReason}`);
    }

    await new Promise(r => setTimeout(r, intervalMs));
  }
}

const result = await pollOnramp(onramp.reference);

import time

def poll_onramp(reference, interval_s=10):
    while True:
        res  = requests.get(f"{BASE}/onramp/{reference}", headers=make_headers())
        data = res.json()["data"]

        print(f"Status: {data['status']}")

        if data["status"] in ("crypto_sent", "completed"):
            print("On-ramp complete!")
            return data

        if data["status"] == "failed":
            raise RuntimeError(f"On-ramp failed: {data.get('failureReason')}")

        time.sleep(interval_s)

result = poll_onramp(reference)

Rather than polling, configure a webhook to receive a notification when the status changes. See Webhooks for setup instructions.

Inspecting stage progress

The stages object in the status response shows the exact state of each pipeline step.

{
  "stages": {
    "payment":      { "status": "completed",   "completedAt": "2025-06-10T10:02:30Z" },
    "payout":       { "status": "completed",   "completedAt": "2025-06-10T10:03:10Z" },
    "swap":         { "status": "in_progress", "startedAt":   "2025-06-10T10:03:15Z", "attempts": 1 },
    "swapWithdraw": { "status": "skipped" },
    "cryptoSend":   { "status": "pending" }
  }
}

Error handling

Scenario	Recommended action
`status: "failed"`	Read `failureReason` and display it; offer the customer a retry
`status: "pending_payment"` after 1 hour	The virtual account expired; start a new on-ramp
Stage `status: "failed"`	Read `stages[*].lastError` for the provider-level reason
Network error polling	Retry with exponential backoff; the on-ramp reference is idempotent

Getting started

Online payments

Subwallets

Webhooks

How it works

Pipeline stages

Overall status values

Key concepts

Quotes are required and single-use

Virtual bank accounts expire

Supported chains and currencies

Integration

Prerequisites

Authentication guide

Step 1 — Discover available chains and coins

Step 2 — Get a quote

Step 3 — Show the quote to your customer

Step 4 — Initiate the on-ramp

Step 5 — Display bank transfer details

Step 6 — Poll for completion

Inspecting stage progress

Error handling

​How it works

​Pipeline stages

​Overall status values

​Key concepts

​Quotes are required and single-use

​Virtual bank accounts expire

​Supported chains and currencies

​Integration

​Prerequisites

Authentication guide

​Step 1 — Discover available chains and coins

​Step 2 — Get a quote

​Step 3 — Show the quote to your customer

​Step 4 — Initiate the on-ramp

​Step 5 — Display bank transfer details

​Step 6 — Poll for completion

​Inspecting stage progress

​Error handling

How it works

Pipeline stages

Overall status values

Key concepts

Quotes are required and single-use

Virtual bank accounts expire

Supported chains and currencies

Integration

Prerequisites

Step 1 — Discover available chains and coins

Step 2 — Get a quote

Step 3 — Show the quote to your customer

Step 4 — Initiate the on-ramp

Step 5 — Display bank transfer details

Step 6 — Poll for completion

Inspecting stage progress

Error handling