Koywe
On this page

5-Minute Quickstart

What You’ll Build

Create a simple PAYIN order to accept a payment from a customer. This quickstart gets you up and running without diving into complex concepts.

By the end of this guide, you’ll be able to:

  • Authenticate with the Koywe API
  • Create a payment order
  • Track the payment status

Prerequisites

Before you begin, make sure you have:

  • API Key and Secret (contact soporte@koywe.com if you don’t have these)
  • Organization ID
  • Merchant ID
  • A tool to make HTTP requests (cURL, Postman, or your preferred programming language)

This quickstart uses the sandbox environment. All payments are simulated and no real money is involved.

Fast lane: the CLI (≈ 30 seconds)

If you’re an AI agent or you just want to see an order move end-to-end, skip the HTTP walkthrough and use the Koywe CLI. Three commands — browser sign-in, pick an org, run a guided order flow:

Terminal
npx @koyweforest/cli init                              # browser login + auto-create credentials
npx @koyweforest/cli config set organizationId <org_id>
npx @koyweforest/cli flow order                        # interactive: quote → create → wait

flow order prompts for the type, currency, amount, and payment method, then chains quote + order creation + status polling into one command. 26 of the 142 commands (the create and update ones) accept --schema to print the full request-body JSON schema — run that before constructing a payload instead of guessing fields.

If you prefer to hit the API directly, keep reading — the rest of this page walks through the same flow with curl, Node, and Python.

Step 1: Authenticate

First, obtain an access token using your API credentials:

curl -X POST 'https://api-sandbox.koywe.com/api/v1/auth/sign-in' \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "your_api_key",
    "secret": "your_secret"
  }'

Response:

JSON
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Store this token securely. You’ll need to include it in all subsequent requests as:
Authorization: Bearer YOUR_TOKEN

The token expires after 1 hour. In production, implement token refresh logic.

Step 2: Create a Contact (Optional)

While optional, creating a contact helps you track which customer made the payment:

