CashMaal API Documentation

Starting Steps

How to start if you want to accept Online payments on your Site within few simple steps?

1. Create your cashmaal account
2. Login now and go to
3. Merchant setting
4. Add your Site in Merchant Settings
5. You will get a Web ID
6. Go live....







1. Receive Money API

This API allows you to redirect users to the Cashmaal payment gateway to receive payments.

Endpoint

URL: https://www.cashmaal.net/Pay/

Method: POST

Parameters

Parameter Name Description Type Required Example
pay_method Payment method (cm, pm, jca, epa, btc). If left blank, the user will select on Cashmaal. String No "cm"
amount Payment amount. Number Yes 2000
currency Currency type (PKR, USD). String Yes "USD"
succes_url URL to redirect the user if the payment is completed successfully. String Yes "https://www.cashmaal.net/success"
cancel_url URL to redirect the user if the payment is not completed. String Yes "https://www.cashmaal.net/cancel"
client_email Client's email address where payment confirmation will be sent. String Yes "[email protected]"
web_id Your website ID which can be found in your Cashmaal panel. String Yes "2"
order_id Unique Order ID (Optional) (Max 80 characters). String No ""
addi_info Additional information (Optional) (Max 80 characters). String No "John Domain renewal payment"

Example HTML Form

<form action="https://www.cashmaal.net/Pay/" method="POST">
    <input type="hidden" name="pay_method" value="">
    <input type="hidden" name="amount" value="2000">
    <input type="hidden" name="currency" value="USD">
    <input type="hidden" name="succes_url" value="https://www.cashmaal.net/success">
    <input type="hidden" name="cancel_url" value="https://www.cashmaal.net/cancel">
    <input type="hidden" name="client_email" value="[email protected]">
    <input type="hidden" name="web_id" value="2">
    <input type="hidden" name="order_id" value="">
    <input type="hidden" name="addi_info" value="John Domain renewal payment">
    <input type="submit" name="Submit" value="Pay With Cashmaal">
</form>

2. Receive Money Verification Using IPN

Use IPN (Instant Payment Notification) to verify transactions. Ensure that the IPN URL is added in your Cashmaal merchant settings. You will receive IPN in the same currency that you request from the user.

IPN Response Data Sample

{
    "status": "1",
    "web_id": "6",
    "CM_TID": "CK858BZ9416",
    "Amount": "0.5",
    "currency": "USD",
    "fee": "0",
    "client_email": "[email protected]",
    "order_id": "510561948",
    "date_time": "02-06-2019 10:53:22 AM",
    "addi_info": "For Ads",
    "ipn_key": "A39KxWfeCk9bw4ztNa3ydqfg7qbvOioQb52"
}

IPN Response Details

Parameter Name Description
status 1 (Successful) | 2 (Pending) | 3 (Rejected) | 0 (Cancelled)
web_id Your Web ID (Can be found in merchant settings in Cashmaal account)
CM_TID Cashmaal Transaction ID
Amount Amount received
currency Currency in which the user paid
fee Fee on the amount received
client_email Client's email address provided in the POST data
order_id Order ID provided in the POST data
date_time Transaction date and time
addi_info Additional information provided in the POST data
ipn_key Your IPN key (Must match with the IPN key in your Cashmaal account settings)

PHP Sample for IPN

<?php

$IPN_key = ""; // Your IPN Key here (You can get IPN Key from your Cashmaal Account (Merchant settings Tab))

if ($_POST['ipn_key'] == $IPN_key) { // Ensure this is real post data

    if ($_POST['status'] == 1) { // Ensure you have received this payment

        $CM_TID = $_POST['status']; // Cashmaal Transaction ID
        $web_id = $_POST['web_id']; // Cashmaal website ID
        $Amount = $_POST['Amount']; // Received Amount
        $currency = $_POST['currency']; // Transaction currency
        $fee = $_POST['fee']; // Transaction Fee
        $client_email = $_POST['client_email']; // Client email ID
        $order_id = $_POST['order_id']; // Order ID
        $date_time = $_POST['date_time']; // Transaction DateTime
        $addi_info = $_POST['addi_info']; // Additional information

        /*
        IMPORTANT: After updating data in your database, please show us the body response '**OK**' (OK in between double stars).
        Use a command like exit('**OK**');
        If you show this response, our system will resend callbacks until it gets this response. If you don't show this, then the system will try once only.
        */

        exit('**OK**');

    } elseif ($_POST['status'] == 2) {
        echo "Pending! Your payment is pending in the Cashmaal account.";
    } else {
        echo "Error! Payment not received. Please pay again.";
    }

} else {
    echo "Error! Data Invalid";
}

