Accept Payments

To facilitate payment acceptance, you can initiate a transaction through our API, our client JavaScript library, Popup JS, or our SDKs. Each transaction will generate a unique link that enables users to finalize the payment process seamlessly.

Popup

Lahza Popup offers a user-friendly and hassle-free payment flow designed for web applications. Integrating it into your platform is a breeze and can be accomplished in just five simple steps, making it the most straightforward method to begin accepting payments.

Collect customer information

To initialize the transaction, you need to pass information such as email, mobile, amount, transaction reference, etc. The key, email ,mobile and amount parameters are the only required parameters. The table below lists the parameters that you can pass when initializing a transaction.

Param	Required?	Description
key	Yes	Your public key from Lahza. Use test key for test mode and live key for live mode
email	No	Email address of customer
mobile	No	Mobile number of customer
firstName	No	First name of the customer
lastName	No	Last name of the customer
amount	Yes	Amount (in the lowest currency value - agora, cents) you are debiting customer.
ref	No	Unique case sensitive transaction reference. Only -,., =and alphanumeric characters allowed. If you do not pass this parameter, Lahza will generate a unique reference for you.
currency	No	Currency charge should be performed in. Allowed values are: ILS, JOD or USD It defaults to your integration currency.
channels	No	An array of payment channels to control what channels you want to make available to the user to make a payment with. Available channels include; ['card', 'bank', 'ussd', 'qr', 'mobile_money', 'bank_transfer']
metadata	No	Object containing any extra information you want recorded with the transaction. Fields within the custom_field object will show up on merchant receipt and within the transaction information on the Lahza Dashboard. You can learn more on the Metadata page.
label	No	String that replaces customer email as shown on the checkout form
onSuccess	No	Function that runs when payment is successful. This should ideally be a script that uses the verify endpoint on the Lahza API to check the status of the transaction.
onCancel	No	Javascript function that is called if the customer closes the payment window instead of making a payment.

HTML

<form id="form">
  <div class="form-group">
    <label for="email">Email Address</label>
    <input type="email" id="email" required />
  </div>
  <div class="form-group">
    <label for="amount">Amount</label>
    <input type="text" id="amount" required />
  </div>
  <div class="form-submit">
    <button type="submit" onclick="pay()"> Pay </button>
  </div>
</form>

<script src="https://js.lahza.io/inline.min.js"></script>

Javascript

<script>
    const paymentForm = document.getElementById('form');
    paymentForm.addEventListener("submit", pay, false);
    function pay(e) {
      e.preventDefault();
      const lahza = new LahzaPopup();
          lahza.newTransaction({
              key: 'pk_test_xxxxxxxx',
              email: document.getElementById("email").value,
              currency:"ILS",
              amount: document.getElementById("amount").value * 100,
              onSuccess: (transaction) => {
                   let message = 'Payment complete! Reference: ' + transaction.reference;
                   alert(message);
              },
              onCancel: () => {
                   alert('Window closed.');
              }
          });
    }
</script>

In this sample, notice how:

1. The Lahza inline javascript is included using a script tag. This is how you import Lahza into your code.

2. The amount here can be hardcoded if you want to charge a specific amount.

3. The Pay button has been tied to an onClick function called pay. This is the action that causes the Lahza popup to load.

If you don't collect customer email addresses, you can generate email addresses using the available information (e.g., phone numbers) along with your website URL.

Handle the callback method.

The callback method is fired when the transaction is successful. This is where you include any action you want to perform when the transaction is successful.

The recommended next step here is to verify the transaction to confirm the status.

To verify a transaction, you need to set up a server route or page where you pass the transaction reference. From your server, you can call the Lahza verify endpoint to check the status of the transaction. The response from the verification is then returned to your frontend for further processing.

There are 2 ways you can call your server from the callback function

1. Make an AJAX request to the endpoint on your server that handles the transaction verification

onSuccess: function(response){
  $.ajax({
    url: 'http://example.com/verify?reference='+ response.reference,
    method: 'get',
    success: function (response) {
      // the transaction status is in response.data.status
    }
  });
}

