Wallet

Wallet Endpoints

This folder contains all endpoints related to wallet operations in the Finecore BAAS platform.

Available Actions:

Create a new wallet for a user or organization
Retrieve wallet details by ID or user reference
Check current wallet balance
View wallet transaction history

Notes:

Wallets are linked to users or organizations by unique identifiers
All balances are returned in the default system currency
Transactions include metadata such as type (credit/debit), source, and timestamp

Ensure your requests include the required headers, especially:

X-API-Key: API_KEY

Fetch customer transaction

Fetch Transaction by Customer ID and Reference

Endpoint: GET /v1/transactions/customer/:customer_id/:reference

Description:
This endpoint retrieves a specific transaction for a given customer based on their unique customer_id and a unique transaction reference.

Parameters:

customer_id (path parameter): The unique identifier for the customer whose transaction is being fetched.
reference (path parameter): The unique reference code of the transaction you want to retrieve.

Response:

On success, returns the transaction details including:
- Amount
- Status (e.g., FAILED, COMPLETE, PENDING)
- Date of transaction
- Transaction type (CREDIT or DEBIT)
- Metadata (optional)
Error Handling:
- If the transaction is not found, a 404 Not Found response is returned.
- If an error occurs, a relevant error message with status code is returned.

Example Request:

Notes:

Ensure that the customer_id and reference are correctly passed as path parameters.
Include the X-API-Key header for authentication: X-API-Key: API_KEY

Method: GET

{{BASE_URL}}/transactions/customer/:customer_id/:reference

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Response: 200

Response example:

json

{
  "statusCode": 200,
  "status": "success",
  "data": {
    "id": "509eae9c-9373-486d-b25d-0c46994b66f9",
    "user_id": "2da3424b-1d1e-4155-a65e-d2347c37a73c",
    "reference": "TXN-1736445726-87dc1349d8f78a0a",
    "currency": "NGN",
    "environment": "SANDBOX",
    "status": null,
    "balance_after": 600,
    "balance_before": 400,
    "metadata": null,
    "type": "CREDIT",
    "category": "CREDIT_CUSTOMER_WALLET"
  }
}

Fetch customer transactions

Fetch All Transactions by Customer ID

Endpoint: GET /v1/transactions/customer/:customer_id

Description:
This endpoint retrieves all transactions associated with a specific customer identified by their unique customer_id. Use this to view the complete transaction history for a customer.

Parameters:

customer_id (path parameter): The unique identifier for the customer whose transactions are being fetched.

Response:

On success, returns a list of transactions with details including:
- Amount
- Status (e.g., successful, failed)
- Date of transaction
- Transaction type (credit or debit)
- Metadata (optional)
Error Handling:
- If no transactions are found for the given customer, returns an empty list.
- If the customer ID is invalid, a 404 Not Found response is returned.
- Any other errors will return a relevant error message with a corresponding status code.

Notes:

Ensure that the customer_id is passed correctly as a path parameter.
Include the X-API-Key header for authentication: X-API-Key: API_KEY

Method: GET

{{BASE_URL}}/transactions/customer/:customer_id

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Response: 200

Response example:

json

