Donations Use Case
The following steps can be used to create a p2p platform for collecting donations. This guide helps you get started immediately in a staging environment to quickly deliver a proof of concept.
It's advisable to keep a separate database of users that are being created. This would allow you to carry out various tasks that would be mentioned further down this guide.
You would need to register for a Deposits account from the developer console.
In the staging environment, your account is approved automatically and you can begin interacting with the APIs. However, in the production environment, you would need to have your account approved by the back office.
After you've registered, you would need to do the following:
create a new client and give it a name.
assign a primary email address to that client.
select the default wallets that would be used in your application. This guide uses
USD
You would be redirected to your client area. You would see the client you just created and your API key. This would be used to interact with Deposits. Please don't share this with anyone as it would give them full access to your account.
The BASE_URL for endpoints is https://client.user.swys.xyz/api/v1
From the docs, you can see all the information you can collect to create a new user.
After you create a new user, a lot of information is returned. A quick snapshot of the most relevant information we would need from this user would look like this:
{"status": "success","message": "Account created successful.","data": {"user": {"first_name": "Fred","last_name": "Williams","username": "f_williams","email": "[email protected]","id": 612...},"wallet": 0}}
It probably makes sense to mention again at this point that you should save this info on a separate database. This gives you accurate information on the user_id of all your users. This information would be useful in the following steps. It would also allow for you to authenticate users on your application and ensure they only view the information they are authorized to view.
Depending on your use case, you might want to have anonymous users who would want to try out the platform without necessarily creating an account. A solution that might help with this would be to create emails that look like
[email protected]_domain.com. Please note that it is not possible to update the email address of a user on Deposits currently.
We can see that after a user is created on Deposits, a wallet is automatically created for them as well. This would be the store of value for transactions that are performed on the platform.
This wallet information can also be saved on your database so you can have a glimpse of what is contained in a user's wallet at any given point in time.
In a situation where you would want users to directly make donations to NGOs, you could show how much is left in a user's wallet in your UI. If donations are being handled by a single back office, there might not be a need to show the amount left in a wallet in your UI. This would be discussed further down in the guide.
This section discusses the various ways in which you can collect payments from users on the platform.
Our payment pages automatically generate invoices and allow you collect payments. You can generate a new payment page by calling this endpoint: https://client.user.swys.xyz/api/v1/user/payment-page/add​
A sample body passed along with the request would look like:
{"api_key": "KwjqFjcvQxUHczQJ","user_id": "563","name":"Swift Technologies","description":"Get the very best technology at swift technologies","items":[{"name":"msi Optix AG32CQ","description":"msi 32in curved monitor","amount":450,"quantity":1}]}
This would return a response that looks like this:
{"status": "success","message": "Payment Page saved","data": {"id": 7,"client_id": "7","user_id": "563","name": "Swift Technologies","description": "Get the very best technology at swift technologies","amount": 450,"paid_at": null,"extra_info": null,"payment_type": null,"payment_interval": null,"payment_key": "a306248c72ce4ad","total": "450","status": "active","created_at": "2021-08-25T14:33:08.000000Z","updated_at": "2021-08-25T14:33:08.000000Z","link": "https:\/\/client.user.swys.xyz\/payment_page\/new-client\/a306248c72ce4ad","items": [{"id": 9,"client_id": "7","payment_page_id": "7","name": "msi Optix AG32CQ","description": "msi 32in curved monitor","amount": "450","quantity": "1","status": "active","created_at": "2021-08-25T14:33:08.000000Z","updated_at": "2021-08-25T14:33:08.000000Z"}]}}
The link to the page that we want can be found at data.link. You can grab this link and redirect a user to that page to follow the next steps. You can navigate to that link here​
From the docs, you can initiate a request to debit a bank account. If this is successful, the user who initiated the request would have their wallet topped up with the amount passed in.
To collect payments via Card, you can call this endpoint. If this is successful, the user who initiated the request would have their wallet topped up with the amount passed in.
This guide assumes that payouts are handled by the back office. There are a couple of ways to handle how payouts would be made and we will discuss two of them below. For both methods, the bank account details would be for the bank account of the platform.
This would require that you have a separate database created as suggested earlier in the guide.
Keeping track of the wallet amount each time a transaction is made will make this process easier. You could run a cron job to go over each entry in your database. This would read two fields from each entry, user_id, and wallet.
The user_id can then be passed to this endpoint as well as the current amount in the wallet.
It's also possible to move money to the platform's bank account immediately after a transaction occurs.
In this case, whenever a payment is collected, you can withdraw those funds to the platform's bank account by calling this endpoint with the current user's user_id as well as the amount.
It's possible to retrieve all transactions that were made by a user. If you would want to show those transactions in your UI, you can call this endpoint.
That returns every single transaction that was made and a quick snapshot of what is returned would look like this:
{"status": "success","message": "transactions retrieved ","data": [{"type": "credit","amount": "1,000.00","id": 571,"currency": "usd","transaction_id": "10838773","reference": "10838773","balance": "1,120.00","description": "Wallet topup","status": "success",...},...]}
You may want to filter data from the payload in your UI to only show when a user made a payment.
In the back office, it might make sense to keep track of all the withdrawals that have been made into the platform's bank account. You can view this information by calling this endpoint.
This shows withdrawals made by individual users on your platform.
