Merchant Acquiring Reseller

This page is the canonical onboarding reference for resellers. It walks through every API call, every document type, and every screening check between an empty merchant record and a live, transacting wallet.

The flow is ordered — most steps depend on prior ones. Skipping a step (for example, omitting companyNumber at organisation creation, or not assigning a DIRECTOR position before submitting ratification) causes the KYB ruleset to fail or routes the case to manual compliance review. Plan your UX to enforce the data minimums at the point of collection rather than trying to repair gaps at submission.

At a glance

Actors

Phase summary

Phase 1 — Organisation Setup

Step 01 — Create the merchant organisation

Register the legal entity. The returned organisationId is required for every subsequent call.

Actor: Reseller

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations

⚠️

companyNumber is mandatory for MATCH

Omitting companyNumber causes the Mastercard MATCH check to be skipped. A skipped MATCH flags the ratification result for manual compliance review and delays activation. For Sole Proprietors with no registered company, see Step 08 for the alternative document set.

Step 02 — Add organisation address

Submit registered and trading addresses separately if they differ.

Actor: Reseller

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/addresses

📘

Two calls if addresses differ

Call this endpoint twice if the trading address differs from the registered address — once with addressType: REGISTERED and once with addressType: PHYSICAL.

Phase 2 — Customer Registration & Positions

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

A 200 response means the customer exists — reuse the returned customerId and skip Step 04. A 404 means proceed to create.

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

Minimum fields for KYC

Additional fields for foreign nationals (use instead of national ID)

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

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

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}

⚠️

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

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" }

Phase 3 — Organisation Documents & T&Cs

Step 08 — Upload organisation business documents

All KYB-required business documents are uploaded against the organisation record. One call per document. All documents must be in place before ratification is submitted in Step 12.

Actor: Reseller

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/documents

Mandatory — all business types

CERT_OF_INCORP or CERT_OF_REGISTRATION · PROOF_OF_ADDRESS · TAX · BANK_ACCOUNT_CONFIRMATION · BANK_STATEMENT (Source of Funds)

⚠️

Sole Proprietor — no registered company

CERT_OF_INCORP and CERT_OF_REGISTRATION are not applicable. Upload the owner's personal KYC documents at the customer level (ID, proof of address) in Step 05, plus a TAX document (SARS income tax reference) at the organisation level. The KYB ruleset relies on the positional holder's KYC data in lieu of a company registration certificate.

📘

CERT_OF_INCORP vs CERT_OF_REGISTRATION

CERT_OF_REGISTRATION is the correct type for CIPC-issued documents. Use CERT_OF_INCORP if the tenant's KYB ruleset references that specific field name — they serve the same purpose.

Optional — supported document types

BUSINESS_LICENSE · PARTNERSHIP_DEED · TRUST_DEED · LOGO · PROOF_OF_FUNDS · ENHANCED_DUE_DILIGENCE · USA_W_8 · USA_W_9 · AFFIDAVIT

Step 09 — Upload signed T&Cs and website URL as organisation attachments

Records merchant acceptance of EFT Corporation terms and the merchant's website URL. Two attachments — call the endpoint twice.

Actor: Reseller

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/attachments

Call 1 — Signed T&Cs

Call 2 — Website URL

📘

Website URL — interim location

The website URL is required by compliance for the website audit in Step 17. It will become a dedicated field on the organisation creation endpoint in a future Eclipse API release — for now, record it as a website.url attachment.

Phase 4 — Verification & KYB Submission

Step 10 — Assign MCC

Set or confirm the merchant category code. The value is validated against the tenant's allowed list — codes not on the list are rejected.

Actor: Reseller

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}

The allowed list is held in the tenant config public.industrial.classification.allowed.values.{tenantId}.

If categoryCode was already set during organisation creation in Step 01, this call is only needed to update it.

Step 11 — Validate bank account via AVS

Account Verification Service validates that the supplied bank account details belong to the registered organisation. Pass onlyCheck=true to validate without creating a beneficiary record.

Actor: Reseller

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/beneficiaries?onlyCheck=true

Account details must match the uploaded bank statement document exactly. If validation passes and you want to persist the beneficiary record, repeat the call with saveOnPass=true.

AVS result

Step 12 — Submit KYB ratification

Triggers the automated screening pipeline. All document uploads from Steps 05 and 08 must be complete before this call.

Actor: Reseller

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/ratify
GET  /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/ratify

Submit with type: NORMAL. Poll the GET endpoint until results are populated.

Possible outcomes

