Standalone Customer Use Cases
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.
Updated 3 months ago