Koywe Documentation

https://docs.koywe.com/en
Admin
A comprehensive documentation set for the Koywe project, covering integration guides, API...
Tokens:113,737
Snippets:970
Trust Score:8.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### GET /onboarding/me

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get your onboarding status.

```APIDOC
## GET /onboarding/me

### Description
Get your onboarding status.

### Method
GET

### Endpoint
/onboarding/me
```

--------------------------------

### Install ngrok CLI

Source: https://docs.koywe.com/en/advanced/webhooks

Global installation of the ngrok tool for local tunnel creation.

```bash
npm install -g ngrok
```

--------------------------------

### Install and run Koywe CLI

Source: https://docs.koywe.com/en/cli

Use npx for one-off execution or install globally for a persistent command alias.

```bash
npx @koyweforest/cli --help
```

```bash
npm install -g @koyweforest/cli
koywe --help
```

--------------------------------

### GET /pre-onboarding/registrations

Source: https://docs.koywe.com/en/cli/api-cross-reference

List all registrations.

```APIDOC
## GET /pre-onboarding/registrations

### Description
List all registrations.

### Method
GET

### Endpoint
/pre-onboarding/registrations
```

--------------------------------

### GET /pre-onboarding/registration-draft/{draftId}

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get a registration draft by ID.

```APIDOC
## GET /pre-onboarding/registration-draft/{draftId}

### Description
Get a registration draft by ID.

### Method
GET

### Endpoint
/pre-onboarding/registration-draft/{draftId}

### Parameters
#### Path Parameters
- **draftId** (string) - Required - The unique identifier of the registration draft.
```

--------------------------------

### GET /api/v1/pre-onboarding/registrations

Source: https://docs.koywe.com/en/getting-started/onboarding-kyb

Lists all registrations.

```APIDOC
## GET /api/v1/pre-onboarding/registrations

### Description
Retrieves a list of all registrations.

### Method
GET

### Endpoint
/api/v1/pre-onboarding/registrations
```

--------------------------------

### Order Status Response Example

Source: https://docs.koywe.com/en/accepting-payments/integration-guide

Example JSON response returned when querying an order status.

```json
{
  "id": "ord_abc123xyz",
  "type": "PAYIN",
  "status": "COMPLETED",
  "amountIn": 50000,
  "originCurrencySymbol": "COP",
  "destinationCurrencySymbol": "COP",
  "externalId": "order-12345",
  "dates": {
    "confirmationDate": "2025-11-13T10:00:00Z",
    "paymentDate": "2025-11-13T10:05:00Z",
    "deliveryDate": "2025-11-13T10:06:00Z"
  }
}
```

--------------------------------

### GET /pre-onboarding/registrations/{registrationId}/status

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get registration status.

```APIDOC
## GET /pre-onboarding/registrations/{registrationId}/status

### Description
Get registration status.

### Method
GET

### Endpoint
/pre-onboarding/registrations/{registrationId}/status

### Parameters
#### Path Parameters
- **registrationId** (string) - Required - The unique identifier of the registration.
```

--------------------------------

### Start Local Server

Source: https://docs.koywe.com/en/advanced/webhooks

Command to initiate a local Node.js server for webhook reception.

```bash
node server.js
# Server running on http://localhost:3000
```

--------------------------------

### GET /onboarding/me

Source: https://docs.koywe.com/en/cli/reference

Retrieve the current user's onboarding status.

```APIDOC
## GET /onboarding/me

### Description
Get your onboarding status.

### Method
GET

### Endpoint
/onboarding/me

### Parameters
#### Query Parameters
- **evaluation-status** (string) - Optional - Filter by evaluation status
- **setup-status** (string) - Optional - Filter by setup status
```

--------------------------------

### GET /countries/{countrySymbol}/states/{stateId}

Source: https://docs.koywe.com/en/cli/reference

Get state details.

```APIDOC
## GET /countries/{countrySymbol}/states/{stateId}

### Description
Get state details.

### Method
GET

### Endpoint
/countries/{countrySymbol}/states/{stateId}
```

--------------------------------

### GET /api/v1/onboarding/me

Source: https://docs.koywe.com/en/getting-started/onboarding-kyb

Retrieves the current user's onboarding status.