Step 13 — Create the organisation wallet

This call triggers the KYB ruleset evaluation. The ruleset reads the latest ratification result, runs KYC on all DIRECTOR positions, and if all checks pass creates the wallet in BARRED status. Compliance unbars it in Phase 6.

Actor: Reseller

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/organisations/{organisationId}/wallets

⚠️

Ratification must pass first

The KYB ruleset must find a passing ratification result from Step 12. If ratification has not been run, or the last result was not a pass, this call is rejected by the ruleset with the message Please do KYB in order to create the wallet for this ruleset.

Phase 5 — Automated Screening

All steps in this phase run automatically once the wallet creation call succeeds. No reseller action is required — these are documented so you understand what is happening behind the scenes and so you can correlate inbound Jira tickets in Step 16 to the right merchant case.

Step 14 — Document legitimacy checks

Each uploaded document is validated by a type-specific processor.

Actor: System

Step 15 — Sanctions and MATCH screening

MATCH, OFAC, PEP, UN, EU, and internal blacklist checks run in parallel.

Actor: System

Step 16 — Compliance Jira ticket auto-raised

Fires only if any screening processor returns hits. A clean result produces no ticket and the flow continues to Phase 6 compliance review.

Actor: System

When a hit is returned, JiraRatifyResultAlerter opens an issue in the compliance project automatically.

Jira ticket summary format

TenantID - {tenantId}, OrgID - {orgId} -- KYB Organisation Compliance agency Checks Result

📘

Tenant configuration required

Jira auto-creation depends on compliance.jira.ticket.config.* being configured on the tenant.

Phase 6 — Compliance Review & Activation

Step 17 — Website audit and screening review

EFT Corporation compliance reviews the merchant's website and adjudicates any screening hits from Step 16.

Actor: Compliance

Manual review by the EFT Corporation compliance team. Ensure the merchant's website URL is recorded on the organisation via the Step 09 attachment. Where Jira tickets were raised, compliance adjudicates each hit — you may be contacted for additional documentation (Enhanced Due Diligence).

Possible outcomes

⚠️

Website audit is a gating step

If the website audit fails, the wallet cannot be unbarred regardless of the screening outcome.

Step 18 — Unbar the wallet

Compliance clears the BARRED flag and the wallet becomes live for transactions. Only compliance-role users can perform this action.

Actor: Compliance

Wallet status flags

Step 19 — Confirm go-live

Verify wallet status is ACTIVE and notify the merchant.

Actor: Reseller

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}

Verify status = 0 (ACTIVE).

📘

Retain these identifiers

organisationId, walletId, and the customerId of the primary contact are required for every future support, reporting, and configuration call. Store them against the merchant record in your own system.

Field, document, and code quick reference

Document types — at the customer level

NATIONAL_IDENTITY · BACK_OF_NATIONAL_IDENTITY · 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

Document types — at the organisation level

CERT_OF_INCORP · CERT_OF_REGISTRATION · PROOF_OF_ADDRESS · TAX · BANK_ACCOUNT_CONFIRMATION · BANK_STATEMENT · BUSINESS_LICENSE · PARTNERSHIP_DEED · TRUST_DEED · LOGO · PROOF_OF_FUNDS · ENHANCED_DUE_DILIGENCE · USA_W_8 · USA_W_9 · AFFIDAVIT

Attachment types — at the organisation level

terms.and.conditions · website.url

Position types

DIRECTOR · HEAD · OWNER · MANAGER · PARTNER · MEMBER · EMPLOYEE · PRIMARY_CONTACT

Business types

LIMITED_COMPANY · SOLE_PROPRIETOR · PARTNERSHIP · CLOSE_CORPORATION · TRUST · PUBLIC_LISTED_COMPANY

Identity types — AVS

Wallet status codes

Operational reminders

• Treat the entire payload across all 19 steps as confidential and PII-bearing. Transport must be TLS 1.3; at rest your storage layer must encrypt with AES-256 or equivalent.
• Never log base64EncodedDocument content, identity numbers, or password fields. Sanitise before persisting to your audit trail — PCI Requirement 10 plus ISO 27001 control A.8.10 (information deletion) apply.
• Apply the Principle of Least Privilege to the API user you call Eclipse with: scope it to the onboarding endpoints used in this flow and rotate credentials on a defined cadence.
• The reseller remains the merchant's first line of support. Compliance-driven outcomes (EDD requests, rejection) must be communicated through the reseller — EFT Corporation does not contact the merchant directly.

What's next

• Support and escalations → Support