async function createContact(token, orgId, merchantId) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
    {
      firstName: 'Juan',
      lastName: 'Pérez',
      countrySymbol: 'CO',
      businessType: 'PERSON',
      type: 'PERSON',
      email: 'customer@example.com',
      phone: '+573001234567',
      documentType: 'CED_CIU',
      documentNumber: '1234567890'
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Usage
const contact = await createContact(token, 'your_org_id', 'your_merchant_id');
console.log('Contact ID:', contact.id);

Step 3: Get a Quote

Get an exchange rate quote for the payment (optional but recommended for transparency):

async function getQuote(token, orgId, merchantId) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
    {
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'COP',
      amountIn: 50000, // 50,000 COP
      orderType: 'PAYIN',
      executable: true
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Usage
const quote = await getQuote(token, 'your_org_id', 'your_merchant_id');
console.log('Quote:', quote);

Step 4: Create Your First PAYIN Order

Now create the payment order. This generates a payment URL where your customer can complete the payment:

async function createPayinOrder(token, orgId, merchantId, contactId) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
    {
      type: 'PAYIN',                              // Order type: receiving payment
      originCurrencySymbol: 'COP',                // Currency: Colombian Pesos
      destinationCurrencySymbol: 'COP',           // Same currency (no conversion)
      amountIn: 50000,                            // Amount: 50,000 COP
      description: 'Payment for Order #12345',    // Description for customer
      externalId: `order-${Date.now()}`,          // Your internal reference
      contactId: contactId,                       // Customer who is paying
      paymentMethods: [
        {
          method: 'PSE',                                       // Payment method: PSE (Colombian bank transfer)
          extra: { bankAccount: { name: 'BANCOLOMBIA' } }      // Per-method extras
        }
      ],
      successUrl: 'https://yoursite.com/payment/success',  // Redirect after success
      failedUrl: 'https://yoursite.com/payment/failed'     // Redirect after failure
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Usage
const order = await createPayinOrder(token, 'your_org_id', 'your_merchant_id', contact.id);
console.log('Order created:', order.id);
console.log('Payment URL:', order.providedAction);

Response:

JSON
{
  "id": "ord_abc123xyz",
  "type": "PAYIN",
  "status": "PENDING",
  "amountIn": 50000,
  "originCurrencySymbol": "COP",
  "destinationCurrencySymbol": "COP",
  "providedAction": "https://checkout.koywe.com/pay/ord_abc123xyz",
  "externalId": "order-1699999999",
  "description": "Payment for Order #12345",
  "createdAt": "2025-11-13T10:00:00Z"
}

Success! You’ve created your first payment order. The providedAction is where you should redirect your customer to complete the payment.

Step 5: Track the Order Status

You can check the order status at any time:

async function getOrderStatus(token, orgId, merchantId, orderId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders/${orderId}`,
    {
      headers: { 
        'Authorization': `Bearer ${token}`
      }
    }
  );
  
  return response.data;
}
 
// Usage
const orderStatus = await getOrderStatus(token, 'your_org_id', 'your_merchant_id', order.id);
console.log('Order status:', orderStatus.status);
// Possible statuses: PENDING, PROCESSING, PAID, COMPLETED, FAILED, CANCELLED, EXPIRED

Order Status Flow:

Text
PENDING → PROCESSING → PAID → COMPLETED
  • PENDING: Order created, waiting for customer payment
  • PROCESSING: Payment is being processed
  • PAID: Payment confirmed
  • COMPLETED: Funds credited to your virtual balance

Complete End-to-End Example

Here’s a complete working example that puts it all together:

const axios = require('axios');
 
const BASE_URL = 'https://api-sandbox.koywe.com/api/v1';
const ORG_ID = process.env.KOYWE_ORG_ID;
const MERCHANT_ID = process.env.KOYWE_MERCHANT_ID;
const API_KEY = process.env.KOYWE_API_KEY;
const SECRET = process.env.KOYWE_SECRET;
 
async function main() {
  try {
    // 1. Authenticate
    console.log('1. Authenticating...');
    const authResponse = await axios.post(`${BASE_URL}/auth/sign-in`, {
      apiKey: API_KEY,
      secret: SECRET
    });
    const token = authResponse.data.token;
    console.log('✓ Authenticated');
 
    // 2. Create contact
    console.log('\n2. Creating contact...');
    const contactResponse = await axios.post(
      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/contacts`,
      {
        email: 'customer@example.com',
        phone: '+573001234567',
        firstName: 'Juan',
        lastName: 'Pérez',
        countrySymbol: 'CO',
        documentType: 'CED_CIU',
        documentNumber: '1234567890',
        businessType: 'PERSON',
        type: 'PERSON'
      },
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const contactId = contactResponse.data.id;
    console.log('✓ Contact created:', contactId);
 
    // 3. Create PAYIN order
    console.log('\n3. Creating payment order...');
    const orderResponse = await axios.post(
      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/orders`,
      {
        type: 'PAYIN',
        originCurrencySymbol: 'COP',
        destinationCurrencySymbol: 'COP',
        amountIn: 50000,
        description: 'Payment for Order #12345',
        externalId: `order-${Date.now()}`,
        contactId: contactId,
        paymentMethods: [{ method: 'PSE', extra: { bankAccount: { name: 'BANCOLOMBIA' } } }],
        successUrl: 'https://yoursite.com/success',
        failedUrl: 'https://yoursite.com/failed'
      },
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const order = orderResponse.data;
    console.log('✓ Order created:', order.id);
    console.log('✓ Payment URL:', order.providedAction);
 
    // 4. Check order status
    console.log('\n4. Checking order status...');
    const statusResponse = await axios.get(
      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/orders/${order.id}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    console.log('✓ Current status:', statusResponse.data.status);
 
    console.log('\n✅ Success! Payment order created.');
    console.log('👉 Redirect your customer to:', order.providedAction);
 
  } catch (error) {
    console.error('❌ Error:', error.response?.data || error.message);
  }
}
 
main();

What’s Next?

Congratulations! You’ve successfully created your first payment order. Here’s what to explore next:

Core Concepts

Understand organizations, merchants, virtual accounts, and order types

Complete Integration

Full production-ready integration with webhooks and error handling

Testing Guide

Test different payment scenarios in the sandbox environment

Setup Webhooks

Get real-time notifications when payments complete

Need Help?