DiscHub Logo

DiscHub

Your Reliable Partner

Our Digital Services

Domain Search

Email Hosting

Web Hosting

Apps Development

Graphic Designing

Payment Gateway
DiscHub - Responsive Sidebar Nav
Our WordPress plugin is currently under maintenance until further notice

API Documentation

Welcome to the official Dischub API documentation. Please read the documentation carefully before integrating.

Dischub provides an easy to use integration for receiving payments between Dischub and Merchant's online platforms. This integration 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 platform.
  3. Receive payment status: Get payment statuses by making a POST request for efficient management.

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

1 Configuring Your Account

You are going to config your account. Follow below steps on how to config account.

  1. Visit Finance Page: Navigate to the finance page to manage your bank accounts and wallets at Gateway | Finance.
  2. Visit Dashboard: Navigate to the dashboard at Gateway | Dashboard.
  3. Generate API Key: Click the "Generate" button to generate your own API Key
  4. Enter Business Name: Enter your business name you want your clients to see when they make payments.
  5. Enter Website URL: This is optional !

2 Create Order or Initiate Payment

You need to create a payment order to Dischub by sending a POST request with three (3) required arguments to initiate a transaction. These arguments include: POST Endpoint URL, Request Headers and Request Data.

POST Endpoint
https://dischub.co.zw/api/orders/create/
Request Headers

The API supports application/json. Your API key must be passed in the request headers, not in the request body.

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "6945f57cdbf14b00812cb15df1933f2a"
}
Request Data

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

request = {
    "order_id"  : "344245663",
    "sender"    : "+263780070488",
    "recipient" : "softwarez@gmail.com",
    "amount"    : 14.58,
    "currency"  : "USD",
    "callback_url" : "https://softwarez.co.zw/payment/status/",
    "redirect_url" : "https://softwarez.co.zw/take/me/back/"
}

The request body should include the following fields. Please take note of instructions highlighted in red color

  • order_id: A unique string generated from your system to track this transaction. Must be a string, must be unique across all your orders, and must not exceed 30 characters.
  • sender: The phone number of the customer making the payment. Accepted formats: +263780070488 or 0780070488.
  • recipient: The email address used to create your Dischub merchant account.
  • amount: The payment amount. Must be a valid number, greater than 0 and less than 481.
  • currency: The currency for the transaction. Accepted values: USD or ZWG only.
  • callback_url: (Optional) A URL to which Dischub will send a POST request with the payment status once the transaction is processed. Must be a valid URL and scheme must be 'https only'
  • redirect_url: (Optional) The URL to which the user will be redirected after completing the payment. Must be a valid URL and scheme must be http or https
Responses

After making a POST request, you will receive a JSON response indicating the status of the request. Below are all possible responses you may encounter.

If your request is well integrated, you will receive the following response:

{
    "status": "success",
    "message": "order created successfully",
    "response_code": 201
}

If the X-Api-Key header is missing entirely, you will get the following response:

{
    "status": "error",
    "message": "missing api key in request headers",
    "response_code": 401
}

If one or more required fields are missing or empty in the request body, you will get the following response:

{
    "status": "error",
    "message": "missing or invalid required keys in request data",
    "response_code": 422
}

If the order_id is not sent as a string (e.g. sent as an integer), you will get the following response:

{
    "status": "error",
    "message": "order_id must be posted as a string",
    "response_code": 400
}

If you use the same order_id that was already used in a previous request, you will get the following response:

{
    "status": "error",
    "message": "duplicate order_id detected, please create a new unique order_id",
    "response_code": 409
}

If the order_id is longer than 30 characters, you will get the following response:

{
    "status": "error",
    "message": "order_id must be 30 characters or less",
    "response_code": 422
}

If the amount is not a valid number, or is zero, negative, or 481 and above, you will get the following response:

{
    "status": "error",
    "message": "amount must be greater than 0 and less than 481",
    "response_code": 422
}

If the sender's phone number does not match an accepted format, you will get the following response:

{
    "status": "error",
    "message": "invalid sender phone number format",
    "response_code": 422
}

If the currency value is anything other than USD or ZWG, you will get the following response:

{
    "status": "error",
    "message": "invalid or unsupported currency. Accepted values: USD, ZWG",
    "response_code": 400
}

If the X-Api-Key header and recipient do not match any merchant account, you will get the following response:

{
    "status": "error",
    "message": "authorization failed: wrong api key or recipient identifier",
    "response_code": 401
}

