Integration Guides

Customer Use Cases

These use cases apply when customers are not grouped into organizations and there is no use of company cards or other corporate features. Instead, the focus is on simpler scenarios where a tenant sells directly to individual customers who use personal wallets or cards.

Register a New Customer with a Digital Wallet

In order to sign up a new customer and issue a digital wallet, first create the customer along with the required customer information and then create the wallet with a walletTypeId for a closed loop digital wallet.

Prerequisites

  • A valid JWT for API calls.
  • The customer should have KYC documentation available.

It is recommended to search for a customer to view any potential duplicates of the cardholder within the Tenant.

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers

Step 1 – Create Customer

Create a customer record with the required demographic fields.

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

{
  "firstName": "Sipho",
  "lastName": "Dlamini",
  "dateOfBirth": "1990-03-15",
  "phone1": "27821234567",
  "email": "[email protected]",
  "nationalIdentityNumber": "9003155012083",
  "externalUniqueId": "cust-sipho-001"
}

Response (201 Created):

{
  "customerId": 4829104,
  "tenantId": 42,
  "firstName": "Sipho",
  "lastName": "Dlamini",
  "dateOfBirth": "1990-03-15",
  "phone1": "27821234567",
  "email": "[email protected]",
  "nationalIdentityNumber": "9003155012083",
  "status": "ACTIVE",
  "externalUniqueId": "cust-sipho-001",
  "created": "2026-05-19T10:00:00.000Z"
}

The customerId returned is the permanent identifier for this customer. Store it — it is required for all subsequent calls.

Step 2 – Add Address Details

Add a physical address (required for most KYC wallet types).

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

{
  "line1": "12 Mandela Street",
  "line2": "Sandton",
  "city": "Johannesburg",
  "state": "Gauteng",
  "postalCode": "2196",
  "country": "ZAF",
  "addressType": "RESIDENTIAL"
}

Response (201 Created): Returns the address with a system-assigned addressId.

Step 3 – Upload KYC Documents

Upload identity documents as base64-encoded content. Supported document types: NATIONAL_IDENTITY, PASSPORT, FACIAL_PHOTO, PROOF_OF_ADDRESS, AUTO (auto-detect).

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/documents?performOcr=true&validateDocType=true
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "documentType": "NATIONAL_IDENTITY",
  "fileName": "id_front.jpg",
  "contentType": "image/jpeg",
  "content": "base64EncodedImageDataHere..."
}
POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/documents?performOcr=true&validateDocType=true
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "documentType": "FACIAL_PHOTO",
  "fileName": "selfie.jpg",
  "contentType": "image/jpeg",
  "content": "base64EncodedSelfieDataHere..."
}
📘

Note

  • Pass performOcr=true on ID documents so that OCR is performed at upload time, making the subsequent ratify call faster.
  • Pass validateDocType=true to reject the document immediately if it does not match the declared type. This surfaces document errors early in the journey rather than at ratify time.
  • Do not use COMPARISON_NATIONAL_IDENTITY, COMPARISON_PASSPORT, or COMPARISON_FACIAL_PHOTO for onboarding — those types are for post-onboarding comparison checks (e.g. password reset identity verification).

Step 4 – Kick Off Ratify (KYC)

Run the KYC pipeline against the uploaded documents and customer profile.

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

{}

Response (200 OK) — example result:

{
  "ratifyResultId": 98274,
  "userId": 4829104,
  "tenantId": 42,
  "ratifyType": "NORMAL",
  "verifiedStatus": "PENDING",
  "status": "COMPLETED",
  "created": "2026-05-19T10:05:00.000Z",
  "lastModified": "2026-05-19T10:05:00.000Z"
}

The verifiedStatus will be PENDING until manually reviewed or automatically accepted. resultData contains the serialised EclipseKycResult check details. Update the customer record or replace the document and re-call ratify until the required KYC level is achieved. To check which wallet types the customer is eligible for based on their current KYC status:

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/wallet-types

Step 5 – Create Wallet

Create a digital wallet for the customer once KYC has passed.

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

