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

1
async function getOrganizations(token) {
2
  const response = await axios.get(
3
    'https://api-sandbox.koywe.com/api/v1/user/organizations',
4
    {
5
      headers: { 'Authorization': `Bearer ${token}` }
6
    }
7
  );
8
  
9
  return response.data;
10
}
11
12
// Usage
13
const orgs = await getOrganizations(token);
14
console.log('Organizations:', orgs);

Response:

1
[
2
  {
3
    "id": "org_abc123",
4
    "name": "Acme Corporation",
5
    "country": "CO",
6
    "createdAt": "2025-01-01T00:00:00Z"
7
  }
8
]

Listing Merchants in an Organization

1
async function getMerchants(token, organizationId) {
2
  const response = await axios.get(
3
    `https://api-sandbox.koywe.com/api/v1/organizations/${organizationId}/merchants`,
4
    {
5
      headers: { 'Authorization': `Bearer ${token}` }
6
    }
7
  );
8
  
9
  return response.data;
10
}
11
12
// Usage
13
const merchants = await getMerchants(token, 'org_abc123');
14
console.log('Merchants:', merchants);

Response:

1
[
2
  {
3
    "id": "mrc_xyz789",
4
    "name": "Acme Store",
5
    "organizationId": "org_abc123",
6
    "status": "ACTIVE",
7
    "createdAt": "2025-01-15T00:00:00Z"
8
  },
9
  {
10
    "id": "mrc_def456",
11
    "name": "Acme Marketplace",
12
    "organizationId": "org_abc123",
13
    "status": "ACTIVE",
14
    "createdAt": "2025-02-01T00:00:00Z"
15
  }
16
]

Getting Specific Merchant Details

1
async function getMerchant(token, organizationId, merchantId) {
2
  const response = await axios.get(
3
    `https://api-sandbox.koywe.com/api/v1/organizations/${organizationId}/merchants/${merchantId}`,
4
    {
5
      headers: { 'Authorization': `Bearer ${token}` }
6
    }
7
  );
8
  
9
  return response.data;
10
}
11
12
// Usage
13
const merchant = await getMerchant(token, 'org_abc123', 'mrc_xyz789');
14
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

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

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