Onramp - Buy Cryptocurrency

Convert fiat currency to cryptocurrency using your virtual balance.

What is ONRAMP?

ONRAMP allows you to purchase cryptocurrency using fiat funds from your virtual account.

Supported cryptocurrencies:

USDC (USD Coin)
USDT (Tether)
ETH (Ethereum)
BTC (Bitcoin)
And more…

Deals vs Orders

Important: ONRAMP operations use the /deals endpoint, not /orders. A deal represents the intent to buy crypto and can be paid in full or partially. Each payment creates one or more orders that execute the purchase.

Key differences:

Deal: The crypto purchase intent (can be partially funded)
Order: The actual execution of the purchase (created automatically by the deal)
Partial payments: You can pay a deal in multiple installments for ONRAMP
Destination: Deals only need the destination wallet/account

Automatic Payment Execution

Balance Required: By default, you need sufficient balance in your virtual account to close an ONRAMP deal. ONRAMP payments execute automatically when there’s a credit to your currency balance.

How it works:

Create an ONRAMP deal for X amount of crypto
Deal requires Y fiat in your virtual account
When your virtual account receives funds (PAYIN, etc.), the deal automatically executes
Orders are created and crypto is purchased

Pre-approved Merchants:

Some merchants can operate deals without requiring upfront balance
This allows creating deals before funds are available
Contact Koywe to request pre-approval for this feature

Quick Example


// Buy USDC with COP
 
// 1. Get quote (network required!)
const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    type: 'ONRAMP',
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USDC',
    amountIn: 50000,  // 50,000 COP
    network: 'ETHEREUM'  // Required for crypto quotes
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Will receive:', quote.data.amountOut, 'USDC'); // e.g., 12.34 USDC
console.log('Network fee:', quote.data.networkFee, 'COP');
console.log('Quote valid for:', quote.data.validFor || '10-15', 'seconds');
 
// 2. Create deal (not order!)
const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    type: 'ONRAMP',
    destinationAccountId: 'wallet_abc123',  // Your crypto wallet
    quoteId: quote.data.id
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal created:', deal.data.id);
console.log('Deal will create orders automatically as it executes');
// Monitor deal.status: PENDING → PROCESSING → COMPLETED

Step-by-Step Integration

Step 1: Get Crypto Wallet

You need a wallet address to receive the cryptocurrency:


// Option 1: Get merchant's wallet
const wallet = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/wallet`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('USDC address:', wallet.data.addresses.USDC);

Step 2: Check Fiat Balance

Balance Required: Unless your merchant is pre-approved, you need sufficient balance to close the deal. The deal will execute automatically when funds are available.


const balances = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/accounts/balances`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
const copBalance = balances.data.find(b => b.currencySymbol === 'COP');
 
if (copBalance.availableBalance < 50000) {
  console.log('Insufficient balance. Deal will execute when funds arrive.');
  // For pre-approved merchants, you can continue
  // For others, you may need to wait for PAYIN to credit the account
}

Step 3: Get Quote


const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    type: 'ONRAMP',
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USDC',
    amountIn: 50000,
    network: 'ETHEREUM'  // Required for crypto quotes
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
// Display to user
console.log('Exchange rate:', quote.data.exchangeRate);
console.log('Will receive:', quote.data.amountOut, 'USDC');
console.log('Koywe fee:', quote.data.koyweFee, 'COP');
console.log('Network fee:', quote.data.networkFee, 'COP');
console.log('Total cost:', quote.data.amountIn + quote.data.koyweFee + quote.data.networkFee, 'COP');
console.log('Quote expires in:', quote.data.validFor || '10-15', 'seconds');

Step 4: Create Deal


const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    type: 'ONRAMP',
    destinationAccountId: wallet.data.addresses.USDC,  // Only need destination
    quoteId: quote.data.id,
    externalId: `onramp-${Date.now()}`
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal created:', deal.data.id);
console.log('Status:', deal.data.status); // "PENDING"
console.log('Deals can be paid in full or partially');