{
  "walletTypeId": 7825,
  "status": "ACTIVE",
  "name": "Sipho's Wallet",
  "currency": "ZAR",
  "externalUniqueId": "wallet-sipho-001"
}

Response (201 Created):

{
  "walletId": 1092847,
  "customerId": 4829104,
  "tenantId": 42,
  "walletTypeId": 7825,
  "name": "Sipho's Wallet",
  "currency": "ZAR",
  "status": "ACTIVE",
  "currentBalance": 0,
  "availableBalance": 0,
  "friendlyId": "R982DFP2",
  "externalUniqueId": "wallet-sipho-001",
  "created": "2026-05-19T10:10:00.000Z"
}

walletTypeId must correspond to a closed-loop digital wallet type. The wallet is immediately active and ready for top-ups and transfers.

Add a Card to a Digital Wallet

In order to add a card to a digital wallet, the digital wallet, WalletTypeId must be for a wallet of type closed loop digital wallet and all the card issuing parameters should be configured on that wallet type.

In order to issue a physical card, the card needs to be handed over to the customer. The physical debit card can be added to the wallet as a primary card after the wallet has been created and KYC has been complete. Depending on the card packaging, either the PAN, Pack ID or Card QR code will be used to register the physical card. Physical debit cards can be added to any wallet of wallet type closed loop digital wallet.

Prerequisites

To add a physical card to an existing wallet:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/cards
{
	"externalUniqueId": "68a72f21-1",
	"physicalCardIdentifier": {
		"qrCode": "1234567890"
	},
	"status": "ACTIVE",
	"name": "Card",
	"description": null,
	"walletTypeId": 5496,
	"cardType": "physical",
	"configuration": [],
	"accountNumber": "",
	"operationType": "PRIMARY_CARD"
}

To add a virtual card to an existing wallet:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/cards
{
	"externalUniqueId": "0d87cfb7-b",
	"status": "ACTIVE",
	"name": "Card",
	"description": null,
	"walletTypeId": 5496,
	"cardType": "virtual",
	"configuration": [],
	"accountNumber": "",
	"operationType": "PRIMARY_CARD"
}

You can now optionally call:

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/cards

This will return the cards belonging the customer.

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

This will return the wallets belonging to the customer.

You can now add additional cards to the wallet in the form of Supplementary and Add-On cards :(Add On and Supplementary Cards)

📘

Note

Only PCI compliant tenants can pass the PAN is as the physical card identifier. For non-PCI compliant tenants the packId or qrCode associated with the card must be used.

Register a New Customer and Issue a Physical Card (one step)

Prerequisites

  • A valid JWT for API calls.
  • Tenant config cardManagementSystem should be set to Postilion
  • A customer has been created and completed KYC as described in the section Register a New Customer and Issue a Digital Wallet and the card has been handed over to the customer.

To issue a wallet with a card in one step you need to specify the primary physical card identifier as either cardId, packId, pan, or qrCode. We also support combinations that include card pin and last 4 digits of the PAN.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customer/{customerId}wallets
{
	"externalUniqueId": "4ad7a652-4",
	"primaryPhysicalCardIdentifier": {
		"qrCode": "1234567890"
	},
	"status": "ACTIVE",
	"name": "Test Phys card",
	"description": null,
	"walletTypeId": 7825,
	"cardType": "physical",
	"configuration": [],
	"accountNumber": ""
}

Register a New Customer and Issue a Virtual Card (one step)

Eclipse cards can be issued automatically when a closed loop digital wallet is created - to enable this set wallet type parameter alwaysCreateCard to true.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/wallets
{
	"externalUniqueId": "70802005-4",
	"status": "ACTIVE",
	"name": "Test card",
	"description": "Description",
	"walletTypeId": 7825,
	"cardType": "virtual",
	"customerSearch": "",
	"searchBy": "lastName",
	"configuration": [],
	"accountNumber": ""
}

Locking Customer information for modification by the Customer

