Merchant Wallets

Overview

The Merchant Wallet Public API provides a comprehensive set of endpoints for managing merchant wallets, including wallet creation, balance inquiries, transactions, and transfers. This API enables merchants to programmatically manage their wallet operations within the Interswitch ecosystem.

Base URL: https://merchant-wallet.k8.isw.la/merchant-wallet

API Version: v1

Authentication

All API requests require Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer {your_access_token}

The Bearer token should be obtained through the Interswitch OAuth2 authentication flow and will contain merchant-specific claims.

You can view how to generate an access token here Authentication

Endpoints

Create Wallet

Creates a new merchant wallet for transaction management.

Endpoint: POST /api/v1/wallet

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
    "name": "string",
    "merchantCode": "string",
    "status": "ACTIVE",
    "mobileNo": "string",
    "provider": "PRIME",
    "firstName": "string",
    "pin": "string",
    "email": "string"
}

Request Parameters:

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "walletId": "string",
        "name": "string",
        "merchantCode": "string",
        "status": "ACTIVE"
    }
}

Get Merchant Wallet

Retrieves wallet information for a specific merchant.

Endpoint: GET /api/v1/wallet/{merchantCode}

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Path Parameters:

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "walletId": "string",
        "name": "string",
        "merchantCode": "string",
        "status": "string",
        "balance": number,
        "mobileNo": "string"
    }
}

Get Wallet Balance

Retrieves the current balance for a specific wallet.

Endpoint: GET /api/v1/wallet/balance/{merchantCode}

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Path Parameters:

Query Parameters:

Example Request:

GET /api/v1/wallet/balance/MX16174?walletId=3570000409

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "walletId": "3570000409",
        "balance": number,
        "currency": "NGN"
    }
}

Get Wallet Details

Retrieves detailed information about a wallet including balance and transaction history.

Endpoint: GET /api/v1/details/balance/{merchantCode}

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Path Parameters:

Query Parameters:

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "walletId": "string",
        "balance": number,
        "ledgerBalance": number,
        "availableBalance": number,
        "currency": "NGN"
    }
}

Transact (Debit Wallet)

Debits a merchant wallet for a transaction.

Endpoint: POST /api/v1/transaction/transact

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
    "walletId": "string",
    "amount": "string",
    "pin": "string",
    "reference": "string",
    "transactionCode": "string",
    "narration": "string"
}

Request Parameters:

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "transactionCode": "api-charge",
    "reference": "bdgeyweiektj",
    "data": {
        "amount": 100,
        "walletId": "3570011881",
        "transactionCode": "api-charge",
        "narration": "prevvv  everyyyyyyyeveryyyyyyydemoo",
        "reference": "bdgeyweiektj",
        "multiple": false
    }
}

Reverse Transaction

Reverses a previously completed transaction.

Endpoint: POST /api/v1/transaction/reverse

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
    "walletId": "string",
    "reference": "string",
    "reversalReference": "string"
}

Request Parameters:

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "reversalReference": "string",
        "originalReference": "string",
        "status": "REVERSED"
    }
}

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "transactionReference": "string",
        "status": "PROCESSING",
        "details": []
    }
}

Get Transaction Summary

Retrieves a summary of wallet transactions within a date range.

Endpoint: GET /api/v1/transaction/summary

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Query Parameters:

Example Request:

GET /api/v1/transaction/summary?startDate=01/03/2023&endDate=31/10/2024&merchantCode=MX16174&walletId=3570000409

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "transactions": [
            {
                "reference": "string",
                "amount": number,
                "transactionDate": "string",
                "status": "string",
                "narration": "string"
            }
        ],
        "totalCount": number,
        "totalAmount": number
    }
}

Get Transaction by Reference

Retrieves a specific transaction by its reference number.

Endpoint: GET /api/v1/transaction/

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Query Parameters:

Example Request:

GET /api/v1/transaction/?merchantCode=MX16174&reference=edeydomewawawaw

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "reference": "string",
        "amount": number,
        "transactionDate": "string",
        "status": "string",
        "walletId": "string",
        "narration": "string",
        "transactionType": "string"
    }
}

GET /api/v1/transaction/re-query?walletId=3570000409&paymentReference=7620335110RRDDJKLTMRKF1LM

Success Response:

{
    "statusCode": "200",
    "responseCode": "00",
    "responseMessage": "SUCCESSFUL",
    "data": {
        "paymentReference": "string",
        "status": "string",
        "amount": number,
        "transactionDate": "string"
    }
}

Response Codes

The API uses standard response codes to indicate the status of requests:

Error Handling

All API responses follow a standard error format:

{
    "statusCode": "string",
    "responseCode": "string",
    "responseMessage": "string",
    "error": {
        "code": "string",
        "message": "string",
        "details": "string"
    }
}

Common Error Scenarios:

1. Authentication Failure (401)

   • Invalid or expired Bearer token
   • Missing Authorization header

2. Validation Error (400)

   • Missing required fields
   • Invalid data format
   • Invalid PIN

3. Not Found (404)

   • Wallet not found
   • Transaction reference not found

4. Insufficient Funds (400)

   • responseCode: "51"
   • Wallet balance insufficient for transaction

5. System Error (500)

   • Internal server error
   • Service temporarily unavailable

Best Practices

Security

1. Token Management

   • Store Bearer tokens securely
   • Implement token refresh mechanism
   • Never expose tokens in client-side code

2. PIN Handling

   • Never log or store PINs in plain text
   • Use HTTPS for all API communications
   • Implement PIN retry limits

3. Reference Generation

   • Generate unique references for each transaction
   • Use timestamp + random string for uniqueness
   • Store references for reconciliation

Transaction Management

1. Idempotency

   • Use unique references to prevent duplicate transactions
   • Implement transaction status checking
   • Handle timeout scenarios gracefully

2. Balance Verification

   • Check wallet balance before initiating transactions
   • Handle insufficient fund scenarios

3. Transaction Monitoring

   • Use re-query endpoint to verify transaction status
   • Implement webhook handlers for transaction notifications
   • Reconcile transactions regularly

Error Recovery

1. Retry Logic

   • Implement exponential backoff for retries
   • Don't retry transactions that have completed
   • Log all retry attempts

2. Status Verification

   • Always verify transaction status before retry
   • Use the re-query endpoint for status checks
   • Implement timeout handling

Testing

Test Environment

• Base URL: (Contact support for test environment URL)
• Test Merchant Code: (Provided upon registration)
• Test Wallet IDs: (Provided upon registration)

Test Cards/Wallets

Test wallets are provided with pre-loaded balances for testing various scenarios including successful transactions, insufficient funds, and error conditions.