Wallet as a Service

Introduction

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

Introduction - Wallets API

Wallet as a service enables you to efficiently manage multiple accounts, offering full control over transactions, balances, and account settings. With features like real-time tracking and detailed transaction history, the API helps streamline payment workflows and ensures 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.

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

Register a client

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

Creating a Client Profile

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

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

Request body

{
    "client_name": "LIPAD",
    "client_email": "[email protected]",
    "client_phone_number": "254712345678",
    "contact_person_name": "Admin",
    "contact_person_email": "[email protected]",
    "contact_person_msisdn": "254712345678",
    "business_pin": "1",
    "physical_address": "456 Elm St",
    "country": "Canada",
    "logo": "https://example.com/logo2.png",
    "description": "Lorem ipsum dolor sit amet consectetur adipiscing elit.",
    "is_active": 1
}

Payload Description

Key	Value Type	Required	Description
client_name	string	Yes	Name of the client (business or individual).
client_email	string	Yes	Email address of the client.
client_phone_number	string	Yes	Phone number of the client, 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.
business_pin	string	Yes	Business identification number or PIN.
physical_address	string	No	Physical address of the client.
country	string	Yes	The country where the client is located.
logo	string	No	URL for the client's logo.
description	string	No	Brief description of the client.
is_active	number	Yes	Indicates whether the client profile is active (1 for active, 0 for inactive).

Example Response

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

{
    "client_id": "123",
    "client_name": "Emlyn",
    "client_email": "[email protected]",
    "client_phone_number": 7209323323,
    "contact_person_name": "Emlyn",
    "contact_person_email": "[email protected]",
    "contact_person_msisdn": 7209323323,
    "business_pin": "A102035",
    "physical_address": "Nairobi, Kenya",
    "country": "Kenya",
    "description": "Test",
    "is_active": 1,
    "client_code": "EML67BG6W1",
    "logo": "https://example.com/logo.png"
}

Create a Wallet

Once a client profile has 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.

Creating 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": "LIPNZPMF7O",
    "account_type_code": "FLOAT_ACCOUNT",
    "account_name": "Collection Account KES 2",
    "currency": "KES",
    "minimum_balance": 0,
    "can_overdraw": false,
    "status": "ACTIVE",
    "status_description": "Collection Account"
}

Payload Description

Key	Value Type	Required	Description
client_code	string	Yes	Unique client code generated when the client profile is created.
account_type_code	string	Yes	The type of account, e.g., FLOAT_ACCOUNT, AVAILABLE_COLLECTIONS,HYBRID_ACCOUNT,ACQUIRER_RESERVE,ROLLING_RESERVE,COMMISSION_ACCOUNT,COMMISSION_TAX_ACCOUNT.
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	No	Specifies whether the account can be overdrawn (true or false).
status	string	Yes	Status of the wallet, e.g., ACTIVE, INACTIVE.
status_description	string	No	A brief description of the wallet’s purpose or 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": "Test account",
    "created_at": "2024-09-05T17:14:04.734Z",
    "updated_at": "2024-09-05T17:14:04.734Z"
}

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

Key Features of a Client Service:

• Transaction Types: A client service can be configured to handle both CREDIT and DEBIT transactions, or only one of them, depending on the service requirements. (Note: This attribute is under review, as most services seem to require both types.)
• Transaction Fees: If applicable, the client service can define specific transaction fees for its operations.
• Transaction Limits: The service can also set minimum and maximum allowable amounts for transactions.

Creating a Client Service

POST https://{{BASE_URL}}/api/v1/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 generated when the client profile is created.
client_service_name	string	Yes	Name of the client service (e.g., "Payout KES Nairobi").
service_code	string	Yes	A unique service identifier, e.g., CUSTOM_SERVICE.
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
}

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 {{BASE_URL}}/api/v1/transactions?command=CREDIT (or DEBIT for debits)

Request Body

{
    "account_number": "10000099",
    "client_service_code": "FLOIQ2XAFJ",
    "transaction_source": "EXTERNAL",
    "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_service_code	string	Yes	The unique code for the client service handling the transaction.
transaction_source	string	Yes	Source of the transaction (e.g., EXTERNAL, INTERNAL).
transaction_amount	number	Yes	The amount of money involved in the transaction.
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 (ISO 8601)	Yes	The date and time when the transaction occurred (ISO 8601 format).

Expected Response

{
    "transaction_id": "7607",
    "account": "10000110",
    "client_service": "PAY1CNAELX",
    "transaction_type": "CREDIT",
    "currency": "KES",
    "transaction_amount": "96.0000",
    "previous_balance": "0.0000",
    "current_balance": "96.0000",
    "other_party_account": "10000002",
    "other_party_transaction_hash": "N/A",
    "transaction_source": "EXTERNAL",
    "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 https://{{BASE_URL}}/api/v1/account-transfers

Request Body

{
    "source_account_number": "10000014",
    "destination_account_number": "10000015",
    "client_service_code": "INT_NHQ5Y77",
    "transaction_amount": 10.0,
    "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_service_code	string	Yes	The client service code that authorizes the transaction.
transaction_amount	number	Yes	The amount of money to be transferred.
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 (ISO)	Yes	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",
        "currency": "KES",
        "transaction_amount": "10.0000",
        "previous_balance": "2985.0000",
        "current_balance": "2975.0000",
        "other_party_account": "10000095",
        "other_party_transaction_hash": "N/A",
        "transaction_source": "INTERNAL",
        "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",
        "currency": "KES",
        "transaction_amount": "10.0000",
        "previous_balance": "0.0000",
        "current_balance": "10.0000",
        "other_party_account": "10000097",
        "other_party_transaction_hash": "N/A",
        "transaction_source": "INTERNAL",
        "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 {{wallet_url}}/transactions/:id?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",
        "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",
        "source_transaction_id": "RVS21212adas",
        "source_transaction_data": {
            "data": "Dashboard"
        },
        "transaction_narration": "1213124",
        "transaction_date": "2024-09-05T17:58:00.000Z",
        "transaction_id": "7610"
    }
}