?>

3. Received Money Verification Using API Without IPN

This API allows you to verify transactions after redirecting the user back to your success URL.

Endpoint

URL: https://www.cashmaal.net/Pay/verify_v2.php

Method: GET

Parameters

Parameter Name Description Type Required Example
CM_TID Transaction ID returned after the payment. String Yes CK858BZ9416
web_id Your website ID found in your Cashmaal account. String Yes 2

Example PHP Code for Verification

<?php
$web_id = "2"; // Your Web ID

if (isset($_POST['CM_TID'])) {
    $CM_TID = $_POST['CM_TID']; // Getting TID from user redirection

    $url = "https://www.cashmaal.net/Pay/verify_v2.php?CM_TID=" . urlencode($CM_TID) . "&web_id=" . urlencode($web_id);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_URL, $url);
    $result = curl_exec($ch);
    curl_close($ch);

    $obj = json_decode($result);

    if ($obj['status'] == 1) { // Payment received
        if ($obj['USD_amount'] == '200') {
            // Payment Confirmed USD 200 Received
        } else {
            // Error: we have not received the full amount
        }
    } else {
        echo "Error: " . $obj['error'];
    }
}
?>

Example Response

{
    "status": "1",
    "receiver_account": "8",
    "USD_amount": "1.670",
    "fee_in_USD": "0.000",
    "PKR_amount": "280",
    "fee_in_PKR": "0",
    "USD_amount_with_fee": "1.670",
    "PKR_amount_with_fee": "280",
    "trx_website": "website.com",
    "transaction_id": "2JW9651118P",
    "trx_date": "25-03-2020 9:13:48 PM",
    "order_id": "12345678",
    "addi_info": "Test Payment",
    "sender_details": "Fund Received From 161919",
    "trx_details": "$1.67 Receive against TID: '2JW9651118P'"
}

Response Parameters

Parameter Name Description Type Example
status Status of the transaction: 1 (Successful), 2 (Pending), 3 (Rejected), 0 (Cancelled). Integer 1
receiver_account Your Cashmaal receiver account ID. Integer 8
USD_amount Amount received in USD. Float 1.670
fee_in_USD Transaction fee in USD. Float 0.000
PKR_amount Amount received in PKR. Float 280
fee_in_PKR Transaction fee in PKR. Float 0
USD_amount_with_fee Total amount received in USD including fees. Float 1.670
PKR_amount_with_fee Total amount received in PKR including fees. Float 280
trx_website The website from which the transaction was made. String website.com
transaction_id Unique transaction ID from Cashmaal. String 2JW9651118P
trx_date Date and time of the transaction. String 25-03-2020 9:13:48 PM
order_id Order ID sent in the initial payment request. String 12345678
addi_info Additional information sent in the initial payment request. String Test Payment
sender_details Details of the sender. String Fund Received From 161919
trx_details Details of the transaction. String $1.67 Receive against TID: '2JW9651118P'

4. Send Money to CashMaal User

This API allows you to send money to your clients directly from your website.

Endpoint

URL: https://www.cashmaal.net/Pay/payout_v2.php

Method: POST

Parameters

Parameter Name Description Type Required Example
to_email Email address of the recipient. String Yes [email protected]
currency_is Currency of the transaction (e.g., USD, PKR). String Yes USD
sending_amount The amount of money to send. Float Yes 1
order_id Order ID for tracking (Optional). String No
addi_info Additional information about the transaction (Optional). String No this is test payment
p_secretkey Your Payout Secret Key (needed for API authentication). String Yes ADD_PAYOUT_SECRET_KEY_HERE

Example PHP Code for Sending Money