```APIDOC
## GET /api/v1/onboarding/me

### Description
Retrieves the onboarding evaluation status for the currently authenticated user.

### Method
GET

### Endpoint
/api/v1/onboarding/me
```

--------------------------------

### GET /countries/{countrySymbol}/states/{stateId}/counties/{countyId}

Source: https://docs.koywe.com/en/cli/reference

Get county details.

```APIDOC
## GET /countries/{countrySymbol}/states/{stateId}/counties/{countyId}

### Description
Get county details.

### Method
GET

### Endpoint
/countries/{countrySymbol}/states/{stateId}/counties/{countyId}
```

--------------------------------

### GET /payment-method

Source: https://docs.koywe.com/en/cli/api-cross-reference

List available payment methods.

```APIDOC
## GET /payment-method

### Description
List available payment methods.

### Method
GET

### Endpoint
/payment-method
```

--------------------------------

### GET /countries/{countrySymbol}/states

Source: https://docs.koywe.com/en/cli/reference

List states for a country.

```APIDOC
## GET /countries/{countrySymbol}/states

### Description
List states for a country.

### Method
GET

### Endpoint
/countries/{countrySymbol}/states
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/onboarding/kyb/{kybId}

Source: https://docs.koywe.com/en/cli/reference

Retrieve the status of a specific KYB process.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/onboarding/kyb/{kybId}

### Description
Get KYB process status.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/onboarding/kyb/{kybId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - Organization ID
- **merchantId** (string) - Required - Merchant ID
- **kybId** (string) - Required - KYB process ID
```

--------------------------------

### GET /countries/{countrySymbol}/economic-activities

Source: https://docs.koywe.com/en/cli/reference

List economic activities for a country.

```APIDOC
## GET /countries/{countrySymbol}/economic-activities

### Description
List economic activities for a country.

### Method
GET

### Endpoint
/countries/{countrySymbol}/economic-activities
```

--------------------------------

### Initialize and create orders

Source: https://docs.koywe.com/en/cli

Quick start commands to authenticate and begin the order flow.

```bash
koywe init                 # Browser login + auto-create API credentials
koywe config set organizationId <org>
koywe flow order           # Guided: quote → create order → wait for approval
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/onboarding/kyb

Source: https://docs.koywe.com/en/cli/reference

List KYB processes for a specific merchant within an organization.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/onboarding/kyb

### Description
List KYB processes for a merchant.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/onboarding/kyb

### Parameters
#### Path Parameters
- **orgId** (string) - Required - Organization ID
- **merchantId** (string) - Required - Merchant ID
```

--------------------------------

### GET /users/me

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get the authenticated user profile.

```APIDOC
## GET /users/me

### Description
Get the authenticated user profile.

### Method
GET

### Endpoint
/users/me
```

--------------------------------

### GET /auth/me

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get current user information.

```APIDOC
## GET /auth/me

### Description
Get current user information.

### Method
GET

### Endpoint
/auth/me
```

--------------------------------

### GET /currencies/{id}

Source: https://docs.koywe.com/en/cli/reference

Retrieves detailed information for a specific currency by its ID.

```APIDOC
## GET /currencies/{id}

### Description
Get currency details by ID.

### Method
GET

### Endpoint
/currencies/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the currency.
```

--------------------------------

### GET /currencies/symbol/{symbol}

Source: https://docs.koywe.com/en/cli/reference

Retrieves currency information based on the provided symbol.

```APIDOC
## GET /currencies/symbol/{symbol}

### Description
Get currency by symbol.

### Method
GET

### Endpoint
/currencies/symbol/{symbol}

### Parameters
#### Path Parameters
- **symbol** (string) - Required - The currency symbol to retrieve.
```

--------------------------------

### GET /countries/{countrySymbol}/states/{stateId}/counties

Source: https://docs.koywe.com/en/cli/reference

List counties for a state.

```APIDOC
## GET /countries/{countrySymbol}/states/{stateId}/counties

### Description
List counties for a state.

### Method
GET

### Endpoint
/countries/{countrySymbol}/states/{stateId}/counties
```

--------------------------------

### Create and configure an organization-level policy

Source: https://docs.koywe.com/en/cli

Sets up a basic policy and adds a rule to permit BALANCE_TRANSFER operations.

