Phase 2 — Customer Registration & Positions
Steps 3–7 of reseller onboarding — register directors, owners, and UBOs, upload their KYC documents, and link them to the organisation.
Part of Merchant Acquiring Reseller — Phase 2 of 6 · Actor: ResellerRegister each person behind the business, upload their KYC documents, and assign their position in the organisation. The KYB ruleset later runs KYC on every positional holder, so complete identity data here is essential.
Step 03 — Check if customer already exists
Avoid duplicate records — check by ID number, email, or passport before creating. Repeat for every director, owner, and UBO.
Actor: Reseller
HEAD /eclipse-conductor/rest/v1/tenants/{tenantId}/customers📎 API reference: Check if a customer exists
A 200 response means the customer exists — reuse the returned customerId and skip Step 04. A 404 means proceed to create.
| Query parameter | Notes |
|---|---|
nationalIdentityNumber | SA ID number |
passportNumber | Foreign passport number |
email | Email address |
phone1 | Mobile number |
identity | Login identity username |
asylumRefNumber | Asylum reference number |
Pass at least one of the above.
Step 04 — Create customer
Register each director, owner, and UBO as a customer. Minimum KYC fields must be populated at creation — the KYB ruleset runs KYC on every positional holder later, and incomplete identity data will cause that step to fail.
Actor: Reseller
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers📎 API reference: Register a new customer · Update a customer
Minimum fields for KYC
| Field | Notes |
|---|---|
externalUniqueId | Your unique reference for this customer (6–100 chars) |
firstName | Legal first name (2–50 chars) |
lastName | Legal surname (2–50 chars) |
dateOfBirth | Format: yyyyMMdd e.g. 19850214 |
nationalIdentityNumber | SA ID number (5–20 chars) |
nationalIdentityCountryOfIssuance | ISO alpha-2 e.g. ZA |
nationalIdentityDateOfIssuance | Format: yyyyMMdd — not required for SA ID (derived from ID number); required for foreign ID / passport |
nationalIdentityExpiry | Format: yyyyMMdd — not required for SA ID (SA ID does not expire); required for foreign ID / passport |
Additional fields for foreign nationals (use instead of national ID)
| Field | Notes |
|---|---|
passportNumber | Passport number (5–20 chars) |
passportCountry | ISO alpha-2 country of issue |
passportDateOfIssuance | Format: yyyyMMdd |
passportExpiry | Format: yyyyMMdd |
passportPlaceOfIssuance | City or office of issuance |
nationality | Country of nationality |
Ultimate Beneficial Owners (UBOs)
Every UBO must be registered as a customer, ID uploaded and KYC'dUBO stands for "Ultimate Beneficial Owner" — the real person(s) who ultimately own or control the company. They are the individuals who benefit from the company's profits or have significant influence over its operations and decision-making. You must register every individual with a 5% or more ownership stake or control as a customer here, upload their identity document in Step 05 — this is mandatory — and ensure it is KYC'd.
For each UBO, populate the following on the customer record (set at creation via the create-customer API, or later via the update-customer API):
| Field | Value |
|---|---|
other | Identifies the customer as a UBO and their ownership percentage — e.g. UBO – 25%. Complete for each UBO with 5% or more ownership. |
Record each UBO's source of funds as a customer attachment (SOURCE_OF_FUNDS) — see Step 05. Source of funds is not set as a field on the customer record.
Step 05 — Upload customer KYC documents
Upload supporting identity documents for each customer registered in Step 04. One call per document type. Repeat for every director, owner, and UBO.
Actor: Reseller
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/documents📎 API reference: Add a new document against the customer
| Field | Notes |
|---|---|
documentType | See supported types below |
base64EncodedDocument | Base64-encoded file content |
mediaType | image/jpeg · image/png · application/pdf |
performOcr | Query param — enables OCR on upload |
validateDocType | Query param — verifies content matches the declared type (requires performOcr=true) |
Mandatory — Green Book (SA ID Book)
NATIONAL_IDENTITY
Mandatory — Smart ID Card (both sides required)
NATIONAL_IDENTITY · BACK_OF_NATIONAL_IDENTITY
Optional — supported document types
PASSPORT · DRIVERS_LICENSE · BACK_OF_DRIVERS_LICENSE · TEMPORARY_IDENTITY · TEMPORARY_IDENTITY_RECEIPT · BIRTH_CERTIFICATE · FACIAL_PHOTO · ENHANCED_DUE_DILIGENCE · ASYLUM_PAPERS · VISA · WORK_PERMIT · TEMP_RESIDENCY_PERMIT · PERMIT · PROOF_OF_ADDRESS · BANK_STATEMENT · PROOF_OF_FUNDS · TAX · AFFIDAVIT · FOREIGN_CERTIFICATE
UBO identity documents are mandatoryFor every UBO (5% or more ownership), the identity document must be uploaded here and KYC'd — it is not optional. See the UBO note in Step 04.
See the full list in the quick reference.
Add the customer's source of funds (attachment)
The customer's source of funds is recorded as a customer attachment with type SOURCE_OF_FUNDS — not as a field on the customer record. This is required for every UBO.
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/attachments📎 API reference: Add a new attachment on the customer
| Field | Notes |
|---|---|
attachmentType | SOURCE_OF_FUNDS |
info | The source-of-funds value — one of the accepted values below |
mediaType | Media type of the attachment — required in practice, even for this info-only attachment. The API spec marks it optional, but the backend rejects a null media_type with 400 SQL001. Use text/plain for a text info value, or application/pdf / image/png / image/jpeg for a document. |
base64EncodedAttachment | Optional supporting document (Base64-encoded), if provided |
Source of funds — accepted values
Salary · Securities / Investments · Property (Commercial / residential investments) · Beneficiaries of trusts or foundations · Inheritance, gift, or donations · Business / Partnership · Divorce settlement · Sale of business or other principle asset · Savings · Sale of Investments · Loan · Maturity or surrender of life assurance policy · Insurance claims · Other court award · Other income · Relationship to third party · Business income / profits · Asset swap · Winnings · Trust donor · Passive income (rental, dividends, interest) · Other
Step 06 — Create customer identity (login) — optional
This step is optionalCreating a login identity is only required for individuals who need portal or API access (typically the merchant admin). It is not required for onboarding, KYB, or for silent directors / UBOs. Skip this step — and Step 07's welcome email — if the customer does not need to log in.
Provision portal access credentials for the merchant admin user.
Actor: Reseller
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/identities
HEAD /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/identities
GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/identities/{identity}📎 API reference: Create a username/password for a customer · Check if a customer has any identities · Get a specific customer identity
| Field | Notes |
|---|---|
identity | Username for login (3–40 chars) — typically the customer's email address |
password | Leave unset — trigger a password-set email via Step 07 instead |
totpEnabled | true to require TOTP MFA — response returns the QR seed |
changeAfter | ISO 8601 — force password reset after this date |
Do not set a password at creationIf you do create an identity, do not issue a password in the API call — that would mean the reseller has handled the credential. Defer to the password-set email triggered in Step 07 so the customer sets their own credential — least-privilege handling for authentication material.
Step 07 — Assign customer position in organisation
Links the customer to the organisation. The KYB ruleset checks every positional holder for KYC compliance.
Actor: Reseller
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/positions📎 API reference: Add a position held by the customer
| Field | Notes |
|---|---|
organisationId | The org this position belongs to |
position | See position types below |
Available position types
DIRECTOR · HEAD · OWNER · MANAGER · PARTNER · MEMBER · EMPLOYEE · PRIMARY_CONTACT
At least oneDIRECTORis required for company structuresThe KYB ruleset iterates all
DIRECTORpositions and runs KYC on each one. If no directors are assigned the ruleset fails immediately. For Sole Proprietors useHEADorMANAGER— the ruleset will check whichever positional holders apply to the business structure. AssignPRIMARY_CONTACTto the main point of contact in all cases.
After position assignment — send the welcome email (optional)
Optional — only if you created an identity in Step 06This is only applicable when the customer has a login identity (Step 06). Skip it otherwise.
Trigger a password-set link to the customer. This sends the welcome email with a one-time link for the customer to set their own password.
POST /eclipse-conductor/rest/v1/global/identities/{identity}/password-change-init{ "type": "LINK" }| Field | Notes |
|---|---|
type | LINK — sends a password-reset / set email to the customer's registered address |
Navigation
- ◀ Previous: Phase 1 — Organisation Setup
- ▲ Overview: Merchant Acquiring Reseller
- ▶ Next: Phase 3 — Organisation Documents & T&Cs
Updated about 1 hour ago