Wallet as a Service

Introduction

How to build and deploy digital wallets on our reliable and scalable infrastructure.

Introduction - Wallets API

The Wallets API helps you efficiently manage your transactions and balances, providing comprehensive control over your financial operations. This service is designed to streamline payment workflows, enabling real-time tracking of transactions and ensuring seamless financial operations across your platform.

Some use cases:

E-commerce Platforms: Easily manage customer wallets, process payments, and handle refunds with real-time tracking of balances.
Banking and Financial Services: Enable secure and efficient management of multiple customer accounts, supporting deposits, withdrawals, and transfers.
Subscription-Based Services: Automate recurring payments, manage subscription balances, and track transaction history for seamless customer billing.
Crowdfunding Platforms: Manage individual campaign accounts, track contributions, and handle disbursements with full control over each account’s transactions.
Gaming and Digital Platforms: Manage in-game purchases, reward points, and wallet balances, ensuring smooth and secure financial transactions.

Our API supports a wide range of other use cases. If you need further clarification, don’t hesitate to reach out.

Check out the following guides to get started with our REST API.

API Base URLs

Use the following URLs as the base for all API requests:

Sandbox https://wallet.api.dev.lipad.io/api/v1

Authentication

An authorization header is required for all calls made to the Wallet API. To generate an access token, you will need to obtain your username and password.

POST https://{{BASE_URL}}/api/v1/auth/login

Once an access_token is generated, it should be passed as a header param i.e Authorization = Bearer <ACCESS_TOKEN>

Request Body

Name	Type
username	Body Field
password	Body Field

Client Profile

A profile refers to either an individual or a business entity that holds an account within the wallet system. Before an account can be established, a profile must first be created.

Create a Profile

To create a profile within the wallet system, you need to send a POST request with the following payload. The profile includes details about the profile and the contact person.

POST `/profiles`

Request body

{
    "client_code": "ENTREPR",
    "profile_name": "Branch 1",
    "profile_type": "BUSINESS",
    "client_profile_id": "BRANCH1",
    "profile_email": "[email protected]",
    "profile_msisdn": "254712345678",
    "contact_person_name": "Admin",
    "contact_person_email": "[email protected]",
    "contact_person_msisdn": "254712345678",
    "identification_number": "1",
    "physical_address": "456 Elm St",
    "country": "Canada",
    "description": "Lorem ipsum dolor sit amet consectetur adipiscing elit.",
    "is_active": 1
}

Payload Description

Key	Value Type	Required	Description
client_code	string	Yes	Client code of the client.
profile_name	string	Yes	Name of the profile (business or individual).
profile_type	enum	Yes	The type can be either BUSINESS or INDIVIDUAL.
client_profile_id	string	Yes	A unique profile identifier of the profile
profile_email	string	Yes	Email address of the profile.
profile_msisdn	string	Yes	Phone number of the profile, including country code.
contact_person_name	string	Yes	Name of the contact person managing the account.
contact_person_email	string	Yes	Email address of the contact person.
contact_person_msisdn	string	Yes	Contact person's phone number, including country code.
identification_number	string	Yes	Business/Individual identification number or PIN.
physical_address	string	Yes	Physical address of the profile.
country	string	Yes	The country where the profile is located.
description	string	No	Brief description of the profile.
is_active	number	Yes	Indicates whether the profile is active (1 for active, 0 for inactive).

Example Response

Upon successful creation, the API will return a response containing the profile details and a unique profile reference.

{
    "profile_id": "123",
    "profile_name": "Emlyn",
    "profile_type": "BUSINESS",
    "client_profile_id": "BRANCH1",
    "profile_email": "[email protected]",
    "profile_msisdn": 7209323323,
    "contact_person_name": "Emlyn",
    "contact_person_email": "[email protected]",
    "contact_person_msisdn": 7209323323,
    "identification_number": "A102035",
    "physical_address": "Nairobi, Kenya",
    "country": "Kenya",
    "description": "Test",
    "is_active": 1
}

Fetch Profile

To fetch profiles within the wallet system, you need to send a GET request with the following payload.

