The following use cases are ones where there is no grouping of customers into organisations and no use of company cards and other functionality for corporate use cases. The simpler cases focus on a tenant selling to customers who have wallets/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
First create a customer providing all required fields

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

The system will reply with the customer along with its unique customerId

Step 2 – Add Address Details
Add address details for the customer (if required for the level of KYC required for the wallet type)

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

Step 3 – Add KYC Doc info
Add customer supporting KYC documentation (if required for the level of KYC required for the wallet type) There are several types of document that customer can upload for KYC e.g FACIAL_PHOTO, NATIONAL_IDENTITY, PASSPORT, PROOF_OF_ADDRESS. We can also use document type AUTO if we want to let eclipse detect the type of uploaded document whether it is NATIONAL_IDENTITY or PASSPORT.

📘
Note

Customer must not use COMPARISON_NATIONAL_IDENTITY, COMPARISON_PASSPORT, COMPARISON_FACIAL_PHOTO for KYC purposes as these document types are used for checking if the document matches what is already on file (The Typical use case for these document type are password resets etc)

If a document is a passport/ID and is going to be used for KYC, then it is advised to pass query param performOcr=true so OCR is done at the time of upload so that the ratify call, later on, is faster.

If a document is a passport/ID or selfie (FACIAL_PHOTO) and is going to be used for KYC, then it is advised to pass query param validateDocType=true - this will validate the document and fail on upload if not validated. This allows the KYC journey to address document issues as they are uploaded instead of waiting till the ratify call is done.

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/documents?performOcr=true&validateDocType=true

Step 4 – Kick-off Ratify

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

This will kick off the various checks and algorithms in Eclipse to analyse the customer profile, address/s and attached documents to update the customers KYC status. This call will return detailed results of the KYC process such as what passed and what failed in the various tests. The customer profile can be updated along with addresses and documents and ratified again until the required KYC status for the wallet type is obtained. The wallet type determines what level of KYC is required for a customer/organisation to own that type of wallet.

📘
Note
A user can always determine what wallets can be provisioned based on the provided KYC/B information by calling the wallet-types endpoint for the customer or for the organisation.

Step 5 – Create Wallet
Create a digital wallet for the customer. This refers to the following API in swagger:

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

WalletTypeId must be for a wallet of type closed loop digital wallet.

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

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.

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 :(https://developer.ukheshe.com/docs/card-on-file-use-cases#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.

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.

Give Customer Eclipse API Access

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 that 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

Tenant can search customer using eclipse Apis

Prerequisites

Valid JWT

Search Customer
You can search for a customer using either:
Email, Last Name, ID number, Passport Number or phone number

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

A cross tenant transfer thus results in 8 ledger entries in total (4 DR/CR pairs). This is all done automatically by Eclipse. The transfer itself is done like any other transfer where the source and destination wallet details are provided.

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}

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.

Standalone Customer Use Cases

Register a New Customer with a Digital Wallet

📘
Note

📘
Note

Add a Card to a Digital Wallet

📘
Note

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

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

Locking Customer information for modification by the Customer

Give Customer Eclipse API Access

Search for a Customer

Update Customer Information

Update Customer Address

Update Customer Documentation

Customer KYC Validation and Update

Update Customer Status to "BARRED"

Register a New Customer with a Digital Wallet

📘Note

📘Note

Add a Card to a Digital Wallet

📘Note

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

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

Locking Customer information for modification by the Customer

Give Customer Eclipse API Access

Search for a Customer

Update Customer Information

Update Customer Address

Update Customer Documentation

Customer KYC Validation and Update

Update Customer Status to "BARRED"

📘
Note

📘
Note

📘
Note