Building a Donation Engine with Deposits.com

Introduction
The guide outlines the steps necessary to create a peer-to-peer platform for receiving donations. This guide helps you get started in a staging environment to deliver a proof of concept quickly.
It is advisable to keep a separate database of users created. This will allow you to carry out various tasks mentioned further down this guide.
Getting Started
The first thing you need to do is register for a Deposits account from the developer console.​
Your account is automatically approved in the staging environment, and you can begin interacting with the APIs. However, your account needs to be approved by the back office in the production environment.
After registering,
Create and name a new client
Assign a primary email address to that client.
Select the default wallets that will be used in your application.
Please Note: This guide uses the United States Dollar (USD)
You will then be redirected to your client area. Your recently created client and API key will be made available to you on this page.
The API key is your ticket to interacting with Deposits and should not be shared with anyone as it would give them full access to your account.
The BASE_URL for endpoints is https://api.deposits.dev/api/v1.
Creating Users
Our API documentation provides the necessary information needed to create a new user.
After you create a new user, a response similar to this is returned:
{
    "status": "success",
    "message": "Account created successful.",
    "data": {
        "user": {
            "first_name": "Fred",
            "last_name": "Williams",
            "username": "f_williams",
            "email": "[email protected]",
            "id": 612
						...
        },
        "wallet": 0
    }
}
Please make sure this information is saved on a separate database, as it gives you accurate information on the user_id of all your users. This information will be useful in the following steps. It will allow you to authenticate users on your application and ensure they only view their authorized information.
Depending on your use case, you might want to have anonymous users who would 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: It is not possible to update the email address of a user on Deposits currently.
User Wallets
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 performed on the platform.
The wallet information can also be saved on your database so you can have a glimpse of what is in a user's wallet at any given point in time.
In a situation where you want users to make donations to NGOs directly, you could show how much is left in a user's wallet in your UI. If donations are handled by a single back office, there might not be a need to show the amount left in a wallet in your UI. This will be discussed further in the guide.
Collecting Payments
This section discusses the various ways you can collect payments from users on the platform
via Deposits Payment pages (recommended)
This section discusses the various ways in which you can collect payments from users on the platform.
via Deposits Payment pages (recommended)
Our payment pages automatically generate invoices and allow you to collect payments. You can generate a new payment page by calling this endpoint:
​https://api.deposits.com/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
        }
    ]
}
If successful, a response similar to the one below will be returned:
{
    "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 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.
Collecting Payments via Bank Account
You can learn how to initiate a request to debit a bank account from the API documentation. If this is successful, the user who initiated the request would have their wallet topped up with the amount passed in.
Collecting Payments via Card
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.
Payouts
This guide assumes that the back office handles payouts. There are a couple of ways to manage how payouts would be made, and we will discuss two of them below. For both methods, the bank account details will be for the platform's bank account.
via CRON job
This would require a separate database created, as suggested earlier.
Keeping track of the wallet amount each time a transaction is made will make this process easier. You can 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 and the current amount in the wallet can then be passed to this endpoint.
Every time a Payment is Collected
It is also possible to move money to the platform's bank account immediately after a transaction.
In this case, whenever a payment is received, you can withdraw those funds to the platform's bank account by calling this endpoint with the current user's user_id and the amount.
Keeping Track of Transactions
It is possible to retrieve all transactions that a user made If you want to show those transactions in your UI, you can call this endpoint.
This returns every single transaction made, and the response gotten should be similar to 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 only to show when a user made a payment.
Withdrawals
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.
guides - Previous
Building an Invoice Management System
Last modified 21d ago
Copy link
On this page
Introduction
Getting Started
Creating Users
User Wallets
Collecting Payments
via Deposits Payment pages (recommended)
Collecting Payments via Bank Account
Collecting Payments via Card
Payouts
via CRON job
Every time a Payment is Collected
Keeping Track of Transactions
Withdrawals