Cash DZ Payment System
What is Cash DZ Payment System?
Cash DZ is an online wallet that can hold your Algerian Dinar funds and can facilitate transfer of money between Cash DZ accounts or make payments on websites or services that accept Cash DZ as a form of payment.
Website integration
Your customers shop on your website, and then are redirected to your checkout page where you can offer payment with Cash DZ. When they click the "Pay with Cash DZ" button, they are redirected to their Cash DZ account where they can make payment, and then redirected back to your website.
Payment Flow
The customer starts from your checkout page. You will have to insert a Pay with Cash DZ button ( See Pay Button section below ). You will replace the word CALLBACK with your Javacript function that calls your back-end script ( See Back-end script section below ). Your back-end script should build a message that contains your application ID, order details, and return URL. Sign the message, then redirects the customer to the Cash DZ payment portal at https://cashdz.com/pay/ and pass the message and signature. Once the customer completes payment, they are redirected back to your website at the returl URL.

→
↓
←
↓
Pay Button
Insert the following code in your checkout page to show the Cash DZ Pay Now button. This is optional. You can always create your own Pay Button that redirects to your backend payment script:

HTML Code
<script src="https://cashdz.com/pay/lib.js?pay_callback=CALLBACK&mode=MODE&size=SIZE"></script>
Parameters
  - pay_callback: Replace it with a javascript function that would start the payment flow. You can pass a function name or an entire call with the parameters. For example: payNow, payNow(), payNow('ORDER_55').
  - mode: This can take one of the following values: light, dark (Optional).
  - size: This can take one of the following values: small, medium, large (Optional).
Preview
Light mode
Dark mode
Back-end Script
You will need your application ID and API secret key found in the Developers portal here. The script will build the message, sign it, and redirect to Cash DZ.
Payment Message
The backend script should build a JSON object for the payment message to send to Cash DZ. The following is the structure of this object:

	{
		"app_id": YOUR_APP_ID,
		"return_url": RETURN_URL
		"order": {
			"order_id": YOUR_CUSTOM_ORDER_ID,
			"items": [
				{
					"description": PRODUCT_DESCRIPTION,
					"price": PRICE,
					"quantity": QUANTITY
				},
				{
					"description": PRODUCT_DESCRIPTION,
					"price": PRICE,
					"quantity": QUANTITY
				},
				...
			],
			"total": ORDER_TOTAL
		},
	}
Parameters
  - app_id: The App ID of the application you created in the Developers Portal.
  - return_url: The URL to the return web page on your site where the customer is redirected after the payment is complete.
  - order: Object containing the order details.
    - order_id: You custom order ID you set for your internal tracking.
    - items: A list of order items.
      - description: Description of the product or service.
      - price: Price of the product in Algerian Dinars.
      - quantity: Quantity of this product (Optional).
    - shipping: Shipping charged (Optional).
    - tax: Tax to be charged (Optional).
    - total: Total order amount to be charged to the customer.
Signature
After that you need to calculate a signature. Before you do that, the object should canonicalized to ensure correct signature calculation. The canonicalization of the data ensures all properties are ordered by key. The JSON string must not be pretified with no spaces or new lines. The above message after we put concrete data, canonicalize it, remove white spaces and new lines, would look like this:

{"app_id":9999,"order":{"items":[{"description":"Men' Shirt - Blue - M","price":2900,"quantity":1},{"description":"Men' Pants - Black - 34/34","price":3900,"quantity":1}],"order_id":"ksieo592dFt0284gV","total":6800},"return_url":"https://yourdomain.com/thankyou.php"}

You can then calculate the signature by generating a digital fingerprint with Message Authentication Code and SHA-256 hashing algorithm. The following is a PHP code that shows how to do that:

		$APISecretKey = 'YOUR APP SECRET KEY';
		
		$message = '{"app_id":9999,"order":{"items":[{"description":"Men' Shirt - Blue - M","price":2900,"quantity":1},{"description":"Men' Pants - Black - 34/34","price":3900,"quantity":1}],"order_id":"ksieo592dFt0284gV","total":6800},"return_url":"https://yourdomain.com/thankyou.php"}';
		
		$signature = hash_hmac('sha256', $message, $APISecretKey);
Redirect to Cash DZ
Now it is time to redirect the customer to Cash DZ payment portal. Pass the base64-encoded canonicalized message as well as the signature to Cash DZ. The following is the redirect URL:

https://cashdz.com/pay/?message=BASE_64_OF_MESSAGE&signature=SIGNATURE
Parameters
  - message: The base64-encoded string of the message described above.
  - signature: The MAC Hash signature calculated above.
