Cloud Wallet is a powerful but simple double-entry ledger API. Integrate it into your app to implement new business models, internal economies, asset accounting and more.
Cloud Wallet is an API that cover asset accounting at scale.
This page covers basic concepts of the API. A more detailed description, is available here: https://rapidapidocs.walletapi.cloud/
You are welcome to use our OpenAPI definition: https://rapidapidocs.walletapi.cloud/Rapid_API.yaml
First, let's get a feel for the key terms used.
A project is the first item you create. Projects store customer records and wallets that are linked to one application or focus on one idea. Transactions are available only for wallets within one project.
An asset can be anything of value owned by someone, such as virtual or real currencies, bonus points, or subway rides. Inventory items like water bottles, bags of coffee beans, or packets of sugar can also be assets. Asset amounts are stored in wallets.
A customer is a record that reflects your existing users and enables you to create wallets for them. Basically, customers own wallets. You decide how you map customers into your system. People, devices, vehicles, or appliances that contain value can act as customers. We respect your users' privacy and only ask you to provide an ID that you can later identify and map back to the user in your system.
A wallet stores value, as well as the user’s balance history. Each wallet belongs either to a customer or to you (then it is called a system wallet). Assign as many wallets to your users or devices as you’d like. The wallet balance can’t dip below zero.
An operation is a basic atomic action which updates one or two wallet balances. Each operation posts an entry to the ledger of each wallet it affects.
There are three types of operations:
An operation can be performed only within a transaction.
A transaction is a set of operations (one or more) that must be performed together. When a transaction is performed, operations are performed in the order in which they’re listed.
When all the operations in a set can be performed successfully, the whole transaction will be completed. If any single operation fails, all the other operations will be reverted back and the transaction will fail.
A wallet entry is a record in a wallet ledger about an event.
There are several types of events:
Cloud Wallet is based on the idea that you already have your customer database integrated with your app or service. There is no need to copy all the information about your customers into our system. All we need is a unique ID for your customer that matches the information listed in your database. A number, string, or email will work (we treat these IDs as strings). You may supply additional information, such as the customer’s name or a description, but that is only for your convenience. That data is not required for our API to operate properly. The endpoints that create customer records employ the same logic as UPSERT (insert if not exist, otherwise update).
Each wallet is created in open mode. Open wallets can hold a balance and participate in transactions. Suspended wallets keep holding their balance, but you’re unable to perform transactions with them. Only empty wallets can be closed, and you can't reopen wallets once you’ve closed them.
Most of the wallets in your projects will be customer wallets. These wallets belong to customers and should reflect assets owned by the customers.
If you need to record something that you, the system operator, own, you can create system wallets. They are linked to a project and usually are created to collect commissions or accept fees, among other reasons.
Our API is web-based, yet the Internet is not a 100% reliable means of communication. Occasionally, you will initiate a transaction but be unable to complete it due to connection problems. Also, trying again may result in a duplicate transaction. To avoid any duplicate transactions, you, as the transaction initiator, are required to provide a Reference ID.
A reference ID is a string identifier that must be unique for each project. If the connection gets interrupted, it’s safe to repeat the call with the same Reference ID. If the connection broke before it reached our servers, your retry call will get through. Otherwise, you will receive a DuplicateReferenceId error and a current transaction state (including its ID). This will effectively recover the transaction information.
You decide how you make unique identifiers. The easiest way is to generate a UUID-like random value.
Internally, each transaction undergoes several stages. In most cases, you will see transactions in one of two final states: Transaction Completed or Transaction Failed.
Transaction Completed means that all the operations were performed successfully.
Transaction Failed means that at least one operation failed, which resulted in all the operations being rolled back. You can find which operation caused the rollback and why in the result data.
Ultimately, either all the operations in a transaction will be completed or none of them will. Internally, operations are performed in the order in which they appear in your request. This means that you must design your sequence so as not to break one basic rule: your wallet balance must not drop below 0.
Here’s one example:
You have two wallets — W1 ( with a balance of 5 units) and W2 (with a balance of 7 units) — and you perform a two-operation transaction:
Operation 1: Transfer 11 units from W1 to W2
Operation 2: Issue 6 units to W1.
Although it may seem as though there is enough money on W1 (the original 5 units and the subsequent 6 issued), operation 1 will be performed before operation 2 and break the rule of a non-negative wallet balance.
So, the transaction will fail. You can fix this problem by putting the Issue Operation before the Transfer.