API Reference

The DoronPay API provides a comprehensive set of endpoints that enable you to process transactions, manage payments, and integrate payment solutions into your applications.

Overview

DoronPay is a mobile payment gateway that enables digital payments and collection services across Ghana. The platform supports transactions from all major mobile money providers, bank accounts, and cryptocurrencies.

Base URL: https://doronpay.com/api/hub

Key Features

  • Send and receive mobile money payments
  • Process bank transactions
  • Handle cryptocurrency transactions (BTC, USDT)
  • Verify account information
  • Configure custom USSD codes
  • Monitor transaction status in real-time

Getting Started

To start using the DoronPay API, follow these steps:

1. Create a DoronPay Account

Sign up for a merchant account at doronpay.com

2. Generate API Credentials

Generate your API key and merchant ID from the dashboard under Developers > API Keys

3. Set Up Webhook (Optional)

Configure webhook endpoints to receive real-time notifications about transaction events

4. Make Your First API Request

Generate an authentication token and start making API calls

Authentication

Learn how to authenticate your API requests.

Authentication Flow

DoronPay API uses a token-based authentication system. To make authenticated requests, you need to:

  1. Generate an authentication token using your API key and merchant ID
  2. Include the token in all subsequent API requests using the Authorization header
⚠️ Tokens expire after 1 hour. Generate a new token if you receive authentication errors.

Obtaining API Credentials

To get your API key and merchant ID:

  1. Log in to your DoronPay merchant account
  2. Navigate to the Developer section
  3. Click on "API Keys"
  4. Generate a new API key if you don't have one
Example Token Generation
// Request to generate authentication token
POST https://doronpay.com/api/hub/token
Content-Type: application/json

{
  "apikey": "your-api-key",
  "merchantId": "your-merchant-id",
  "operation": "DEBIT" // or "CREDIT" depending on your operation
}
Example Using Authentication Token
// Including token in subsequent requests
POST https://doronpay.com/api/hub/credit
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoieW91ci1tZXJjaGFudC1pZCIsIm9wZXJhdGlvbiI6IkRFQklUIiwiaWF0IjoxNjE2NzYzOTcwLCJleHAiOjE2MTY3Njc1NzB9

{
  "externalTransactionId": "123434675",
  // rest of your request payload...
}

Errors & Response Codes

Learn about the various response codes and error handling.

Response Codes

The DoronPay API uses the following response codes to indicate the status of a transaction or request:

Code Status Description
00 SUCCESS Transaction successful. Payment received and processed successfully.
01 PENDING Transaction received for processing. The request has been accepted and is being processed.
02 FAILED Transaction failed. The request could not be completed.
03 INVALID_REQUEST Invalid request. The request format or parameters are incorrect.
04 AUTHENTICATION_ERROR Authentication error. The API key, merchant ID, or token is invalid or expired.
05 INSUFFICIENT_FUNDS Insufficient funds. The account does not have enough balance to complete the transaction.
06 ACCOUNT_NOT_FOUND Account not found. The specified account number does not exist.
07 RATE_LIMIT_EXCEEDED Rate limit exceeded. Too many requests made in a short period.

Error Response Format

When an error occurs, the API returns a JSON response with the following structure:

Error Response Format
{
  "success": false,
  "code": "04",
  "status": "AUTHENTICATION_ERROR",
  "message": "Invalid API key or merchant ID",
  "transactionId": "123243535345" // if applicable
}

Error Handling Best Practices

  • Always check the success field to determine if the request was successful
  • Implement exponential backoff for retrying failed requests
  • Store the transactionId for tracking and troubleshooting
  • Check the transaction status endpoint if you receive a 01 (PENDING) response
  • Log error responses for debugging purposes

Rate Limits

Understand the rate limits applied to the API.

API Rate Limits

To ensure the stability and performance of the DoronPay API, rate limits are applied to all API endpoints. Rate limits are based on the number of requests made per minute.

Plan Rate Limit Description
Standard 60 requests/minute Default rate limit for standard merchants
Business 120 requests/minute Increased rate limit for business merchants
Enterprise 300 requests/minute Highest rate limit for enterprise merchants

