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

Node.js

1 // Buy USDC with COP
2 
3 // 1. Get quote (network required!)
4 const quote = await axios.post(
5   `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
6   {
7     type: 'ONRAMP',
8     originCurrencySymbol: 'COP',
9     destinationCurrencySymbol: 'USDC',
10     amountIn: 50000,  // 50,000 COP
11     network: 'ETHEREUM'  // Required for crypto quotes
12   },
13   { headers: { 'Authorization': `Bearer ${token}` } }
14 );
15 
16 console.log('Will receive:', quote.data.amountOut, 'USDC'); // e.g., 12.34 USDC
17 console.log('Network fee:', quote.data.networkFee, 'COP');
18 console.log('Quote valid for:', quote.data.validFor || '10-15', 'seconds');
19 
20 // 2. Create deal (not order!)
21 const deal = await axios.post(
22   `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
23   {
24     type: 'ONRAMP',
25     destinationAccountId: 'wallet_abc123',  // Your crypto wallet
26     quoteId: quote.data.id
27   },
28   { headers: { 'Authorization': `Bearer ${token}` } }
29 );
30 
31 console.log('Deal created:', deal.data.id);
32 console.log('Deal will create orders automatically as it executes');
33 // Monitor deal.status: PENDING → PROCESSING → COMPLETED

Step-by-Step Integration

Step 1: Get Crypto Wallet

You need a wallet address to receive the cryptocurrency:

Get Wallet

1 // Option 1: Get merchant's wallet
2 const wallet = await axios.get(
3   `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/wallet`,
4   { headers: { 'Authorization': `Bearer ${token}` } }
5 );
6 
7 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.

Check Balance

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

Step 3: Get Quote

Get Quote

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

Step 4: Create Deal

Create Deal

1 const deal = await axios.post(
2   `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
3   {
4     type: 'ONRAMP',
5     destinationAccountId: wallet.data.addresses.USDC,  // Only need destination
6     quoteId: quote.data.id,
7     externalId: `onramp-${Date.now()}`
8   },
9   { headers: { 'Authorization': `Bearer ${token}` } }
10 );
11 
12 console.log('Deal created:', deal.data.id);
13 console.log('Status:', deal.data.status); // "PENDING"
14 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

1 // Via webhooks (recommended)
2 app.post('/webhooks/koywe', (req, res) => {
3   const event = JSON.parse(req.body);
4   
5   // Deal status updates
6   if (event.type === 'deal.completed' && event.data.type === 'ONRAMP') {
7     console.log('Deal completed!');
8     console.log('Deal ID:', event.data.id);
9   }
10   
11   // Orders created by the deal
12   if (event.type === 'order.completed' && event.data.type === 'ONRAMP') {
13     console.log('Crypto received!');
14     console.log('Order ID:', event.data.id);
15     console.log('Amount:', event.data.amountOut, event.data.destinationCurrencySymbol);
16   }
17   
18   res.status(200).send('OK');
19 });

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

Node.js

1 // Create a deal for 100 USDC
2 const quote = await axios.post(
3   `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
4   {
5     type: 'ONRAMP',
6     originCurrencySymbol: 'COP',
7     destinationCurrencySymbol: 'USDC',
8     amountIn: 400000  // 400,000 COP for ~100 USDC
9   },
10   { headers: { 'Authorization': `Bearer ${token}` } }
11 );
12 
13 const deal = await axios.post(
14   `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
15   {
16     type: 'ONRAMP',
17     destinationAccountId: 'wallet_abc123',
18     quoteId: quote.data.id
19   },
20   { headers: { 'Authorization': `Bearer ${token}` } }
21 );
22 
23 console.log('Deal created for 100 USDC');
24 console.log('You can now pay this deal in full or partially');
25 console.log('Each payment will create an order and purchase crypto proportionally');
26 
27 // Payment 1: Pay 50% now (200,000 COP → ~50 USDC)
28 // Payment 2: Pay 50% later (200,000 COP → ~50 USDC)
29 // 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

Buy USDC

1 async function buyUSDC(amount) {
2   try {
3     const token = await authenticate();
4     
5     // 1. Check COP balance
6     const balances = await getBalances(token, orgId, merchantId);
7     const copBalance = balances.find(b => b.currencySymbol === 'COP');
8     
9     if (copBalance.availableBalance < amount) {
10       throw new Error('Insufficient COP balance');
11     }
12     
13     // 2. Get wallet address
14     const wallet = await axios.get(
15       `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/wallet`,
16       { headers: { 'Authorization': `Bearer ${token}` } }
17     );
18     
19     // 3. Get quote
20     const quote = await axios.post(
21       `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
22       {
23         type: 'ONRAMP',
24         originCurrencySymbol: 'COP',
25         destinationCurrencySymbol: 'USDC',
26         amountIn: amount
27       },
28       { headers: { 'Authorization': `Bearer ${token}` } }
29     );
30     
31     console.log(`Converting ${amount} COP to ${quote.data.amountOut} USDC`);
32     console.log(`Rate: 1 USDC = ${quote.data.exchangeRate} COP`);
33     
34     // 4. Create deal
35     const deal = await axios.post(
36       `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
37       {
38         destinationAccountId: wallet.data.addresses.USDC,
39         quoteId: quote.data.id
40       },
41       { headers: { 'Authorization': `Bearer ${token}` } }
42     );
43     
44     console.log('USDC purchase deal created:', deal.data.id);
45     console.log('Deal will create orders as it executes');
46     
47     return deal.data;
48     
49   } catch (error) {
50     console.error('Error:', error.response?.data || error.message);
51     throw error;
52   }
53 }
54 
55 // Usage
56 await buyUSDC(50000); // Buy USDC with 50,000 COP

Next Steps

Offramp - Sell Crypto

Sell cryptocurrency for fiat

Orders & Types

Understanding crypto order types

Testing

Test crypto operations in sandbox

API Reference

Complete API documentation