Global Integrator Use Cases

A global integrator is a special type of tenant on Eclipse that holds one or more funding wallets and can disburse funds to wallets in any other tenant on the platform. This enables use cases like payroll, loyalty payouts, insurance claim payments, and bulk disbursements — without the integrator needing to know in advance which tenants their recipients use.

Global integrators do not have customers or organisations of their own. Their identity is created with PKI authentication (mutual TLS) to secure high-value wallet access.

Authentication

Global integrators authenticate using PKI (RSA 4096) rather than a username/password. The Eclipse platform issues a JWT after verifying the client certificate.

For setup details, see PKI Authentication.

Customer / Wallet Lookup

Before transferring to a recipient, use the global wallet search to find their walletId across all tenants. The API is privacy-preserving: at least two search criteria must match before any results are returned, and all personal fields in the response are obfuscated.

GET /eclipse-conductor/rest/v1/global/wallets
Authorization: Bearer {jwt}

Query parameters (at least two must match the customer's profile):

Example — search by last name and phone:

GET /eclipse-conductor/rest/v1/global/wallets?lastName=Dlamini&phone=27821234567
Authorization: Bearer {jwt}

Response (200 OK):

[
  {
    "walletId": 1092847,
    "tenantId": 42,
    "tenantName": "Sipho Mobile Money",
    "walletFriendlyId": "R982DFP2",
    "walletName": "Sipho's Wallet",
    "walletTypeId": 7825,
    "status": "ACTIVE",
    "lastName": "Dl****i",
    "phone1": "+2782***4567",
    "customerId": 4829104
  }
]

Personal fields (lastName, phone1, nationalIdentityNumber, etc.) are partially masked with * characters. The walletId is never masked — store it once found rather than searching again during each payroll run. The API is rate-limited to discourage bulk scanning.

Privacy rule: The API returns a maximum of 100 records per call. A request with only one matching field will return no results.

Wallet Transfer (Disbursement)

Once you have the recipient's walletId, transfer from the integrator's wallet to any tenant's wallet using the standard wallet transfer endpoint.

POST /eclipse-conductor/rest/v1/tenants/{integratorTenantId}/wallets/{integratorWalletId}/transfer
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "toWalletId": 1092847,
  "amount": 1500.00,
  "currency": "ZAR",
  "description": "May payroll disbursement",
  "externalUniqueId": "payroll-2026-05-sipho-001"
}

Response (200 OK):

{
  "walletTransferId": 88120,
  "sourceWalletId": 9900001,
  "destinationWalletId": 1092847,
  "amount": 1500.00,
  "currency": "ZAR",
  "status": "COMPLETED",
  "description": "May payroll disbursement",
  "externalUniqueId": "payroll-2026-05-sipho-001",
  "created": "2026-05-19T14:00:00.000Z"
}

The transfer is immediate and atomic. An HTTP 2xx response means the funds have moved. Any other HTTP status means the transfer did not occur — no partial transfers are possible.

Always use a unique externalUniqueId per transfer (a UUID is recommended). If the network drops before you receive the response, retry with the same externalUniqueId to prevent double-payment — Eclipse will return the original result rather than creating a duplicate transaction.

Direct Cash Withdrawal for Recipients

Instead of transferring to an Eclipse wallet, the integrator can send a withdrawal token directly to a recipient's phone. The recipient takes the token to a participating cash outlet (ATM, retailer) to collect the funds.

Eclipse verifies that the destination phone does not receive more than R24 000 per month in withdrawal tokens as a fraud prevention control.

POST /eclipse-conductor/rest/v1/tenants/{integratorTenantId}/wallets/{integratorWalletId}/withdrawals
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "amount": 500.00,
  "currency": "ZAR",
  "description": "Insurance claim payout",
  "externalUniqueId": "claim-payout-sipho-001",
  "deliverToPhone": "+27821234567",
  "type": "ZA_NEDBANK_ATM"
}

Common withdrawal types for cash disbursements:

Response (201 Created):

{
  "withdrawalId": 55201,
  "walletId": 9900001,
  "amount": 500.00,
  "status": "PENDING",
  "type": "ZA_NEDBANK_ATM",
  "deliverToPhone": "+27821234567",
  "description": "Insurance claim payout",
  "externalUniqueId": "claim-payout-sipho-001",
  "created": "2026-05-19T14:05:00.000Z"
}

If deliverToPhone is provided, the recipient receives an SMS with the token and collection instructions. If omitted, the token is returned in the response body and the integrator is responsible for delivering it.

Withdrawal status values:

Eclipse sends a callback to the callbackUrl (if provided) when the withdrawal reaches a terminal status. You can also poll the withdrawal status:

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals/{withdrawalId}
Authorization: Bearer {jwt}

Integrator Wallet Balance

Check the current balance of any integrator wallet:

GET /eclipse-conductor/rest/v1/tenants/{integratorTenantId}/wallets/{integratorWalletId}
Authorization: Bearer {jwt}

Response (200 OK):

{
  "walletId": 9900001,
  "tenantId": 100,
  "currency": "ZAR",
  "status": "ACTIVE",
  "currentBalance": 985000.00,
  "availableBalance": 985000.00,
  "walletFriendlyId": "G1000001"
}

Reconciliation

Query by externalUniqueId

To verify a specific transfer, query the wallet transaction history filtering by your externalUniqueId:

GET /eclipse-conductor/rest/v1/tenants/{integratorTenantId}/wallets/{integratorWalletId}/history?externalUniqueId=payroll-2026-05-sipho-001
Authorization: Bearer {jwt}

Query by date range

To reconcile a payroll run, retrieve all transactions in a time window:

GET /eclipse-conductor/rest/v1/tenants/{integratorTenantId}/wallets/{integratorWalletId}/history?startDate[gteq]=2026-05-19T00:00:00Z&startDate[lt]=2026-05-20T00:00:00Z
Authorization: Bearer {jwt}

Response (200 OK):

[
  {
    "walletHistoryId": 441022,
    "walletId": 9900001,
    "amount": -1500.00,
    "balance": 985000.00,
    "type": "TRANSFER",
    "description": "May payroll disbursement",
    "externalUniqueId": "payroll-2026-05-sipho-001",
    "created": "2026-05-19T14:00:00.000Z"
  }
]

Bulk Disbursements

For large payroll runs, use the bulk transfer endpoint instead of individual calls. This accepts a list of recipients and processes all transfers atomically:

POST /eclipse-conductor/rest/v1/tenants/{integratorTenantId}/wallets/{integratorWalletId}/bulk-transfers
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "externalUniqueId": "payroll-run-2026-05-19",
  "transfers": [
    { "toWalletId": 1092847, "amount": 1500.00, "description": "May payroll", "externalUniqueId": "payroll-2026-05-sipho-001" },
    { "toWalletId": 1092848, "amount": 2000.00, "description": "May payroll", "externalUniqueId": "payroll-2026-05-thabo-001" }
  ]
}

See Wallet Use Cases — Bulk Transfer for the full bulk transfer API reference.

Permissions Required

Global integrator accounts are created by EFT Corporation with pre-configured permissions. The relevant permissions are: