User Guide: Leveraging the Wallet Service and Transfers API

Introduction

This guide will walk you through how to leverage the Wallet Service and Transfers API provided by the platform. By the end of this guide, you will be able to:

Sign up as a new user.
Create a tenant space.
Enable and use various services and products tailored to your needs.

Prerequisites:

A registered Katsu account
Understanding of secure coding practices

RoleSignUpType Description

The RoleSignUpType enumeration defines the various roles that a user can have when signing up for the platform. Each role has specific permissions and functionalities associated with it, catering to different types of users and business entities.

Descriptions of Users by roles

CUSTOMER Individuals making purchases, using wallet services, and accessing personal financial tools provisioned for a super admin.

MERCHANT A business entity or individual selling goods or services through the platform. Retailers, shop owners, and online sellers managing sales, inventory, and customer interactions.

SUPPLIER A provider of products or services, often to merchants or businesses. Eg Vendors supplying goods to merchants, handling orders, and managing logistics.

BUSINESS A general business account used by companies to manage their operations on the platform. Companies of various sizes utilizing the platform for business transactions, employee management, and financial services.

CLIENT An entity or individual receiving services from another business or partner on the platform. Customers or organizations that use services provided by merchants, suppliers, or partners.

PARTNER Entities collaborating with the platform to offer combined services or products. Businesses engaging in strategic partnerships, co-branding, or joint ventures with the platform.

AGENCY_BANKING Agents providing banking services on behalf of financial institutions. Agents offering services such as cash deposits, withdrawals, and other banking operations in remote or underserved areas.

SABI_AGENT Agents specifically affiliated with the Sabi platform to offer various services. Representatives providing Sabi-specific services, customer support, and on-the-ground operations.

SABI_OWN Accounts owned by the Sabi platform itself for managing internal operations. Administrative accounts used by Sabi for platform management, support, and internal transactions.

TRACE_BUYER Users who are buyers within the TRACE system, a part of the platform's ecosystem. Entities or individuals buying goods or services within the TRACE network.

TRACE_SELLER Users who are sellers within the TRACE system. Entities or individuals selling goods or services within the TRACE network.

FARMER Farmers managing crop sales, supply chain, and financial transactions related to agriculture.

DRIVER Drivers handling logistics, deliveries, and transportation services for various entities on the platform.

TENANT_SUPER_ADMIN Administrators responsible for managing all aspects of a tenant's account, including user management, financial transactions, and service configurations.

Katsu Wallet Services Overview

Katsu offers a comprehensive suite of financial services, including secure and efficient wallet functionalities. This guide focuses on integrating these features into your application using Katsu's well-documented APIs.

Authentication

To access Katsu's services, you'll need to obtain proper authentication credentials. These credentials include:

baseURL: Base URL for the Katsu API (e.g., https://dfs-registry-dev.sabi.am)
apiKey: Your unique API key for authentication
accessToken: Access token for authentication (generated during user registration)
tenantID: Unique identifier for your tenant space
userID: Unique identifier for a user within your tenant space
referenceID: Unique identifier for a specific transaction/action

Environment Variables	Description	Example Value
`baseURL`	Platform base URL	`{platformBaseUrl}`
`apiKey`	Set your wallet API key in the header	`yourApiKey`
`accessToken`	authenticate using the bearer token header	`yourBearerToken`
`tenantId`	Identifies a service; wallet tenant-id	`yourTenantId`
`userId`	Unique identifier for a user	`yourUserId`
`referenceId`	Unique identifier for a specific transaction/action	`yourReferenceId`
`countryCode`	Two-letter country code (ISO 3166-1)	`yourCountryCode`

You can refer to Katsu's official API documentation for detailed instructions on acquiring authentication credentials.

Tenant account set up

Sign Up as Tenant Super Admin To initiate the setup of a tenant within the Katsu Platform, the first step entails registering on the platform itself. This registration process involves creating an administrative account, which serves as the anchor for managing your designated space. The registration is facilitated through an API endpoint, utilizing a POST request to api/v1/users/public. Providing the required details for user creation, such as username, password, role, first name, last name, country, phone, among others.

Create an account

This endpoint allows you to register as a new user on the Katsu platform. Upon successful registration, you'll be granted access to the platform's features.

Request Body: The request body should be formatted in JSON and include the following parameters:

username (required):
- String. Unique identifier for your account.
password (required):
- String. Your secure login password.
role (required):
- String. Defines your user role on the platform (e.g., "TENANT_SUPER_ADMIN").
firstName (required):
- String. Your first name.
lastName (required):
- String. Your last name.
middleName (optional):
- String. Your middle name, if applicable.
country (required):
- Object. Contains your country information.
  - name (required):
    - String. Full name of your country.
  - code (required):
    - String. Two-letter country code.
  - currency (required):
    - String. The currency used in your country.
state (required):
- Object. Contains your state information.
  - name (required):
    - String. Full name of your state.
  - code (required):
    - String. Two-letter state code, if applicable.

phone (required):

String. Your phone number, including country code.

Method: POST

URL: {{baseURL}}/api/v1/users/public

Headers:

apiKey: {{apiKey}}

Body:

{
    "username": "testingexample@gmail.com",
    "password": "testingpassword@*",
    "role": "TENANT_SUPER_ADMIN",
    "firstName": "John",
    "lastName": "Doe",
    "country": {
        "name": "Nigeria",
        "code": "NG",
        "currency": "NGN"
    },
    "phone": "0703XXXXXXX"
}

Example

    curl --location 'https://dfs-registry-dev.sabi.am/api/v1/users/public' \
    --header 'apiKey: {{apiKey}}' \
    --data-raw '{
        "username": "testingexample@gmail.com",
        "password": "Makingmoney4*",
        "role": "TENANT_SUPER_ADMIN",
        "firstName": "John",
        "lastName": "Doe",
        "country": {
            "name": "Nigeria",
            "code": "NG",
            "currency": "NGN"
        },
        "phone": "07036497798"
}'

Response

{
    "wallet": {
        "createdAt": null,
        "virtualBankCode": "035",
        "virtualBankName": "Wema Bank"
    },
    "location": {
        "coordinates": [
            0,
            0
        ],
        "type": "Point"
    },
    "metadata": {
        "essentialCertification": []
    },
    "_id": "6653cbedd3ac52fd2d4364cb",
    "__v": 0,
    "appDefaultView": {
        "TRACE": "NONE",
        "LOFT": "NONE",
        "KATSU": "NONE",
        "SABI_MARKET": "NONE",
        "PLATFORM": "NONE",
        "DEAL": "NONE"
    },
    "businesses": [],
    "bvnVerified": false,
    "commodityActiveTraderStatus": "NONE",
    "country": {
        "name": "Nigeria",
        "code": "NG",
        "currency": "NGN",
        "_id": "6653cbed950fb36672aa2a86"
    },
    "createdAt": "2024-05-26T23:55:24.792Z",
    "createdBy": null,
    "driversLicenseVerified": false,
    "emailVerification": false,
    "firstName": "John",
    "hasPin": false,
    "isDistributor": false,
    "isForeigner": false,
    "isManufacturer": false,
    "lastName": "Doe",
    "ninVerified": false,
    "passId": "SLW-acce255fd96ae5916a3796f14eca43",
    "passportNumberVerified": false,
    "password": null,
    "passwordExpirationDate": null,
    "permissions": [],
    "phone": "2347036497798",
    "phoneVerified": false,
    "profileOwners": [],
    "roles": [
        "TENANT_SUPER_ADMIN",
        "TENANT_GLOBAL"
    ],
    "status": "ACTIVE",
    "tenants": [],
    "type": "USER",
    "updatedAt": "2024-05-26T23:55:24.792Z",
    "username": "testingexample@gmail.com",
    "voterCardVerified": false
}

Log In

Access your tenant account by logging in with the required credentials. This endpoint authenticates the user and provides access to the Katsu platform services based on the specified role.

Request Body:

username (string): This is the email address used to log in to the tenant account.
password (string): This is the password associated with the tenant account.
role (string): This defines the user's role within the tenant account. For this example, the role is "TENANT_SUPER_ADMIN", which grants the highest level of access and control over the tenant account.

Use these credentials to authenticate and access the full suite of Katsu platform services tailored to your business needs.

Method: POST

URL: {{baseURL}}/registries/api/v1/users/login/public

Headers:

apiKey: {{api-key}}

Body:

  {
    "username": "tech@sabi.am",
    "password": "*******",
    "role": "TENANT_SUPER_ADMIN"
  }

Create a tenant space

Establish a dedicated tenant space within your user account. You must provide details like tenant name, userId and a reuseExistKyb value that is usually set to false by default.

Request Body: The request body should be formatted in JSON and include the following parameters:

userId (required): Unique identifier for your user account.
name (required): The desired name for your tenant space.
reuseExistKyb (required): Specifies whether to reuse existing KYC (Know Your Customer) information. By default, this value should be set to false to initiate a fresh KYC process for the tenant space.

Method: POST

URL: {{baseURL}}/api/v1/users/{userId}/tenants

Authorization:

Token: {{bearer_token}}

Body:

 {
   "userId": "664d26584c693bxxxxxxxxxx",
   "name": "Nomy",
   "email": "xxxx@gmail.com",
   "phone": "081xxxxxxx",
   "reuseExistKyb": false
 }

Creating Services

Once you have a tenant space, you can create services to integrate with the Katsu platform. Services are essentially functionalities you want to expose or consume within the Katsu ecosystem.

Required Data: The request body should be formatted in JSON and include the following details:

name (string): The name of the service.
apiKeyRotationPeriod (string): The period for API key rotation. Valid values include "HOURS", "DAYS", etc.
apiKeyRotationValue (number): The value for the API key rotation period.
apiKeyRotationCustomDate (object): Custom date for API key rotation, if applicable.
config (array of objects): An array of configuration options for the service. Each element in the array represents a configuration option.
urlIdentity (string): URL identity for the service.

[!Note:] You can easily obtain your Service ID here, which is necessary for assigning services to your tenant account.

Method: POST

URL: {{baseURL}}/api/v1/services/keys/:apiKey/active

Headers:

service-registration-key: <string /> Path Variables:
apiKey

Body:

{
  "name": "<string>",
  "apiKeyRotationPeriod": "HOURS",
  "apiKeyRotationValue": "<number>",
  "apiKeyRotationCustomDate": {},
  "actionBy": "<string>",
  "config": [
    {
      "label": "<string>",
      "key": "<string>",
      "value": "<string>",
      "required": "<boolean>",
      "valueType": "email",
      "formType": "input",
      "formOptions": [
        {
          "label": "<string>",
          "value": "<string>",
          "key": "<string>"
        },
        {
          "label": "<string>",
          "value": "<string>",
          "key": "<string>"
        }
      ]
    },
    {
      "label": "<string>",
      "key": "<string>",
      "value": "<string>",
      "required": "<boolean>",
      "valueType": "string",
      "formType": "multi-select",
      "formOptions": [
        {
          "label": "<string>",
          "value": "<string>",
          "key": "<string>"
        },
        {
          "label": "<string>",
          "value": "<string>",
          "key": "<string>"
        }
      ]
    }
  ],
  "urlIdentity": "<string>"
}

Map Tenants to Services

After creating services for your tenant space on the Katsu platform, you need to establish a connection between your tenants (users within your tenant space) and the services they can access. This process is called "mapping tenants to services." Requires:

tenantId: Tenant's unique identifier
serviceId: Service's unique identifier

Request Body:

userId: User making the request (admin privileges required)
config (service-specific configuration)
apiKeyRotationPeriod (days for API key rotation)

This endpoint establishes associations between tenants and services within the Katsu platform.

Method: PATCH

URL: {{baseURL}}/api/v1/tenants/:tenantId/services/:serviceId/map

Headers:

apiKey: {{api-key}}

Body:

{
  "userId": "664d26584c693bxxxxxxxxxx",
  "config": [],
  "apiKeyRotationPeriod": "YEARS",
  "apiKeyRotationValue": 2
}

Add KYC Details

Verifying your KYC (Know Your Customer) information helps us understand who you are and ensures a secure platform for everyone. Completing your KYC unlocks full access to all the features the Katsu platform offers.

Request Body: The request body includes detailed information about your business and its representatives to verify their identity and ensure compliance with legal requirements. Here’s a detailed breakdown of the structure:

Root Object:
- userId: The unique identifier for the user undergoing the KYC process.
- kycDetails Object: This object contains nested objects related to various aspects of the business and its representatives.
businessDetails Object:
- registeredDate: The date when the business was officially registered.
- registeredBusinessAddress: The official address where the business is registered.
- operatingAddress: The address where the business operates, which may differ from the registered address.
- natureOfBusiness: A description of the business activities or industry sector.
- proofOfBusinessAddress: A document or reference that serves as proof of the business's operating address.
additionalDirector Object: Information about an additional director of the company.
- firstName: The director's first name.
- lastName: The director's last name.
- dob: The director's date of birth.
- gender: The director's gender.
- email: The director's email address.
representativeDetail Object: Information about the business representative.
- firstName: The representative's first name.
- lastName: The representative's last name.
- dob: The representative's date of birth.
- gender: The representative's gender.
- email: The representative's email address.
additionalShareholdersDetails Array: An array containing details of additional shareholders. Each element in the array is an object with the following properties:
- firstName: The shareholder's first name.
- lastName: The shareholder's last name.
- dob: The shareholder's date of birth.
- gender: The shareholder's gender.
- email: The shareholder's email address.
guarantorDetails Array: An array containing details of guarantors. Each element in the array is an object with the following properties:
- firstName: The guarantor's first name.
- lastName: The guarantor's last name.
- dob: The guarantor's date of birth.
- gender: The guarantor's gender.
- email: The guarantor's email address.

Completing the KYC process ensures your account's security and unlocks the full potential of the Katsu platform, giving you access to all its features and services.

Method: PUT

URL: {{baseURL}}/api/v1/tenants/:tenantId/kyc

Headers:

apiKey: {{api-key}}

Body:

    "userId": "664d26584xxxxxxxx",
    "kycDetails": {
      "businessDetails": {
        "registeredDate": "2024-05-22",
        "registeredBusinessAddress": "Lagos",
        "operatingAddress": "Lagos",
        "natureOfBusiness": "export",
        "proofOfBusinessAddress": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/{base64 encoded image}
      },
      "additionalDirector": {
        "firstName": "Mustapha",
        "lastName": "Lamar",
        "dob": "1990-01-01",
        "gender": "FEMALE",
        "email": "xxxxxxx@gmail.com"
      },
      "representativeDetail": {
        "firstName": "Uche",
        "lastName": "Jumbo",
        "dob": "1985-12-31",
        "gender": "MALE",
        "email": "xxxxx@gmail.com"
      },
      "additionalShareholdersDetails": [
        {
          "firstName": "Share",
          "lastName": "Holder",
          "dob": "1970-10-20",
          "gender": "MALE",
          "email": "xxxxx@gmail.com"
        }
      ],
      "guarantorDetails": [
        {
          "firstName": "Mike",
          "lastName": "Runner",
          "dob": "1980-05-15",
          "gender": "MALE",
          "email": "xxxxxx@gmail.com"
        }
      ]
    }
}

Activate Wallet

After verifying your KYC details, you can enable the Wallet service within your tenant space, use the following endpoint. Upon successful activation, the service status will change to "APPROVED". You need your wallet activated to send or receive transfers within the platform.

Method: PATCH

URL: {{baseURL}}/api/v1/tenants/:tenantId/wallet/activate

Body:

{
  "mode": "raw",
  "raw": "",
  "options": {
    "raw": {
      "language": "json"
    }
  }
}

Headers:

apiKey: {{api-key}}

Create a settlement account

A settlement account is linked to a business account and is used to move funds from the holding account to the final destination, such as a bank account or customer's wallet. The settlement account is critical for completing the transaction cycle by ensuring funds reach their intended destination. It has the following features; Settlement accounts provide an alternative method for receiving funds outside the Katsu wallet system. Using allowWithoutWallet means a temporary measure for offline transactions. Ensure you comply with relevant regulations when managing settlement accounts.

Prerequisites** Before creating a settlement account, ensure the following;
- An active tenant space on the Katsu platform.
- Must have a KYC done
- Must have enabled wallet services
- Must have known your bank code: Details of how to get the bank code in the next section.
Settlement Account Object Find the detailed description of the settlement account object.
- userId (required): Unique identifier for the user associated with the settlement account.
- bankName (required): Name of the bank where the settlement account is held.
- bankCode (required): Bank code of the settlement account.
- accountName: Name of the account holder (your business name).
- accountNumber (required): Account number for the settlement account.
- actionBy: Username of the person creating the settlement account.
- allowWithoutWallet (optional): Flag indicating whether to allow transactions without a connected wallet.
- Defaults to false. Use this with caution, primarily for offline payments. Remember to recreate the settlement account with allowWithoutWallet set to false once a wallet is enabled.

Method: POST

URL: {{baseURL}}/api/v1/tenants/{tenantId}/settlement-account?tenantId={{tenantId}}

Headers:

apiKey: {{apiKey}}

Body:

{
  "userId": "string",
  "bankName": "string",
  "bankCode": "string",
  "accountName": "string",
  "accountNumber": "string",
  "actionBy": "string",
  "allowWithoutWallet": false
}

Tenant Payments - Wallet Services

The Katsu Wallet Service empowers you to integrate various payment methods into your application, facilitating seamless transactions for your users. This section explores the functionalities offered through the Wallet Service API.

USSD

Initiate USSD Payment

This endpoint allows you to initiate a USSD payment flow.

Required Data: The request body should be formatted in JSON and include the following details:

requestId: Unique identifier for the payment request (ideally generated by your application)
accountId: Unique identifier for the account receiving the payment
narration: Optional description of the payment
transactionCategory: Categorization of the transaction (e.g., "SALES", "RENTAL INCOME")
customer: Customer information object containing:
name: Customer's full name
email: Customer's email address (optional)
phoneNumber: Customer's phone number for USSD interaction
userId: Unique identifier for the user initiating the payment
amount: Payment amount (specify the currency)
bankCode: Bank code associated with the customer's account (optional, depending on the USSD service provider)

Method: POST

URL: {{baseURL}}/payments/ussd/invokereference?countryCode={{countryCode}}&tenantId={{tenantId}}&userId={{userId}}

Headers:

apiKey: {{api-key}}

Body:

{
  "requestId": "string",
  "accountId": "string",
  "narration": "string",
  "transactionCategory": "SALES",
  "customer": {
    "name": "string",
    "email": "string",
    "phoneNumber": "stringstri"
  },
  "userId": "string",
  "amount": 100,
  "bankCode": "string"
}

Querying USSD Payment Status

This endpoint allows you to check the status of a previously initiated USSD payment.

Required Parameter:
- referenceId: The unique identifier obtained during USSD payment initiation.

Method: GET

URL: {{baseURL}}/payments/ussd/status-query/:{referenceId}

Headers:

countryCode: {{countryCode}}
tenantId: {{tenantId}}
apiKey: {{api-key}}

Body:

{
  "mode": "raw",
  "raw": "",
  "options": {
    "raw": {
      "language": "json"
    }
  }
}

Retrieving Supported Banks for USSD

This endpoint provides a list of banks supported for USSD payments within the Katsu platform.

Method: GET

URL: {{baseURL}}/payments/ussd/getbanks

Headers:

apiKey: {{api-key}}

Paylink

Initiate Payment via Paylink

This section describes how to initiate a payment flow using a Paylink on the Katsu platform. Paylinks are secure, shareable URLs that allow your customers to complete payments through various methods (e.g., debit/credit cards, wallets).

Required Parameters:

requestId: A unique identifier for the payment request. It's recommended to generate this ID within your application to help track and manage payments.
accountId: The unique identifier of the account that will receive the payment.
narration: A brief description of the payment (e.g., "Invoice #123").
transactionCategory: A category for the transaction (e.g., "SALES", "RENTAL INCOME"). This helps with organizing your payment data.
customer: Information about the customer making the payment.
name: The customer's full name.
email: The customer's email address (optional).
phoneNumber: The customer's phone number (optional).
userId: The unique identifier of the user initiating the payment process.

Method: POST

URL: {{baseURL}}/payments/paylink/InvokePayment?countryCode={{countryCode}}&userId={{userId}}&tenantId={{tenantId}}

Headers:

countryCode: {{countryCode}}
tenantId: {{tenantId}}
userId: {{userId}}
apiKey: {{api-key}}

Body:

{
  "requestId": "string",
  "accountId": "string",
  "narration": "string",
  "transactionCategory": "SALES",
  "customer": {
    "name": "string",
    "email": "string",
    "phoneNumber": "stringstri"
  },
  "userId": "string",
  "customization": {
    "logoUrl": "string",
    "title": "string",
    "description": "string"
  },
  "amount": 100
}

query payment link status

Once you've initiated a payment via Paylink, you can use the following endpoint to check its status: Purpose: Query the status of a Paylink payment.

Parameter:

referenceId (string):The unique identifier for the Paylink payment session.

Method: GET

URL: {{baseURL}}/payments/paylink/status-query/:referenceId?countryCode={countryCode}&tenantId={tenantId}

Headers:

countryCode: {{countryCode}}
apiKey: {{api-key}}

Body:

{
  "mode": "raw",
  "raw": "",
  "options": {
    "raw": {
      "language": "json"
    }
  }
}

NQR