{
  "statusCode": 200,
  "status": "success",
  "data": [
    {
      "id": "a0d95df4-b004-4c38-95b8-b9308d0340c1",
      "user_id": "2da3424b-1d1e-4155-a65e-d2347c37a73c",
      "reference": "TXN-1736446870-9572309761397768",
      "currency": "NGN",
      "environment": "SANDBOX",
      "status": null,
      "amount": 200,
      "balance_after": 1000,
      "balance_before": 800,
      "metadata": "eyJyZWFzb24iOiAiZm9yIGNvbXBsZXRpb24gb2YgdGFzayJ9",
      "type": "CREDIT",
      "category": "CREDIT_CUSTOMER_WALLET",
      "total_items": 3
    },
    {
      "id": "f94d933c-75c3-42c5-8f6c-ceb7e64f8d80",
      "user_id": "2da3424b-1d1e-4155-a65e-d2347c37a73c",
      "reference": "TXN-1736445802-9e8bc1decbdc2178",
      "currency": "NGN",
      "environment": "SANDBOX",
      "status": null,
      "amount": 0,
      "balance_after": 800,
      "balance_before": 600,
      "metadata": null,
      "type": "CREDIT",
      "category": "CREDIT_CUSTOMER_WALLET",
      "total_items": 3
    },
    {
      "id": "509eae9c-9373-486d-b25d-0c46994b66f9",
      "user_id": "2da3424b-1d1e-4155-a65e-d2347c37a73c",
      "reference": "TXN-1736445726-87dc1349d8f78a0a",
      "currency": "NGN",
      "environment": "SANDBOX",
      "status": null,
      "amount": 0,
      "balance_after": 600,
      "balance_before": 400,
      "metadata": null,
      "type": "CREDIT",
      "category": "CREDIT_CUSTOMER_WALLET",
      "total_items": 3
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "totalItems": 3,
    "totalPages": 1
  }
}

Create customer wallet

Create Wallet

Endpoint: POST /v1/wallets

Description:
This endpoint allows the creation of a new wallet for a customer. You need to provide the customer's personal information, such as BVN, name, date of birth, phone number, email, and address. A wallet will be created and linked to the provided customer details.

Request Body:
The request body must contain the following fields:

bvn (string): The customer's Bank Verification Number (BVN) for identity verification.
first_name (string): The first name of the customer, default is John/Doe for sandbox environment.
last_name (string): The last name of the customer.
date_of_birth (string): The customer's date of birth in DD-MM-YYYY(15-01-1990) format.
phone_number (string): The customer's phone number.
email (string): The customer's email address.
address (string): The customer's residential address.
On success, returns the details of the created wallet, including:
- Wallet ID
- Customer details (name, email, etc.)
- Wallet balance (initially 0)
Error Handling:
- If required fields are missing or invalid, a 400 Bad Request response is returned.
- If there are issues with the provided BVN, a 422 Unprocessable Entity response is returned.
- Other errors will return a relevant error message with the corresponding status code.

Notes:

Ensure that all required fields are included in the request body.
Include the X-API-Key header for authentication: X-API-Key: API_KEY

Method: POST

 {{BASE_URL}}/wallets

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Body (raw)

json

{
  "bvn": "31034529415",
  "first_name": "Leo",
  "last_name": "Doe",
  "date_of_birth": "20-09-2000",
  "phone_number": "03013452943",
  "email": "igbayomarvelous02@gmail.com",
  "address": "No 12, Rahama Road, Kaduna"
}

Response: 201

Response example:

json

{
  "success": true,
  "message": "Customer wallet created successfully",
  "data": {
    "id": "964aaac3-2db7-4f88-809e-23d8c3667dd2",
    "merchant_id": "c0f0faec-5f1a-450f-84c7-20c7a18d1249",
    "environment": "SANDBOX",
    "currency": "NGN",
    "bank_name": "Xpresswallet",
    "bank_code": "100040",
    "account_name": "Salu Belben",
    "account_number": "4401630673",
    "updated_at": "2025-04-04T08:58:29.638524Z",
    "created_at": "2025-04-04T08:58:29.638524Z",
    "booked_balance": 0,
    "available_balance": 0,
    "status": "ACTIVE",
    "updated": false,
    "wallet_type": "Customer",
    "user_id": "ed382df0-b6f6-4210-bc8b-5dd7d6721caa"
  }
}

Fetch Customer Wallets

Fetch Wallets (Paginated)

Endpoint: GET /v1/wallets

Description:
This endpoint allows you to fetch a list of customer wallets with pagination. You can specify the page number and limit to control how many wallets are returned per request. This is useful when you need to retrieve a large set of wallets in chunks.

Query Parameters:

page (integer): The page number to retrieve. Defaults to 1 if not provided.
limit (integer): The number of wallets to return per page. Defaults to 10 if not provided. The maximum allowed value is 100.

Response:

On success, returns a paginated list of wallets with the following details:
- Customer information (e.g., name, email, etc.)
- Wallet balance
- Pagination details (e.g., current page, total pages, etc.)
Error Handling:
- If the page or limit parameters are invalid (e.g., negative numbers or non-integer values), a 400 Bad Request response is returned.
- Any other errors will return a relevant error message with the corresponding status code.

Notes:

Ensure that the page and limit query parameters are provided for pagination.
Include the X-API-Key header for authentication: X-API-Key: API_KEY

Method: GET

{{BASE_URL}}/wallets?page_number=1&page_size=5

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Query Params

Param	value
page_number	1
page_size	5

Response: 200

Response example:

json

{
  "success": true,
  "message": "Successfully fetched wallets",
  "data": [
    {
      "id": "964aaac3-2db7-4f88-809e-23d8c3667dd2",
      "merchant_id": "c0f0faec-5f1a-450f-84c7-20c7a18d1249",
      "environment": "SANDBOX",
      "currency": "NGN",
      "bank_name": "Xpresswallet",
      "bank_code": "100040",
      "account_name": "Salu Belben",
      "account_number": "4401630673",
      "updated_at": "2025-04-04T08:58:29.638524Z",
      "created_at": "2025-04-04T08:58:29.638524Z",
      "booked_balance": 100,
      "available_balance": 100,
      "status": "ACTIVE",
      "updated": false,
      "wallet_type": "Customer",
      "user_id": "ed382df0-b6f6-4210-bc8b-5dd7d6721caa"
    }
  ]
}

Fetch wallet

Fetch Customer Wallet

Endpoint: GET /v1/wallets/:customer_id

Description:
This endpoint allows you to fetch the details of a customer's wallet using their unique customer_id. The response will contain the wallet information such as the current balance and other associated customer details.

Parameters:

customer_id (path parameter): The unique identifier of the customer whose wallet is being fetched.

Response:

On success, returns the wallet details, including:
- Customer information (e.g., name, email, etc.)
- Wallet balance
- Additional metadata (if available)
Error Handling:
- If the customer wallet does not exist, a 404 Not Found response is returned.
- If the customer_id is invalid, a 400 Bad Request response is returned.
- Any other errors will return a relevant error message with the corresponding status code.

Notes:

Ensure that the customer_id is passed correctly as a path parameter.
Include the X-API-Key header for authentication: X-API-Key: API_KEY

Method: GET

{{BASE_URL}}/wallets/:customer_id

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Response: 200

Response example:

json

{
  "success": true,
  "message": "Successfully fetched wallet",
  "data": {
    "id": "964aaac3-2db7-4f88-809e-23d8c3667dd2",
    "merchant_id": "c0f0faec-5f1a-450f-84c7-20c7a18d1249",
    "environment": "SANDBOX",
    "currency": "NGN",
    "bank_name": "Xpresswallet",
    "bank_code": "100040",
    "account_name": "Salu Belben",
    "account_number": "4401630673",
    "updated_at": "2025-04-04T08:58:29.638524Z",
    "created_at": "2025-04-04T08:58:29.638524Z",
    "booked_balance": 100,
    "available_balance": 100,
    "status": "ACTIVE",
    "updated": false,
    "wallet_type": "Customer",
    "user_id": "ed382df0-b6f6-4210-bc8b-5dd7d6721caa"
  }
}

Credit customer

Credit Customer Wallet

Endpoint: POST /v1/wallets/credit

Description:
This endpoint allows you to credit a customer's wallet with a specified amount. You need to provide the customer_id, amount, and optional reference. If a reference is provided by the client, it will be used; otherwise, a reference will be automatically generated.

Request Body:
The request body must contain the following fields:

amount (float): The amount to credit to the customer's wallet.
customer_id (string): The unique identifier of the customer whose wallet is being credited.
reference (string, optional): The unique reference for the transaction. If not provided, a reference will be automatically generated for you.
metadata (object, optional): Additional information regarding the transaction. In this case, a reason field can be included, such as the purpose for the credit. If no reference is provided, the system will generate one.

Response:

On success, returns a confirmation of the credited amount along with the transaction details:
- Amount credited
- Customer wallet balance (updated)
- Transaction reference
- Metadata (if included)
Error Handling:
- If any required fields are missing or invalid, a 400 Bad Request response is returned.
- If the customer_id does not exist, a 404 Not Found response is returned.
- If the amount is negative or invalid, a 400 Bad Request response is returned.
- Any other errors will return a relevant error message with the corresponding status code.

Method: POST

{{BASE_URL}}/wallets/credit

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Body (raw)

json

{
  "amount": 1000,
  "customer_id": "fd9ae7c6-61a7-4f5a-b44f-63f49fa2c577",
  "metadata": {
    "reason": "for completion of task"
  }
}

🔑 Authentication noauth

Param	value	Type

Response: 201

Response example:

json

{
  "success": true,
  "message": "Successfully credit customer wallet",
  "data": {
    "id": "f92abf64-ca8a-44f5-b633-bdbf1f202546",
    "reference": "TXN-1743766099-328df4d3f44bcafc",
    "currency": "NGN",
    "environment": "SANDBOX",
    "balance_after": 100,
    "balance_before": 50,
    "merchant_id": "c0f0faec-5f1a-450f-84c7-20c7a18d1249",
    "metadata": "eyJyZWFzb24iOiAiZm9yIGNvbXBsZXRpb24gb2YgdGFzayJ9",
    "amount": 50,
    "status": "COMPLETED",
    "destination": null,
    "description": null,
    "type": "CREDIT",
    "category": "CREDIT_CUSTOMER_WALLET"
  }
}

Fetch transaction by reference

Fetch Transaction by Reference

Endpoint: GET /v1/transactions/:reference

Description:
This endpoint retrieves a specific transaction using its unique transaction reference. The reference is typically a code generated for each transaction to track it in the system.

Parameters:

reference (path parameter): The unique reference code of the transaction you want to retrieve. This reference is assigned to each transaction at the time of creation.

Response:

On success, returns the transaction details including:
- Amount
- Status (e.g., successful, failed)
- Date of transaction
- Transaction type (credit or debit)
- Metadata (optional)
Error Handling:
- If the transaction is not found, a 404 Not Found response is returned.
- If an invalid reference is provided, a 400 Bad Request response is returned.
- Any other errors will return a relevant error message with status code.

Notes:

Ensure that the reference is passed correctly as a path parameter.
Include the X-API-Key header for authentication: X-API-Key: API_KEY

Method: GET

{{BASE_URL}}/transactions/TXN-1746091774-9a097fcb63592df3

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

🔑 Authentication noauth

Param	value	Type

Response: 200

Response example:

json

{
  "success": true,
  "message": "Successfully fetched transactions",
  "data": {
    "id": "4b74a5b6-6419-4621-9bfd-0b20da820748",
    "user_id": "38d48e8a-6bb4-4565-b67a-a5dbb51fb755",
    "merchant_id": "cf07ad9f-35c1-4036-9f01-9e03f6c2f22b",
    "reference": "TXN-1745837500-8d8c8442b1ed68e7",
    "currency": "NGN",
    "environment": "SANDBOX",
    "from_wallet_id": "33218f41-4067-4bb4-b3d4-1bc32f202583",
    "to_wallet_id": "d7d68f02-82cb-455d-805f-7613246ab67b",
    "amount": 100,
    "status": "COMPLETED",
    "balance_after": 100,
    "balance_before": 0,
    "metadata": "eyJyZWFzb24iOiAiZm9yIGNvbXBsZXRpb24gb2YgdGFzayJ9",
    "type": "CREDIT",
    "category": "CREDIT_CUSTOMER_WALLET"
  }
}

Wallet to wallet transfer

Method: POST

{{BASE_URL}}/wallets/transfer/bank

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Body (raw)

json

{
  "amount": 1000,
  "from_wallet_id": "23f59762-8dea-4eca-908e-4e57df125527",
  "to_wallet_id": "517aef2c-1a35-4166-b77f-33fc7d2d97a7",
  "narration": "Customer transfer",
  "reference": "0briwiiipkpiVcxMLd",
  "metadata": {
    "reason": "for completion of task"
  }
}

//23f59762-8dea-4eca-908e-4e57df125527

Upgrade To Tier Two Wallet

Create Wallet

Endpoint: POST /v1/wallets

Request Body:
The request body must contain the following fields:

bvn (string): The customer's Bank Verification Number (BVN) for identity verification.
first_name (string): The first name of the customer, default is John/Doe for sandbox environment.
last_name (string): The last name of the customer.
date_of_birth (string): The customer's date of birth in DD-MM-YYYY(15-01-1990) format.
phone_number (string): The customer's phone number.
email (string): The customer's email address.
address (string): The customer's residential address.
On success, returns the details of the created wallet, including:
- Wallet ID
- Customer details (name, email, etc.)
- Wallet balance (initially 0)
Error Handling:
- If required fields are missing or invalid, a 400 Bad Request response is returned.
- If there are issues with the provided BVN, a 422 Unprocessable Entity response is returned.
- Other errors will return a relevant error message with the corresponding status code.

Notes:

Ensure that all required fields are included in the request body.
Include the X-API-Key header for authentication: X-API-Key: API_KEY

Method: POST

{{BASE_URL}}/wallets/upgrade-tier-2

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Body (raw)

json

{
  "nin": "31034529415",
  "account_number": "4000033892"
}

Response: 201

Response example:

json

{
  "success": true,
  "message": "Customer wallet created successfully",
  "data": {
    "id": "964aaac3-2db7-4f88-809e-23d8c3667dd2",
    "merchant_id": "c0f0faec-5f1a-450f-84c7-20c7a18d1249",
    "environment": "SANDBOX",
    "currency": "NGN",
    "bank_name": "Xpresswallet",
    "bank_code": "100040",
    "account_name": "Salu Belben",
    "account_number": "4401630673",
    "updated_at": "2025-04-04T08:58:29.638524Z",
    "created_at": "2025-04-04T08:58:29.638524Z",
    "booked_balance": 0,
    "available_balance": 0,
    "status": "ACTIVE",
    "updated": false,
    "wallet_type": "Customer",
    "user_id": "ed382df0-b6f6-4210-bc8b-5dd7d6721caa"
  }
}

Create Tier Two Wallet

Create Wallet

Endpoint: POST /v1/wallets

Request Body:
The request body must contain the following fields:

bvn (string): The customer's Bank Verification Number (BVN) for identity verification.
first_name (string): The first name of the customer, default is John/Doe for sandbox environment.
last_name (string): The last name of the customer.
date_of_birth (string): The customer's date of birth in DD-MM-YYYY(15-01-1990) format.
phone_number (string): The customer's phone number.
email (string): The customer's email address.
address (string): The customer's residential address.
On success, returns the details of the created wallet, including:
- Wallet ID
- Customer details (name, email, etc.)
- Wallet balance (initially 0)
Error Handling:
- If required fields are missing or invalid, a 400 Bad Request response is returned.
- If there are issues with the provided BVN, a 422 Unprocessable Entity response is returned.
- Other errors will return a relevant error message with the corresponding status code.

Notes:

Ensure that all required fields are included in the request body.
Include the X-API-Key header for authentication: X-API-Key: API_KEY

Method: POST

{{BASE_URL}}/wallets/tier-2

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Body (raw)

json

{
  "bvn": "31034529411",
  "nin": "53230490802",
  "first_name": "Leo",
  "last_name": "Doe",
  "date_of_birth": "15-01-1990",
  "phone_number": "09013452943",
  "email": "igbayomarvelous02@gmail.com",
  "address": "No 12, Rahama Road, Kaduna"
}

Response: 201

Response example:

json

{
  "success": true,
  "message": "Customer wallet created successfully",
  "data": {
    "id": "964aaac3-2db7-4f88-809e-23d8c3667dd2",
    "merchant_id": "c0f0faec-5f1a-450f-84c7-20c7a18d1249",
    "environment": "SANDBOX",
    "currency": "NGN",
    "bank_name": "Xpresswallet",
    "bank_code": "100040",
    "account_name": "Salu Belben",
    "account_number": "4401630673",
    "updated_at": "2025-04-04T08:58:29.638524Z",
    "created_at": "2025-04-04T08:58:29.638524Z",
    "booked_balance": 0,
    "available_balance": 0,
    "status": "ACTIVE",
    "updated": false,
    "wallet_type": "Customer",
    "user_id": "ed382df0-b6f6-4210-bc8b-5dd7d6721caa"
  }
}

Create Tier Three Wallet

Method: POST

{{BASE_URL}}/wallets/tier-3

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Body formdata

Param	value	Type
utility_bill_image	/C:/Users/USER/Downloads/ChatGPT Image Oct 3, 2025, 03_57_11 PM.png	file
address	49 MODUPE STREET FOLA AGORO, LAGOS	text
bvn	00000000000	text
postal_ccode	20832	text
country	Nigeria	text
state	LAGOS	text
nin	00000000000	text
lga	Ikeja	text
first_name	John	text
last_name	Doe	text
city	Lagos	text
phone	1234567895	text
email	gla6@gmail.com	text
dob	1990-01-15	text

🔑 Authentication bearer

Param	value	Type
token	eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIzMnVJTUlnUEN4UHVfRmhqT29IZHdXaDVvanM5YXVxblRJak53RTlPaGlvIn0.eyJleHAiOjE3NjI1NjgwNDQsImlhdCI6MTc2MjUzMjA0NCwianRpIjoiOTVhNGVkYmYtMWQzYi00MzY0LWEyOWYtYzZjZTIxNDU1NmZlIiwiaXNzIjoiaHR0cHM6Ly9iYWFzLWF1dGguZGV2LmdldHJvdmEuY28udWsva2V5Y2xvYWsvcmVhbG1zL3JvdmEiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiNzUwZDQwNjQtMmJiNC00Zjk0LWEyN2QtODI3M2Q2ZTFiYTIyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiMDFKREFBNUs3U1ZGM1JER05OOUY2NlRSOVAiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJkZWZhdWx0LXJvbGVzLXJvdmEiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2QgZW1haWwgYWRkcmVzcyBwcm9maWxlIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJjbGllbnRIb3N0IjoiMTAuMC40LjIyMyIsImFkZHJlc3MiOnt9LCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtMDFqZGFhNWs3c3ZmM3JkZ25uOWY2NnRyOXAiLCJjbGllbnRBZGRyZXNzIjoiMTAuMC40LjIyMyIsImNsaWVudF9pZCI6IjAxSkRBQTVLN1NWRjNSREdOTjlGNjZUUjlQIn0.Ggv1H4GH3GC70VbSGW1bSTI4KNq0XK7Torb2AgeXleMVoas1_Sbo-7DiAPNlOciMLzfdRmTR1xkkMt_bgZkenNi3gCnfM2pzL6jSftKEGT8yGQFFclMh6SfQSGv9HRJ9TE6muPSFlzc3npyw2ZqDBV-ljJmRKDBn3gzyyuYxgO6x5tDdiNpZDSa8YWPC904uD-7nd0z3W8rQ3nTKBNi3c2vlQKrJppQEm0eJFDacGQ-oRtLy2GSEEWpjeYJBauynOCTdEG0RNRX9Uu-JFeoQB-OppkmDvpzpaIn3i09Y-i2sjnhswPDDBbWHo7MAFOQ5xRlo9zyWtDGQNuhXm8FQ	string

Response: 201

Response example:

json

{
  "success": true,
  "message": "Wallet created successfully",
  "data": {
    "id": "b07ac185-5b9d-44a6-bdca-88c40941e86a",
    "merchant_id": "d0c70a28-1023-484e-849f-3fb41cee743b",
    "environment": "SANDBOX",
    "currency": "NGN",
    "bank_name": "FCMB MFB",
    "bank_code": "090409",
    "account_name": "John Doe",
    "account_number": null,
    "updated_at": "2025-09-05T11:13:14.884459Z",
    "created_at": "2025-09-05T11:13:14.884459Z",
    "booked_balance": 0,
    "available_balance": 0,
    "status": "IN_ACTIVE",
    "updated": false,
    "user_id": "03e08fe0-c341-45fb-bfda-60777df710c1",
    "account_type": "WALLET",
    "expiry_time": null,
    "account_category": "CUSTOMER",
    "tier": "TIER_THREE"
  }
}

Freeze Wallet

Method: POST

{{BASE_URL}}/wallets/freeze

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Body (raw)

json

{
  "account_number": "4000033892",
  "reason": "i dont want to bank with you"
}

🔑 Authentication bearer

Param	value	Type
token	`BEARER_TOKEN`	string

UnFreeze Wallet

Method: POST

{{BASE_URL}}/wallets/freeze

Headers

Content-Type	Value
X-API-Key	`X-API-Key`

Body (raw)

json

{
  "account_number": "4000033892",
  "reason": "i dont want to bank with you"
}

🔑 Authentication bearer

Param	value	Type
token	`BEARER_TOKEN`	string

Get Tier Three Wallet Status

Method: GET

Query Params

Param	value
reference	b07ac185-5b9d-44a6-bdca-88c40941e86a

🔑 Authentication bearer

Param	value	Type
token	eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIzMnVJTUlnUEN4UHVfRmhqT29IZHdXaDVvanM5YXVxblRJak53RTlPaGlvIn0.eyJleHAiOjE3NTcxMDQ4NDgsImlhdCI6MTc1NzA2ODg0OCwianRpIjoiMDUxMGMyOWItMDlhZS00ZTJjLWExOTItMWJmNDI2YjFmOTIzIiwiaXNzIjoiaHR0cHM6Ly9iYWFzLWF1dGguZGV2LmdldHJvdmEuY28udWsva2V5Y2xvYWsvcmVhbG1zL3JvdmEiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiNzUwZDQwNjQtMmJiNC00Zjk0LWEyN2QtODI3M2Q2ZTFiYTIyIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiMDFKREFBNUs3U1ZGM1JER05OOUY2NlRSOVAiLCJhY3IiOiIxIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJkZWZhdWx0LXJvbGVzLXJvdmEiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6InByb2QgZW1haWwgYWRkcmVzcyBwcm9maWxlIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJjbGllbnRIb3N0IjoiMTAuMC41LjM3IiwiYWRkcmVzcyI6e30sInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC0wMWpkYWE1azdzdmYzcmRnbm45ZjY2dHI5cCIsImNsaWVudEFkZHJlc3MiOiIxMC4wLjUuMzciLCJjbGllbnRfaWQiOiIwMUpEQUE1SzdTVkYzUkRHTk45RjY2VFI5UCJ9.Fxi9RMW8C2vX-Qed77wMqb9qypXe8W2UGW4yw2VAfcW5jvjtSRPs_B4AFqPo5As56xBAu_WC_0dXpl_0nOcbDGdvDBsr8PtKSPlxeYKWCEB2J2wG6pEqKUHkV1m-TPfal5O2maRYt2xbcT8Im2RHTD3yE4drUMthMypEhAVMADc2QGDUIUq6fpXhQnx20YxJe5IMl88H4pKWX--CcB7eA0NIxP_YQXlLlGlOJ3R0lixj8dzx5cjedY847HY9N4Z52fsXe1j71td-k1GYjji8ZryADXuxoKc0CEZ6FRgUlRlQxAzjN9o8a1OQZjFbwMC7zJ42uvL7BpO9r8TgJ5btqA	string

Fetch Merchant Wallet Details

Method: GET

{{BASE_URL}}/wallets/merchants

Response: 200

Response example:

json

{
  "success": true,
  "message": "wallet detail retrieved successfully",
  "data": {
    "id": "2bc8d899-c2a2-44d6-7960-55117e4a9462",
    "merchant_id": "d0c70a82-1023-484e-849f-3fb41cee743b",
    "environment": "SANDBOX",
    "currency": "NGN",
    "bank_name": "Bank name",
    "bank_code": "Bank code",
    "account_name": "Account name",
    "account_number": "9900981701",
    "updated_at": "2025-05-01T19:11:11.020038Z",
    "created_at": "2025-05-01T19:11:11.020038Z",
    "booked_balance": 0,
    "available_balance": 55349,
    "status": "ACTIVE",
    "updated": false,
    "user_id": null,
    "account_type": "WALLET",
    "expiry_time": null,
    "account_category": "MERCHANT"
  }
}

Wallet ​

Fetch customer transaction ​

Method: GET ​

Headers ​

Response: 200 ​

Fetch customer transactions ​

Method: GET ​

Headers ​

Response: 200 ​

Create customer wallet ​

Method: POST ​

Headers ​

Body (raw) ​

Response: 201 ​

Fetch Customer Wallets ​

Method: GET ​

Headers ​

Query Params ​

Response: 200 ​

Fetch wallet ​

Method: GET ​

Headers ​

Response: 200 ​

Credit customer ​

Method: POST ​

Headers ​

Body (raw) ​

🔑 Authentication noauth ​

Response: 201 ​

Fetch transaction by reference ​

Method: GET ​

Headers ​

🔑 Authentication noauth ​

Response: 200 ​

Wallet to wallet transfer ​

Method: POST ​

Headers ​

Body (raw) ​

Upgrade To Tier Two Wallet ​

Method: POST ​

Headers ​

Body (raw) ​

Response: 201 ​

Create Tier Two Wallet ​

Method: POST ​

Headers ​

Body (raw) ​

Response: 201 ​

Create Tier Three Wallet ​

Method: POST ​

Headers ​

Body formdata ​

🔑 Authentication bearer ​

Response: 201 ​

Freeze Wallet ​

Method: POST ​

Headers ​

Body (raw) ​

🔑 Authentication bearer ​

UnFreeze Wallet ​

Method: POST ​

Headers ​

Body (raw) ​

🔑 Authentication bearer ​

Get Tier Three Wallet Status ​

Method: GET ​

Query Params ​

🔑 Authentication bearer ​

Fetch Merchant Wallet Details ​

Method: GET ​

Response: 200 ​

Wallet

Fetch customer transaction

Method: GET

Headers

Response: 200

Fetch customer transactions

Method: GET

Headers

Response: 200

Create customer wallet

Method: POST

Headers

Body (raw)

Response: 201

Fetch Customer Wallets

Method: GET

Headers

Query Params

Response: 200

Fetch wallet

Method: GET

Headers

Response: 200

Credit customer

Method: POST

Headers

Body (raw)

🔑 Authentication noauth

Response: 201

Fetch transaction by reference

Method: GET

Headers

🔑 Authentication noauth

Response: 200

Wallet to wallet transfer

Method: POST

Headers

Body (raw)

Upgrade To Tier Two Wallet

Method: POST

Headers

Body (raw)

Response: 201

Create Tier Two Wallet

Method: POST

Headers

Body (raw)

Response: 201

Create Tier Three Wallet

Method: POST

Headers

Body formdata

🔑 Authentication bearer

Response: 201

Freeze Wallet

Method: POST

Headers

Body (raw)

🔑 Authentication bearer

UnFreeze Wallet

Method: POST

Headers

Body (raw)

🔑 Authentication bearer

Get Tier Three Wallet Status

Method: GET

Query Params

🔑 Authentication bearer

Fetch Merchant Wallet Details

Method: GET

Response: 200