Organizations & Merchants

The Organization-Merchant hierarchy is the foundation of how you structure your business in Koywe Payments.

Organizations

An Organization is the top-level entity that represents your company in the Koywe system.

What is an Organization?

• The root entity for your entire company
• Can contain multiple merchants (business units)
• Manages company-wide users and permissions
• Controls API credentials and access
• Handles organization-level reporting and billing

Organization Permissions

Organizations have hierarchical permissions:

• Organization-level users can access all merchants within the organization
• Root users have full administrative access
• API credentials can be scoped to organization or merchant level

Merchants

A Merchant represents an individual business unit, brand, or operational entity within your organization.

What is a Merchant?

• A sub-entity under an organization
• Has its own virtual accounts for each currency
• Processes payments independently
• Maintains separate transaction history
• Can have specific users and permissions

When to Use Multiple Merchants

Use separate merchants when you need to:

Merchant Automatic Resources

When a merchant is created, Koywe automatically provisions:

1. Virtual Accounts: One for each supported currency

   • COP (Colombian Peso)
   • BRL (Brazilian Real)
   • MXN (Mexican Peso)
   • CLP (Chilean Peso)
   • USD (US Dollar)
   • EUR (Euro)
   • And more…

2. Default Contact: Merchant information as a contact

   • Used for compliance and reporting
   • Represents the merchant in transactions

How They Work Together

API Operations

Getting Organization Information

async function getOrganizations(token) {
  const response = await axios.get(
    'https://api-sandbox.koywe.com/api/v1/user/organizations',
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Usage
const orgs = await getOrganizations(token);
console.log('Organizations:', orgs);

def get_organizations(token):
    response = requests.get(
        'https://api-sandbox.koywe.com/api/v1/user/organizations',
        headers={'Authorization': f'Bearer {token}'}
    )
    
    return response.json()
 
# Usage
orgs = get_organizations(token)
print(f'Organizations: {orgs}')

curl -X GET 'https://api-sandbox.koywe.com/api/v1/user/organizations' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response:

[
  {
    "id": "org_abc123",
    "name": "Acme Corporation",
    "country": "CO",
    "createdAt": "2025-01-01T00:00:00Z"
  }
]

Listing Merchants in an Organization

async function getMerchants(token, organizationId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${organizationId}/merchants`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Usage
const merchants = await getMerchants(token, 'org_abc123');
console.log('Merchants:', merchants);

def get_merchants(token, organization_id):
    response = requests.get(
        f'https://api-sandbox.koywe.com/api/v1/organizations/{organization_id}/merchants',
        headers={'Authorization': f'Bearer {token}'}
    )
    
    return response.json()
 
# Usage
merchants = get_merchants(token, 'org_abc123')
print(f'Merchants: {merchants}')

curl -X GET 'https://api-sandbox.koywe.com/api/v1/organizations/org_abc123/merchants' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response:

[
  {
    "id": "mrc_xyz789",
    "name": "Acme Store",
    "organizationId": "org_abc123",
    "status": "ACTIVE",
    "createdAt": "2025-01-15T00:00:00Z"
  },
  {
    "id": "mrc_def456",
    "name": "Acme Marketplace",
    "organizationId": "org_abc123",
    "status": "ACTIVE",
    "createdAt": "2025-02-01T00:00:00Z"
  }
]

Getting Specific Merchant Details

async function getMerchant(token, organizationId, merchantId) {
  const response = await axios.get(
    `https://api-sandbox.koywe.com/api/v1/organizations/${organizationId}/merchants/${merchantId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return response.data;
}
 
// Usage
const merchant = await getMerchant(token, 'org_abc123', 'mrc_xyz789');
console.log('Merchant details:', merchant);

Best Practices

Organization Structure

Merchant Strategy

Naming Conventions

Use clear, descriptive names:

✅ Good names:

• “Acme Store - Main E-commerce”
• “Acme Bogotá Location”
• “Acme Wholesale Division”

❌ Avoid:

• “Merchant 1”
• “Test Merchant”
• “New Merchant 2025”

Permissions and Access Control

Organization-Level Permissions

Users with organization-level access can:

• View all merchants
• Create new merchants
• Manage organization settings
• Generate API credentials

Merchant-Level Permissions

Users with merchant-level access can:

• View only assigned merchant(s)
• Process orders for that merchant
• Manage merchant contacts
• View merchant balances

API Credential Scoping

API credentials can be scoped to:

1. Organization Level

   • Access all merchants
   • Useful for platform-wide integrations

2. Merchant Level

   • Access only specific merchant
   • More secure for limited use cases

// Organization-level credentials can access any merchant
const orders = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
  { headers: { 'Authorization': `Bearer ${orgLevelToken}` } }
);
 
// Merchant-level credentials are pre-scoped
const orders = await axios.get(
  `https://api-sandbox.koywe.com/api/v1/organizations/${orgId}/merchants/${merchantId}/orders`,
  { headers: { 'Authorization': `Bearer ${merchantLevelToken}` } }
);

Real-World Example

Multi-Brand E-Commerce Company

Organization: FashionCo Inc.

Merchants:

1. PremiumBrand Store

   • High-end fashion e-commerce
   • Virtual accounts: COP, USD, EUR
   • Average transaction: $200 USD

2. BudgetBrand Store

   • Affordable fashion e-commerce
   • Virtual accounts: COP, BRL, MXN
   • Average transaction: $30 USD

3. FashionCo Marketplace

   • Third-party seller platform
   • Virtual accounts: COP, USD, BRL, MXN
   • Handles both PAYIN (customer) and PAYOUT (seller)

Benefits of this structure:

• Separate financial reporting per brand
• Different branding for payment experiences
• Independent balance management
• Clearer reconciliation

Next Steps