NQR (Near-Field Communication with QR code) payments allow users to scan QR codes with their mobile devices to initiate contactless payments. This section details functionalities related to NQR payments within the Katsu platform.

Register NQR Merchants

This functionality allows you to register merchants within the NQR payment ecosystem.

Method: POST

URL: {{baseURL}}/payments/nqr/merchants?countryCode={countryCode}

Headers:

countryCode: {{countryCode}}
tenantId: {{tenantId}}
userId: {{userId}}
apiKey: {{api-key}}

Body:

{
  "mode": "raw",
  "raw": "",
  "options": {
    "raw": {
      "language": "json"
    }
  }
}

Invoke dynamic qr

This functionality allows you to generate dynamic QR codes for NQR payments. Dynamic QR codes can be used for variable payment amounts, unlike static QR codes with predefined amounts. Required Data (JSON format):

merchantId: Unique identifier for the merchant associated with the payment.
amount: Payment amount (specify the currency).
transactionCategory: Categorization of the transaction (e.g., "SALES", "RENTAL INCOME").
requestId: Unique identifier for the payment request (ideally generated by your application).
accountId: Unique identifier for the account receiving the payment.
narration (optional): Description of the payment.
customer (optional): Customer information object containing:
name: Customer's full name.
email: Customer's email address.

Method: POST

URL: {{baseURL}}/payments/nqr/invokedynamicqr?countryCode={{countryCode}}&tenantId={{tenantId}}&userId={{userId}}

Headers:

apiKey: {{api-key}}

Body:

{
  "merchantId": "string",
  "amount": 200,
  "transactionCategory": "SALES",
  "requestId": "string",
  "accountId": "string",
  "narration": "string",
  "customer": {
    "name": "string",
    "email": "string",
    "phoneNumber": "stringstri"
  }
}

Register NQR Terminals

NQR terminals are devices that scan QR codes to initiate contactless payments. You can use this functionality to register NQR terminals associated with your business. Required Data (JSON format):