If your merchant account has no business name configured, you will get the following response:

{
    "status": "error",
    "message": "merchant account has no business name configured",
    "response_code": 403
}

If the payment gateway charges are not configured on the server, you will get the following response:

{
    "status": "error",
    "message": "payment gateway charges are not configured, please contact support",
    "response_code": 503
}

If an unexpected server error occurs during order creation, you will get the following response:

{
    "status": "error",
    "message": "order could not be created due to an internal error",
    "response_code": 500
}

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/{orderid}

{orderid} → The unique order ID generated by your system for the transaction.

Example:
https://dischub.co.zw/api/make/payment/to/344245663

4 Completing Payment

Once successfully redirected to Dischub platform, client has to select payment method of choice and complete all further processes until they get either a "Payment successful" or "Payment failed"

5 Receiving Payment Status

This applies when the callback_url fails to receive payment status from Dischub, or when no callback_url was set, as it is optional.

Once a payment is processed, you will need to make a POST request to the Dischub payment status 3 step URL. This allows you to track the success or failure of transactions in real time.

Steps to Handle Payment Status
  1. Make a POST request: Ensure that you make a POST request to the Dischub payment status 3 step URL with proper arguments.
  2. Receive the Payment Status: Dischub returns the payment status as a JSON payload to your request.
  3. Update Your Records: Use the received data to update your database or application with the current payment status.
POST Endpoint
https://dischub.co.zw/api/payment/status/3/step/
Request Headers

The API supports application/json. Your API key must be passed in the request headers, not in the request body.

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "6945f57cdbf14b00812cb15df1933f2a"
}
Request Data

Replace the following data in the request body with your own credentials and the order you want to check:

request = {
    "order_id"  : "344245663",
    "recipient" : "softwarez@gmail.com"
}

The request body should include the following fields. Please take note of instructions highlighted in red color

  • order_id: The order_id you used when creating the order in step 2. This must match exactly the order_id you submitted in the create order request.
  • recipient: The email address used to create your Dischub merchant account.
Responses

After making a POST request, you will receive a JSON response indicating the status of the request. Below are all possible responses you may encounter.

If your request is well integrated, you will receive the following response:

{
    "order_id"  : "344245663",
    "recipient" : "My Business Name",
    "sender"    : "+263780070488",
    "status"    : "success",
    "currency"  : "USD",
    "amount"    : "14.58",
    "timestamp" : "2025-01-09 04:20:08.702591+00:00"
}

If the X-Api-Key header is missing entirely, you will get the following response:

{
    "status": "error",
    "message": "missing api key in request headers",
    "response_code": 401
}

If one or more required fields are missing or empty in the request body, you will get the following response:

{
    "status": "error",
    "message": "missing or invalid required keys in request data",
    "response_code": 422
}

If the X-Api-Key header and recipient do not match any merchant account, you will get the following response:

{
    "status": "error",
    "message": "authorization failed: wrong api key or recipient identifier",
    "response_code": 401
}

If no order is found matching the provided order_id and recipient, you will get the following response:

{
    "status": "error",
    "message": "no order found matching the provided order_id and recipient",
    "response_code": 404
}

If an unexpected server error occurs while retrieving the order, you will get the following response:

{
    "status": "error",
    "message": "an unexpected error occurred while retrieving the order",
    "response_code": 500
}

The status field in the success response can have the following values: "success" (payment completed), "pending" (payment not yet confirmed) or "failed" (payment failed or timed out). Use this to update your system accordingly.

Help

If you face challenges, get help from our developers on Whatsapp

Dischub provides an easy to use, customizable WordPress plugin for receiving payments on your WordPress website. This integration focuses on how to:

  1. Download and install the plugin: Get the Dischub Payments plugin and activate it on your WordPress website.
  2. Configure your merchant credentials: Connect the plugin to your Dischub merchant account using your API key and email.
  3. Accept payments: Add the payment form to any page or post and start receiving payments from customers.
  4. Review payment statuses: Monitor all transactions and their statuses from your Dischub merchant dashboard.

No programming skills are required to integrate this plugin into a WordPress website.

1 Configuring Your Account

You are going to config your account. Follow below steps on how to config account.

  1. Visit Finance Page: Navigate to the finance page to manage your bank accounts and wallets at Gateway | Finance.
  2. Visit Dashboard: Navigate to the dashboard at Gateway | Dashboard.
  3. Generate API Key: Click the "Generate" button to generate your own API Key
  4. Enter Business Name: Enter your business name you want your clients to see when they make payments.
  5. Enter Website URL: This is optional !

