--- updatedAt: 2026-08-06T19:16:00.000Z agentTools: projectIndex: https://developer.eftcorp.com/llms.txt --- # Getting Started - Digital Wallets and KYC Authenticate, onboard a customer, open a digital wallet, fund it, and run KYC — a complete walkthrough with real API calls. **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](getting-started-on-sandbox) if you don't have these yet. *** ## Step 1 — Authenticate All Eclipse API calls require a JWT bearer token. ```http POST {baseUrl}/eclipse-conductor/rest/v1/login Content-Type: application/json ``` ```json { "identity": "admin@yourcompany.co.za", "password": "YourPassword123!" } ``` **Response:** ```json { "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](https://developer.eftcorp.com/docs/authentication-and-authorisation). [API Reference →](https://developer.eftcorp.com/reference/post_eclipse-conductor-rest-v1-authentication-login) *** ## Step 2 — Create a Customer ```http POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers Authorization: Bearer {jwt} Content-Type: application/json ``` ```json { "firstName": "Sipho", "lastName": "Dlamini", "phone1": "27821234567", "email": "sipho.dlamini@example.co.za", "nationalIdentityNumber": "9001015009087", "userTypeId": 1 } ``` **Response:** ```json { "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 →](https://developer.eftcorp.com/reference/post_eclipse-conductor-rest-v1-tenants-tenantid-customers) *** ## Step 3 — Create a Wallet Link a digital wallet to the customer. Use the `walletTypeId` for the digital wallet type on your tenant. ```http POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/wallets Authorization: Bearer {jwt} Content-Type: application/json ``` ```json { "walletTypeId": "{digitalWalletTypeId}", "currency": "ZAR" } ``` **Response:** ```json { "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: ```http GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallet-types Authorization: Bearer {jwt} ``` [API Reference →](https://developer.eftcorp.com/reference/post_eclipse-conductor-rest-v1-tenants-tenantid-customers-customerid-wallets) *** ## Step 4 — Fund the Wallet Transfer funds from the pre-funded sandbox source wallet into the customer wallet. ```http POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/transfers Authorization: Bearer {jwt} Content-Type: application/json ``` ```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 ```http GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/1092847 Authorization: Bearer {jwt} ``` **Response:** ```json { "walletId": 1092847, "currentBalance": 500.00, "availableBalance": 500.00, "currency": "ZAR", "status": "ACTIVE" } ``` [API Reference →](https://developer.eftcorp.com/reference/get_eclipse-conductor-rest-v1-tenants-tenantid-wallets-walletid) *** ## 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. ```http POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify Authorization: Bearer {jwt} Content-Type: application/json ``` ```json {} ``` **Response:** An `EclipseKycResult` object with one field per named check (e.g. `sanctionsListCheck`, `selfieMatchesNationalIdentity`), each carrying `checked`/`passed`/`pending`/`comment`. Checks that run inline are fully resolved by the time this call returns. ```json { "sanctionsListCheck": { "checked": true, "passed": true, "pending": false }, "selfieMatchesNationalIdentity": { "checked": true, "passed": true, "pending": false }, "lastModified": "2026-05-19T08:32:00.000Z" } ``` ### Note `EclipseKycResult` has a top-level `status` field in its schema, but the ratify pipeline never populates it — it stays absent unless an admin sets it manually via the Admin Portal. Don't build logic around it; check the individual per-check fields instead. *** ## Step 7 — Check KYC Result Some checks — for example Standard Bank's `sbsaRelyComplyCheck` — run asynchronously and come back with `pending: true` before they resolve. If every check that applies to this customer is `checked: true` with no `pending: true` items, the Step 6 response is already final. Otherwise, poll: ```http GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify?offset=0&limit=1 Authorization: Bearer {jwt} ``` **Response:** ```json [ { "sanctionsListCheck": { "checked": true, "passed": true, "pending": false }, "selfieMatchesNationalIdentity": { "checked": true, "passed": true, "pending": false }, "lastModified": "2026-05-19T08:32:05.000Z" } ] ``` Check each item's `passed` field to see what succeeded or failed — `false` means that check didn't pass, and `comment` explains why. See [Understanding Smart Failures](https://developer.eftcorp.com/docs/kyc-use-cases#understanding-smart-failures) for how to read the `reason` field on the wallet-types endpoint, and [Handling the Asynchronous sbsaRelyComplyCheck](https://developer.eftcorp.com/docs/kyc-use-cases#handling-the-asynchronous-sbsarelycomplycheck) for the polling pattern to use when a check comes back `pending`. [API Reference →](https://developer.eftcorp.com/reference/get_eclipse-conductor-rest-v1-tenants-tenantid-customers-customerid-ratify) *** ## 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](getting-started-card-issuance) | | Accept payments into a wallet | [Getting Started: E-Commerce Acquiring](getting-started-with-e-commerce-acquiring) | | Wallet transfers and withdrawals | [Wallet Use Cases](https://developer.eftcorp.com/docs/wallet-use-cases) | | Full customer management reference | [Standalone Customer Use Cases](https://developer.eftcorp.com/docs/standalone-customer-use-cases) | | Full KYC documentation | [KYC Use Cases](https://developer.eftcorp.com/docs/kyc-use-cases) |