```bash
# Create an organization-level policy
koywe policy create --data '{"name":"default"}'
 
# Add a rule that allows BALANCE_TRANSFER orders
koywe policy rules create --schema   # see the exact schema
koywe policy rules create --data '{
  "name": "allow-balance-transfer",
  "scope": "ORDER",
  "match": { "orderType": ["BALANCE_TRANSFER"] },
  "decision": { "action": "ALLOW" }
}'
```

--------------------------------

### GET /payment-method/card/merchants/{merchantId}/verify

Source: https://docs.koywe.com/en/cli/reference

Verify card payment method for a merchant.

```APIDOC
## GET /payment-method/card/merchants/{merchantId}/verify

### Description
Verify card payment method for a merchant.

### Method
GET

### Endpoint
/payment-method/card/merchants/{merchantId}/verify

### Parameters
#### Path Parameters
- **merchantId** (string) - Required - Merchant ID

#### Query Parameters
- **org-id** (string) - Optional - Organization ID
- **merchant-id** (string) - Optional - Merchant ID
```

--------------------------------

### Initialize and run order flow with Koywe CLI

Source: https://docs.koywe.com/en/getting-started/quickstart

Use the CLI to authenticate, configure the organization ID, and execute an interactive payment order flow.

```bash
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
```

--------------------------------

### GET /organizations/{orgId}/webhooks/{webhookId}

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get webhook details.

```APIDOC
## GET /organizations/{orgId}/webhooks/{webhookId}

### Description
Get webhook details.

### Method
GET

### Endpoint
/organizations/{orgId}/webhooks/{webhookId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.
- **webhookId** (string) - Required - The webhook identifier.
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/accounts/balances

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get balances for all accounts.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/accounts/balances

### Description
Get balances for all accounts.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/accounts/balances

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.
- **merchantId** (string) - Required - The merchant identifier.
```

--------------------------------

### Complete End-to-End Payment Integration

Source: https://docs.koywe.com/en/accepting-payments/integration-guide

A full implementation example covering authentication, fetching payment methods, creating a customer contact, and initiating a payment order.

```javascript
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 acceptPayment(customerData, orderDetails) {
  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');
 
    const headers = { 
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
 
    // 2. Get payment methods
    console.log('\n2. Getting payment methods...');
    const methodsResponse = await axios.get(
      `${BASE_URL}/payment-method`,
      {
        params: { 
          countrySymbol: customerData.country,
          currencySymbol: orderDetails.currency
        },
        headers: { 'Authorization': `Bearer ${token}` }
      }
    );
    const methods = methodsResponse.data;
    console.log('✓ Available methods:', methods.map(m => m.method).join(', '));
 
    // 3. Create contact
    console.log('\n3. Creating customer contact...');
    const contactResponse = await axios.post(
      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/contacts`,
      {
        firstName: customerData.firstName,
        lastName: customerData.lastName,
        email: customerData.email,
        phone: customerData.phone,
        countrySymbol: customerData.country,
        documentType: customerData.documentType,
        documentNumber: customerData.documentNumber,
        businessType: 'PERSON',
        type: 'PERSON'
      },
      { headers }
    );
    const contactId = contactResponse.data.id;
    console.log('✓ Contact created:', contactId);
 
    // 4. Create PAYIN order
    console.log('\n4. Creating payment order...');
    const orderResponse = await axios.post(
      `${BASE_URL}/organizations/${ORG_ID}/merchants/${MERCHANT_ID}/orders`,
      {
        type: 'PAYIN',
        originCurrencySymbol: orderDetails.currency,
        destinationCurrencySymbol: orderDetails.currency,
        amountIn: orderDetails.amount,
        description: orderDetails.description,
        externalId: orderDetails.orderId,
        contactId: contactId,
        paymentMethods: [
          {
            method: orderDetails.paymentMethod,
            extra: orderDetails.bank
          }
        ],
        successUrl: 'https://yoursite.com/payment/success',
        failedUrl: 'https://yoursite.com/payment/failed'
      },
      { headers }
    );
    const order = orderResponse.data;
    console.log('✓ Order created:', order.id);
    console.log('✓ Status:', order.status);
 
    // 5. Return payment URL
    console.log('\n5. Payment URL ready:');
    console.log(order.providedAction);
    
    return {
      success: true,
      orderId: order.id,
      providedAction: order.providedAction,
      status: order.status
    };
 
  } catch (error) {
    console.error('❌ Error:', error.response?.data || error.message);
    throw error;
  }
}
 
