--- updatedAt: 2026-08-06T19:16:00.000Z agentTools: projectIndex: https://developer.eftcorp.com/llms.txt --- # Organisation Use Cases Creating organisations, running KYB, and managing organisation wallets and members. 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 ```http POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations Authorization: Bearer {jwt} Content-Type: application/json { "name": "Dlamini Trading (Pty) Ltd", "tradingName": "Dlamini Traders", "email": "contact@dlaminitrading.co.za", "phone1": "27115551234", "companyNumber": "2021123456", "taxNumber": "9876543210", "industrialSector": "Retail", "industrialClassification": "General Merchandise", "categoryCode": 5999, "type": "BUSINESS", "externalUniqueId": "org-dlamini-001" } ``` **Response (201 Created):** ```json { "organisationId": 88142, "tenantId": 42, "name": "Dlamini Trading (Pty) Ltd", "tradingName": "Dlamini Traders", "email": "contact@dlaminitrading.co.za", "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 ```http 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. ```http 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..." } ``` ```http 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](https://developer.eftcorp.com/docs/standalone-customer-use-cases). ```http POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/positions Authorization: Bearer {jwt} Content-Type: application/json { "customerId": 4829104, "position": "OWNER" } ``` **Response (201 Created):** ```json { "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. ```http POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/ratify Authorization: Bearer {jwt} Content-Type: application/json {} ``` **Response (200 OK):** The response is a flat object with one result per KYB check that ran — there is no top-level `status`/`kycStatus`/`riskScore` wrapper. Each check reports `checked`/`passed`/`pending`, matching the shape used for KYC (customer) ratify: ```json { "companyNumberMatchesCertOfIncorp": { "checked": true, "passed": true, "pending": false, "lastRun": "2026-05-19T10:10:00.000Z", "inReview": false }, "sanctionsListCheck": { "checked": true, "passed": true, "pending": false, "lastRun": "2026-05-19T10:10:00.000Z", "inReview": false }, "pepCheck": { "checked": true, "passed": true, "pending": false, "lastRun": "2026-05-19T10:10:00.000Z", "inReview": false }, "lastModified": "2026-05-19T10:10:00.000Z" } ``` See [KYC Use Cases](https://developer.eftcorp.com/docs/kyc-use-cases) for the full list of checks, how rulesets combine them, and how to read smart failures. ## Step 6 — Create an Organisation Wallet ```http 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):** ```json { "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. 1. Complete the standard customer registration (Steps 1–4 of [Customer Use Cases](https://developer.eftcorp.com/docs/standalone-customer-use-cases)) 2. Add the customer as a position holder in the organisation (Step 4 above) 3. Create a wallet under the organisation linked to the customer: ```http 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 ```http GET /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/wallets Authorization: Bearer {jwt} ``` Returns all wallets belonging to the organisation. *** # Update Organisation Information ```http PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId} Authorization: Bearer {jwt} Content-Type: application/json { "organisationId": 88142, "email": "newemail@dlaminitrading.co.za", "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** ```http 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** ```http 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 |