GET `/client-profiles/client-profile-id/{client_profile_id}`

Where {client_profile_id} is the placeholder for the actual value you will provide in your request. It is the client_profile_id you provided when creating a profile. It can also be found in dashboard under profiles section.

Request Header

You need to provide a bearer token in the Authorization header when making requests.

Authorization Bearer Content-Type application/json

Example Response

{
    "profile_id": "53",
    "profile_name": "Test Profile 1",
    "client_profile_id": "BRANCH1",
    "profile_email": "[email protected]",
    "profile_msisdn": "+254712345678",
    "contact_person_name": "Admin",
    "contact_person_email": "[email protected]",
    "contact_person_msisdn": "+254712345678",
    "identification_number": "1",
    "physical_address": "456 Elm St",
    "country": "Kenya",
    "description": "Lorem ipsum dolor sit amet consectetur adipiscing elit.",
    "is_active": 1,
    "created_at": "2024-11-04T11:58:50.213Z",
    "updated_at": "2024-11-04T11:58:50.213Z",
    "profile_type": "BUSINESS",
    "client": {
        "client_id": "88",
        "client_code": "LIPAD"
    },
    "accounts": [
        {
            "account_id": "377",
            "account_name": "Collection Account KES 1",
            "account_number": "10000134",
            "currency": "KES",
            "minimum_balance": "0.0000",
            "can_overdraw": false,
            "status": "ACTIVE",
            "status_description": "All KYC steps completed",
            "created_at": "2024-11-04T12:35:31.242Z",
            "updated_at": "2024-11-12T22:33:41.707Z",
            "current_balance": "0.0000"
        },
        {
            "account_id": "380",
            "account_name": "Collection Account KES 3",
            "account_number": "10000135",
            "currency": "KES",
            "minimum_balance": "0.0000",
            "can_overdraw": false,
            "status": "ACTIVE",
            "status_description": "All KYC steps completed",
            "created_at": "2024-11-04T12:48:45.712Z",
            "updated_at": "2024-11-12T22:33:41.707Z",
            "current_balance": "0.0000"
        },
        {
            "account_id": "382",
            "account_name": "Collection Account KES 4",
            "account_number": "10000136",
            "currency": "KES",
            "minimum_balance": "0.0000",
            "can_overdraw": false,
            "status": "ACTIVE",
            "status_description": "All KYC steps completed",
            "created_at": "2024-11-04T12:54:45.162Z",
            "updated_at": "2024-11-12T22:33:41.707Z",
            "current_balance": "100.0000"
        }
    ]
}

Update Profile State

Enable or disable a profile by issuing a specific command (ACTIVATE or DEACTIVATE).

Endpoint

POST `/profiles/client-profile-id/{client_profile_id}?command={COMMAND}`

Modify the activation state of a profile by providing a valid command i.e, ACTIVATE, DEACTIVATE

For example:

To ACTIVATE a profile:

POST `/profiles/client-profile-id/6758?command=ACTIVATE`

To DEACTIVATE a profile:

POST `/profiles/client-profile-id/6758?command=DEACTIVATE`

Headers

Header	Type	Required	Description
`Authorization`	String	Yes	Bearer token for authenticated users.

Path Parameters

Parameter	Type	Required	Description
`id`	String	Yes	Unique identifier of the profile.

Query Parameters

Parameter	Type	Required	Description
`command`	Enum (ProfileCommandTypes)	Yes	The command to modify the profile's state. Valid values: `ACTIVATE`, `DEACTIVATE`.

Request Body

No request body is required for this endpoint.

Response

200 OK

Indicates the profile state has been successfully updated.

{
    "id": "123",
    "status": "ACTIVE",
    "message": "Profile state updated successfully."
}

404 Not Found

Indicates the profile state has been successfully updated.

{
    "status": 404,
    "message": "Profile not found",
    "code": "HttpException"
}

Wallet Type

A wallet type is a specific category or classification of wallets, used to define and organize different types of wallets based on their intended purpose, features, or restrictions. After it has been created, you will receive a account type code which you will pass during creation of a wallet.

Create a Wallet Type

To create a wallet type for a client, you need to send a POST request with the following payload. The payload includes details such as the client code,account_type_name and account_type_description.

POST `/account-types`

Request Body

{
    "client_code": "ENTREPR",
    "account_type_name": "Current Account",
    "account_type_description": "Account type that allows in-flow and out-flow of funds.",
    "is_active": "1"
}

Payload Description

Key	Value Type	Required	Description
client_code	string	Yes	Client code of the client.
account_type_name	string	Yes	Name of the type of account
account_type_description	string	No	Brief description of the wallet type.
is_active	number	No	Indicates whether the wallet type is active (1 for active, 0 for inactive).

Expected Response

{
    "account_type_id": "1",
    "account_type_code": "FLOATBCAS",
    "account_type_name": "Float Account 1",
    "account_type_description": "KES",
    "is_active": 1,
    "created_at": "2024-09-05T17:14:04.734Z",
    "updated_at": "2024-09-05T17:14:04.734Z"
}

Fetch Wallet Types

To fetch wallet types within the wallet system, you need to send a GET request with the following payload.

GET https://{{BASE_URL}}/api/v1/account-types

Request Header

You need to provide a bearer token in the Authorization header when making requests.

Authorization Bearer Content-Type application/json

Request body

{
    "page": 1,
    "limit": 10
}

Example Response

{
    "metadata": {
        "page": 1,
        "per_page": 2,
        "total_count": 2
    },
    "statistics": [
        {
            "name": "Total Account Types",
            "count": 2
        },
        {
            "name": "Active Account Types",
            "count": 2
        },
        {
            "name": "Inactive Account Types",
            "count": 0
        }
    ],
    "records": [
        {
            "account_type_id": "5",
            "account_type_name": "Float Account 5",
            "account_type_code": "FLOBD8A2GY ",
            "is_mandatory_account": 0,
            "account_type_description": "Float Account 5",
            "is_active": 1,
            "is_default": 1,
            "created_at": "2024-11-07T12:25:47.999Z",
            "updated_at": "2024-11-07T12:25:47.999Z",
            "client": {
                "client_id": "88",
                "client_code": "LIPAD"
            }
        }
    ]
}

Wallet

Once a client profile and wallet types have been successfully created, you can proceed to create a wallet for the client. A wallet represents an account tied to the client within the wallet system, and it is essential for storing and managing funds.

Create a Wallet

To create a wallet for a client, you need to send a POST request with the following payload. The payload includes details such as the client code, account type, currency, and status of the account.

POST https://{{BASE_URL}}/api/v1/accounts

Request Body

{
    "client_code": "ENTREPR",
    "client_profile_id": "LIPNZPMF7O",
    "account_type_code": "CURRENT_ACCOUNT",
    "account_name": "Collection Account KES 1",
    "currency": "KES",
    "minimum_balance": 0,
    "can_overdraw": false,
    "status": "ACTIVE",
    "status_description": "All KYC steps completed"
}

Payload Description

Key	Value Type	Required	Description
client_code	string	Yes	Client code of the client.
client_profile_id	string	Yes	Unique reference generated when the client profile is created.
account_type_code	string	Yes	The type of account that was created in "Creating a Wallet Type" step i.e `CURRENT_ACCOUNT` (account type that allows daily inflow and outflow of cash).
account_name	string	Yes	Name of the account for identification purposes.
currency	string	Yes	The currency for the wallet, e.g., `KES` (Kenyan Shilling), `USD` (US Dollar).
minimum_balance	number	Yes	The minimum balance required for the account, typically `0`.
can_overdraw	boolean	Yes	Specifies whether the account can be overdrawn (`true` or `false`).
status	enum	Yes	Status of the wallet ; `PRE_ACTIVE`,`ACTIVE`, `DORMANT`,`CLOSED`,`SUSPENDED`
status_description	string	No	A brief description of the wallet’s status.

Expected Response