Rate Limit Headers

The API returns the following headers in each response to help you track your rate limit usage:

Header Description
X-RateLimit-Limit The maximum number of requests allowed per minute
X-RateLimit-Remaining The number of requests remaining in the current rate limit window
X-RateLimit-Reset The time in seconds when the current rate limit window resets

Handling Rate Limit Exceeded

When you exceed the rate limit, the API will return a 429 Too Many Requests HTTP status code with a response containing the 07 error code. Best practices for handling rate limits:

  • Monitor the rate limit headers to avoid exceeding limits
  • Implement exponential backoff when receiving rate limit errors
  • Batch multiple operations together when possible
  • Cache responses to avoid making redundant requests

API Versioning

Information about the API versioning system.

Version Policy

The DoronPay API uses a versioning system to ensure backward compatibility and provide new features. The current version is v1.0.

API Version Lifecycle

Each API version goes through the following lifecycle:

  • Current: The latest stable version with full support
  • Deprecated: Still functional but scheduled for retirement
  • Retired: No longer available for use
⚠️ We provide at least 6 months notice before retiring an API version.

Staying Updated

To stay informed about API changes and updates:

  • Subscribe to our developer newsletter
  • Follow our changelog in the Developer Dashboard
  • Join our Developer Community for announcements

Versioning Strategy

Our versioning strategy follows these principles:

  • New endpoints or parameters are added without changing the version
  • Breaking changes require a new version
  • Bug fixes and performance improvements are implemented without version changes

Authentication Token

Generate an authentication token for subsequent API calls.

POST
/token

This endpoint generates an authentication token that must be used for all subsequent API requests. The token is valid for a limited time period.

Parameters
Responses
Code Examples
Try It

Request Headers

Name Type Required Description
Content-Type string YES Must be set to application/json

Request Body

Name Type Required Description
apikey string YES Your DoronPay API key
merchantId string YES Your DoronPay merchant ID
operation string YES Type of operation: DEBIT or CREDIT
Request Body Example
{
  "apikey": "390925-495q-40",
  "merchantId": "4y5e76687957iiytj6",
  "operation": "DEBIT"
}

Response Parameters

Name Type Description
success boolean Indicates if the request was successful
message string A message describing the result of the operation
data string The authentication token to use in subsequent requests

Response Examples

Success Response

Status: 200 OK
{
  "success": true,
  "message": "Token generated successfully",
  "data": "argerghstOIOGIRNIONO283985898w9fndsksplgkslmfpstg400KByUBt"
}

Error Response

Status: 401 Unauthorized
{
  "success": false,
  "code": "04",
  "message": "Invalid API key or merchant ID"
}
cURL
JavaScript
Python
PHP
curl -X POST https://doronpay.com/api/hub/token \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "390925-495q-40",
    "merchantId": "4y5e76687957iiytj6",
    "operation": "DEBIT"
  }'
fetch('https://doronpay.com/api/hub/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    apikey: '390925-495q-40',
    merchantId: '4y5e76687957iiytj6',
    operation: 'DEBIT'
  })
})
.then(response => response.json())
.then(data => {
  console.log('Success:', data);
  // Store the token for subsequent requests
  const token = data.data;
})
.catch((error) => {
  console.error('Error:', error);
});
import requests

url = "https://doronpay.com/api/hub/token"
payload = {
    "apikey": "390925-495q-40",
    "merchantId": "4y5e76687957iiytj6",
    "operation": "DEBIT"
}
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if data["success"]:
    # Store the token for subsequent requests
    token = data["data"]
    print(f"Token: {token}")
else:
    print(f"Error: {data['message']}")
<?php
$url = "https://doronpay.com/api/hub/token";
$payload = array(
    "apikey" => "390925-495q-40",
    "merchantId" => "4y5e76687957iiytj6",
    "operation" => "DEBIT"
);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json'
));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data["success"]) {
    // Store the token for subsequent requests
    $token = $data["data"];
    echo "Token: " . $token;
} else {
    echo "Error: " . $data["message"];
}
?>

Test Authentication Token Endpoint


                    