// Usage
const result = await acceptPayment(
  {
    firstName: 'Juan',
    lastName: 'Pérez',
    email: 'customer@example.com',
    phone: '+573001234567',
    country: 'CO',
    documentType: 'CC',
    documentNumber: '1234567890'
  },
  {
    currency: 'COP',
    amount: 50000,
    description: 'Payment for Order #12345',
    orderId: `order-${Date.now()}`,
    paymentMethod: 'PSE',
    bank: 'BANCOLOMBIA'
  }
);
 
console.log('\n✅ Complete! Redirect customer to:');
console.log(result.providedAction);
```

--------------------------------

### POST /auth/organizations/{orgId}/api-users/mfa/prepare

Source: https://docs.koywe.com/en/cli/reference

Start delegated MFA enrollment by sending your public key.

```APIDOC
## POST /auth/organizations/{orgId}/api-users/mfa/prepare

### Description
Start delegated MFA enrollment by sending your public key.

### Method
POST

### Endpoint
/auth/organizations/{orgId}/api-users/mfa/prepare

### Parameters
#### Path Parameters
- **orgId** (string) - Required

#### Query Parameters
- **--public-key-file** (path) - Optional - Path to PEM public key file
- **--org-id** (string) - Optional - Organization ID
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/contacts/{contactId}

Source: https://docs.koywe.com/en/cli/reference

Get contact details.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/contacts/{contactId}

### Description
Get contact details.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/contacts/{contactId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - Organization ID
- **merchantId** (string) - Required - Merchant ID
- **contactId** (string) - Required - Contact ID
```

--------------------------------

### Create a Payment Link in JavaScript

Source: https://docs.koywe.com/en/core-concepts/orders-and-order-types

Demonstrates creating a basic payment link and sending it to a customer.

```javascript
// 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.providedAction);
 
// Send via email, WhatsApp, SMS, or generate QR code
await sendEmail(customerEmail, {
  subject: 'Payment Request - Invoice #789',
  body: `Please pay here: ${link.providedAction}`
});
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get bank account details.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}

### Description
Get bank account details.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.
- **merchantId** (string) - Required - The merchant identifier.
- **accountId** (string) - Required - The account identifier.
```

--------------------------------

### Create an order from a file

Source: https://docs.koywe.com/en/cli

Reads order configuration from a local JSON file.

```bash
koywe orders create --file order.json
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/bankIncome/accounts

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get deposit account information (bank income).

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/bankIncome/accounts

### Description
Get deposit account information (bank income).

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/bankIncome/accounts

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.
- **merchantId** (string) - Required - The merchant identifier.
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/orders

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get orders report for an account.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/orders

### Description
Get orders report for an account.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/orders

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.
- **merchantId** (string) - Required - The merchant identifier.
- **accountId** (string) - Required - The account identifier.
```

--------------------------------

### Implement a currency converter tool

Source: https://docs.koywe.com/en/core-concepts/quotes-and-exchange-rates

Use the getQuote function to build a real-time currency conversion utility.

```javascript
// Real-time currency converter
async function convertCurrency(amount, from, to) {
  const quote = await getQuote(token, orgId, merchantId, {
    orderType: 'BALANCE_TRANSFER',
    from: from,
    to: to,
    amount: amount
  });
 
  return {
    from: `${amount} ${from}`,
    to: `${quote.finalAmountOut} ${to}`,
    rate: `1 ${to} = ${quote.exchangeRate} ${from}`,
    fee: `${quote.fee} ${from}`
  };
}
 
// Usage
const result = await convertCurrency(1000000, 'COP', 'USD');
console.log(result);
// { from: "1000000 COP", to: "248.75 USD", rate: "1 USD = 4000 COP", fee: "5000 COP" }
```

--------------------------------

### View ngrok Forwarding URL

Source: https://docs.koywe.com/en/advanced/webhooks

Example output showing the public URL mapped to the local server.

```text
Forwarding: https://abc123.ngrok.io -> http://localhost:3000
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-statement

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get ledger statement for an account.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-statement

### Description
Get ledger statement for an account.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-statement

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.
- **merchantId** (string) - Required - The merchant identifier.
- **accountId** (string) - Required - The account identifier.
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/balance

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get balance for a specific account.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/balance

