DoronPay API Documentation

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.

Our comprehensive API allows you to integrate payment solutions into your applications, websites, or business systems. This documentation provides detailed information about available endpoints, request/response formats, and examples.

Authentication

All API requests require authentication using an API key and merchant ID. These credentials must be included in the request headers.

Obtaining Credentials

  1. Create a DoronPay merchant account.
  2. Generate your unique API key and merchant ID from the dashboard.
  3. Store these credentials securely.

Supported Payment Providers

DoronPay supports the following payment providers for transactions:

  • MTN
  • Vodafone
  • AirtelTigo
  • All major Ghanaian banks
  • Cryptocurrencies (BTC, USDT)

USSD Configuration

DoronPay enables merchants to configure their own USSD shortcodes directly through the merchant dashboard. This feature allows customers to make payments using custom USSD codes without requiring any technical integration.

Setting Up USSD Payments

  1. Access Wallet Settings
    • Navigate to your merchant dashboard
    • Access the Hub section
    • Click "Update Wallet Details Icon"
  2. Configure USSD Settings
    • Enter your USSD shortcode (e.g., *123#)
    • Provide a callback URL for USSD payment notifications
    • Enable USSD Payments using the checkbox
    • Save your configuration by clicking "Update Settings"

Key Features

  • Direct integration with existing USSD systems
  • Real-time transaction processing
  • Support for all major mobile money providers
  • Automated payment reconciliation
  • No technical integration required

1. Authentication Token

Generate an authentication token for subsequent API calls.

POST https://doronpay.com/api/hub/token
Generate a secure token that must be used for all subsequent API requests. The token is valid for a limited time period.

Headers

Parameter Value Type Required Description
Content-Type Application/json YES This is needed to encode all requests and responses as JSON

Request Payload

Parameter Value Type Required Description
apikey string YES Unique key generated for merchant
merchantId string YES Unique ID generated for merchant
operation string YES Type of operation being performed
Sample Payload
{
  "apikey": "390925-495q-40",
  "merchantId": "4y5e76687957iiytj6",
  "operation": "DEBIT"
}

Sample Response

Success Response
{
  "success": true,
  "message": "Token generated successfully",
  "data": "argerghstOIOGIRNIONO283985898w9fndsksplgkslmfpstg400KByUBt"
}

Try It Out

2. Credit Transaction

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

POST https://doronpay.com/api/hub/credit
Send money to a recipient's mobile money account. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Headers

Parameter Value Type Required Description
Content-Type Application/json YES This is needed to encode all requests and responses as JSON
Authorization Bearer Token YES Authorization token obtained from the token endpoint

Request Payload

Parameter Value 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
Sample 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"
}

Sample Response

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

3. Debit Transaction

Request funds from a mobile money account.

POST https://doronpay.com/api/hub/debit
Request money from a user's mobile money account. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Request Payload

Parameter Value Type Required Description
externalTransactionId String YES Unique transaction identifier
account_name String YES Account holder's name
amount String YES Transaction amount
account_number String YES Recipient mobile number
account_issuer String YES Network provider of recipient mobile number
description String YES Brief description of the transaction
callbackUrl String YES Webhook URL for transaction status updates
Sample Payload
{
  "externalTransactionId": "123434675",
  "account_name": "John Doe",
  "amount": "1",
  "account_number": "0207573792",
  "account_issuer": "vodafone",
  "description": "doronpay test",
  "callbackUrl": "https://webhook.site/36b4ec20-8ead-4b30-8b01-98c91697c5ed"
}

Sample Response

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

4. Card Payment

Process card payments.

POST https://doronpay.com/api/hub/card
Process payments using payment cards. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Request Payload

Parameter Value Type Required Description
amount string YES Amount to be paid
account_name string YES Account holder's name
card object YES Card details object (see below)
description string YES Brief description of the transaction
callbackUrl String YES Webhook URL for transaction status
clientRedirectUrl String YES Client URL to redirect to

Card Object

Parameter Value Type Required Description
cvc string YES Secret code for the card
expiry string YES Expiry date for the card
number string YES Card number
Sample Payload
{
  "externalTransactionId": "00100234",
  "account_name": "Kweku Frimpong",
  "amount": "1",
  "description": "card test",
  "card": {
    "cvc": "123",
    "expiry": "09/23",
    "number": "12345678910"
  },
  "callbackUrl": "https://webhook.site/7fcce040-8d4f-4e79-bde6-31abcd3ff897",
  "clientRedirectUrl": "https://doronpay.com"
}

