Skip to main content

​
Payment API Documentation

​
Overview

The Payment API provides endpoints for processing various types of payments, including card payments, USSD payments, and POS card payments. It supports multiple payment providers and currencies.

​
Base URL

/api/v1/payment

​
Authentication

All endpoints require authentication using an API key in the request headers:
  • X-API-KEY: Your API key

​
Endpoints

​
Card Payment

Initiate a payment using a card. Endpoint: POST /card/pay Headers:
  • X-API-KEY: API key for authentication
Request Body: 
{
  "requestId": "string",
  "amount": "number",
  "accountId": "string",
  "narration": "string",
  "callbackUrl": "string",
  "currency": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "authorizationUrl": "string",
    "reference": "string",
    "accessCode": "string"
  }
}

​
USSD Payment

Initiate a payment using USSD. Endpoint: POST /ussd/pay Headers:
  • X-API-KEY: API key for authentication
Request Body: 
{
  "requestId": "string",
  "amount": "number",
  "accountId": "string",
  "narration": "string",
  "callbackUrl": "string",
  "currency": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "ussdCode": "string",
    "reference": "string"
  }
}

​
POS Card Payment

Process a card payment through a POS terminal. Endpoint: POST /pos/purchase Headers:
  • X-API-KEY: API key for authentication
Request Body: 
{
  "requestId": "string",
  "terminalId": "string",
  "amount": "number",
  "accountType": "string",
  "terminalSerialNumber": "string",
  "cardData": "string",
  "currency": "string",
  "accountId": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "transactionId": "string",
    "status": "string",
    "referenceNumber": "string",
    "cardNumber": "string",
    "cardType": "string"
  }
}

​
Error Responses

401 Unauthorized 
{
  "statusCode": 401,
  "message": "user not found",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "account not found",
  "data": null
}
409 Conflict 
{
  "statusCode": 409,
  "message": "duplicate request id",
  "data": null
}
422 Unprocessable Entity 
{
  "statusCode": 422,
  "message": "amount must be more than 100",
  "data": null
}

​
Notes

  • Payment Methods:
    • Card payments (online)
    • USSD payments
    • POS card payments
  • Payment Requirements:
    • Minimum amount is 100
    • Accounts must be active
    • Currencies must be supported
    • User must own the account
    • Platform admins cannot perform payments
  • Payment Processing:
    • Card payments are processed through payment gateways
    • USSD payments generate USSD codes
    • POS payments require terminal data
    • All payments are tracked with unique references
  • Security:
    • All payments require authentication
    • Duplicate request IDs are rejected
    • Account ownership is verified
    • Platform admins are restricted
  • Payment Status:
    • Processing
    • Approved
    • Failed
    • Pending
  • Payment Notifications:
    • Users are notified of payment status
    • Callback URLs are supported
    • Webhook notifications are sent
  • Payment Tracking:
    • All payments are logged
    • Payment history is maintained
    • Payment status can be queried
  • Payment Fees:
    • Fees are calculated based on payment type
    • Fees are included in the payment amount
    • Fee formulas are configurable
  • Payment Validation:
    • Amounts are validated
    • Currencies are validated
    • Account status is checked
    • User permissions are verified
  • Payment Settlement:
    • Card payments are settled immediately
    • USSD payments are settled after confirmation
    • POS payments are settled after terminal response
    • Settlement status is tracked