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://cmaal.com/Pay/

Method: POST

Parameters

Example HTML Form

<form action="https://cmaal.com/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://cmaal.com/success">
    <input type="hidden" name="cancel_url" value="https://cmaal.com/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

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://api.cmaal.com/verify_v2

Method: GET

Parameters

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://api.cmaal.com/verify_v2?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

4. Send Money to CashMaal User

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

Endpoint

URL: https://api.cmaal.com/payout_v2

Method: POST

Parameters

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://api.cmaal.com/'.$cmd);
        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

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://api.cmaal.com/verify_accounts

Method

GET

2. Parameters

3. Example Request

GET /[email protected]

4. Example Response

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

5. Response Parameters

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://api.cmaal.com/verify_accounts?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://api.cmaal.com/check_balance

Method

GET

2. Parameters

3. Example Request

GET /[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

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://api.cmaal.com/check_balance?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://api.cmaal.com/check_balance

Method

GET

2. Parameters

3. Example Request

GET /[email protected]&password=myPassword

4. Example Response

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

5. Response Parameters

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://api.cmaal.com/check_balance?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.