Orders & Order Types

[
  { "method": "KHIPU" }
]

[
  { "method": "PSE", "extra": { "bankAccount": { "name": "BANCOLOMBIA" } } }
]

{
  "type": "PAYIN",                              // Order type
  "originCurrencySymbol": "COP",                // Fiat currency
  "destinationCurrencySymbol": "COP",           // Same as origin
  "amountIn": 50000,                            // Amount to collect
  "description": "Payment for Order #12345",    // Customer-facing description
  "paymentMethods": [                                     // At least one payment method
    {
      "method": "PSE",                                    // Payment method code
      "extra": { "bankAccount": { "name": "BANCOLOMBIA" } } // Per-method extras
    }
  ],
  "successUrl": "https://yoursite.com/success", // Redirect after success
  "failedUrl": "https://yoursite.com/failed"    // Redirect after failure
}

{
  "contactId": "cnt_abc123",                    // Link to customer contact
  "externalId": "order-12345",                  // Your internal reference
  "metadata": { "orderId": "12345" },           // Custom data
  "dueDate": "2025-11-14T23:59:59Z"            // Payment deadline
}

async function createPayinOrder(token, orgId, merchantId) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'PAYIN',
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'COP',
      amountIn: 50000,
      description: 'Payment for Order #12345',
      externalId: `order-${Date.now()}`,
      paymentMethods: [
        {
          method: 'PSE',
          extra: { bankAccount: { name: 'BANCOLOMBIA' } }
        }
      ],
      successUrl: 'https://yoursite.com/success',
      failedUrl: 'https://yoursite.com/failed'
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
const order = await createPayinOrder(token, orgId, merchantId);
console.log('Payment URL:', order.paymentUrl);
// Redirect customer to order.paymentUrl

{
  "type": "PAYOUT",                              // Order type
  "originCurrencySymbol": "COP",                 // Fiat currency
  "destinationCurrencySymbol": "COP",            // Same as origin
  "amountIn": 100000,                            // Amount to send
  "destinationAccountId": "ba_xyz789",           // Provider's bank account ID
  "description": "Payment for Invoice #456"      // Internal description
}

{
  "contactId": "cnt_provider123",                // Link to provider contact
  "externalId": "invoice-456",                   // Your internal reference
  "metadata": { "invoiceId": "456" }            // Custom data
}

