Documentation Overview

Introduction

Welcome to the PeerPay API Documentation. This documentation provides comprehensive information about all available APIs for integrating with PeerPay's services. This overview covers the fundamental concepts, authentication, request/response formats, and base endpoints that apply across all services.

API Basics

All PeerPay APIs follow consistent patterns for authentication, request formatting, and response handling. Understanding these basics will help you integrate with any PeerPay service.

Base API Endpoint URLs

Each service has its own base endpoint URL format. Replace {base_url} with your environment's base URL and {version_name} with the API version (e.g., v1).

Service	Base Endpoint Format
P2P Credit Service	`{base_url}/api/{version_name}/p2p-credit`
Loans Service	`{base_url}/api/{version_name}/loancollection`
Central Identity Service	`{base_url}/api/{version_name}/cis`

Current P2P Credit Base URL: http://52.208.185.172:8089. Replace {base_url} accordingly when calling P2P Credit endpoints.

Current Loans Service Base URL: http://52.208.185.172:8086. Use this host whenever referencing the Loan Recollection APIs.

Current Central Identity Service Base URL: http://52.208.185.172:8085. Use this host for CIS endpoints (e.g., authorization, token refresh).

Note: For all services, the current {version_name} is v1; update when a new version is released.

Headers

All API requests require specific headers to be included. The following headers are standard across all PeerPay APIs.

Header	Description
`Authorization`	JWT Bearer Token. Format: `Bearer YOUR_JWT_TOKEN`
`Content-Type`	`application/json` - Required for all POST, PUT, and PATCH requests.

Example Request Headers

{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "Content-Type": "application/json"
}

HTTP Methods

PeerPay APIs use standard HTTP methods to indicate the type of operation being performed.

Method	Description	Common Use Cases
GET	Retrieve data	Fetching records, searching, viewing details
POST	Create new resources	Creating records, submitting requests, authorization
PUT	Update existing resources	Updating records, modifying data, password changes
DELETE	Remove resources	Deleting records (if applicable)

Authorization

Most PeerPay API endpoints require authentication using a JWT Bearer token. To obtain a token, you must first authenticate using the Central Identity Service authorization endpoint.

POST{cis_auth_endpoint_url}/authorization

Request Payload

Parameter	Type	Required	Description
`email`	String	Yes	Login email address.
`password`	String	Yes	Plain-text password (securely transmitted over TLS).
`applicationId`	String	Yes	The UUID for the application from which login is requested.

Sample Request

const axios = require('axios');

const authorize = async () => {
  try {
    const response = await axios.post(
      '{cis_auth_endpoint_url}/authorization',
      {
        email: 'emmanuel@gtbank.com',
        password: 'AdminPeer1234@',
        applicationId: 'ce58dda3-e800-4205-9e7e-98c756622451'
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': '{{apiKey}}'
        }
      }
    );

    console.log(response.data);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
};

authorize();

Success Response – HTTP 200:

{
  "status": true,
  "statusCode": "99",
  "statusMessage": "Login Successful",
  "data": {
    "tokenExpiry": "1751360309",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UiLCJ1c2VyVHlwZSI6IkFkbWluIiwiZW1haWwiOiJqb2huQGRvZS5jb20iLCJ0b2tlbkV4cGlyeSI6IjE3NTEzNjAzMDkiLCJyb2xlcyI6W3sibmFtZSI6Ik1ha2VyIiwiaWQiOiJkY2M5NTlmMy05MjA2LTRmYTctOTI2Yi1kNDMzMjYxNTJkN2UifSx7Im5hbWUiOiJBZG1pbiIsImlkIjoiZGRmMDc0ODQtYjdlNC00NWQwLWI0MWYtZjc4ZWIzZDBkYWY0In1dLCJVc2VyRGV0YWlscyI6eyJ1c2VyVHlwZSI6IkJhbmsiLCJpZCI6ImRjYzk1OWYzLTkyMDYtNGZhNy05MjZiLWQ0MzMyNjE1MmQ3ZSJ9fQ.BFnAJSQ79GmUxXdOl5ioarhzQSH89BYFKm5X8ZKs9b0"
  }
}

Note: Use the returned token in the Authorization header for subsequent API requests as: Bearer YOUR_TOKEN

Requests and Responses

All PeerPay APIs use a consistent request and response format. This section outlines the standard formats you'll encounter.

Request Format

All requests must be sent as JSON with the Content-Type: application/json header. Request bodies vary by endpoint and are documented in each service's specific documentation.

Response Format

All API responses follow a consistent structure with the following fields:

Parameter	Type	Description
`status`	Boolean	Overall status of the request – success (`true`) or failed (`false`).
`statusCode`	String	The status code for the response.
`statusMessage`	String	The status message for the response code.
`data`	Object/Array	Any extra data that should be sent with the response.

Default Response Payload

Standard successful response format:

{
  "status": false,
  "statusCode": "21",
  "statusMessage": "Response Message",
  "data": {}
}

Default Error Response Payload – HTTP 401, 403

{
  "status": false,
  "statusCode": "30",
  "statusMessage": "UNAUTHORIZED ACCESS REQUEST",
  "data": {}
}

Default Error Response Payload – HTTP 400, 500

{
  "status": false,
  "statusCode": "20",
  "statusMessage": "Error while performing action",
  "data": {}
}

Error Handling

The API uses standard HTTP response codes to indicate success or failure. Always check the status field in the response to determine if the request was successful.

Code	Meaning	Description
200	OK	The request was successful.
400	Bad Request	Invalid parameters were supplied. The response will contain a descriptive error message.
401	Unauthorized	Authentication failed (invalid or missing token). Returns statusCode "30".
403	Forbidden	Access denied. Returns statusCode "30".
404	Not Found	The requested resource does not exist.
500	Server Error	An error occurred on the PeerPay server. Returns statusCode "20".