{
    "account_id": "1",
    "account_number": "10000110",
    "account_name": "Float Account 1",
    "currency": "KES",
    "minimum_balance": "0.1000",
    "can_overdraw": false,
    "status": "ACTIVE",
    "status_description": "All KYC steps completed",
    "created_at": "2024-09-05T17:14:04.734Z",
    "updated_at": "2024-09-05T17:14:04.734Z"
}

Fetch Wallet

To fetch wallet within the wallet system, you need to send a GET request with the following payload.

GET `/accounts/account-number/{account_number}`

Where {account_number} is the placeholder for the actual value you will provide in your request. It is the account number that was generated when creating a wallet. It can also be found in dashboard under wallets section.

Request Header

You need to provide a bearer token in the Authorization header when making requests.

Authorization Bearer Content-Type application/json

Example Response

{
    "account_id": "273",
    "account_name": "AVAILABLE_COLLECTIONS 72",
    "account_number": "10000086",
    "currency": "KES",
    "minimum_balance": "0.0000",
    "can_overdraw": true,
    "status": "ACTIVE",
    "status_description": "ACTIVE",
    "created_at": "2024-07-30T13:57:43.126Z",
    "updated_at": "2024-10-31T17:56:40.832Z",
    "profile": null,
    "client": {
        "client_id": "110",
        "client_name": "Stic Financial LTD",
        "client_code": "STI6G1PTUQ"
    },
    "current_balance": "423.9000"
}

Update Wallet State

Modify the state of a specific account by issuing a command (e.g.,ACTIVATE, CLOSE, DORMANT, SUSPEND). Note that this can cause the account to be in a state where transaction might be denied.

Endpoint

POST `/accounts/account-number/{account_number}?command={COMMAND}`

For example:

To activate an account:

POST `/accounts/account-number/10000021?command=ACTIVATE`

To suspend an account:

POST `/accounts/account-number/10000021?command=SUSPEND`

Headers

Header	Type	Required	Description
`Authorization`	String	Yes	Bearer token for authenticated users.

Path Parameters

Parameter	Type	Required	Description
`account_number`	String	Yes	Unique identifier of the account.

Query Parameters

Parameter	Type	Required	Description
`command`	Enum (AccountCommandTypes)	Yes	The command to modify the account state. Valid values: `ACTIVATE`,`CLOSE`, `DORMANT`, `SUSPEND`.

Request Body

No request body is required for this endpoint.

Response

200 OK

Indicates the account state has been successfully updated.

{
    "account_number": "100221212",
    "status": "ACTIVE",
    "message": "Account state updated successfully."
}

404 Not Found

Indicates the account has not been found.

{
    "status": 404,
    "message": "Profile not found",
    "code": "HttpException"
}

401 Unauthorized

Unauthorized exception.

{
    "status": 401,
    "message": "Unauthorized",
    "code": "HttpException"
}

400 Bad Request

Bad request exception.

{
    "status": 400,
    "message": ["command must be one of the following values: CLOSE, ACTIVATE, DORMANT, SUSPEND"],
    "code": "HttpException"
}

Generate a statement

Most of the time, you will need to reconcil transactions. You can use the following method to generate an account statement either in excel or pdf format.

To generate an account statement, you need to make a GET request to the following endpoint with the appropriate query parameters.

GET `/account-statements/doc`

For example to generate a statement between 2024-08-27 and 2024-10-04 you will make a GET request as shown below:

GET `/account-statements/doc?start_date=2024-08-27T13:31:08.69012Z&end_date=2024-10-04T18:31:08.69012Z&doc_type=EXCEL&account_number=10000114`

Request Query Parameter

Key	Value Type	Required	Description
account_number	string	Yes	The account number from which the funds will be transferred.
start_date	string	Yes	The date and time when the the statement should start.
end_date	string	Yes	The date and time when the the statement should end transaction.
doc_type	enum	Yes	The document type either EXCEL or PDF.

Expected Response

Success (HTTP 200): When the document is successfully generated, the response will trigger a file download in the specified format (e.g., Excel). The response will not contain a body, as the file will be sent directly to the client.

