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

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.
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
WalletJSON Web Token used as an Authorization header on all HTTP calls to indicate to the backend which authenticated tenant/customer is doing the call
CustomerA customer of the tenant. A physical human being with name, details etc.
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 auth process.
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.
UsernameSame as identity. Used for logging in
Customer IDA unique system generated numeric identifier for a customer which never changes for the lifetime of the customer. E.g. 12345
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.
ID NumberThe legal reference number for a customer - e.g. a national identity number or passport number.
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.
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
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).
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.
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.
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.
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.
TransactionAn entry on the Eclipse ledger representing a debit or credit on a wallet.
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.
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.
Top UpThe process of a customer using a bank account, credit card, debit card etc to increase the balance of their Eclipse wallet.
Base URLEclipse sandbox environment:
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.
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.
Tenant IDUnique identifier for a tenant. Created by the system when a tenant is created
Wallet Type IDUnique identifier for a type of wallet
OrganizationOrganization is typically a business or group of people to which the customers are associated with. A tenant may add multiple organizations. (Any international transactions must be either reported against either an Organization or Customer, not a Tenant)
AddressThe address of the customer or organization.
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.
System IdentityThe identity of a tenant system used to authenticate with Eclipse
CardA physical to virtual payment card, such as an EMV Mastercard.
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.
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.
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.