What happens next: The deal will automatically create orders as payments are processed. You can fund the deal in one payment or multiple partial payments.

Step 5: Monitor Deal and Orders


// Via webhooks (recommended)
app.post('/webhooks/koywe', (req, res) => {
  const event = JSON.parse(req.body);
  
  // Deal status updates
  if (event.type === 'deal.completed' && event.data.type === 'ONRAMP') {
    console.log('Deal completed!');
    console.log('Deal ID:', event.data.id);
  }
  
  // Orders created by the deal
  if (event.type === 'order.completed' && event.data.type === 'ONRAMP') {
    console.log('Crypto received!');
    console.log('Order ID:', event.data.id);
    console.log('Amount:', event.data.amountOut, event.data.destinationCurrencySymbol);
  }
  
  res.status(200).send('OK');
});


// Or poll deal status
async function checkDealStatus(dealId) {
  const deal = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals/${dealId}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  console.log('Deal status:', deal.data.status);
  console.log('Orders created:', deal.data.orders); // Array of order IDs
  
  return deal.data;
}

Supported Networks

Cryptocurrency	Networks
USDC	Ethereum, Polygon, BSC
USDT	Ethereum, Polygon, BSC, Tron
ETH	Ethereum
BTC	Bitcoin
MATIC	Polygon
BNB	BSC

Network Selection: Specify the network when creating the wallet address or using destination account.

Partial Payments (ONRAMP Only)

Unique to ONRAMP: Unlike OFFRAMP (which must be paid completely), ONRAMP deals can be paid in multiple partial payments. Each partial payment creates an order that purchases the corresponding amount of crypto.

How Partial Payments Work

Example: Partial Payment Deal


// Create a deal for 100 USDC
const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    type: 'ONRAMP',
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USDC',
    amountIn: 400000  // 400,000 COP for ~100 USDC
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
const deal = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
  {
    type: 'ONRAMP',
    destinationAccountId: 'wallet_abc123',
    quoteId: quote.data.id
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Deal created for 100 USDC');
console.log('You can now pay this deal in full or partially');
console.log('Each payment will create an order and purchase crypto proportionally');
 
// Payment 1: Pay 50% now (200,000 COP → ~50 USDC)
// Payment 2: Pay 50% later (200,000 COP → ~50 USDC)
// Result: 2 orders created, 100 USDC total received

Use Case: Partial payments are useful for:

Dollar-cost averaging (DCA) strategies
Staged purchases over time
Managing cash flow while building crypto position
Allowing customers to pay in installments

Complete Example


async function buyUSDC(amount) {
  try {
    const token = await authenticate();
    
    // 1. Check COP balance
    const balances = await getBalances(token, orgId, merchantId);
    const copBalance = balances.find(b => b.currencySymbol === 'COP');
    
    if (copBalance.availableBalance < amount) {
      throw new Error('Insufficient COP balance');
    }
    
    // 2. Get wallet address
    const wallet = await axios.get(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/wallet`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    // 3. Get quote
    const quote = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
      {
        type: 'ONRAMP',
        originCurrencySymbol: 'COP',
        destinationCurrencySymbol: 'USDC',
        amountIn: amount
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    console.log(`Converting ${amount} COP to ${quote.data.amountOut} USDC`);
    console.log(`Rate: 1 USDC = ${quote.data.exchangeRate} COP`);
    
    // 4. Create deal
    const deal = await axios.post(
      `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
      {
        destinationAccountId: wallet.data.addresses.USDC,
        quoteId: quote.data.id
      },
      { headers: { 'Authorization': `Bearer ${token}` } }
    );
    
    console.log('USDC purchase deal created:', deal.data.id);
    console.log('Deal will create orders as it executes');
    
    return deal.data;
    
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
    throw error;
  }
}
 
// Usage
await buyUSDC(50000); // Buy USDC with 50,000 COP

Next Steps

money-billOfframp - Sell Crypto

Sell cryptocurrency for fiat

🧾Orders & Types

Understanding crypto order types

🧪Testing

Test crypto operations in sandbox

📖API Reference

Complete API documentation