async function createPayoutOrder(token, orgId, merchantId, contactId, bankAccountId) {
  // 1. Check balance first
  const balances = await getMerchantBalances(token, orgId, merchantId);
  const copBalance = balances.find(b => b.currencySymbol === 'COP');
  
  if (copBalance.availableBalance < 100000) {
    throw new Error('Insufficient balance');
  }
  
  // 2. Create payout order
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'PAYOUT',
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'COP',
      amountIn: 100000,
      contactId: contactId,
      destinationAccountId: bankAccountId,
      description: 'Payment for Invoice #456',
      externalId: `invoice-456-${Date.now()}`
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
const payout = await createPayoutOrder(token, orgId, merchantId, 'cnt_provider', 'ba_xyz789');
console.log('Payout created:', payout.id);

{
  "type": "BALANCE_TRANSFER",                    // Order type
  "originCurrencySymbol": "COP",                 // Source currency
  "destinationCurrencySymbol": "USD",            // Target currency
  "amountIn": 1000000                            // Amount to convert (1M COP)
}

async function transferCurrency(token, orgId, merchantId) {
  // 1. Get quote for exchange rate
  const quote = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
    {
      type: 'BALANCE_TRANSFER',
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'USD',
      amountIn: 1000000
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  console.log('Exchange rate:', quote.data.exchangeRate);
  console.log('Will receive:', quote.data.amountOut, 'USD');
  
  // 2. Create transfer order — passing quoteId locks rate & amount, so omit
  //    originCurrencySymbol / destinationCurrencySymbol / amountIn / amountOut
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'BALANCE_TRANSFER',
      quoteId: quote.data.id
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return response.data;
}
 
const transfer = await transferCurrency(token, orgId, merchantId);
console.log('Transfer completed instantly:', transfer.status); // "COMPLETED"

{
  "type": "ONRAMP",
  "originCurrencySymbol": "COP",                 // Fiat currency
  "destinationCurrencySymbol": "USDC",           // Crypto currency
  "amountIn": 50000                              // Fiat amount
}

{
  "type": "ONRAMP",
  "destinationAccountId": "wallet_abc123",       // Crypto wallet ID
  "quoteId": "quote_xyz789"                      // Quote ID
}

async function buyUSDC(token, orgId, merchantId, walletId) {
  // 1. 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
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  console.log('Will receive:', quote.data.amountOut, 'USDC');
  console.log('Exchange rate:', quote.data.exchangeRate);
  console.log('Network fee:', quote.data.networkFee);
  
  // 2. Create deal (not order!)
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
    {
      type: 'ONRAMP',
      destinationAccountId: walletId,
      quoteId: quote.data.id
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return response.data;
}
 
const deal = await buyUSDC(token, orgId, merchantId, 'wallet_abc123');
console.log('ONRAMP deal created:', deal.id);
console.log('Deal can be paid in full or partially');

{
  "type": "OFFRAMP",
  "originCurrencySymbol": "USDC",                // Crypto currency
  "destinationCurrencySymbol": "COP",            // Fiat currency
  "amountIn": 10                                 // Crypto amount (10 USDC)
}

{
  "type": "OFFRAMP",
  "destinationAccountId": "va_cop_12345",        // Virtual account ID
  "quoteId": "quote_xyz789"                      // Quote ID
}

async function sellUSDC(token, orgId, merchantId) {
  // 1. Get quote
  const quote = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
    {
      type: 'OFFRAMP',
      originCurrencySymbol: 'USDC',
      destinationCurrencySymbol: 'COP',
      amountIn: 10  // 10 USDC
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  console.log('Will receive:', quote.data.amountOut, 'COP');
  
  // 2. Create deal (not order!)
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
    {
      type: 'OFFRAMP',
      destinationAccountId: 'va_cop_12345',  // Virtual account for COP
      quoteId: quote.data.id
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return response.data;
}
 
const deal = await sellUSDC(token, orgId, merchantId);
console.log('OFFRAMP deal created:', deal.id);
console.log('Deposit address:', deal.depositAddress);
console.log('Send full crypto amount to complete');
// Funds will be credited to COP virtual account after crypto received

{
  "type": "PAYMENT_LINK",                        // Order type
  "originCurrencySymbol": "COP",                 // Currency
  "destinationCurrencySymbol": "COP",            // Same as origin
  "amountIn": 75000,                             // Amount to collect
  "description": "Invoice #789"                  // Shows to customer
}

{
  "dueDate": "2025-11-14T23:59:59Z",           // Link expiry
  "externalId": "invoice-789",                  // Your reference
  "successUrl": "https://yoursite.com/success", // Redirect after payment
  "failedUrl": "https://yoursite.com/failed"    // Redirect on failure
}

// Minimal example - just create and share!
async function createPaymentLink(amount, description) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'PAYMENT_LINK',
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'COP',
      amountIn: amount,
      description: description
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return response.data;
}
 
// Usage
const link = await createPaymentLink(75000, 'Invoice #789 - Web Design');
console.log('Share this link:', link.paymentUrl);
 
// Send via email, WhatsApp, SMS, or generate QR code
await sendEmail(customerEmail, {
  subject: 'Payment Request - Invoice #789',
  body: `Please pay here: ${link.paymentUrl}`
});

// Full example with all options
async function createPaymentLinkWithOptions(invoiceData) {
  const dueDate = new Date();
  dueDate.setHours(dueDate.getHours() + 24); // Expires in 24h
  
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'PAYMENT_LINK',
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'COP',
      amountIn: invoiceData.amount,
      description: invoiceData.description,
      externalId: invoiceData.invoiceNumber,
      dueDate: dueDate.toISOString(),
      successUrl: 'https://yoursite.com/payment/success',
      failedUrl: 'https://yoursite.com/payment/failed'
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return response.data;
}
 
// Usage
const link = await createPaymentLinkWithOptions({
  amount: 150000,
  description: 'Monthly Subscription - November 2025',
  invoiceNumber: 'INV-2025-11-789'
});
 
console.log('Payment link:', link.paymentUrl);

def create_payment_link(amount, description):
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/orders',
        json={
            'type': 'PAYMENT_LINK',
            'originCurrencySymbol': 'COP',
            'destinationCurrencySymbol': 'COP',
            'amountIn': amount,
            'description': description
        },
        headers={'Authorization': f'Bearer {token}'}
    )
    
    return response.json()
 
# Usage
link = create_payment_link(75000, 'Invoice #789 - Web Design')
print(f"Share this link: {link['paymentUrl']}")

{
  "id": "ord_abc123",
  "type": "PAYMENT_LINK",
  "status": "PENDING",
  "paymentUrl": "https://checkout.koywe.com/pay/ord_abc123",
  "amountIn": 75000,
  "originCurrencySymbol": "COP",
  "description": "Invoice #789 - Web Design",
  "createdAt": "2025-11-13T15:00:00Z"
}

{
  "externalId": "order-12345-20251113"  // Your unique identifier
}

{
  "metadata": {
    "orderId": "12345",
    "customerId": "cust_67890",
    "source": "mobile_app",
    "campaign": "summer_sale"
  }
}

const response = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${sourceMerchantId}/orders`,
  {
    type: 'INTER_MERCHANT_TRANSFER',
    destinationMerchantId: 'mer_destination_abc',
    originCurrencySymbol: 'USD',
    destinationCurrencySymbol: 'USD',
    amountIn: 1000,
    description: 'July commission settlement'
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
// Sandbox completes instantly like BALANCE_TRANSFER:
console.log(response.data.status); // "COMPLETED"

{
  "id": "ord_imt_xyz789",
  "type": "INTER_MERCHANT_TRANSFER",
  "status": "COMPLETED",
  "originMerchantId": "mer_source_123",
  "destinationMerchantId": "mer_destination_abc",
  "originCurrencySymbol": "USD",
  "destinationCurrencySymbol": "USD",
  "amountIn": 1000,
  "amountOut": 1000,
  "description": "July commission settlement",
  "createdAt": "2026-04-24T12:00:00Z",
  "completedAt": "2026-04-24T12:00:01Z"
}

# Via CLI (the CLI reflects all 7 types correctly):
npx @koyweforest/cli orders list --type INTER_MERCHANT_TRANSFER --format table
 
# Via raw HTTP:
curl -H "Authorization: Bearer $TOKEN" \
  "https://api-sandbox.koywe.com/api/v1/organizations/$ORG/merchants/$MERCHANT/orders?type=INTER_MERCHANT_TRANSFER"