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

NameDescription
AddressThe address of the customer or organisation.
AuthenticationThe 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 UserA 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 BalanceThe 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 URLThe 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/
CardA physical to virtual payment card, such as an EMV Card.
Current BalanceThe 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.
CustomerA customer of the tenant. A physical human being with name, details etc.
Customer IDA unique system generated numeric identifier for a customer which never changes for the lifetime of the customer. E.g. 12345
ID NumberThe legal reference number for a customer - e.g. a national identity number or passport number.
DepositA 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 IDSome 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 IDAPI’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.
IdentityA tenant or customers username used in conjunction with a password and possibly one time pin or public key when authenticating.
JWTJSON Web Token used as an Authorization header on all HTTP calls to indicate to the backend which authenticated tenant/customer is doing the call
OrganisationOrganisation 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 IDA 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 OTPA 6 digit code SMS’d to a customer (OTP) as a means of verifying the customer has access to their registered phone number.
PKIA 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.
PositionThe 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 KeyThe 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 KeyThe 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.
ReservationsFunds 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).
RatifyEclipse’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 IdentityThe identity of a tenant system used to authenticate with Eclipse.
Tenant IDUnique identifier for a tenant. Created by the system when a tenant is created
3DS3-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.
TransactionAn entry on the Eclipse ledger representing a debit or credit on a wallet.
TransferA 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 CodeA 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 UpThe process of a customer using a bank account, credit card, debit card etc. to increase the balance of their Eclipse wallet.
UsernameSame as identity. Used for logging in.
WalletA wallet is an entity that securely stores payment information and can be used by tenants for disbursements and collections.
Wallet Minimum BalanceWallet 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 IDUnique identifier for a type of wallet.
WithdrawalThe 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 IDWallets 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.