Error (HTTP 4xx/5xx): If there is an error during the document generation process, such as invalid parameters or server issues, the API will return an appropriate error response with a status code (e.g., 400 for bad request, 500 for server error) and a JSON object containin the message i.e No transactions within period etc

Client Service

Before transactions can be initiated within the wallet system, a client service must be created. A client service contains various settings and rules that govern how transactions are processed within the wallet.

Create a Client Service

POST `/client-services`

Request Body

{
    "client_code": "LIPNZPMF7O",
    "client_service_name": "Payout KES Nairobi",
    "service_code": "CUSTOM_SERVICE",
    "has_transaction_fee": true,
    "transaction_fee_type": "FIXED",
    "transaction_fee": 0.0,
    "minimum_transaction_amount": 1.0,
    "maximum_transaction_amount": 100.0,
    "is_active": 1
}

Payload Description

Key	Value Type	Required	Description
client_code	string	Yes	Unique client code that was generated when the client was created.
client_service_name	string	Yes	Name of the client service (e.g., "Payout KES Nairobi").
service_code	enum	Yes	A unique service identifier; `CUSTOM_SERVICE` currently supported.
has_transaction_fee	boolean	Yes	Specifies if the service charges a transaction fee (`true` or `false`).
transaction_fee_type	string	No	Type of transaction fee, either `PERCENTAGE` or `FIXED`. Optional if no fee is charged.
transaction_fee	number	No	The amount charged as a fee, e.g., `0.00`. Optional if `has_transaction_fee` is false.
minimum_transaction_amount	number	Yes	The minimum transaction amount allowed by this service.
maximum_transaction_amount	number	Yes	The maximum transaction amount allowed by this service.
is_active	number	Yes	Indicates whether the service is active (1 for active, 0 for inactive).

Example Response

Upon successful creation, the API will return a response containing the details of the newly created client service.

{
    "client_service_id": "1",
    "client_service_code": "PAY1CNAELX",
    "client_code": "LIPNZPMF7O",
    "client_service_name": "Payout KES Nairobi",
    "service_code": "CUSTOM_SERVICE",
    "has_transaction_fee": true,
    "transaction_fee_type": "FIXED",
    "transaction_fee": 0.0,
    "minimum_transaction_amount": 1.0,
    "maximum_transaction_amount": 100.0,
    "is_active": 1
}

Fetch Client Services

To fetch client service within the wallet system, you need to send a GET request with the following payload.

GET `/client-services`

Request Header

You need to provide a bearer token in the Authorization header when making requests.

Authorization Bearer Content-Type application/json

Request body

{
    "page": 1,
    "limit": 10
}

Example Response

{
    "metadata": {
        "page": 1,
        "per_page": 1,
        "total_count": 37
    },
    "statistics": [
        {
            "name": "Total",
            "count": 37
        },
        {
            "name": "Active",
            "count": 37
        },
        {
            "name": "Inactive",
            "count": 0
        }
    ],
    "records": [
        {
            "transaction_fee_tiers": [],
            "client_service_id": "1942",
            "client_service_name": "FLOAT_DEPOSIT",
            "client_service_code": "FLO7X2SIGF",
            "minimum_transaction_amount": "0.0001",
            "maximum_transaction_amount": "200000.0000",
            "is_active": 1,
            "created_at": "2024-07-30T13:56:03.158Z",
            "updated_at": "2024-07-30T13:56:03.158Z",
            "has_transaction_fee": false,
            "transaction_fee_type": null,
            "transaction_fee": "0.0000",
            "service": {
                "service_id": "6",
                "service_name": "Custom Service",
                "service_code": "CUSTOM_SERVICE",
                "service_transaction_type": "BOTH"
            },
            "client": {
                "client_id": "88",
                "client_name": "LIPAD"
            }
        }
    ]
}

Transactions

In the wallet system, transactions can be performed by combining the client, client service, and wallet that have been created. These components work together to handle various types of transactions.

Transaction Types

Primarily, the following types of transactions can be performed:

Credit: Adding funds to a wallet or account.
Debit: Deducting funds from a wallet or account.
Account Transfer: Moving funds between different wallets or accounts.
Reversal: Reversing a previously performed transaction.