### Description
Get balance for a specific account.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/balance

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.
- **merchantId** (string) - Required - The merchant identifier.
- **accountId** (string) - Required - The account identifier.
```

--------------------------------

### POST /pre-onboarding/registration-form/{draftId}

Source: https://docs.koywe.com/en/cli/api-cross-reference

Submit a registration draft for review.

```APIDOC
## POST /pre-onboarding/registration-form/{draftId}

### Description
Submit a registration draft for review.

### Method
POST

### Endpoint
/pre-onboarding/registration-form/{draftId}

### Parameters
#### Path Parameters
- **draftId** (string) - Required - The unique identifier of the registration draft.
```

--------------------------------

### Implement Secure Logging Practices

Source: https://docs.koywe.com/en/advanced/security

Demonstrates the difference between logging safe business metadata and prohibited sensitive information.

```javascript
// ✅ Good logging
console.log('Order created:', {
  orderId: order.id,
  type: order.type,
  amount: order.amountIn,
  currency: order.originCurrencySymbol
});
 
// ❌ Bad logging
console.log('Order created:', {
  orderId: order.id,
  customerEmail: 'customer@example.com', // DON'T LOG PII
  token: 'Bearer abc123...' // DON'T LOG TOKENS
});
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/contacts/{contactId}/accounts/{accountId}

Source: https://docs.koywe.com/en/cli/reference

Get account details for a contact.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/contacts/{contactId}/accounts/{accountId}