Sample Response

Success Response
{
  "code": "00",
  "success": true,
  "message": "success",
  "status": "stats",
  "redirectUrl": "redirectUrl",
  "transactionId": "8618063568197732",
  "date": "2023-02-13T11:18:21.042Z"
}

5. Get Transaction Status

Retrieve the status of a transaction using its unique external ID.

GET https://doronpay.com/api/hub/status/{externalTransactionId}
Check the status of a previously initiated transaction using its external transaction ID. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Parameters

Parameter Parameter Type Required Description
externalTransactionId Path Parameter YES The unique transaction identifier
Sample URL Request
https://doronpay.com/api/hub/status/123243535345

Sample Response

Error Response - Transaction Not Found
{
  "success": false,
  "code": "02",
  "status": "FAILED",
  "message": "Transaction not found",
  "transactionId": "123243535345"
}

6. Account Name Verification

Get the verified registered name on the recipient account number.

POST https://doronpay.com/api/hub/enquiry

Verify the registered name on a mobile money account or bank account. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Specify the account type field as either "momo" or "bank". By default, the account type is "momo".

Note: For bank transactions, account_issuers should be passed as the bank code and not the bank name. For example, ABSA BANK GHANA LIMITED has code "300303".

Request Payload

Parameter Value Type Required Description
account_number string YES Mobile number or bank account to check the name
account_issuer string YES Network provider or bank code
account_type string NO "Bank" or "Momo" (default: "Momo")
Sample Payload
{
  "account_number": "0506259044",
  "account_issuer": "vodafone"
}

Sample Response

Success Response
{
  "success": true,
  "code": "00",
  "message": "success",
  "data": "Dany Christopher PERRIERE"
}

7. Bank Transaction

Process transactions with bank accounts.

POST https://doronpay.com/api/hub/credit

Process transactions with bank accounts. When performing bank transactions, use the bank's code as the account_issuer instead of the bank name.

Important: account_issuer should be a string of integer (passed as a code) when performing bank transaction requests. Each bank has a special code that is used instead of their name.

Request Payload

Parameter Value Type Required Description
externalTransactionId String YES Unique transaction identifier
account_name String YES Account holder's name
amount String YES Transaction amount
account_number String YES Bank account number
account_issuer String YES Bank code (e.g., "300303" for ABSA Bank)
account_type String YES Must be set to "bank"
serviceType String NO Transfer type: "NRT" or "GIP" (default: "GIP")
description String YES Brief description of the transaction
callbackUrl String YES Webhook URL for transaction status updates
Sample Payload
{
  "externalTransactionId": "123434675", 
  "account_name": "Joseph Osei Luiz", 
  "amount": "5", 
  "account_number": "0413541220",
  "account_issuer": "300303",
  "account_type": "bank",
  "serviceType": "GIP",
  "description": "doronpay test",
  "callbackUrl": "https://webhook.site/36b4ec20-8ead-4b30-8b01-98c91697c5ed"
}

Sample Response

Success Response
{
  "success": true,
  "code": "01",
  "message": "Transaction queued for processing",
  "transactionId": "7598218378153776",
  "date": "2025-01-23T17:35:47.738Z",
  "externalTransactionId": "123434675"
}

8. Get Bank List

Retrieve a list of supported banks and their codes.

GET https://doronpay.com/api/hub/banks/get
Retrieve a list of supported banks with their respective codes, which are required for bank transactions. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Sample Response

Success Response
{
  "success": true,
  "message": "success",
  "data": [
    {
      "BankCode": "300302",
      "BankName": "STANDARD CHARTERED BANK (GH) LTD",
      "NrtActive": "True",
      "IsActive": "True"
    },
    {
      "BankCode": "300303",
      "BankName": "ABSA BANK (GH) LTD.",
      "NrtActive": "True",
      "IsActive": "True"
    }
    // ... other banks
  ]
}

Supported Banks and Codes

Here are the supported banks and their corresponding codes for transactions:

Bank Code Bank Name
300302 STANDARD CHARTERED BANK (GH) LTD
300303 ABSA BANK (GH) LTD.
300304 GCB BANK
300305 NATIONAL INVESTMENT BANK LTD
300325 UNITED BANK FOR AFRICA (GH) LTD
300306 ARP APEX BANK LTD
300308 SG GHANA LTD
300309 UNIVERSAL MERCHANT BANK
300310 REPUBLIC BANK
300311 ZENITH BANK (GH) LTD
300312 ECOBANK (GH) LTD
300313 CAL BANK LTD
300316 FIRST ATLANTIC MERCHANT BANK LTD
300317 PRUDENTIAL BANK LTD
300318 STANBIC BANK GHANA LTD
300320 BANK OF AFRICA LTD
300323 FIDELITY BANK GHANA LTD
300322 GUARANTY TRUST BANK
300324 OmniBSIC GHANA
300329 ACCESS BANK (GH) LTD
300334 FIRST NATIONAL BANK
300331 CONSOLIDATED BANK GHANA
300307 AGRICULTURAL DEVELOPMENT BANK
300319 FBN BANK LTD

Important Notes:

  • Always use the bank code (not bank name) as the account_issuer when making bank transactions
  • Set account_type to "bank" for all bank transactions
  • Bank codes must be passed as strings (e.g., "300303" not 300303)
  • The serviceType parameter accepts either "NRT" or "GIP" values
  • If serviceType is not specified, it defaults to "GIP"
  • Verify bank account details before processing transactions

9. Credit Transaction (USDT)

Transfer USDT to a specified account.

POST https://doronpay.com/api/hub/credit
Transfer USDT to a specified wallet address. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Request Payload

Parameter Value 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 USDT wallet address
account_type String YES Type of account ("usdt")
description String YES Transaction description
callbackUrl String YES Webhook URL for transaction status updates
Sample Payload
{
  "externalTransactionId": "1121",
  "account_name": "John Doe",
  "amount": "0.5",
  "account_number": "TAdt5etY92vZFQwkv7DYt7HtvJFEjJ",
  "account_type": "usdt",
  "description": "USDT to my Binance test 2",
  "callbackUrl": "https://webhook.site/426d06e1-9fd2-4ce6-9326-1a6be60bdb20"
}

10. Debit Transaction (USDT)

Request funds in USDT from a specific account.

POST https://doronpay.com/api/hub/debit
Request USDT funds from a specified wallet address. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Request Payload

Parameter Value Type Required Description
externalTransactionId String YES Unique transaction identifier
account_name String YES Account holder's name
account_type String YES Type of account ("usdt")
account_number String YES Recipient's USDT wallet address
amount String YES Transaction amount
description String YES Brief description of the transaction
callbackUrl String YES Webhook URL for transaction status updates
Sample Payload
{
  "externalTransactionId": "111",
  "account_name": "John Doe",
  "account_type": "usdt",
  "account_number": "TAdt5etY92vZFQwkv7DYt7HtvJFEjJ",
  "amount": "1",
  "description": "Transaction payment",
  "callbackUrl": "https://webhook.site/426d06e1-9fd2-4ce6-1a6be60bdb20"
}

11. Credit Transaction (BTC)

Transfer BTC to a specified account.

POST https://doronpay.com/api/hub/credit
Transfer BTC to a specified wallet address. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Request Payload

Parameter Value 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 BTC wallet address
account_type String YES Type of account ("btc")
description String YES Transaction description
callbackUrl String YES Webhook URL for transaction status updates
Sample Payload
{
  "externalTransactionId": "1121",
  "account_name": "John Doe",
  "amount": "1",
  "account_number": "btc wallet address",
  "account_type": "btc",
  "description": "BTC to 2",
  "callbackUrl": "https://webhook.site/426d06e1-9fd2-4ce6-9326-1a6be60bdb20"
}

12. Debit Transaction (BTC)

Request funds in BTC from a specific account.

POST https://doronpay.com/api/hub/debit
Request BTC funds from a specified wallet address. This endpoint requires authorization using the token obtained from the Authentication Token endpoint.

Request Payload

Parameter Value Type Required Description
externalTransactionId String YES Unique transaction identifier
account_name String YES Account holder's name
account_type String YES Type of account ("btc")
amount String YES Transaction amount
description String YES Brief description of the transaction
callbackUrl String YES Webhook URL for transaction status updates
Sample Payload
{
  "externalTransactionId": "111",
  "account_name": "John Doe",
  "account_type": "btc",
  "amount": "1",
  "description": "Transaction payment",
  "callbackUrl": "https://webhook.site/426d06e1-9fd2-4ce6-9326-1a6be60bdb20"
}

Responses and Error Codes

Here's a list of response codes that may be returned by the API.

Code Description
00 Transaction successful. Payment received and processed successfully
01 Transaction received for processing
02 Transaction failed