Each transaction type can be executed through the use of a client’s wallet, associated with the specific client service, to ensure compliance with the defined transaction rules and settings.

Make a Debit or Credit

To perform a transaction within the wallet system, you need to combine the client, client service, and wallet that have been created. Using these components, you can initiate credit and debit transactions.

Creating a Transaction

To make a transaction, you will need to send a POST request to the following endpoint. The command parameter in the URL determines whether the transaction is a credit or a debit.

For a Credit transaction, use command=CREDIT.
For a Debit transaction, use command=DEBIT.

POST `/transactions?command=CREDIT (or DEBIT for debits)`

For example, for a CREDIT Transaction, you need to make POST request as shown below:

POST `/transactions?command=CREDIT`

In the request body :

{
    "account_number": "10000099",
    "client_service_code": "FLOIQ2XAFJ",
    "transaction_amount": 100.0,
    "currency": "KES",
    "source_transaction_id": "12325524445",
    "source_transaction_data": {
        "data": "test"
    },
    "transaction_narration": "Test",
    "transaction_date": "2024-07-29T12:34:56Z"
}

For a DEBIT transaction, you need to make POST request as below:

POST `/transactions?command=DEBIT`

In the request body :

{
    "account_number": "10000099",
    "client_service_code": "FLOIQ2XAFJ",
    "currency": "KES",
    "transaction_amount": 100.0,
    "source_transaction_id": "12325524445",
    "source_transaction_data": {
        "data": "test"
    },
    "transaction_narration": "Test",
    "transaction_date": "2024-07-29T12:34:56Z"
}

Payload Description

Key	Value Type	Required	Description
account_number	string	Yes	The wallet or account number where the transaction will be applied.
client_code	string	Yes	Unique client code that was generated when the client was created.
client_service_code	string	Yes	The unique code for the client service handling the transaction.
transaction_amount	number	Yes	The amount of money involved in the transaction.
currency	string	Yes	The currency of the transaction. Conversion will be done incase of mismatch with wallet currency
source_transaction_id	string	Yes	A unique reference ID for the transaction from the source system.
source_transaction_data	object	No	Additional data related to the source transaction.
transaction_narration	string	No	A brief description or narration for the transaction.
transaction_date	string	No	The date and time when the transaction occurred (ISO 8601 format).

Expected Response

{
    "transaction_id": "7607",
    "account": "10000110",
    "client_service": "PAY1CNAELX",
    "transaction_type": "CREDIT", // or DEBIT
    "transaction_source": "EXTERNAL_CREDIT", //or EXTERNAL_DEBIT
    "currency": "KES",
    "transaction_amount": "96.0000",
    "previous_balance": "0.0000",
    "current_balance": "96.0000",
    "other_party_account": "10000002",
    "other_party_transaction_hash": "N/A",
    "source_transaction_id": "121231234",
    "source_transaction_data": {
        "data": "Dashboard"
    },
    "transaction_narration": "2131321",
    "transaction_date": "2024-09-05T17:47:00.000Z"
}

Make an Internal Transfer

An internal transfer allows you to transfer funds between two accounts within the wallet system. The transfer will be made between the source account and the destination account, and it requires the use of a valid client service.

Creating an Internal Transfer

To make an internal transfer, you need to send a POST request to the following endpoint with the appropriate payload:

POST `/account-transfers`

Request Body

{
    "source_account_number": "10000014",
    "destination_account_number": "10000015",
    "client_service_code": "INT_NHQ5Y77",
    "transaction_amount": 10.0,
    "currency": "KES",
    "source_transaction_id": "1",
    "transaction_source": "INTERNAL",
    "source_transaction_data": {},
    "transaction_narration": "Transfer for payment",
    "transaction_date": "2022-07-29T12:34:56Z"
}

Request Description

