Organization Setup & Invitations

This guide covers the public setup endpoints used before you start processing payments: organization invitations, merchant creation, user invitations, role assignment, and API credential generation.

Typical Setup Flow

1. Accept Organization Access

These endpoints are typically used when a new user is joining an existing organization:

POST /api/v1/auth/organization-invitation/redeem
POST /api/v1/auth/invitation/redeem
POST /api/v1/auth/invitation/check-status

Use the organization invitation flow for organization-wide access and the merchant invitation flow for merchant-scoped access.

2. List Organizations

After authentication, list the organizations the current user can access:


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

This response gives you the organizationId needed for all organization-scoped operations.

3. Create and Manage Merchants

Merchant lifecycle endpoints:

POST /api/v1/organizations/{organizationId}/merchants
GET /api/v1/organizations/{organizationId}/merchants
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}
PUT /api/v1/organizations/{organizationId}/merchants/{merchantId}
DELETE /api/v1/organizations/{organizationId}/merchants/{merchantId}

When a merchant is created, Koywe automatically provisions default resources such as contacts and virtual accounts. See Organizations & Merchants for the resource model.

Minimal Merchant Creation Example


curl -X POST 'https://api-sandbox.koywe.com/api/v1/organizations/YOUR_ORG_ID/merchants' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Colombia",
    "countrySymbol": "CO"
  }'

4. Invite Users and Assign Roles

Public invitation endpoints:

POST /api/v1/users/organizations/{organizationId}/invitations
GET /api/v1/users/organizations/{organizationId}/invitations
POST /api/v1/users/organizations/{organizationId}/merchants/{merchantId}/invitations
GET /api/v1/users/organizations/{organizationId}/merchants/{merchantId}/invitations

Public user-management endpoints:

GET /api/v1/organizations/{organizationId}/users
PUT /api/v1/organizations/{organizationId}/users
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/users
PUT /api/v1/organizations/{organizationId}/merchants/{merchantId}/users

Use organization invitations for company-wide administrators and merchant invitations for operational users limited to a specific merchant.

5. Create API Credentials

Credential endpoints:

POST /api/v1/auth/organizations/{organizationId}/credentials
POST /api/v1/auth/organizations/{organizationId}/merchants/{merchantId}/credentials
POST /api/v1/auth/organizations/{organizationId}/merchants/{merchantId}/pos/credentials/create

Use organization credentials when one integration needs broad access across merchants. Use merchant credentials when you want stricter isolation.

Merchant Credential Example


curl -X POST 'https://api-sandbox.koywe.com/api/v1/auth/organizations/YOUR_ORG_ID/merchants/YOUR_MERCHANT_ID/credentials' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "backend-service",
    "roles": ["merchant_root"]
  }'

6. Review Merchant Resources

Useful follow-up endpoints after setup:

GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/features
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/virtual-accounts
GET /api/v1/organizations/{organizationId}/merchants/{merchantId}/accounts/balances
GET /api/v1/organizations/{organizationId}/balances

These help confirm the merchant is ready for PAYIN, PAYOUT, and balance-management flows.

Best Practices

Keep sandbox and production organizations and credentials separate.
Prefer merchant-scoped credentials unless your use case truly needs organization-wide access.
Use invitations for ongoing access management instead of sharing credentials.
Capture and store the returned IDs for organizations, merchants, users, and credentials in your internal config store.