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 = "[e-mail]"; // 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.