Key	Value Type	Required	Description
source_account_number	string	Yes	The account number from which the funds will be transferred.
destination_account_number	string	Yes	The account number to which the funds will be transferred.
client_code	string	Yes	Unique client code that was generated when the client was created.
client_service_code	string	Yes	The client service code that authorizes the transaction.
transaction_amount	number	Yes	The amount of money to be transferred.
currency	string	Yes	The currency of the transaction. Conversion will be done incase of mismatch with wallet currency
source_transaction_id	string	Yes	A unique reference ID for the transaction from the source system.
transaction_source	string	Yes	Indicates the source of the transaction, e.g., `INTERNAL`.
source_transaction_data	object	No	Additional data related to the transaction, if applicable.
transaction_narration	string	No	A brief description of the transaction, e.g., "Transfer for payment".
transaction_date	string	No	The date and time when the transaction occurred (in ISO 8601 format).

Example Response

Upon successfully creating the internal transfer, the API will return a response with transaction details and a unique transaction ID.

{
    "source_transaction": {
        "transaction_id": "7611",
        "account": "10000097",
        "client_service": "INTBPHGRXO",
        "transaction_type": "DEBIT",
        "transaction_source": "INTERNAL_TRANSFER_DEBIT",
        "currency": "KES",
        "transaction_amount": "10.0000",
        "previous_balance": "2985.0000",
        "current_balance": "2975.0000",
        "other_party_account": "10000095",
        "other_party_transaction_hash": "N/A",
        "source_transaction_id": "IFT112242342412324",
        "source_transaction_data": {
            "data": "Dashboard"
        },
        "transaction_narration": "1242142421421",
        "transaction_date": "2024-09-05T18:36:42.774Z"
    },
    "destination_transaction": {
        "transaction_id": "7612",
        "account": "10000095",
        "client_service": "INTBPHGRXO",
        "transaction_type": "CREDIT",
        "transaction_source": "INTERNAL_TRANSFER_CREDIT",
        "currency": "KES",
        "transaction_amount": "10.0000",
        "previous_balance": "0.0000",
        "current_balance": "10.0000",
        "other_party_account": "10000097",
        "other_party_transaction_hash": "N/A",
        "source_transaction_id": "IFT212242342412324",
        "source_transaction_data": {
            "data": "Dashboard"
        },
        "transaction_narration": "1242142421421",
        "transaction_date": "2024-09-05T18:36:42.788Z"
    }
}

Make a Reversal

A reversal allows you to reverse a previously performed transaction in the wallet system. This can be used to undo incorrect or duplicate transactions. To reverse a transaction, you need the transaction ID of the original transaction and the proper command.

Creating a Reversal

To make a reversal, send a POST request to the following endpoint. Replace :id in the URL with the transaction ID of the original transaction.

POST `/transactions/:id?command=REVERSE`

For example :

POST `/transactions/12122232?command=REVERSE`

Expected Response

{
    "source_transaction": {
        "transaction_id": "7609",
        "account": "10000110",
        "client_service": "REVN6D91E4",
        "transaction_type": "DEBIT",
        "currency": "KES",
        "transaction_amount": "997.0000",
        "previous_balance": "1093.0000",
        "current_balance": "96.0000",
        "other_party_account": "10000002",
        "other_party_transaction_hash": "N/A",
        "transaction_source": "INTERNAL_REVERAL_DEBIT",
        "source_transaction_id": "RVS11212adas",
        "source_transaction_data": {
            "data": "Dashboard"
        },
        "transaction_narration": "1213124",
        "transaction_date": "2024-09-05T17:58:00.000Z"
    },
    "destination_transaction": {
        "transaction_id": "7610",
        "account": "10000002",
        "client_service": "REVN6D91E4",
        "transaction_type": "CREDIT",
        "currency": "KES",
        "transaction_amount": "997.0000",
        "previous_balance": "9195.0000",
        "current_balance": "10192.0000",
        "other_party_account": "10000110",
        "other_party_transaction_hash": "N/A",
        "transaction_source": "INTERNAL_REVERAL_CREDIT",
        "source_transaction_id": "RVS21212adas",
        "source_transaction_data": {
            "data": "Dashboard"
        },
        "transaction_narration": "1213124",
        "transaction_date": "2024-09-05T17:58:00.000Z",
        "transaction_id": "7610"
    }
}