### Description
Get account details for a contact.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/contacts/{contactId}/accounts/{accountId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - Organization ID
- **merchantId** (string) - Required - Merchant ID
- **contactId** (string) - Required - Contact ID
- **accountId** (string) - Required - Account ID
```

--------------------------------

### GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-entry/{entryId}

Source: https://docs.koywe.com/en/cli/api-cross-reference

Get a specific ledger entry.

```APIDOC
## GET /organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-entry/{entryId}

### Description
Get a specific ledger entry.

### Method
GET

### Endpoint
/organizations/{orgId}/merchants/{merchantId}/accounts/{accountId}/reports/ledger-entry/{entryId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier.
- **merchantId** (string) - Required - The merchant identifier.
- **accountId** (string) - Required - The account identifier.
- **entryId** (string) - Required - The ledger entry identifier.
```

--------------------------------

### POST /pre-onboarding/registration-draft

Source: https://docs.koywe.com/en/cli/api-cross-reference

Create a new registration draft.

```APIDOC
## POST /pre-onboarding/registration-draft

### Description
Create a new registration draft.

### Method
POST

### Endpoint
/pre-onboarding/registration-draft
```

--------------------------------

### Create a PAYIN order

Source: https://docs.koywe.com/en/getting-started/quickstart

Examples for initiating a payment order in different environments. Ensure you have a valid token and the required organization, merchant, and contact identifiers.

```javascript
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);
```

```python
def create_payin_order(token, org_id, merchant_id, contact_id):
    import time
    
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/orders',
        json={
            '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': f'order-{int(time.time())}',   # Your internal reference
            'contactId': contact_id,                      # Customer who is paying
            'paymentMethods': [
                {
                    'method': 'PSE',                      # Payment method: PSE
                    'extra': 'BANCOLOMBIA'                # Specific bank
                }
            ],
            'successUrl': 'https://yoursite.com/payment/success',
            'failedUrl': 'https://yoursite.com/payment/failed'
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Usage
order = create_payin_order(token, 'your_org_id', 'your_merchant_id', contact['id'])
print(f"Order created: {order['id']}")
print(f"Payment URL: {order['providedAction']}")
```

```bash
curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/YOUR_ORG_ID/merchants/YOUR_MERCHANT_ID/orders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "PAYIN",
    "originCurrencySymbol": "COP",
    "destinationCurrencySymbol": "COP",
    "amountIn": 50000,
    "description": "Payment for Order #12345",
    "externalId": "order-1699999999",
    "contactId": "CONTACT_ID_FROM_STEP_2",
    "paymentMethods": [
      {
        "method": "PSE",
        "extra": { "bankAccount": { "name": "BANCOLOMBIA" } }
      }
    ],
    "successUrl": "https://yoursite.com/payment/success",
    "failedUrl": "https://yoursite.com/payment/failed"
  }'
```

--------------------------------

### Perform a Balance Transfer with JavaScript

Source: https://docs.koywe.com/en/balance-management

This example demonstrates how to retrieve an exchange rate quote and execute a balance transfer order using the Koywe API.

```javascript
// Convert 1,000,000 COP to USD
 
// 1. Get quote
const quote = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
  {
    orderType: 'BALANCE_TRANSFER', executable: true,
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USD',
    amountIn: 1000000
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Exchange rate:', quote.data.exchangeRate); // e.g., 4000 COP per USD
console.log('Will receive:', quote.data.finalAmountOut, 'USD'); // e.g., 248.75 USD
console.log('Fee:', quote.data.fee, 'COP'); // e.g., 5000 COP
 
// 2. Create transfer order
const order = await axios.post(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
  {
    type: 'BALANCE_TRANSFER',
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USD',
    amountIn: 1000000,
    quoteId: quote.data.id  // Lock the rate
  },
  { headers: { 'Authorization': `Bearer ${token}` } }
);
 
console.log('Transfer completed:', order.data.status); // "COMPLETED"
```

--------------------------------

### POST /api/v1/auth/organizations/{organizationId}/api-users/mfa/enroll/prepare

Source: https://docs.koywe.com/en/advanced/passkeys-and-approvals

Loads a prepared enrollment request for the root user to sign.

```APIDOC
## POST /api/v1/auth/organizations/{organizationId}/api-users/mfa/enroll/prepare

### Description
Loads the prepared enrollment request for the root user to review and sign with their passkey.

### Method
POST

### Endpoint
https://api-sandbox.koywe.com/api/v1/auth/organizations/{organizationId}/api-users/mfa/enroll/prepare

### Parameters
#### Path Parameters
- **organizationId** (string) - Required - The unique identifier of the organization.

#### Request Body
- **pendingApprovalId** (string) - Required - The ID of the pending approval request.
```

--------------------------------

### GET /organizations

Source: https://docs.koywe.com/en/cli/api-cross-reference

List all organizations.

```APIDOC
## GET /organizations

### Description
List all organizations.

### Method
GET

### Endpoint
/organizations
```

--------------------------------

### Manage CLI Profiles

Source: https://docs.koywe.com/en/cli

Commands to add, switch, and list authentication profiles for different environments.

```bash
koywe config profile add staging --env sandbox
koywe config profile add prod --env production
koywe config profile use staging
koywe config profile list
```

--------------------------------

### POST /api/v1/pre-onboarding/registration-draft

Source: https://docs.koywe.com/en/getting-started/onboarding-kyb

Creates a new registration draft for user onboarding.

```APIDOC
## POST /api/v1/pre-onboarding/registration-draft

### Description
Creates a new registration draft to begin the user onboarding process.

### Method
POST

### Endpoint
/api/v1/pre-onboarding/registration-draft
```

--------------------------------

### GET /currencies

Source: https://docs.koywe.com/en/cli/api-cross-reference

List available currencies.

```APIDOC
## GET /currencies

### Description
List available currencies.

### Method
GET

### Endpoint
/currencies
```

--------------------------------

### GET /countries

Source: https://docs.koywe.com/en/cli/api-cross-reference

List available countries.

```APIDOC
## GET /countries

### Description
List available countries.

### Method
GET

### Endpoint
/countries
```

--------------------------------

### Create Provider Contact via API

Source: https://docs.koywe.com/en/paying-providers/integration-guide

Examples for registering a new provider contact using JavaScript and Python.

```javascript
async function createProviderContact(token, orgId, merchantId, providerData) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
    {
      firstName: providerData.firstName,
      countrySymbol: providerData.country,
      documentType: providerData.documentType,
      documentNumber: providerData.documentNumber,
      businessType: providerData.businessType,  // 'PERSON' or 'COMPANY'
      type: providerData.type,                  // 'PERSON', 'BUSINESS', etc.
      email: providerData.email,
      phone: providerData.phone
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Usage - Company provider
const provider = await createProviderContact(token, orgId, merchantId, {
  firstName: 'Servicios ABC SAS',
  country: 'CO',
  documentType: 'NIT',  // Tax ID for companies in Colombia
  documentNumber: '900123456-1',
  businessType: 'COMPANY',
  type: 'BUSINESS',
  email: 'provider@example.com',
  phone: '+573001234567'
});
 
console.log('Provider contact created:', provider.id);
```

```python
def create_provider_contact(token, org_id, merchant_id, provider_data):
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/contacts',
        json={
            'firstName': provider_data['first_name'],
            'countrySymbol': provider_data['country'],
            'documentType': provider_data.get('document_type'),
            'documentNumber': provider_data.get('document_number'),
            'businessType': provider_data['business_type'],
            'type': provider_data['type'],
            'email': provider_data.get('email'),
            'phone': provider_data.get('phone')
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    response.raise_for_status()
    
    return response.json()
 
# Usage
provider = create_provider_contact(token, org_id, merchant_id, {
    'first_name': 'Servicios ABC SAS',
    'country': 'CO',
    'document_type': 'NIT',
    'document_number': '900123456-1',
    'business_type': 'COMPANY',
    'type': 'BUSINESS',
    'email': 'provider@example.com',
    'phone': '+573001234567'
})
```

--------------------------------

### GET /banks

Source: https://docs.koywe.com/en/cli/api-cross-reference

List available banks.

```APIDOC
## GET /banks

### Description
List available banks.

### Method
GET

### Endpoint
/banks
```

--------------------------------

### Test Payment Methods in Sandbox

Source: https://docs.koywe.com/en/accepting-payments/payment-methods

Demonstrates how to trigger success and failure scenarios in the sandbox environment using specific amount values.

```javascript
// Success scenario (any amount except 666)
const order = await createPayinOrder(token, orgId, merchantId, {
  amountIn: 50000,
  paymentMethods: [{ method: 'PSE', extra: { bankAccount: { name: 'BANCOLOMBIA' } } }]
  // ... other fields
});
// Result: Order auto-completes successfully
 
// Failure scenario (amount = 666)
const order = await createPayinOrder(token, orgId, merchantId, {
  amountIn: 666,  // Special test amount
  paymentMethods: [{ method: 'PSE', extra: { bankAccount: { name: 'BANCOLOMBIA' } } }]
  // ... other fields
});
// Result: Order fails
```

--------------------------------

### Create a contact via API

Source: https://docs.koywe.com/en/core-concepts/contacts-and-bank-accounts

Examples for creating a new contact using different programming languages and tools.

```javascript
async function createContact(token, orgId, merchantId, contactData) {
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/contacts`,
    {
      firstName: contactData.firstName,
      lastName: contactData.lastName,               // Optional
      email: contactData.email,                     // Optional
      phone: contactData.phone,                     // Optional
      countrySymbol: contactData.countrySymbol,
      documentType: contactData.documentType,       // Optional
      documentNumber: contactData.documentNumber,   // Optional (required if documentType is provided)
      businessType: 'PERSON',                       // or 'COMPANY'
      type: 'PERSON'                                // PERSON, BUSINESS, GOVERNMENT, NGO, FOREIGN
    },
    {
      headers: { 
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  return response.data;
}
 
// Usage - Creating a customer contact
const customer = await createContact(token, orgId, merchantId, {
  firstName: 'Juan',
  lastName: 'Pérez',
  countrySymbol: 'CO',
  email: 'customer@example.com',
  phone: '+573001234567',
  documentType: 'CC',
  documentNumber: '1234567890'
});
 
console.log('Contact created:', customer.id);
```

```python
def create_contact(token, org_id, merchant_id, contact_data):
    response = requests.post(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{org_id}/merchants/{merchant_id}/contacts',
        json={
            'firstName': contact_data['first_name'],
            'lastName': contact_data.get('last_name'),        # Optional
            'email': contact_data.get('email'),               # Optional
            'phone': contact_data.get('phone'),               # Optional
            'countrySymbol': contact_data['country'],
            'documentType': contact_data.get('document_type'),    # Optional
            'documentNumber': contact_data.get('document_number'),# Optional (required if documentType is provided)
            'businessType': 'PERSON',
            'type': 'PERSON'
        },
        headers={
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    )
    
    return response.json()
 
# Usage
customer = create_contact(token, org_id, merchant_id, {
    'first_name': 'Juan',
    'last_name': 'Pérez',
    'email': 'customer@example.com',
    'phone': '+573001234567',
    'country': 'CO',
    'document_type': 'CC',
    'document_number': '1234567890'
})
```

```bash
curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/YOUR_ORG_ID/merchants/YOUR_MERCHANT_ID/contacts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Juan",
    "lastName": "Pérez",
    "email": "customer@example.com",
    "phone": "+573001234567",
    "countrySymbol": "CO",
    "documentType": "CC",
    "documentNumber": "1234567890",
    "businessType": "PERSON",
    "type": "PERSON"
  }'
```

--------------------------------

### Perform ONRAMP Test

Source: https://docs.koywe.com/en/getting-started/testing

Create a crypto wallet and initiate an onramp order using sandbox-compatible network settings.

```javascript
async function testOnramp() {
  // Create crypto wallet (or use existing)
  const wallet = await createCryptoWallet(token, orgId, merchantId, {
    address: '0x0000000000000000000000000000000000000000',
    network: 'ETHEREUM'  // Automatically uses Sepolia in sandbox
  });
  
  // Buy USDC with COP
  const order = await createOrder(token, orgId, merchantId, {
    type: 'ONRAMP',
    originCurrencySymbol: 'COP',
    destinationCurrencySymbol: 'USDC',
    amountIn: 50000,
    destinationAccountId: wallet.id
  });
  
  console.log('ONRAMP order:', order.id);
  // In sandbox, crypto is "sent" to test address
}
```

--------------------------------

### GET /global-feature-flags

Source: https://docs.koywe.com/en/cli/api-cross-reference

List global feature flags.

```APIDOC
## GET /global-feature-flags

### Description
List global feature flags.

### Method
GET

### Endpoint
/global-feature-flags
```

--------------------------------

### Create a Payment Link in Python

Source: https://docs.koywe.com/en/core-concepts/orders-and-order-types

Basic implementation using the requests library.

```python
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['providedAction']}")
```

--------------------------------

### GET /documents

Source: https://docs.koywe.com/en/cli/api-cross-reference

List available document types.

```APIDOC
## GET /documents

### Description
List available document types.

### Method
GET

### Endpoint
/documents
```

--------------------------------

### GET /applicant-company-roles

Source: https://docs.koywe.com/en/cli/api-cross-reference

List applicant company roles.

```APIDOC
## GET /applicant-company-roles

### Description
List applicant company roles.

### Method
GET

### Endpoint
/applicant-company-roles
```

--------------------------------

### Execute ONRAMP Purchase Flow

Source: https://docs.koywe.com/en/core-concepts/orders-and-order-types

Example implementation of the full ONRAMP flow, including quote retrieval and deal creation.

```javascript
async function buyUSDC(token, orgId, merchantId, cryptoAccountId) {
  // 1. Get quote
  const quote = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/quotes`,
    {
      orderType: 'ONRAMP',
      executable: true,
      originCurrencySymbol: 'COP',
      destinationCurrencySymbol: 'USDC',
      amountIn: 50000
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
 
  console.log('Will receive:', quote.data.finalAmountOut, 'USDC');
  console.log('Exchange rate:', quote.data.exchangeRate);
  console.log('Fee:', quote.data.fee);
 
  // 2. Create deal (not order!)
  const response = await axios.post(
    `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/deals`,
    {
      destinationAccountId: cryptoAccountId,
      quoteId: quote.data.id
    },
    { headers: { 'Authorization': `Bearer ${token}` } }
  );
  
  return response.data;
}
 
const deal = await buyUSDC(token, orgId, merchantId, 'acc_77a80cf9-496c-4d72-9c33-fca3c8d5bcfe');
console.log('ONRAMP deal created:', deal.id);
console.log('Deal can be paid in full or partially');
```

--------------------------------

### GET /organizations/{orgId}/webhook-events

Source: https://docs.koywe.com/en/cli/api-cross-reference

Lists webhook events.

```APIDOC
## GET /organizations/{orgId}/webhook-events

### Description
List webhook events.

### Method
GET

### Endpoint
/organizations/{orgId}/webhook-events

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The unique identifier of the organization.
```

--------------------------------

### GET /economic-activities

Source: https://docs.koywe.com/en/cli/api-cross-reference

List all economic activities (global, not country-specific).

```APIDOC
## GET /economic-activities

### Description
List all economic activities (global, not country-specific).

### Method
GET

### Endpoint
/economic-activities
```
Tokens:
Raw