2. Redirect to the server URL by setting a window.location to the URL where the verification endpoint is set on your server.

onSuccess: function(response) {
  window.location = "http://example.com/verify.php?reference=" + response.reference;
};
// On the redirected page, you can call Lahza's verify endpoint.

For security reasons, it is essential to never directly call the Lahza API from your frontend. This prevents exposing your secret key on the client-side. Instead, all requests to the Lahza API should be initiated from your server. Your frontend can then receive the response from your server, ensuring the confidentiality of your secret key. This practice helps maintain the integrity of your payment system and safeguards sensitive information.

Verify the Transaction

After payment is made, the next step is to verify the transaction. Here's how to verify transactions with Lahza.

Handle Webhook

When a payment is successful, Lahza sends a charge.success webhook event to your webhook URL. You can learn more here.

Redirect

Here, you call the Initialize TransactionAPI from your server to generate a checkout link, then redirect your users to the link so they can pay. After payment is made, the users are returned to your website at the callback_url

Please ensure that your server is capable of establishing a TLSv1.2 connection with Lahza's servers. The majority of modern software supports this capability. If you encounter any SSL errors, it is recommended to contact your service provider for guidance and assistance in resolving the issue.

Initialize transaction

To initiate a transaction, follow these steps:

1. When a customer clicks the payment action button, send a POST request to our API to initialize the transaction. Include parameters such as email, amount, and any other required fields in the request to the Initialize Transaction API endpoint.

2. Upon a successful API call, we will provide you with an authorization URL. Redirect the customer to this URL to allow them to input their payment information and complete the transaction.

Important notes:

• Ensure that the amount field is converted to the lowest currency unit. Multiply the value by 100 to obtain the correct amount. For example, if you want to charge ULS50 or $50 or JOD50, multiply 50 by 100 and pass 5000 in the amount field.

• You should utilize a unique transaction identifier from your own system as the reference.

• If you wish to customize the callback URL for the transaction, set the callback_url in the transaction_data array. If not specified, we will use the callback URL set on your dashboard. Specifying the callback URL in the code allows you to be flexible with the redirect URL if necessary.

• If you do not set a callback URL on either the dashboard or in the code, users will not be redirected back to your site after completing the payment.

• For test transactions, you can set test callback URLs, while for live transactions, use live callback URLs. This distinction allows you to differentiate between test and live environments effectively.

<?php
  $url = "https://api.lahza.io/transaction/initialize";

  $fields = [
    'email' => "[e-mail]",
    'mobile'=>"059912313"
    'amount' => "20000"
  ];

  $fields_string = http_build_query($fields);

  //open connection
  $ch = curl_init();
  
  //set the url, number of POST vars, POST data
  curl_setopt($ch,CURLOPT_URL, $url);
  curl_setopt($ch,CURLOPT_POST, true);
  curl_setopt($ch,CURLOPT_POSTFIELDS, $fields_string);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Authorization: Bearer SECRET_KEY",
    "Cache-Control: no-cache",
  ));
  
  //So that curl_exec returns the contents of the cURL; rather than echoing it
  curl_setopt($ch,CURLOPT_RETURNTRANSFER, true); 
  
  //execute post
  $result = curl_exec($ch);
  echo $result;
?>

Verify Transaction

If the transaction is successful, Lahza will redirect the user back to a callback_url you set. We'll append the transaction reference in the URL. In the example above, the user will be redirected to http://your_website.com/callback.php?reference=YOUR_REFERENCE.

So you retrieve the reference from the URL parameter and use that to call the verify endpoint to confirm the status of the transaction. Learn more about verifying transactions.

It's very important that you call the Verify endpoint to confirm the status of the transactions before delivering value. Just because the callback_url was visited doesn't prove that transaction was successful.

Handle Webhook

When a payment is successful, Lahza sends a charge.success webhook event to webhook URL that you provide. Learn more about using webhooks.

Mobile SDKs

You can integrate Lahza directly into your Android or iOS app using our mobile SDK. For mobile frameworks like Ionic or React Native, please find the libraries here.