Integration Guides
  1. Direct Acquiring

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: Reseller

Register 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 parameterNotes
nationalIdentityNumberSA ID number
passportNumberForeign passport number
emailEmail address
phone1Mobile number
identityLogin identity username
asylumRefNumberAsylum 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

Minimum fields for KYC

FieldNotes
externalUniqueIdYour unique reference for this customer (6–100 chars)
firstNameLegal first name (2–50 chars)
lastNameLegal surname (2–50 chars)
dateOfBirthFormat: yyyyMMdd e.g. 19850214
nationalIdentityNumberSA ID number (5–20 chars)
nationalIdentityCountryOfIssuanceISO alpha-2 e.g. ZA
nationalIdentityDateOfIssuanceFormat: yyyyMMdd — not required for SA ID (derived from ID number); required for foreign ID / passport
nationalIdentityExpiryFormat: 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)

FieldNotes
passportNumberPassport number (5–20 chars)
passportCountryISO alpha-2 country of issue
passportDateOfIssuanceFormat: yyyyMMdd
passportExpiryFormat: yyyyMMdd
passportPlaceOfIssuanceCity or office of issuance
nationalityCountry of nationality

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

FieldNotes
documentTypeSee supported types below
base64EncodedDocumentBase64-encoded file content
mediaTypeimage/jpeg · image/png · application/pdf
performOcrQuery param — enables OCR on upload
validateDocTypeQuery 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

📘

See the full list in the quick reference.

Step 06 — Create customer identity (login)

Provision portal access credentials for the merchant admin user. Only required for individuals who need portal or API access — not required for silent directors or UBOs.

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

FieldNotes
identityUsername for login (3–40 chars) — typically the customer's email address
passwordLeave unset — trigger a password-set email via Step 07 instead
totpEnabledtrue to require TOTP MFA — response returns the QR seed
changeAfterISO 8601 — force password reset after this date
⚠️

Do not set a password at creation

Issuing a password in the API call means 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

FieldNotes
organisationIdThe org this position belongs to
positionSee position types below

Available position types
DIRECTOR · HEAD · OWNER · MANAGER · PARTNER · MEMBER · EMPLOYEE · PRIMARY_CONTACT

⚠️

At least one DIRECTOR is required for company structures

The KYB ruleset iterates all DIRECTOR positions and runs KYC on each one. If no directors are assigned the ruleset fails immediately. For Sole Proprietors use HEAD or MANAGER — the ruleset will check whichever positional holders apply to the business structure. Assign PRIMARY_CONTACT to the main point of contact in all cases.

After position assignment — send the welcome email

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" }
FieldNotes
typeLINK — sends a password-reset / set email to the customer's registered address

Navigation