Getting Started

🏁 Getting Started

Complete integration guide for dashboard users and API developers

Getting Started with Koywe Payments API

This guide provides a comprehensive walkthrough for integrating with the Koywe Payments API. The integration process follows a two-fold approach to accommodate both business users and developers.

Overview

The Koywe integration process involves two main phases:

  1. Dashboard/Frontend Setup - Business users receive organization access and manage merchants through our web interface
  2. API Integration - Developers implement programmatic access using provided credentials and recommended endpoints

Integration Flow

Part 1: Dashboard/Frontend Setup

This section guides business users through the initial setup process using the Koywe dashboard interface.

Prerequisites

Before beginning the dashboard setup, ensure you have:

  • Organization invitation email from the Koywe team
  • Access to your organization’s email to receive and accept invitations
  • Basic understanding of your organization’s merchant structure needs

Step 1: Organization Root User Setup

Receiving and Accepting Organization Invitation

The Koywe team will send an organization invitation to your main user’s email address. This invitation provides root access to your entire organization within the Koywe platform.

Process:

  1. Receive invitation email from Koywe team
  2. Click invitation link and complete registration/sign-in
  3. Accept organization invitation to gain access
  4. Access the Koywe dashboard with root permissions

Understanding Organization Root Permissions

As an organization root user, you have full administrative access including:

  • Merchant management (create, view, edit, delete)
  • User management across all merchants
  • Organization-wide settings configuration
  • API credential generation and management

Step 2: Merchant Creation and Management

Creating Merchants via Dashboard

Process:

  1. Navigate to merchant management section
  2. Create new merchant with business details
  3. Configure merchant-specific settings
  4. Review automatically created default resources

Understanding Default Resources

When you create a merchant, the system automatically creates:

Virtual Accounts:

  • Payin accounts for temporarily holding incoming payments
  • Payout accounts for managing outgoing payments
  • Settlement accounts for final fund processing

Default Contact:

  • Contact information matching merchant details
  • Used for transaction reporting and compliance
  • Represents the merchant in reports and communications

Step 3: User Management

Inviting Users to Merchants

Process:

  1. Select target merchant
  2. Navigate to user management
  3. Send invitations with appropriate role assignments
  4. Monitor invitation status and user access

Permission Assignment

Key Concepts:

  • Creating user automatically receives root permissions over new merchant
  • This prevents merchants without any user permissions
  • Organization root users maintain access to all merchants
  • Permissions can be modified later via dashboard or API

Part 2: API Integration

This section provides guidance for developers implementing API integration with the Koywe Payments system.

Prerequisites

Before beginning API integration, ensure you have:

  • API key and secret provided by the Koywe team
  • Organization ID provided by the Koywe team
  • Development environment set up for API testing

Step 1: Authentication Setup

API Credentials

Your integration will use:

  • API key and secret for authentication
  • Organization ID for scoping operations
  • Bearer token for API requests

Authentication Flow

Process:

  1. Use provided API key and secret to authenticate
  2. Receive bearer token for subsequent requests
  3. Include token in all API requests
  4. Implement token refresh logic as needed

The Koywe team recommends following this sequence for optimal integration:

Organization Invitation Management

Purpose: Programmatically invite users to your organization

  • Send invitations to organization root users
  • Provide access to dashboard for frontend management
  • Assign appropriate organization-level roles

Merchant Creation

Purpose: Create merchants under your organization via API

  • Define merchant business details
  • Configure merchant settings programmatically
  • Automatically create default virtual accounts and contacts

Merchant User Invitations

Purpose: Invite users to specific merchants

  • Send targeted invitations for merchant-specific access
  • Assign merchant-level roles and permissions
  • Enable focused merchant management

API Credential Generation

Purpose: Generate API credentials for merchants

  • Create merchant-specific API keys
  • Enable merchant-scoped API operations
  • Support different credential types and permissions

Step 3: Understanding Default Resource Creation

Automatic Resource Creation

When creating merchants via API, the system automatically provisions:

Virtual Accounts:

  • Multiple account types for different payment flows
  • Multi-currency support
  • Automatic balance tracking and reporting

Default Contacts:

  • Merchant contact information
  • Transaction reporting integration
  • Compliance and regulatory documentation

Permission Inheritance

Key Concepts:

  • API operations inherit user permissions
  • Organization-level access enables merchant creation
  • Merchant creators automatically receive merchant permissions
  • Permissions can be modified post-creation

Step 4: Implementation Considerations

Environment Setup

Development Environment:

  • Use sandbox environment for testing
  • Separate credentials from production
  • Test complete integration flow

Production Environment:

  • Use production API credentials
  • Implement proper error handling
  • Monitor API usage and performance

Best Practices

Security:

  • Store credentials securely
  • Use HTTPS for all API communications
  • Implement proper token management

Error Handling:

  • Handle authentication failures
  • Manage API rate limits
  • Implement retry logic for transient failures

Testing:

  • Test complete integration workflow
  • Verify resource creation and permissions
  • Validate error scenarios

Next Steps

After completing this setup guide:

  1. Payment Processing: Review specific payment creation and processing endpoints
  2. Webhook Integration: Set up webhook handlers for real-time notifications
  3. Advanced Configuration: Explore additional API features and customization options
  4. Production Deployment: Implement security measures and monitoring for production use

Additional Resources

For additional support, contact the Koywe development team via Slack or to contacto@koywe.com or refer to our comprehensive API documentation.