2 Download & Install Plugin

You will download the Dischub Payments plugin from the Dischub website to your computer, then upload and activate it on your WordPress website. Optionally, you can customize the payment form and CSS styling before uploading.

Download Plugin

Click the link below to download the plugin ZIP file to your computer:

Download Dischub Payments Plugin

Customize Plugin (Optional)

Before uploading, you can optionally customize the plugin to match your website's look and feel:

  • Edit the payment form layout in the dischub-payments.php file.
  • Edit the styles in the /assets/css/dischub-style.css file to match your website's colors and typography.
  • Once done, re-zip the folder before uploading.
Upload & Activate Plugin

After downloading (and optionally customizing) the plugin, upload and activate it on your WordPress website using one of the following two methods:

  1. Via WordPress Dashboard (Recommended):
    1. Go to WordPress Dashboard → Plugins → Add New.
    2. Click the Upload Plugin button at the top of the page.
    3. Choose the dischub-payments.zip file you downloaded.
    4. Click Install Now, then click Activate Plugin.
  2. Via FTP:
    1. Extract the dischub-payments.zip file on your computer.
    2. Using an FTP client, upload the extracted dischub-payments folder to your server at /wp-content/plugins/.
    3. Go to WordPress Dashboard → Plugins and click Activate next to Dischub Payments.
Configure Your Merchant Credentials

Once the plugin is activated, you must link it to your Dischub merchant account before it can process payments:

  1. Go to WordPress Dashboard → Dischub Payments → Settings.
  2. Enter your API Key — this is the key generated from your Dischub merchant dashboard.
  3. Enter your Merchant Email — this is the email address used to create your Dischub account.
  4. Save your settings. The plugin is now ready to accept payments.

Please take note of instructions highlighted in red color

  • API Key: Your unique API key provided by Dischub. Generate this from your Dischub dashboard if you have not done so already.
  • Merchant Email: This must be the exact email address used to register your Dischub merchant account.

3 Accept Payments on Your Website

Once the plugin is installed, activated, and configured with your credentials, you can start accepting payments on any page or post of your WordPress website.

  1. Add the Payment Form to a Page: Open the page or post where you want to display the payment form. Insert the following shortcode anywhere in the content: 
    [dischub_payment]
    This will render a payment form with fields for the customer's phone number, currency selection (USD or ZWG), and payment amount.
  2. Customer Submits Payment: Your customer fills in their phone number, selects a currency, enters the amount, and clicks "Make Payment". The plugin validates all input fields automatically before proceeding.
  3. Customer is Redirected to Dischub: After a successful form submission, the customer is automatically redirected to the Dischub payment page to complete the transaction securely.
  4. Payment Confirmation: Once the payment is processed, the customer will see either a "Payment Successful" or "Payment Failed" confirmation on the Dischub platform.

4 Review Payment Statuses

After your customers complete payments through the plugin, you can monitor all transactions and their statuses directly from your Dischub merchant dashboard. No additional setup is required — all payments are recorded automatically.

  1. Log in to your Dischub Dashboard: Visit Gateway | Dashboard and sign in with the email and password linked to your merchant account.
  2. Navigate to Payment Transactions: Click on View Full Report to see a full list of all payment transactions made through your website.
  3. Review Transaction Details: Each transaction record displays the following information:
    • Transaction reference
    • Customer's phone number (sender)
    • Payment status: "success", "pending", or "failed"
    • Currency and amount
    • Date and time of the transaction
  4. Filter and Export: You can filter transactions by date, status, or amount. Successful transactions can also be downloaded for accounting or reporting purposes.

Only payments that were fully completed on the Dischub platform will appear as "success" in your dashboard. Payments that were initiated but not completed will appear as "pending".

Help

If you face challenges, get help from our developers on WhatsApp.

Login to Review
No reviews match your search.

"Highly recommend dischub. The onboarding process is seamless and the tech support is phenomenal."

Daily Brand

"I totally recommend the API, it's easy to intergrate and their charges are good only 2% "

Glory Gift & Beauty Essentials

"very happy, n it gets the job done at no cost. highly recommend it. can be improved though on the UI"

AquaSavvy

"dischub is very simple to understand, it is not complicated like other payment gateways"

CoolCash Media

"👍🏻👍🏻"

Tatenda Digitals