Getting Started

⚡ 5-Minute Quickstart

Make your first API call in minutes

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.

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:

1{
2  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
3}

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:

1async function createContact(token, orgId, merchantId) {
2  const response = await axios.post(
3    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
4    {
5      email: 'customer@example.com',
6      phone: '+573001234567',
7      fullName: 'Juan Pérez',
8      countrySymbol: 'CO',
9      documentType: 'CC',
10      documentNumber: '1234567890',
11      businessType: 'PERSON'
12    },
13    {
14      headers: { 
15        'Authorization': `Bearer ${token}`,
16        'Content-Type': 'application/json'
17      }
18    }
19  );
20  
21  return response.data;
22}
23
24// Usage
25const contact = await createContact(token, 'your_org_id', 'your_merchant_id');
26console.log('Contact ID:', contact.id);

Step 3: Get a Quote

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

1async function getQuote(token, orgId, merchantId) {
2  const response = await axios.post(
3    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
4    {
5      originCurrencySymbol: 'COP',
6      destinationCurrencySymbol: 'COP',
7      amountIn: 50000, // 50,000 COP
8      type: 'PAYIN'
9    },
10    {
11      headers: { 
12        'Authorization': `Bearer ${token}`,
13        'Content-Type': 'application/json'
14      }
15    }
16  );
17  
18  return response.data;
19}
20
21// Usage
22const quote = await getQuote(token, 'your_org_id', 'your_merchant_id');
23console.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:

1async function createPayinOrder(token, orgId, merchantId, contactId) {
2  const response = await axios.post(
3    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
4    {
5      type: 'PAYIN',                              // Order type: receiving payment
6      originCurrencySymbol: 'COP',                // Currency: Colombian Pesos
7      destinationCurrencySymbol: 'COP',           // Same currency (no conversion)
8      amountIn: 50000,                            // Amount: 50,000 COP
9      description: 'Payment for Order #12345',    // Description for customer
10      externalId: `order-${Date.now()}`,          // Your internal reference
11      contactId: contactId,                       // Customer who is paying
12      paymentMethods: [
13        {
14          method: 'PSE',                          // Payment method: PSE (Colombian bank transfer)
15          extra: 'BANCOLOMBIA'                    // Specific bank
16        }
17      ],
18      successUrl: 'https://yoursite.com/payment/success',  // Redirect after success
19      failedUrl: 'https://yoursite.com/payment/failed'     // Redirect after failure
20    },
21    {
22      headers: { 
23        'Authorization': `Bearer ${token}`,
24        'Content-Type': 'application/json'
25      }
26    }
27  );
28  
29  return response.data;
30}
31
32// Usage
33const order = await createPayinOrder(token, 'your_org_id', 'your_merchant_id', contact.id);
34console.log('Order created:', order.id);
35console.log('Payment URL:', order.paymentUrl);

Response:

1{
2  "id": "ord_abc123xyz",
3  "type": "PAYIN",
4  "status": "PENDING",
5  "amountIn": 50000,
6  "originCurrencySymbol": "COP",
7  "destinationCurrencySymbol": "COP",
8  "paymentUrl": "https://checkout.koywe.com/pay/ord_abc123xyz",
9  "externalId": "order-1699999999",
10  "description": "Payment for Order #12345",
11  "createdAt": "2025-11-13T10:00:00Z"
12}

Success! You’ve created your first payment order. The paymentUrl 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:

1async function getOrderStatus(token, orgId, merchantId, orderId) {
2  const response = await axios.get(
3    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders/${orderId}`,
4    {
5      headers: { 
6        'Authorization': `Bearer ${token}`
7      }
8    }
9  );
10  
11  return response.data;
12}
13
14// Usage
15const orderStatus = await getOrderStatus(token, 'your_org_id', 'your_merchant_id', order.id);
16console.log('Order status:', orderStatus.status);
17// Possible statuses: PENDING, PROCESSING, PAID, COMPLETED, FAILED, CANCELLED, EXPIRED

Order Status Flow:

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:

1const axios = require('axios');
2
3const BASE_URL = 'https://api-sandbox.koywe.com/api/v1';
4const ORG_ID = process.env.KOYWE_ORG_ID;
5const MERCHANT_ID = process.env.KOYWE_MERCHANT_ID;
6const API_KEY = process.env.KOYWE_API_KEY;
7const SECRET = process.env.KOYWE_SECRET;
8
9async function main() {
10  try {
11    // 1. Authenticate
12    console.log('1. Authenticating...');
13    const authResponse = await axios.post(`${BASE_URL}/auth/sign-in`, {
14      apiKey: API_KEY,
15      secret: SECRET
16    });
17    const token = authResponse.data.token;
18    console.log('✓ Authenticated');
19
20    // 2. Create contact
21    console.log('\n2. Creating contact...');
22    const contactResponse = await axios.post(
23      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/contacts`,
24      {
25        email: 'customer@example.com',
26        phone: '+573001234567',
27        fullName: 'Juan Pérez',
28        countrySymbol: 'CO',
29        documentType: 'CC',
30        documentNumber: '1234567890',
31        businessType: 'PERSON'
32      },
33      { headers: { Authorization: `Bearer ${token}` } }
34    );
35    const contactId = contactResponse.data.id;
36    console.log('✓ Contact created:', contactId);
37
38    // 3. Create PAYIN order
39    console.log('\n3. Creating payment order...');
40    const orderResponse = await axios.post(
41      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/orders`,
42      {
43        type: 'PAYIN',
44        originCurrencySymbol: 'COP',
45        destinationCurrencySymbol: 'COP',
46        amountIn: 50000,
47        description: 'Payment for Order #12345',
48        externalId: `order-${Date.now()}`,
49        contactId: contactId,
50        paymentMethods: [{ method: 'PSE', extra: 'BANCOLOMBIA' }],
51        successUrl: 'https://yoursite.com/success',
52        failedUrl: 'https://yoursite.com/failed'
53      },
54      { headers: { Authorization: `Bearer ${token}` } }
55    );
56    const order = orderResponse.data;
57    console.log('✓ Order created:', order.id);
58    console.log('✓ Payment URL:', order.paymentUrl);
59
60    // 4. Check order status
61    console.log('\n4. Checking order status...');
62    const statusResponse = await axios.get(
63      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/orders/${order.id}`,
64      { headers: { Authorization: `Bearer ${token}` } }
65    );
66    console.log('✓ Current status:', statusResponse.data.status);
67
68    console.log('\n✅ Success! Payment order created.');
69    console.log('👉 Redirect your customer to:', order.paymentUrl);
70
71  } catch (error) {
72    console.error('❌ Error:', error.response?.data || error.message);
73  }
74}
75
76main();

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?