Organisations let you model merchants for payment acceptance and group customers when more complex permissions are needed. Examples include onboarding a business as a merchant, managing shared wallets where multiple users transact, or linking a minor customer to a guardian for KYC compliance.

Register a New Organisation

Prerequisites:

Valid bearer token
KYB documents ready to upload (company registration certificate, ID documents of directors)

Step 1 — Create the Organisation

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "name": "Dlamini Trading (Pty) Ltd",
  "tradingName": "Dlamini Traders",
  "email": "[email protected]",
  "phone1": "27115551234",
  "companyNumber": "2021123456",
  "taxNumber": "9876543210",
  "industrialSector": "Retail",
  "industrialClassification": "General Merchandise",
  "categoryCode": 5999,
  "type": "BUSINESS",
  "externalUniqueId": "org-dlamini-001"
}

Response (201 Created):

{
  "organisationId": 88142,
  "tenantId": 42,
  "name": "Dlamini Trading (Pty) Ltd",
  "tradingName": "Dlamini Traders",
  "email": "[email protected]",
  "phone1": "27115551234",
  "companyNumber": "2021123456",
  "taxNumber": "9876543210",
  "status": "ACTIVE",
  "externalUniqueId": "org-dlamini-001",
  "created": "2026-05-19T10:00:00.000Z"
}

Store the organisationId — it is required for all subsequent calls.

Step 2 — Add Address Details

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/addresses
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "line1": "45 Commerce Street",
  "line2": "Newtown",
  "city": "Johannesburg",
  "state": "Gauteng",
  "postalCode": "2001",
  "country": "ZAF",
  "addressType": "REGISTERED"
}

Response (201 Created): Returns the address object with a system-assigned addressId.

Step 3 — Upload KYB Documents

Upload company registration and director identity documents as base64-encoded content.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/documents
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "documentType": "COMPANY_REGISTRATION",
  "fileName": "cipc_cert.pdf",
  "contentType": "application/pdf",
  "content": "base64EncodedPdfHere..."
}

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/documents
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "documentType": "NATIONAL_IDENTITY",
  "fileName": "director_id.jpg",
  "contentType": "image/jpeg",
  "content": "base64EncodedImageHere..."
}

Step 4 — Add Customer Positions to the Organisation

Customers become members of an organisation by being assigned a position. Different positions can have different permissions (e.g. OWNER, DIRECTOR, MEMBER).

Prerequisite: The customer must already exist — see Customer Use Cases.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/positions
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "customerId": 4829104,
  "position": "OWNER"
}

Response (201 Created):

{
  "positionId": 77021,
  "organisationId": 88142,
  "customerId": 4829104,
  "position": "OWNER",
  "status": "ACTIVE",
  "created": "2026-05-19T10:05:00.000Z"
}

Step 5 — Run KYB (Ratify)

Once the profile, address, and documents are uploaded, trigger the KYB pipeline.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/ratify
Authorization: Bearer {jwt}
Content-Type: application/json

{}

Response (200 OK):

{
  "ratifyResultId": 98280,
  "organisationId": 88142,
  "status": "COMPLETED",
  "kycStatus": "PASSED",
  "riskScore": 12,
  "results": [
    { "processor": "OcrCheck", "status": "PASSED" },
    { "processor": "SdnCheck", "status": "PASSED" },
    { "processor": "RelyComplyCheck", "status": "PASSED" }
  ],
  "created": "2026-05-19T10:10:00.000Z"
}

See Ratify Use Cases for full details on the KYB processor pipeline.

Step 6 — Create an Organisation Wallet

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/wallets
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "walletTypeId": 7825,
  "status": "ACTIVE",
  "name": "Dlamini Trading Merchant Wallet",
  "currency": "ZAR",
  "externalUniqueId": "wallet-dlamini-001"
}

Response (201 Created):

{
  "walletId": 2081002,
  "organisationId": 88142,
  "tenantId": 42,
  "walletTypeId": 7825,
  "name": "Dlamini Trading Merchant Wallet",
  "currency": "ZAR",
  "status": "ACTIVE",
  "currentBalance": 0,
  "availableBalance": 0,
  "walletFriendlyId": "M741XPQR",
  "externalUniqueId": "wallet-dlamini-001",
  "created": "2026-05-19T10:15:00.000Z"
}

To link a specific customer (cardholder) to the wallet at creation time, include customerId in the request body. That customer must have a position in the organisation.

Register a Customer Under an Organisation

Customers within an organisation follow the same KYC onboarding flow as standalone customers, then are added to the organisation via a position assignment.

Complete the standard customer registration (Steps 1–4 of Customer Use Cases)
Add the customer as a position holder in the organisation (Step 4 above)
Create a wallet under the organisation linked to the customer:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/wallets
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "walletTypeId": 7825,
  "status": "ACTIVE",
  "name": "Member Wallet",
  "currency": "ZAR",
  "customerId": 4829104,
  "externalUniqueId": "wallet-member-sipho-001"
}

View Organisation Wallets

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/wallets
Authorization: Bearer {jwt}

Returns all wallets belonging to the organisation.

Update Organisation Information

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "organisationId": 88142,
  "email": "[email protected]",
  "phone1": "27115559999",
  "version": 1
}

Update Organisation KYB

If KYB fails or documents need to be refreshed, update the relevant profile fields and documents, then re-trigger ratify.

Step 1 — Update documents

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/documents/{documentId}
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "documentId": 20441,
  "documentType": "COMPANY_REGISTRATION",
  "fileName": "cipc_cert_updated.pdf",
  "contentType": "application/pdf",
  "content": "base64EncodedUpdatedPdfHere..."
}

Step 2 — Re-run KYB

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/ratify
Authorization: Bearer {jwt}
Content-Type: application/json

{}

Permissions Required

Permission	Description
`Organisation.CREATE.Allowed`	Create organisations
`Organisation.READ.Allowed`	View organisations
`Organisation.UPDATE.Allowed`	Update organisation profile
`OrganisationPosition.CREATE.Allowed`	Add members to an organisation
`Ratify.CREATE.Allowed`	Run KYB
`Wallet.CREATE.Allowed`	Create organisation wallets