Building an Invoice Management System

Introduction

The following steps can be used to create an Invoice Management System. 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.

Getting Started

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

Creating Users

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.

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 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.

Creating Invoices

Any user on the platform can create a new invoice using this endpoint. It's also possible to use another microservice to email the invoice recipients.

A snapshot of what would be returned by calling the create invoice endpoint would look like this:

{
"status": "success",
"message": "Invoice saved",
"data": {
"id": 26,
"user_id": "563",
"invoice_key": "a680774acb",
"email": "[email protected]",
"phone": "0456352356",
"customer_id": null,
"reschedule_reoccuring_invoice": "yes",
"period": "monthly",
"save_beneficiary": "no",
"start_date": "2021-09-12",
"status": "active",
"created_at": "2021-07-19T11:21:20.000000Z",
"updated_at": "2021-07-19T11:21:20.000000Z",
"items": [{
"id": 31,
"user_invoice_id": "26",
"user_id": "563",
"name": "Butter",
"amount": "123",
"status": "active",
"created_at": "2021-07-19T11:21:20.000000Z",
"updated_at": "2021-07-19T11:21:20.000000Z"
}]
}
}

Each invoice has a unique invoice id that can be saved and referenced later.

Collecting Payments

This section discusses the various ways in which you can collect payments on behalf of users on the platform.

When collecting payments, you should pass across the user_id of the user that initiated the invoice and the invoice id from the previous step.

The money collected from calling the endpoints would be stored in the user's wallet.

Collecting Payments via Bank Account

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.

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.

Withdrawals

Money is collected on behalf of your users and stored in their wallets. This money can then be withdrawn to a bank account using this endpoint.

Viewing Withdrawals

You can keep track of all the withdrawals that have been initiated from each user's wallet by calling this endpoint.