Getting Started - Digital Wallets and KYC

What you'll build: a new customer with a funded digital wallet, verified through KYC.

Time: under 15 minutes.

Prerequisites: sandbox credentials from the Eclipse onboarding team. See Sandbox Environment if you don't have these yet.

Step 1 — Authenticate

All Eclipse API calls require a JWT bearer token.

POST {baseUrl}/eclipse-conductor/rest/v1/login
Content-Type: application/json

{
  "identity": "[email protected]",
  "password": "YourPassword123!"
}

Response:

{
  "headerName": "Authorization",
  "headerValue": "Bearer eyJhbGciOiJSUzI1NiJ9...",
  "tenantId": 42,
  "expires": "2026-05-19T10:30:00+00:00",
  "roles": ["TENANT_SYSTEM"]
}

Use headerValue as the value for the headerName header on every subsequent request (i.e. Authorization: Bearer eyJ...). Check expires before each request and re-authenticate before the token expires.

For production use, PKI-based authentication is recommended over password auth: Authentication and Authorisation.

API Reference →

Step 2 — Create a Customer

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "firstName": "Sipho",
  "lastName": "Dlamini",
  "phone1": "27821234567",
  "email": "[email protected]",
  "nationalIdentityNumber": "9001015009087",
  "userTypeId": 1
}

Response:

{
  "customerId": 3847291,
  "firstName": "Sipho",
  "lastName": "Dlamini",
  "phone1": "27821234567",
  "status": "ACTIVE",
  "created": "2026-05-19T08:30:00.000Z"
}

Save the customerId.

Note: phone1 must be digits only with no + prefix (e.g. 27821234567).

API Reference →

Step 3 — Create a Wallet

Link a digital wallet to the customer. Use the walletTypeId for the digital wallet type on your tenant.

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/wallets
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "walletTypeId": "{digitalWalletTypeId}",
  "currency": "ZAR"
}

Response:

{
  "walletId": 1092847,
  "customerId": 3847291,
  "name": "Digital Wallet",
  "currency": "ZAR",
  "currentBalance": 0.00,
  "availableBalance": 0.00,
  "status": "ACTIVE",
  "created": "2026-05-19T08:30:15.000Z"
}

Save the walletId.

To list available wallet types for your tenant:

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallet-types
Authorization: Bearer {jwt}

API Reference →

Step 4 — Fund the Wallet

Transfer funds from the pre-funded sandbox source wallet into the customer wallet.

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

{
  "fromWalletId": "{sourceWalletId}",
  "toWalletId": 1092847,
  "amount": 500.00,
  "description": "Initial wallet funding",
  "externalUniqueId": "fund-00000001"
}

Response: 204 No Content on success — wallet transfers return no body.

The transfer is synchronous; the funds are available in the destination wallet immediately. Use a new unique value for externalUniqueId on every transfer.

Step 5 — Verify the Balance

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/1092847
Authorization: Bearer {jwt}

Response:

{
  "walletId": 1092847,
  "currentBalance": 500.00,
  "availableBalance": 500.00,
  "currency": "ZAR",
  "status": "ACTIVE"
}

API Reference →

Step 6 — Trigger KYC

KYC (called ratification in Eclipse) verifies the customer's identity before they can transact. Sandbox tenants run KYC against test data.

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify
Authorization: Bearer {jwt}
Content-Type: application/json

{}

Response: An EclipseKycResult object with individual named check fields (e.g. sanctionsListCheck, selfieMatchesNationalIdentity) plus a top-level status string and lastModified timestamp.

{
  "status": "PENDING",
  "lastModified": "2026-05-19T08:32:00.000Z"
}

Step 7 — Check KYC Result

Poll GET .../ratify?offset=0&limit=1 until the top-level status is no longer PENDING (typically a few seconds in sandbox).

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify?offset=0&limit=1
Authorization: Bearer {jwt}

Response (passed):

[
  {
    "status": "PASSED",
    "lastModified": "2026-05-19T08:32:05.000Z",
    "sanctionsListCheck": { "checked": true, "passed": true, "pending": false },
    "selfieMatchesNationalIdentity": { "checked": true, "passed": true, "pending": false }
  }
]

If the status is FAILED, check individual fields where passed=false to understand which verification didn't succeed. See KYC Use Cases for handling failures and configuring KYC rulesets.

API Reference →

What You've Built

You have a customer with:

An active profile (customerId)
A funded digital wallet (walletId, balance 500.00 ZAR)
Passed KYC

This is the foundation for every Eclipse integration. From here, the customer can transact, receive payments, and be issued a card.

Next Steps

Topic	Where to go
Issue a card against this wallet	Getting Started: Card Issuance
Accept payments into a wallet	Getting Started: E-Commerce Acquiring
Wallet transfers and withdrawals	Wallet Use Cases
Full customer management reference	Standalone Customer Use Cases
Full KYC documentation	KYC Use Cases