<?php
function CashMaal_API($cmd, $req = array()) {
    $CashMaal_payout_API = 'ADD_PAYOUT_SECRET_KEY_HERE';
    $req['cmd'] = $cmd;
    $req['p_secretkey'] = $CashMaal_payout_API;
    $req['user_ip'] = $_SERVER['REMOTE_ADDR'];

    $post_data = http_build_query($req, '', '&');
    static $ch = NULL;
    if ($ch === NULL) {
        $ch = curl_init('https://www.cashmaal.net/Pay/'.$cmd.'.php');
        curl_setopt($ch, CURLOPT_FAILONERROR, TRUE);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
    }

    curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
    return $data = curl_exec($ch);
}

$CashMaal_API = CashMaal_API("payout_v2", $req = array(
    "to_email" => "[email protected]",
    "currency_is" => "USD",
    "sending_amount" => "1",
    "order_id" => "",
    "addi_info" => "this is test payment"
));

$CashMaal_API_Json = json_decode($CashMaal_API, true);
if ($CashMaal_API_Json['status'] == 1) {
    echo $CashMaal_API_Json['transaction_details'];
    echo "<br>";
    echo $CashMaal_API_Json['amount'];
    echo "<br>";
    echo $CashMaal_API_Json['fee'];
    echo "<br>";
    echo $CashMaal_API_Json['fee_details'];
    echo "<br>";
    echo $CashMaal_API_Json['currency'];
    echo "<br>";
    echo $CashMaal_API_Json['trx_id'];
    echo "<br>";
    echo $CashMaal_API_Json['receiver_name'];
    echo "<br>";
    echo $CashMaal_API_Json['trx_date'];
    echo "<br>";
    echo $CashMaal_API_Json['order_id'];
    echo "<br>";
    echo $CashMaal_API_Json['addi_info'];
} else {
    echo "Error: " . $CashMaal_API_Json['error'];
}
?>

Example Success Response

{
    "status": "1",
    "amount": "270",
    "fee": 2.70,
    "fee_details": "Fund Transfer Fee 1%",
    "trx_id": "33991275LS5",
    "currency": "PKR",
    "receiver_name": "Nadir Khan",
    "trx_date": "23-02-2022 6:20:31 PM",
    "order_id": "AO12302202223",
    "addi_info": "Payout ($2) of Nadir - 1",
    "transaction_details": "Success ! PKR 270 Successfully Transferred to (Nadir Khan - '[email protected]' - 19527). Transaction ID 33991275LS5",
    "error": ""
}

Response Parameters

Parameter Name Description Type Example
status Status of the transaction: 1 (Successful), 0 (Failed). Integer 1
amount Amount successfully transferred. Float 270
fee Transaction fee charged for the transfer. Float 2.70
fee_details Details about the transaction fee. String Fund Transfer Fee 1%
trx_id Cashmaal transaction ID. String 33991275LS5
currency Currency used for the transaction. String PKR
receiver_name Name of the recipient. String Nadir Khan
trx_date Date and time when the transaction occurred. String 23-02-2022 6:20:31 PM
order_id Order ID associated with the transaction. String AO12302202223
addi_info Additional information about the transaction. String Payout ($2) of Nadir - 1
transaction_details Details about the transaction outcome. String Success ! PKR 270 Successfully Transferred to (Nadir Khan - '[email protected]' - 19527). Transaction ID 33991275LS5
error Error message if the transaction fails. String

5. CashMaal Users Account Validations API

This API allows you to validate a CashMaal user's account by checking if the email exists.

1. Validate User Account

To validate a user's CashMaal account, send a request to the following endpoint:

Endpoint

https://www.cashmaal.net/Pay/verify_accounts.php

Method

GET

2. Parameters

Parameter Type Required Description
email string Yes The CashMaal account email to validate.
mode string Yes Integration mode: 'test' or 'live'.

3. Example Request

GET /Pay/[email protected]

4. Example Response

{
    "status": "1",
    "email": "[email protected]",
    "name": "Client Name",
    "error": ""
}

5. Response Parameters

Parameter Type Description
status integer 1 if account is found, 0 if not found.
email string The validated CashMaal email ID.
name string The name associated with the CashMaal account.
error string Error message if the account is not found.

6. Example Error Response

{
    "status": "0",
    "error": "Account not found"
}

7. PHP Code Example

<?php
$email = '[email protected]'; // Enter cashmaal account email id here.
$mode = 'test'; // Enter integration mode here, ('test' or 'live')

$url = "https://www.cashmaal.net/Pay/verify_accounts.php?mode=".$mode."&email=".urlencode($email);

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
curl_close($ch);