Return URL
Once the customer completes the payment on Cash DZ, they are redirected to your return URL. In the Return URL script on the server-side, you will need to make a call to the Payment Verification API to confirm that the payment is successfully completed.
Two parameters will be passed to the Return URL: cashdz_result and either order_id in case of success, or message in case of failure. If you receive cashdz_result=error, Abort, and display the error message message to the customer
If you receive cashdz_result=success, retrieve the Order Id from the passed parameters under order_id, then calculate a signature.
Signature
You must calculate the signature by concatenating your app id and order id with a dot ( . ). The signature needs to be sent along with the Payment Verification API call. The following is a PHP code that shows how to calculate the signature:

		$APISecretKey = 'YOUR APP SECRET KEY';
		
		$message = $appId . '.' $order_id;
		
		$signature = hash_hmac('sha256', $message, $APISecretKey);
Call the Payment Verification API
Make a web request to the following Payment Verification API:
https://cashdz.com/pay/verify/?app_id=APP_ID&order_id=ORDER_ID&signature=SIGNATURE
Parameters
  - app_id: Your Application ID.
  - order_id: Your internal order id that you received via the Return URL.
  - signature: The MAC Hash signature calculated above.

The following is the response format in case of success.

	{
		"success": true,
		"payment_id" => PAYMENT_ID,
		"customer_id' => CUSTOMER_ID,
		"amount' => AMOUNT,
		"timestamp' => TIMESTAMP
	}

The following is the response format in case of a failure.

	{
		"success": false,
		"error" => ERROR_MESSAGE
	}

If the call is successfull, set your internal order as paid, and proceed to fulfill it. If the call fails, display an error message error to the customer.
Complete Example
Checkout Page (checkout.html)
<html>
	<head>
		<title>Checkout</title>
	</head>
	<script type="javascript">
		function payWithCashDZ() {
			window.location = '/pay_now.php';
		}
	</script>
	<body>
		<script src="https://cashdz.com/pay/lib.js?pay_callback=payWithCashDZ&mode=dark&size=medium"></script>
	</body>
</html>
Back-end Script (pay_now.php)
	
// You find this in your developers portal
$APISecretKey = 'e5f9d4c7a2b8e1f0d9c6b5a4e3d2c1b0a9f8e7d6';

// You would normally get order details from your customer's shopping cart
$payload = [
	'app_id' => 9999,
	'order' => [
		'order_id' => 'ksieo592dFt0284gV',
		'items' => [
			[
				'description' => 'Men\' Shirt - Blue - M',
				'price' => 2900.00,
				'quantity' => 1,
			],
			[
				'description' => 'Men\' Pants - Black - 34/34',
				'price' => 3900.00,
				'quantity' => 1,
			],
		],
		'total' => 6800.00,
	],
	'return_url' => 'https://yourdomain.com/thankyou.php',
];

$canonicalized = canonicalize($payload);
$message = json_encode($canonicalized, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);

// Calculate the HMAC-SHA256 signature
$signature = hash_hmac('sha256', $message, $APISecretKey);

header("Location: https://cashdz.com/pay/?message=" . base64_encode($message) . "&signature=" . $signature, true, 302);

function canonicalize($data) {
    if (is_array($data)) {
        // If it's an associative array, sort it by keys
        if (array_keys($data) !== range(0, count($data) - 1)) {
            ksort($data);
        }
        // Recursively apply to all children
        foreach ($data as $key => $value) {
            $data[$key] = canonicalize($value);
        }
    }
    return $data;
}
Return URL Page (thankyou.php)
$result = (($_GET['cashdz_result'] ?? '') === 'success');
$errorMessage = ($_GET['message'] ?? '');
if ($result === false) {
	echo $errorMessage;
	exit;
}

$appId = 2000;
$orderId = ($_GET['order_id'] ?? '');

// Calculate the HMAC-SHA256 signature
$message = $appId . '.' . $orderId;
$signature = hash_hmac('sha256', $message, $APISecretKey);

// Call the order payment verification API
$responseText = file_get_contents("https://cashdz.com/pay/verify/?app_id=" . $appId . "&order_id=" . $orderId . "&signature=" . $signature);
$response = json_decode($responseText, true);

if ($response['success'] === true) {
	
	// Store internally on your server the fact that the order is paid
	// Start fulfilling the order
	SetOrderAsPaid($orderId);
	
	echo "Thank you for your order. Your order is being processed, and we will send you an email as soon as it is shipped";
} else {
	echo "Error message: " . $response['error'];
}

Cash DZ - Home - Integration Documentation - Developer Portal