Credit Transaction

Transfer money to a specific account, either mobile money or bank account.

POST
/credit

This endpoint transfers money to a recipient's mobile money account. It requires authorization using the token obtained from the Authentication Token endpoint.

Parameters
Responses
Code Examples
Try It

Request Headers

Name Type Required Description
Content-Type string YES Must be set to application/json
Authorization string YES Bearer token obtained from the token endpoint

Request Body

Name Type Required Description
externalTransactionId string YES Unique transaction identifier
account_name string YES Recipient's account name
amount string YES Transaction amount
account_number string YES Recipient's account number
account_issuer string YES Network provider of recipient mobile number
description string YES Transaction description
callbackUrl string YES Webhook URL for transaction status updates
Request Body Example
{
  "externalTransactionId": "123434675",
  "account_name": "John Doe",
  "amount": "0.1",
  "account_number": "0207573792",
  "account_issuer": "vodafone",
  "description": "doronpay test",
  "callbackUrl": "https://webhook.site/36b4ec20-8ead-4b30-8b01-98c91697c5ed"
}

Response Parameters

Name Type Description
code string Response code
success boolean Indicates if the request was successful
message string A message describing the result of the operation
externalTransactionId string Your provided transaction identifier
transactionId string System-generated transaction identifier
date string Transaction date and time (ISO format)

Response Examples

Success Response

Status: 200 OK
{
  "code": "01",
  "success": true,
  "message": "Transaction received for processing",
  "externalTransactionId": "123434675",
  "transactionId": "8618063568197732",
  "date": "2023-02-13T11:18:21.042Z"
}

Error Response

Status: 400 Bad Request
{
  "success": false,
  "code": "03",
  "message": "Invalid account number or account issuer"
}
cURL
JavaScript
Python
PHP
curl -X POST https://doronpay.com/api/hub/credit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "externalTransactionId": "123434675",
    "account_name": "John Doe",
    "amount": "0.1",
    "account_number": "0207573792",
    "account_issuer": "vodafone",
    "description": "doronpay test",
    "callbackUrl": "https://webhook.site/36b4ec20-8ead-4b30-8b01-98c91697c5ed"
  }'
const token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // From token endpoint

fetch('https://doronpay.com/api/hub/credit', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    externalTransactionId: "123434675",
    account_name: "John Doe",
    amount: "0.1",
    account_number: "0207573792",
    account_issuer: "vodafone",
    description: "doronpay test",
    callbackUrl: "https://webhook.site/36b4ec20-8ead-4b30-8b01-98c91697c5ed"
  })
})
.then(response => response.json())
.then(data => {
  console.log('Success:', data);
  // Store the transactionId for status checks
  const transactionId = data.transactionId;
})
.catch((error) => {
  console.error('Error:', error);
});
import requests

url = "https://doronpay.com/api/hub/credit"
token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." # From token endpoint

payload = {
    "externalTransactionId": "123434675",
    "account_name": "John Doe",
    "amount": "0.1",
    "account_number": "0207573792",
    "account_issuer": "vodafone",
    "description": "doronpay test",
    "callbackUrl": "https://webhook.site/36b4ec20-8ead-4b30-8b01-98c91697c5ed"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

if data["success"]:
    # Store the transactionId for status checks
    transaction_id = data["transactionId"]
    print(f"Transaction ID: {transaction_id}")
else:
    print(f"Error: {data['message']}")
<?php
$url = "https://doronpay.com/api/hub/credit";
$token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."; // From token endpoint

$payload = array(
    "externalTransactionId" => "123434675",
    "account_name" => "John Doe",
    "amount" => "0.1",
    "account_number" => "0207573792",
    "account_issuer" => "vodafone",
    "description" => "doronpay test",
    "callbackUrl" => "https://webhook.site/36b4ec20-8ead-4b30-8b01-98c91697c5ed"
);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token
));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

if ($data["success"]) {
    // Store the transactionId for status checks
    $transactionId = $data["transactionId"];
    echo "Transaction ID: " . $transactionId;
} else {
    echo "Error: " . $data["message"];
}
?>

Test Credit Transaction Endpoint