$obj = json_decode($result);

$api_status = $obj->status; // 1 = Account Found, 0 = Account Not found

if ($api_status == 1) {
    echo $obj->email; // CashMaal Email Id
    echo "<br>";
    echo $obj->name; // CashMaal Account Title
} else {
    echo $obj->error; // Showing Error
}
?>

6. Check Available Balance of CashMaal Account

This API allows you to check the available balance of a CashMaal account.

1. Check Account Balance

To check the balance of a CashMaal account, send a request to the following endpoint:

Endpoint

https://www.cashmaal.net/Pay/check_balance.php

Method

GET

2. Parameters

Parameter Type Required Description
email string Yes The CashMaal account email to check balance.
password string Yes The CashMaal account password.
mode string Yes Integration mode: 'test' or 'live'.

3. Example Request

GET /Pay/[email protected]&password=myPassword

4. Example Response

{
    "Status": "1",
    "Balance_in_PKR": "1500",
    "Balance_in_USD": "10",
    "USD_to_PKR_live_Rate": "150",
    "Error": ""
}

5. Response Parameters

Parameter Type Description
Status integer 1 if balance is retrieved successfully, 2 if there is an error.
Balance_in_PKR float Available balance in PKR.
Balance_in_USD float Available balance in USD.
USD_to_PKR_live_Rate float Current live market rate of USD to PKR.
Error string Error message if balance retrieval fails.

6. Example Error Response

{
    "Status": "2",
    "Error": "Invalid credentials"
}

7. PHP Code Example

<?php
$email = '[email protected]'; // Enter your cashmaal account email id here.
$password = 'myPassword'; // Enter your cashmaal Password here
$mode = 'test'; // Enter your integration mode ("test" or "live")

$url = "https://www.cashmaal.net/Pay/check_balance.php?mode=".$mode."&email=".urlencode($email)."&password=".urlencode($password);

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
curl_close($ch);

$obj = json_decode($result);

$api_status = $obj->Status; // 1 = All is well, 2 = Something not working

if ($api_status == 1) {
    echo $obj->Balance_in_PKR; // Getting balance in PKR
    echo "<br>";
    echo $obj->Balance_in_USD; // Getting balance in USD
    echo "<br>";
    echo $obj->USD_to_PKR_live_Rate; // Getting Live USD to PKR Market rate
} else {
    echo $obj->Error; // Showing Error
}
?>

7. Check Live USD to PKR Currency Rates

This API allows you to check the live exchange rate of USD to PKR.

1. Get Live Currency Rate

To check the live USD to PKR currency rate, send a request to the following endpoint:

Endpoint

https://www.cashmaal.net/Pay/check_balance.php

Method

GET

2. Parameters

Parameter Type Required Description
email string Yes The CashMaal account email to check balance.
password string Yes The CashMaal account password.
mode string Yes Integration mode: 'test' or 'live'.

3. Example Request

GET /Pay/[email protected]&password=myPassword

4. Example Response

{
    "Status": "1",
    "USD_to_PKR_live_Rate": "150",
    "Error": ""
}

5. Response Parameters

Parameter Type Description
Status integer 1 if rate is retrieved successfully, 2 if there is an error.
USD_to_PKR_live_Rate float Current live exchange rate of USD to PKR.
Error string Error message if rate retrieval fails.

6. Example Error Response

{
    "Status": "2",
    "Error": "Invalid credentials"
}

7. PHP Code Example

<?php
$email = '[email protected]'; // Enter your cashmaal account email id here.
$password = 'myPassword'; // Enter your cashmaal Password here
$mode = 'test'; // Enter your integration mode ("test" or "live")

$url = "https://www.cashmaal.net/Pay/check_balance.php?mode=".$mode."&email=".urlencode($email)."&password=".urlencode($password);

$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_URL, $url);
$result = curl_exec($ch);
curl_close($ch);

$obj = json_decode($result);

$api_status = $obj->Status; // 1 = All is well, 2 = Something not working

if ($api_status == 1) {
    echo $obj->USD_to_PKR_live_Rate; // Getting Live USD to PKR Market rate
} else {
    echo $obj->Error; // Showing Error
}
?>

8. Contact To Support Team

For any issues related to API integration or questions regarding the documentation, please reach out to us at [email protected]. We are here to assist you.