Naming & Conventions

In order to best understand the API’s and their functionality, its key to cover the various names and conventions used in this document along with the Swagger

Name	Description
Address	The address of the customer or organisation.
Authentication	The process whereby a customer provides an identity & password to prove they are who they say they are and in response are given a token (JWT) to use on any further API calls showing who the call is being done by.
Admin User	A user with an identity which can administer a tenant and its customers and organizations. Tenants would have admin users for their employees and API access.
Available Balance	The amount of money in a wallet which is available to be spent, transferred or withdrawn (i.e. debited). This considers what reservations have been placed and what the minimum balance allowed on the wallet is. The formula for available balance is current balance - minimum balance - reservations.
Base URL	The Base URL is the initial part of an API URL, it is the host of the API. For the Eclipse sandbox environment the base URL is: https://eclipse-java-sandbox.ukheshe.rocks/eclipse-conductor/
Card	A physical to virtual payment card, such as an EMV Card.
Current Balance	The money that is earmarked as belonging to the customer, but not all of it may be available to them as some may be locked (reserved) for current transactions in progress, or unusable for normal transactions due to minimum balance restrictions. This is the value that would appear on the ledger as the balance of the wallet after each transaction and the value that sits in the database as the wallets balance at any point in time. Available balance is a calculation based off of current balance, reservations and minimum balance.
Customer	A customer of the tenant. A physical human being with name, details etc.
Customer ID	A unique system generated numeric identifier for a customer which never changes for the lifetime of the customer. E.g. 12345
ID Number	The legal reference number for a customer - e.g. a national identity number or passport number.
Deposit	A process whereby a customer can give cash to an Eclipse retail partner (e.g. Pick ‘n Pay) and have the corresponding amount show in their wallet. This is equivalent to a cash top-up.
External ID	Some APIs allow the caller to pass in their own transaction identifier for a transaction which can be used for reconciliation purposes. One can use the uniqueId for this as well but sometimes callers want to use the same externalId for multiple transactions which is not allowed with uniqueId but is allowed with externalId.
External Unique ID	API’s which result in a transaction on the Eclipse backend include a unique string passed by the caller which can be used to ensure that duplicate transactions are not processed more than once if there is some network issue or accidental transaction replay. These should be passed as a GUID/UUID created by the API caller or some other concatenated string uniquely identifying the request. These must be unique across all tenants and max length 50 characters.
Identity	A tenant or customers username used in conjunction with a password and possibly one time pin or public key when authenticating.
JWT	JSON Web Token used as an Authorization header on all HTTP calls to indicate to the backend which authenticated tenant/customer is doing the call
Organisation	Organisation is typically a business or group of people to which the customers are associated with. A tenant may add multiple organisations. (Any international transactions must be either reported against either an Organisation or Customer, not a Tenant)
Organisation ID	A unique system generated numeric identifier for an organisation. Typically only used for large partners integrating with Eclipse who want to sign up customers and indicate that those customers fall under a certain structure/organisation.
Phone OTP	A 6 digit code SMS’d to a customer (OTP) as a means of verifying the customer has access to their registered phone number.
PKI	A public key infrastructure (PKI) is a set of roles, policies, hardware, software and procedures needed to create, manage, distribute, use, store and revoke digital certificates and manage public-key encryption. The purpose of a PKI is to facilitate the secure electronic transfer of information for a range of network activities such as e-commerce, internet banking and confidential email. It is required for activities where simple passwords are an inadequate authentication method and more rigorous proof is required to confirm the identity of the parties involved in the communication and to validate the information being transferred.
Position	The defined customers position within an organisation that may allow Ukheshe to contact them for specific queries (such as support or accounts) and may be used to define specific access rights to that organisation.
Private Key	The key used to decrypt messages that have been encrypted using your public key. This key is kept secret and is only known to the key owner.
Public Key	The key used to encrypt messages being sent to the key owner. This key can be shared publicly and is used by others to send encrypted messages to the key owner.
Reservations	Funds in a wallet which cannot be spent as they are set aside for a transaction which is in progress or have not cleared yet. Reservations sum up to the difference between current balance and available balance (assuming minimum balance is zero).
Ratify	Eclipse’s platform for verifying the KYC details of a customer or Organisation. This is the process of capturing a customer's identity document, selfie and details and verifying they all match using OCR and facial pattern matching.
Store of Value (SoV)	The actual end platform that has the master of a wallet balance and ledger. For some wallet types, Eclipse is the store of value and for others such a prepaid cards, the SoV could be an issuing platform like PTS.
System Identity	The identity of a tenant system used to authenticate with Eclipse.
Tenant ID	Unique identifier for a tenant. Created by the system when a tenant is created
3DS	3-D secure - A process whereby an issuing bank interacts with their cardholder via an iFrame, or similar channel, to verify that the person doing the transaction is the cardholder. Typically via a OTP or banking app authentication process.
Transaction	An entry on the Eclipse ledger representing a debit or credit on a wallet.
Transfer	A funds movement consisting of a debit on one wallet and a credit on another. Both the sender and recipient end up with a transaction on their transaction history. Transfers always happen between two Eclipse wallets.
Transient QR Code	A temporary QR Code representing a fixed payment amount to be credited to the associated wallet if scanned & paid. These are typically MasterPass QR Codes and are a 10 digit number that can end up being recycled and reused and have an expiry date. They are used if a customer wants a QR Code that can be scanned and automatically show a fixed amount to be paid.
Top Up	The process of a customer using a bank account, credit card, debit card etc. to increase the balance of their Eclipse wallet.
Username	Same as identity. Used for logging in.
Wallet	A wallet is an entity that securely stores payment information and can be used by tenants for disbursements and collections.
Wallet Minimum Balance	Wallet types and wallets themselves can have an optional configuration “minimumBalance” which defaults to zero if not set. This is balance below which the current balance cannot be debited. Normally 0 suffices as this means the wallet cannot go negative. If a wallet is allowed to go negative (e.g. minimum balance -1000, then this becomes part of the available balance as per its definition. For example a wallet has minimumBalance -1000, current balance -100 and a reservation placed on it of 50, then the availableBalance is -100 - 50 - (-1000) = 850. I.e. 850 can be debited before an insufficient funds error would be returned.
Wallet Type ID	Unique identifier for a type of wallet.
Withdrawal	The opposite of a deposit. A withdrawal is initiated by a customer and allows them to receive cash at a partner retail store and the corresponding amount is debited from the customer’s wallet.
Wallet Friendly ID	Wallets have two unique identifiers - one is a system generated numeric (walletId) and the other is a system generated string (walletFriendlyId) of length 8 which is a mixture of CAPS alphanumeric and numeric which does not contain characters such as O,0,L,I as these can be difficult to distinguish in some fonts. An example walletFriendlyId: R982DFP2. 2 walletFriendlyId’s are unlikely to be similar and hence typing them and getting some characters wrong is unlikely to match a different wallet.