Malum Checkout Form
This guide will walk you through the process of integrating a checkout form on your website using the Malum payment API. The form allows customers to make a payment securely with the provided parameters such as amount, currency, success, and cancel URLs.
Prerequisites
Before proceeding with the integration, ensure you have the following:
Your Malum business ID.
Your Malum private key.
Access to your website's backend to modify PHP files.
<?php
$amount = 1; // The payment amount.
$currency = 'USD'; // The currency code (USD, EUR, etc.).
$webhook_url = 'https://malum.co/?webhook'; // The URL where the payment results will be sent.
$success_url = 'https://malum.co/'; // URL to redirect after a successful payment.
$cancel_url = 'https://malum.co/'; // URL to redirect after a canceled payment.
$business_id = 'XXXXXXXXXXXXX'; // Your Malum Business ID.
$private_key = "sec_XXXXXXXXXXXXXxXXXxxxxxxxx"; // Your Malum Private Key.
$metadata = ""; // Additional information you may want to send along with the payment request.
$customer_email = "[email protected]"; // The email of the customer making the payment.
$buyer_pays_fees = 0; // Whether the buyer will pay the transaction fees (0 = no, 1 = yes).
?>
2. Generate Signed Message
For security, you must generate a signed message to confirm that the payment request is authentic. This is done using a hash of all the parameters and the private key.
$signed_message = md5($amount . $currency . $webhook_url . $success_url . $cancel_url . $customer_email . $buyer_pays_fees . $metadata . $business_id . $private_key);
3. Create the Payment Form
The form below sends the payment request to the Malum API via POST when the user clicks the Pay Now button. Each parameter is passed as a hidden input field, including the signed message to verify the request's authenticity.
<form method="POST" action="https://malum.co/api/v3/checkout/form">
<input type="hidden" name="amount" value="<?php echo $amount; ?>">
<input type="hidden" name="currency" value="<?php echo $currency; ?>">
<input type="hidden" name="webhook_url" value="<?php echo $webhook_url; ?>">
<input type="hidden" name="success_url" value="<?php echo $success_url; ?>">
<input type="hidden" name="cancel_url" value="<?php echo $cancel_url; ?>">
<input type="hidden" name="customer_email" value="<?php echo $customer_email; ?>">
<input type="hidden" name="buyer_pays_fees" value="0">
<input type="hidden" name="metadata" value="<?php echo $metadata; ?>">
<input type="hidden" name="business_id" value="<?php echo $business_id; ?>">
<input type="hidden" name="signed_message" value="<?php echo $signed_message; ?>">
<button type="submit">Pay Now</button>
</form>
4. Form Breakdown
action: The form submits to
https://malum.co/api/v3/checkout/form
, which is the endpoint to start the checkout process with Malum.hidden inputs: These fields contain the payment data required by the API. The user will not see these fields, but they are essential for completing the payment.
Pay Now Button: The button triggers the form submission to process the payment.
You can adjust the style of the button with css.
5. Webhook URL
The webhook_url
specifies the location where Malum will send payment results. Make sure the URL points to an endpoint on your server where you can handle the payment notifications.
$webhook_url = 'https://malum.co/?webhook';
6. Success and Cancel URLs
When a payment is either successfully completed or canceled, the user will be redirected to these URLs.
Success URL: Redirects the user when the payment is successful.
$success_url = 'https://onramply.com/external/waiting';
Cancel URL: Redirects the user when the payment fails or is canceled.
$cancel_url = 'https://onramply.com/external/failed';
7. Handling the Response
Once the payment is processed, Malum will send a response to your webhook_url
. You need to have a backend process to handle these responses. You can verify the authenticity of the webhook response by checking the signature sent by Malum.
Conclusion
This integration allows you to securely create a payment form using the Malum API and handle payments on your website. With the right API keys and webhook setup, you can manage successful and failed payments seamlessly.
Last updated