curl --request POST \
  --url https://direct-pub-api.directgh.com/api/v1/external/request-loan \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "50000",
  "narration": "Business expansion loan",
  "tenure": "6",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "callbackUrl": "https://your-institution.com/api/loan-callbacks"
}
'

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "reference": "LOAN-2024-001234",
  "amount": 50000,
  "interest": 15000,
  "totalRepayment": 65000,
  "totalAmountPaid": 0,
  "tenure": 6,
  "narration": "Business expansion loan",
  "userMonthlyIncome": 150000,
  "userGhanaCard": "GHA-123456789-1",
  "status": "PENDING_APPROVAL",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "John",
    "lastName": "Doe",
    "otherName": "Michael",
    "email": "john.doe@example.com",
    "mobileNumber": "+233241234567",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "product": {
    "id": "prod-123",
    "name": "Standard Loan Product"
  },
  "repaymentDate": "2024-07-20T00:00:00Z",
  "createdAt": "2024-01-20T14:45:00Z"
}

API Reference

Request Loan

Submit a loan request on behalf of an institution member. This endpoint creates a loan application that will be processed according to the institution’s loan product configuration.

Loan Processing:

The loan will be created with a PENDING_APPROVAL status
The system will process the loan according to the institution’s workflow
A callback will be sent to the provided callback URL when the loan status changes

Callback URL:

The callback URL will receive POST requests with loan status updates
Ensure your callback endpoint is publicly accessible
The callback payload will include loan details and status

Validation:

The user must be an active member of the institution associated with the API key
The requested amount and tenure must be valid for the institution’s loan products
The product must be active and configured for the institution
The user must meet age requirements
The user must belong to the institution

Loan Statuses:

PROCESSING: Loan is being processed
PENDING_APPROVAL: Awaiting approval
REJECTED: Loan request rejected
DISBURSED: Loan has been disbursed
ACTIVE: Loan is active and being repaid
COMPLETED: Loan has been fully repaid
DEFAULTED: Loan is in default

POST

external

request-loan

curl --request POST \
  --url https://direct-pub-api.directgh.com/api/v1/external/request-loan \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "50000",
  "narration": "Business expansion loan",
  "tenure": "6",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "callbackUrl": "https://your-institution.com/api/loan-callbacks"
}
'

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "reference": "LOAN-2024-001234",
  "amount": 50000,
  "interest": 15000,
  "totalRepayment": 65000,
  "totalAmountPaid": 0,
  "tenure": 6,
  "narration": "Business expansion loan",
  "userMonthlyIncome": 150000,
  "userGhanaCard": "GHA-123456789-1",
  "status": "PENDING_APPROVAL",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "firstName": "John",
    "lastName": "Doe",
    "otherName": "Michael",
    "email": "john.doe@example.com",
    "mobileNumber": "+233241234567",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "product": {
    "id": "prod-123",
    "name": "Standard Loan Product"
  },
  "repaymentDate": "2024-07-20T00:00:00Z",
  "createdAt": "2024-01-20T14:45:00Z"
}

Authorizations

Authorization

string

header

required

HMAC signature authentication. The Authorization header must contain your public key and HMAC signature in the format: public_key:signature

Format: Authorization: public_key:signature

Example: Authorization: pub_abc123xyz:abc123def456ghi789...

The signature is generated by creating an HMAC hash of the request body (JSON stringified) using your secret key for POST/PUT requests. For GET requests, the signature is generated using the query parameters (JSON stringified) instead of the request body. Contact your account manager to obtain your public key and secret key for generating signatures.

Body

application/json

amount

string

required

Loan amount requested (must be a positive number)

Example:

"50000"

narration

string

required

Description or purpose of the loan

Example:

"Business expansion loan"

tenure

string

required

Loan tenure in months (must be a positive integer)

Example:

"6"

userId

string<uuid>

required

Unique identifier of the institution member requesting the loan

Example:

"550e8400-e29b-41d4-a716-446655440000"

callbackUrl

string<uri>

required

URL where loan status updates will be sent via POST requests

Example:

"https://your-institution.com/api/loan-callbacks"

Response

Loan request created successfully

Loan details including status, user information, and repayment terms

string<uuid>

Unique identifier of the loan

Example:

"660e8400-e29b-41d4-a716-446655440000"

reference

string

Human-readable loan reference number

Example:

"LOAN-2024-001234"

amount

number<double>

Loan amount

Example:

50000

interest

number<double>

Total interest amount for the loan

Example:

15000

totalRepayment

number<double>

Total amount to be repaid

Example:

65000

totalAmountPaid

number<double>

Total amount paid towards the loan

Example:

0

tenure

integer

Loan tenure in months

Example:

6

narration

string | null

Loan description or purpose

Example:

"Business expansion loan"

userMonthlyIncome

number<double>

Monthly income of the loan applicant

Example:

150000

userGhanaCard

string | null

Ghana Card number of the loan applicant

Example:

"GHA-123456789-1"

status

enum<string>

Current status of the loan

Available options:

PROCESSING,

PENDING_APPROVAL,

REJECTED,

DISBURSED,

ACTIVE,

COMPLETED,

DEFAULTED

Example:

"PENDING_APPROVAL"

user

object

User information of the loan applicant

Show child attributes

product

object

Loan product information

Show child attributes

repaymentDate

string<date-time>

Next repayment date

Example:

"2024-07-20T00:00:00Z"

createdAt

string<date-time> | null

Date and time when the loan was created

Example:

"2024-01-20T14:45:00Z"

Get Loan Offer

⌘I