3-Step API Overview

Dischub provides an easy-to-use payment gateway API for sending and receiving payments between users. This API documentation focuses on how to:

1. Create a new payment order : Use a POST request to create payment orders.
2. Complete payments : Enable users to complete transactions seamlessly on Dischub platforms.
3. Receive payment status : Get payment statuses on your platform’s return URL for efficient management.

If you have no programming skills, you can find a developer

Step 1. Activating Demo Accounts

You are going to use demo accounts to test our API on your plaform(s). Follow below steps on how to activate demo accounts.

1. Register accounts : Create both individual and business accounts. If you already have them, skip this stage and go to step 2.
2. Activate Demo : Navigate to your settings in both accounts and activate demo accounts. For individual accounts use this button Individual and for business accounts use this button Business.
3. Add Funds : Add funds to your Individual Demo Account because you are going to test the integration by sending funds from Individual account to Business account.

Step 2. Create Order or Initiate Payment

You need to create a payment order to dischub by sending a POST request with the three (3) required aurguments to initiate a transaction. These aurguments include:

post endpoint url
request headers
request data

Please find them below in more detail :

POST Endpoint

https://dischub.co.zw/api/orders/create/

Request Headers

The API supports application/json

headers = {
        "Content-Type": "application/json" 
          }

Request Data

Replace the following data in the request body with your own credentials and payment details:

request = {
        "api_key" : "WKjY8yYwlTiZ3MxbDgFqVCJmx_E1RV9mLGTf_fppmqIELjy7791NWVJ1WGSCS27s",
        "notify_url" : "https://softwarez.co.zw/payments/success",
        "order_id" : "344245663564",
        "recipient" : "softwarez@gmail.com",
        "amount" : 14.58,
        "currency" : "USD"
        }
            

Responses

After making a post request, you will receive a response in form of json, indicating the status of the post request. Below are the possible responses you may encounter.

{
"status": "success",
"message": "payment initiated",
"response_code": 200
}

{
"status": "error",
"message": "missing or invalid required keys",
"response_code": 400
}

{
"status": "error",
"message": "Invalid or unsupported currency",
"response_code": 400
}

{
"status": "error",
"message": "invalid notify_url format",
"response_code": 400
}

{
"status": "error",
"message": "order_id must be numeric only",
"response_code": 400
}

{
"status": "error",
"message": "authorization failed",
"response_code": 401
}

Step 3. Redirecting To Dischub

This step comes after you have received a 'success' response from step 2 otherwise do not continue and revise your integration first

Upon 'success', the user is redirected to:

https://dischub.co.zw/api/make/payment/to/{recipient}/{orderid}
        

https://dischub.co.zw/api/make/payment/to/softwarez@gmail.com/344245663564
        

Step 4. Completing Payment

4a) User then has to click "Dischub" and login into their individual account by entering email, password and reference

**All fields are mandatory**

**Dischub is the only payment method for testing environment**

Step 5: Receiving Payment Status

Once a payment is processed, Dischub will send a status update to the callback URL (notify_url) you provided during the order creation. This allows you to track the success or failure of transactions in real-time.

Steps to Handle Payment Status

1. Set Your Callback URL : Ensure that your system is configured to receive POST requests at the callback URL you registered.
2. Receive the Payment Status : Dischub sends the payment status as a JSON payload in the body of the POST request.
3. Update Your Records : Use the received data to update your database or application with the current payment status.

Sample Payload

{
'transaction_id': 277602,
'order_id' : '344245663564',
'reference': 'Brian Shumba',
'status': 'success', 
'currency': 'USD', 
'amount': '14.58', 
'timestamp': '2025-01-09 04:20:08.702591+00:00'
}
                    

The status field can have values such as "success" or "failed". Use this information to handle the transaction appropriately in your system.

Error Handling

If your callback URL is unreachable or returns an error, Dischub will retry the notification several times over a period of time. Ensure your endpoint is reliable and logs any issues for debugging purposes.

Recommendations

We recommend you to add more funds of all currencies in your individual demo accounts and test our api as many times as you can. When you get satisfied you can turn off all demo accounts and start receiving real funds.

Developers Forum

If you face challenges, get help from other developers in our forum telegram group chat