Wallet as a Service

Introduction​

API Base URLs​

Authentication​

Request Body​

Client Profile​

Create a Profile​

POST /profiles​

Request body​

Payload Description​

Example Response​

Fetch Profile​

GET /client-profiles/client-profile-id/{client_profile_id}​

Request Header​

Example Response​

Update Profile State​

Endpoint​

POST /profiles/client-profile-id/{client_profile_id}?command={COMMAND}​

POST /profiles/client-profile-id/6758?command=ACTIVATE​

POST /profiles/client-profile-id/6758?command=DEACTIVATE​

Headers​

Path Parameters​

Query Parameters​

Request Body​

Response​

200 OK​

404 Not Found​

Wallet Type​

Create a Wallet Type​

POST /account-types​

Request Body​

Payload Description​

Expected Response​

Fetch Wallet Types​

Request Header​

Request body​

Example Response​

Wallet​

Create a Wallet​

Request Body​

Payload Description​

Expected Response​

Fetch Wallet​

GET /accounts/account-number/{account_number}​

Request Header​

Example Response​

Update Wallet State​

Endpoint​

POST /accounts/account-number/{account_number}?command={COMMAND}​

POST /accounts/account-number/10000021?command=ACTIVATE​

POST /accounts/account-number/10000021?command=SUSPEND​

Headers​

Path Parameters​

Query Parameters​

Request Body​

Response​

200 OK​

404 Not Found​

401 Unauthorized​

400 Bad Request​

Generate a statement​

GET /account-statements/doc​

GET /account-statements/doc?start_date=2024-08-27T13:31:08.69012Z&end_date=2024-10-04T18:31:08.69012Z&doc_type=EXCEL&account_number=10000114​

Expected Response​

Client Service​

Create a Client Service​

POST /client-services​

Request Body​

Payload Description​

Example Response​

Fetch Client Services​

GET /client-services​

Request Header​

Request body​

Example Response​

Transactions​

Transaction Types​

Make a Debit or Credit​

Creating a Transaction​

POST /transactions?command=CREDIT (or DEBIT for debits)​

Introduction

API Base URLs

Authentication

Request Body

Client Profile

Create a Profile

POST `/profiles`

Request body

Payload Description

Example Response

Fetch Profile

GET `/client-profiles/client-profile-id/{client_profile_id}`

Request Header

Example Response

Update Profile State

Endpoint

POST `/profiles/client-profile-id/{client_profile_id}?command={COMMAND}`

POST `/profiles/client-profile-id/6758?command=ACTIVATE`

POST `/profiles/client-profile-id/6758?command=DEACTIVATE`

Headers

Path Parameters

Query Parameters

Request Body

Response

200 OK

404 Not Found

Wallet Type

Create a Wallet Type

POST `/account-types`

Request Body

Payload Description

Expected Response

Fetch Wallet Types

Request Header

Request body

Example Response

Wallet

Create a Wallet

Request Body

Payload Description

Expected Response

Fetch Wallet

GET `/accounts/account-number/{account_number}`

Request Header

Example Response

Update Wallet State

Endpoint

POST `/accounts/account-number/{account_number}?command={COMMAND}`

POST `/accounts/account-number/10000021?command=ACTIVATE`

POST `/accounts/account-number/10000021?command=SUSPEND`

Headers

Path Parameters

Query Parameters

Request Body

Response

200 OK

404 Not Found

401 Unauthorized

400 Bad Request

Generate a statement

GET `/account-statements/doc`

GET `/account-statements/doc?start_date=2024-08-27T13:31:08.69012Z&end_date=2024-10-04T18:31:08.69012Z&doc_type=EXCEL&account_number=10000114`

Expected Response

Client Service

Create a Client Service

POST `/client-services`

Request Body

Payload Description

Example Response

Fetch Client Services

GET `/client-services`

Request Header

Request body

Example Response

Transactions

Transaction Types

Make a Debit or Credit

Creating a Transaction

POST `/transactions?command=CREDIT (or DEBIT for debits)`

POST `/transactions?command=CREDIT`