Typically once a customer has completed KYC and provisioned wallets there is certain customer information that should not be updated by the customer e.g. name, ID number, address, KYC documents, etc. Tenants can control this by setting the profileCompletionStatus field on the customer profile. This field is a bitmask that controls what information related to a customer can be updated by the CUSTOMER position. The field works as follows:

  • The least significant bit (bit 1) means basic profile data like last name is complete and cannot be changed by the CUSTOMER position.
  • Bit 2 indicates address data cannot be changed by the CUSTOMER position.
  • Bit 3 means documents are complete.
  • Bit 4 means attachments are complete.
  • Bit 5 means DOB is validated and cannot be changed by the CUSTOMER position.
  • Bit 6 means National Identity is validated and cannot be changed by the CUSTOMER position.

E.g. To disallow changing attachments, documents, and addresses only, and still allow the customer profile to be updated the profileCompletionStatus field would be set to binary 1110 which equals decimal 14.

In the event that information needs to be updated admin users with sufficient permissions can update the information or they can reset the profileCompletionStatus to allow modification by the CUSTOMER position.

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}
{
  "profileCompletionStatus": 14
}

Please note that updates to the profile status are allowed, even when the profile is locked.

Create a Customer Identity

Tenants may have use cases where their customers call the Eclipse APIs directly and not via the tenant. This requires the customers to have an identity and password so that the customer front end (app, web etc) can obtain a valid JWT for calling Eclipse APIs and only have access to their profile, wallets etc.

Prerequisites

  • A valid tenant JWT

Create Customer Identity and Password
Allow the customer to create their Identity and Password. This may be required for certain API authentication.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/identities
📘

Note

When passing a password for identity creation or updating, one can pass the new password in clear text or as a pre-hashed BCRYPT hash. The hash should ideally be a cost factor of 10 to 12. E.g. $2a$10$tMR2xhUpO0kEpJT9E7p2ZuiJaqxFVmpCJjYJG7H7ttstFq2ddjXfq

Search for a Customer

A tenant can search for customers using a range of filter fields.

Prerequisites

  • Valid JWT

Search Customer
You can search for a customer using:

  • Email
  • Last Name
  • ID number
  • Passport Number
  • Phone number
GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers

Update Customer Information

To update customers information

Prerequisites

  • Valid JWT
  • Customer ID

Step 1 – Update Customer information
Update info
This refers to the following API in swagger:

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}

Update Customer Address

To update a customers address

Prerequisites

  • Valid JWT
  • Pre-existing created addressId

Step 1 – Update the customer address

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/addresses/{addressId}

Update Customer Documentation

Update customer documentation

Prerequisites

  • Pre-existing created documentId
  • Valid JWT

Step 2 – Update the document

PUT /eclipse-conductor/rest/v1/tenants/{tenantId}/documents/{documentId}

Customer KYC Validation and Update

If required, you can validate and update a customer's KYC documents and KYC status.

Prerequisites

  • Customer Documents to be created and uploaded.
  • customerId
  • Valid JWT

Step 1 – Update profile, addresses, documents
PUT/DELETE the customers profile, documents and addresses with the necessary changes.

Step 2 – Validate Customer using Ratify

Run a KYC algorithm on the customer profile and update the KYC status

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify

This will return a detailed status of the checks passed/failed

Update Customer Status to "BARRED"

If any customer is suspected of fraud an administrator is able to freeze their wallets immediately by changing the customer to "BARRED" status which will have the following impacts:

  • Stop all wallets immediately
  • Not able to perform any transactions from any wallet
  • Cancel pending for withdrawal type "ZA_NEDBANK_EFT" and "ZA_NEDBANK_EFT_IMMEDIATE"
  • Once all withdrawals are cancelled, all the wallets which is belong to that customer will be set to BARRED status

Cancel Withdrawals

Below API will be used to cancel the withdrawals

PUT: /eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/{walletId}/withdrawals/{withdrawalId}
  1. Barred Wallet

Below API will be used to barred wallet of customer

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

To enable transfer for BARRED wallet, please configure below property at wallet type level.

  • Property name - barredWalletsAllowDeposits
  • Property value = true

This will only allow to transfer amount / deposit to BARRED wallet. It will not allow to deduct any amount from BARRED wallet.