terminalName: Descriptive name for the NQR terminal.
email (optional): Email address associated with the terminal.
phoneNumber (optional): Phone number associated with the terminal.
qrType: Type of QR code the terminal can scan (refer to Katsu's documentation for supported types).
merchantId: Unique identifier for the merchant associated with the terminal.
accountId: Unique identifier for the account where NQR payments will be deposited.

Method: POST

URL: {{baseURL}}/payments/nqr/terminals?countryCode={{countryCode}}&tenantId={{tenantId}}&userId={{userId}}

Headers:

apiKey: {{api-key}}

Body:

{
  "terminalName": "string",
  "email": "string",
  "phoneNumber": "string",
  "qrType": "string",
  "merchantId": "string",
  "accountId": "string"
}

Query NQR Transactions status

This functionality allows you to query the status of past NQR transactions within a specific timeframe.

Required Data (JSON format):

MerchantId: Unique identifier for the merchant associated with the transaction.
TerminalId: Unique identifier for the NQR terminal used for the transaction (if applicable).
StartTime: Date and time (UTC) representing the start of the query period (format: YYYY-MM-DDTHH:MM:SS.SSSZ).
EndTime: Date and time (UTC) representing the end of the query period (format: YYYY-MM-DDTHH:MM:SS.SSSZ).

Method: POST

URL: {{baseURL}}/payments/nqr/transactions/status?countryCode={{countryCode}}&tenantId={{tenantId}}&userId={{userId}}

Headers:

apiKey: {{api-key}}

Body:

{
  "MerchantId": "string",
  "TerminalId": "string",
  "StartTime": "2024-05-18T07:42:21.712Z",
  "EndTime": "2024-05-18T07:42:21.712Z"
}

NQR Payment Notifications

Katsu can send notification messages to your application when NQR payment events occur. These notifications can be used to update your application's internal state and provide real-time feedback to users. Required Data:

type: The NQR Transaction type
Supported Notification Types:
payment: Notification for a completed NQR payment.
refund: Notification for a refunded NQR payment.

Method: POST

URL: {{baseURL}}/payments/nqr/{type}/notifications?type={type}

Headers:

apiKey: {{api-key}}

Body:

{
  "mode": "raw",
  "raw": "",
  "options": {
    "raw": {
      "language": "json"
    }
  }
}

Query NQR Payment Status

This endpoint allows you to query the status of an NQR Payment.

Method: GET

URL: {{baseURL}}/payments/nqr/status-query/{referenceId}?countryCode=NGN&tenantId={tenantId}&referenceId={referenceId}

Headers:

apiKey: {{api-key}}

Card

This section details functionalities related to card payments within the Katsu platform.

Initiating a Card Payment

This endpoint initiates a debit or credit card payment flow within the Katsu platform.

Required Parameters:

userId (string): Unique identifier for the user initiating the payment.
amount (number): Payment amount (specify the currency).
transactionCategory (string): Categorization of the transaction (e.g., "SALES", "RENTAL INCOME").
requestId (string): Unique identifier for the payment request (ideally generated by your application).
narration (string - optional): Description of the payment.
accountId (string): Unique identifier for the account receiving the payment.
customer (object - optional): Customer information object containing:
name (string): Customer's full name.
email (string - optional): Customer's email address.
phoneNumber (string - optional): Customer's phone number.

Method: POST

URL: {{baseURL}}/payments/card/request-payment?countryCode={{countryCode}}&tenantId={{tenantId}}&userId={{userId}}

Headers:

apiKey: {{api-key}}

Body:

{
  "userId": "string",
  "amount": 100,
  "transactionCategory": "SALES",
  "requestId": "string",
  "narration": "string",
  "accountId": "string",
  "customer": {
    "name": "string",
    "email": "string",
    "phoneNumber": "stringstri"
  }
}

Initiating a Card Payment Refund

This endpoint allows you to initiate a refund for a previously successful card payment. Required Parameters:

amount (number): Refund amount (specify the currency).
tnxId (string): Unique identifier for the card transaction to be refunded.
requestId (string): Unique identifier for the refund request (ideally generated by your application).

Method: POST

URL: {{baseURL}}/payments/card/refund?countryCode=NGN&tenantId={tenantId}&userId={userId}

Headers:
- apiKey: {{api-key}}
Body:

{
  "amount": 0,
  "tnxId": "string",
  "requestId": "string"
}

status query for card payment

This endpoint allows users to query the status of a card payment made on the platform.

Method: GET

URL: {{baseURL}}/payments/card/status-query/{reference_id}?countryCode=NGN&tenantId={tenantId}&referenceId={referenceId}&userId={userId}

Headers:

apiKey: {{api-key}}

Webhook payment method

This endpoint allows you to configure a webhook for a specific payment method supported by Katsu. Webhooks provide a real-time notification mechanism, enabling your application to receive updates about payment events (e.g., successful payments, failures) automatically. Required Parameters:

paymentmethod (Path Parameter): Specify the payment method for which you want to set up a webhook.

Request Body: The request body contains several fields that provide detailed information about the transaction and the webhook configuration.

Method: POST

URL: {{baseURL}}/payments/webhook/{paymentmethod}?paymentmethod={paymentmethod}

Headers:

x-api-key: {{api-key}}

Body:

  {
    "merchantRef": "string",
    "token": "string",
    "transactionRef": "string",
    "retrievalReference": "string",
    "responseMsg": "string",
    "tnxId": "string",
    "TransactionId": "string",
    "TraceId": "string",
    "Amount": 0,
    "ResponseCode": "string",
    "ResponseMessage": "string"
  }

payments metrics

This endpoint provides statistical metrics related to various payment methods. This endpoint returns a JSON object containing the success and failure counts, as well as the success percentage for each payment method. These metrics help in understanding the performance and reliability of different payment options.

Method: GET

URL: {{baseURL}}/payments/metrics

Headers:

apiKey: {{api-key}}

Tenant Transfer - Wallet Services

This section details various functionalities offered by the Katsu platform for transferring funds with the wallet service.

Withdraw Wallet Funds

This endpoint initiates a withdrawal of funds from a business account to a designated recipient (typically a bank account).

Required Data: The request body should be formatted in JSON and include the following details:

debitAccountId: Unique identifier for the account from which funds will be withdrawn
amount: Withdrawal amount (specify the currency)
recipientName: Name of the recipient (optional)
recipientBankCode: Bank code of the recipient's bank (optional)
recipientAccountNumber: Recipient's bank account number
userId: Unique identifier for the user initiating the withdrawal
requestId: Unique identifier for the withdrawal request (ideally generated by your application)
narration: Optional description of the withdrawal

Settlement Option:

settlementUuId: Unique identifier for the settlement account where the withdrawn funds will be deposited (refer to Katsu's API documentation for details on settlement accounts). This option is typically used for internal routing within the Katsu platform. You might need to contact Katsu for guidance on how to populate this field.

Method: POST

URL: {{baseURL}}/transfers/withdraw?countryCode=NGN&tenantId={{tenantId}}&userId={{userId}}

Headers:

apiKey: {{api-key}}

Body:

{
  "debitAccountId": "string",
  "amount": 100,
  "recipientName": "string",
  "recipientBankCode": "string",
  "recipientAccountNumber": "string",
  "userId": "string",
  "requestId": "string",
  "narration": "string",
  "settlementUuId": "string"
}

Validate Account Name

This endpoint allows you to validate the name associated with a bank account before initiating a transfer. Required Data: The request body should be formatted in JSON and include the following details: bankCode: Bank code of the recipient's bank accountNumber: Recipient's bank account number

Method: POST

URL: {{baseURL}}/transfers/validate-account-name?countryCode=NGN&tenantId={{tenantId}}&userId={{userId}}

Headers:

Content-Type: application/json
apiKey: {{api-key}}

Body:

{
  "bankCode": "string",
  "accountNumber": "string"
}

Intra Wallet Transfers

This endpoint initiates a transfer of funds between two accounts belonging to the same business wallet within the Katsu platform.

Required Data: The request body should be formatted in JSON and include the following details:

debitAccountId: Unique identifier for the account sending the funds
recipientAccountId: Unique identifier for the account receiving the funds
amount: Transfer amount (specify the currency)
narration: Optional description of the transfer
category: Categorization of the transfer (e.g., "SALES", "RENTAL INCOME")
userId: Unique identifier for the user initiating the transfer
requestId: Unique identifier for the transfer request (ideally generated by your application)

Method: POST

URL: {{baseURL}}/transfers/intra/wallet?countryCode=NGN&tenantId={{tenantId}}&userId={{userId}}

Headers:

apiKey: {{api-key}}

Body:

{
  "debitAccountId": "string",
  "recipientAccountId": "string",
  "amount": 100,
  "narration": "string",
  "category": "SALES",
  "userId": "string",
  "requestId": "string"
}

Inter Bank Transfers

This endpoint initiates a transfer of funds between a business account within the Katsu platform and an external bank account.

Required Data: The request body should be formatted in JSON and include the following details:

amount: Transfer amount (specify the currency)
bank: Recipient bank details object containing:
bankCode: Bank code of the recipient's bank
accountNumber: Recipient's bank account number
bankName: Name of the recipient's bank (optional)
category: Categorization of the transfer (e.g., "PAYMENT TO VENDOR")
senderAccountId: Unique identifier for the account sending the funds
ownAccountId: Unique identifier for the account credited with the transfer amount (typically the business account within the Katsu platform).
userId: Unique identifier for the user initiating the transfer.
requestId: Unique identifier for the transfer request (ideally generated by your application)
narration: Optional description of the transfer

Method: POST

URL: {{baseURL}}/transfers/inter/bank?countryCode=NGN&tenantId={{tenantId}}&userId={{userId}} Headers:

Content-Type: application/json
apiKey: {{api-key}}

Body:

{
  "amount": 100,
  "bank": {
    "bankCode": "string",
    "accountNumber": "string",
    "bankName": "string"
  },
  "category": "SALES",
  "senderAccountId": "string",
  "ownAccountId": "string",
  "userId": "string",
  "narration": "string",
  "requestId": "string"
}

Deposit internal account

This endpoint initiates a deposit of funds into a business account within the Katsu platform from another internal account.

Required Data: The request body should be formatted in JSON and include the following details:

recipientAccountId: Unique identifier for the account receiving the deposit
amount: Deposit amount (specify the currency)
sendersName: Name of the sender (optional)
sendersBankCode: Bank code of the sender's bank (optional, applicable if depositing from an external bank account)
sendersAccountNumber: Sender's bank account number (optional, applicable if depositing from an external bank account)
userId: Unique identifier for the user initiating the deposit
requestId: Unique identifier for the deposit request (ideally generated by your application)
narration: Optional description of the deposit

Method: POST

URL: {{baseURL}}/transfers/deposit/internal?countryCode=NGN&tenantId={{tenantId}}&userId={{userId}}

Headers:

Content-Type: application/json
amount: 100
sendersName: string
sendersBankCode: string
sendersAccountNumber: string
userId: string
narration: string
requestId: string
apiKey: {{api-key}}

Body:

{
  "recipientAccountId": "string",
  "amount": 100,
  "sendersName": "string",
  "sendersBankCode": "string",
  "sendersAccountNumber": "string",
  "userId": "string",
  "narration": "string",
  "requestId": "string"
}

Deposit commission account

This endpoint initiates a deposit of commission funds into a business account within the Katsu platform.

Required Data: The request body should be formatted in JSON and include the following details (specific requirements may vary depending on regulations):

recipientAccountId: Unique identifier for the account receiving the commission deposit
amount: Deposit amount (specify the currency)
sendersName: Name of the entity paying the commission (optional)
sendersBankCode: Bank code of the entity's bank (optional)
sendersAccountNumber: Entity's bank account number (optional)
userId: Unique identifier for the user initiating the deposit
requestId: Unique identifier for the deposit request (ideally generated by your application)
narration: Optional description of the deposit

Method: POST

URL: {{baseURL}}/transfers/deposit/commission?countryCode=NGN&tenantId={{tenantId}}&userId={{userId}}

Headers:

Content-Type:
apiKey: {{api-key}}

Body:

{
  "recipientAccountId": "string",
  "amount": 100,
  "sendersName": "string",
  "sendersBankCode": "string",
  "sendersAccountNumber": "string",
  "userId": "string",
  "narration": "string",
  "requestId": "string"
}

List Banks via Country Code

This endpoint allows you to retrieve the available banks for transfers using a country code.

Method: GET

URL: {{baseURL}}/transfers/banks?countryCode=NGN

Headers:

Content-Type: application/json
apiKey: {{api-key}}

Body:

{
  "mode": "raw",
  "raw": "",
  "options": {
    "raw": {
      "language": "json"
    }
  }
}

List Banks for Transfers

Retrieve a list of bank code supported by the Katsu platform for inter-bank transfers. Public banks are those whose details are readily available for use within your tenant space.

Method: GET

URL: {{baseURL}}/api/v1/transfers/tenants/{tenantId}/public/banks?tenantId={{tenantId}}

Headers:

apiKey: {{apiKey}}

Tenant Transfer - Registry Services

The Registry service provides a Transfers API for initiating various financial transfers. This section details functionalities for retrieving public banks, initiating interbank transfers, withdrawing funds, and (within this document) intra-wallet transfers (transfers between accounts within the same business wallet). Refer to the Wallet Service documentation for details on inter-wallet transfers (between wallets of different businesses).

Get Public Banks

Retrieve a list of public banks associated with a particular tenant. This can be helpful for displaying bank options to users during the transfer initiation process. Request Parameters:

tenantId (Path Parameter): Unique identifier for the tenant requesting the list of public banks.

Method: GET

URL: {{baseURL}}/api/v1/transfers/tenants/{tenantId}/public/banks?tenantId={{tenantId}}

Headers:

apiKey: {{api-key}}

Body:

{
  "mode": "raw",
  "raw": "",
  "options": {
    "raw": {
      "language": "json"
    }
  }
}

Inter Bank Transfers

Initiate a transfer of funds between a business account within the Katsu platform and an external bank account.

Request Body: The request body should be formatted in JSON and include the following details:

category: (Optional) Categorization of the transfer (e.g., "SALES", "RENTAL INCOME")
bank: Details of the recipient bank account
bankCode: Unique code identifying the recipient bank
bankName: Full name of the recipient bank
accountNumber: Recipient's account number
amount: Transfer amount (specify the currency)
senderAccountId: Unique identifier for the account sending the funds (within the Katsu platform)
ownAccountId: Unique identifier for the account credited after any platform fees (if applicable)
userId: Unique identifier for the user initiating the transfer
requestId: Unique identifier for the transfer request (ideally generated by your application)
pin: User's PIN for authentication (securely transmit this value)

Method: POST

URL: {{baseURL}}/api/v1/transfers/inter-bank

Headers:

apiKey: {{api-key}}

Body:

{
  "category": "SALES",
  "bank": {
    "bankCode": "string",
    "bankName": "string",
    "accountNumber": "string"
  },
  "amount": 0,
  "senderAccountId": "string",
  "ownAccountId": "string",
  "userId": "string",
  "requestId": "string",
  "pin": "string"
}

Withdraw Funds

The request body should be formatted in JSON and include the following details:

amount: Amount to be withdrawn (specify the currency)
debitAccountId: Unique identifier for the account from which funds will be withdrawn
settlementUuId: Unique identifier for the settlement account where the withdrawn funds will be deposited.
userId: Unique identifier for the user initiating the withdrawal
requestId: Unique identifier for the withdrawal request (ideally generated by your application)
pin: User's PIN for authentication (securely transmit this value)

[!Important Note:] Sending the user's PIN within the request body requires secure transmission methods like HTTPS to prevent unauthorized access. Consider using a separate secure mechanism for PIN verification.

Method: POST

URL: {{baseURL}}/api/v1/transfers/withdraw

Headers:

Content-Type: application/json
apiKey: {{api-key}}

Body:

{
  "amount": 0,
  "debitAccountId": "string",
  "settlementUuId": "string",
  "userId": "string",
  "requestId": "string",
  "pin": "string"
}

Intra Wallet Transfers

Initiate a transfer of funds between two accounts belonging to the same business wallet within the Katsu platform. This functionality allows for efficient internal fund management within a business.

Request Body: The request body should be formatted in JSON and include the following details:
category: (Optional) Categorization of the transfer (e.g., "SALES", "RENTAL INCOME")
amount: Transfer amount (specify the currency)
debitAccountId: Unique identifier for the account sending the funds
recipientAccountId: Unique identifier for the account receiving the funds (within the same business wallet)
userId: Unique identifier for the user initiating the transfer
requestId: Unique identifier for the transfer request (ideally generated by your application)
pin: User's PIN for authentication (securely transmit this value)

Method: POST

URL: {{baseURL}}/api/v1/transfers/intra-wallet

Headers:

Content-Type: application/json
apiKey: {{api-key}}

Body:

{
  "category": "SALES",
  "amount": 0,
  "debitAccountId": "string",
  "recipientAccountId": "string",
  "userId": "string",
  "requestId": "string",
  "pin": "string"
}

User Guide: Leveraging the Wallet Service and Transfers API

Introduction

Prerequisites:​

RoleSignUpType Description​

Descriptions of Users by roles​

Katsu Wallet Services Overview​

Authentication​

Tenant account set up​

Create an account​

Log In​

Create a tenant space​

Creating Services​

Map Tenants to Services​

Add KYC Details​

Activate Wallet​

Create a settlement account​

Tenant Payments - Wallet Services​

USSD​

Initiate USSD Payment​

Querying USSD Payment Status​

Retrieving Supported Banks for USSD​

Paylink​

Initiate Payment via Paylink​

query payment link status​

NQR​

Register NQR Merchants​

Invoke dynamic qr​

Register NQR Terminals​

Query NQR Transactions status​

NQR Payment Notifications​

Query NQR Payment Status​

Card​

Initiating a Card Payment​

Initiating a Card Payment Refund​

status query for card payment​

Webhook payment method​

payments metrics​

Tenant Transfer - Wallet Services​

Withdraw Wallet Funds​

Validate Account Name​

Intra Wallet Transfers​

Inter Bank Transfers​

Deposit internal account​

Deposit commission account​

List Banks via Country Code​

List Banks for Transfers​

Tenant Transfer - Registry Services​

Get Public Banks​

Inter Bank Transfers​

Withdraw Funds​

Intra Wallet Transfers​

Prerequisites:

RoleSignUpType Description

Descriptions of Users by roles

Katsu Wallet Services Overview

Authentication

Tenant account set up

Create an account

Log In

Create a tenant space

Creating Services

Map Tenants to Services

Add KYC Details

Activate Wallet

Create a settlement account

Tenant Payments - Wallet Services

USSD

Initiate USSD Payment

Querying USSD Payment Status

Retrieving Supported Banks for USSD

Paylink

Initiate Payment via Paylink

query payment link status

NQR

Register NQR Merchants

Invoke dynamic qr

Register NQR Terminals

Query NQR Transactions status

NQR Payment Notifications

Query NQR Payment Status

Card

Initiating a Card Payment

Initiating a Card Payment Refund

status query for card payment

Webhook payment method

payments metrics

Tenant Transfer - Wallet Services

Withdraw Wallet Funds

Validate Account Name

Intra Wallet Transfers

Inter Bank Transfers

Deposit internal account

Deposit commission account

List Banks via Country Code

List Banks for Transfers

Tenant Transfer - Registry Services

Get Public Banks

Inter Bank Transfers

Withdraw Funds

Intra Wallet Transfers